IDatalink.h

//========================================================================================
// 
// $File$
// 
// Owner: Steve Flenniken
// 
// $Author$
// 
// $DateTime$
// 
// $Revision$
// 
// $Change$
// 
// Copyright 1997-2010 Adobe Systems Incorporated. All rights reserved.
// 
// NOTICE: Adobe permits you to use, modify, and distribute this file in accordance 
// with the terms of the Adobe license agreement accompanying it. If you have received
// this file from a source other than Adobe, then your use, modification, or 
// distribution of it requires the prior written permission of Adobe.
// 
// 
// This file defines an interface for linking to data. The links UI
// uses goes through this interface to get all the information it needs
// about the link. DataLink.cpp implements this interface for files
// (Macintosh and Windows files in a core way). Other implementations
// could be written. In the design I planned for URL files (files on 
// the internet), OLE linked files, and "files" stored in a database.
// 
// virtual int32 GetNameInfo(NameInfo *ni, PMString *formatName, uint32 *filetype) = 0;
// GetNameInfo gets the name and type of a link.
// 
// The ni parameter contains the Name, Volume and DirID that identifies
// a link. For Windows file links, name is the complete path name to 
// the file. For Macintosh file links, name is the filename, Volume is 
// the volume name and DirID is the directory id of the file. 
// 
// The ni object contains the ClassID of the boss that implements this
// IDataLink interface. For file links this is kDataLinkBoss. 
// 
// The formatName parameter is a string that identifies the type of link.
// This is the type string shown in the links information dialog. For file
// links the type string is dependent on the filter used to import the
// data. The string pointer returned is maintained by this interface and 
// must not be freed.
// 
// For Macintosh file links, the filetype parameter is the file type. For
// Windows file links, filetype is 0.
// 
// All parameters are optional, pass 0 when the information is not needed.
// 
// The return value is 0 when the routine is successful.
// 
// virtual StateType GetStoredState(uint64 *size, uint64 *time) = 0;
// GetStoredState retrieves the link's size, time and state. These values
// are stored with the object. Size and time are optional, pass 0 when
// they are not needed.
// 
// virtual PMString *GetBaseName() = 0;
// GetBaseName returns a string pointer to a short name that identifies
// the link. This is the string shown in the links palette. For file
// links the base name is the filename without any directory information.
// The string pointer returned is maintained by this interface and must
// not be freed.
// 
// virtual PMString *GetFullName() = 0;
// GetFullName returns a long name that identifies the link.
// This is the string shown in the links information dialog. For file
// links the full name is the complete path name.
// The string pointer returned is maintained by this interface and must
// not be freed.
// 
// virtual int32 SetNameInfo(NameInfo *ni, PMString *formatName, uint32 filetype) = 0;
// Sets the name and type for the link.
// The return value is 0 when the routine is successful.
// 
// virtual int32 SetStoredState(uint64 *size, uint64 *time, StateType state) = 0;
// Sets the size, time and state information that is stored with the object.
// The size and time parameters are optional, pass 0 and it will not
// be set.
// The return value is 0 when the routine is successful.
// 
// virtual int32 Combine(NameInfo *dirname, NameInfo *newname) = 0;
// Combine creates new name information for a link by combining
// the current link's basename with the directory specified by the dirname
// parameter.
// Combine is used by the find missing command to look for missing 
// links in other directories.
// The return value is 0 when the routine is successful.
// 
// virtual bool16 CompareBaseName(NameInfo *ni) = 0;
// CompareBaseName determines whether the given name information
// has the same basename as the current link.
// Compare returns true when ni specifies the same basename.
// 
// virtual bool16 CompareDirectory(NameInfo *ni) = 0;
// CompareDirectory determines whether the given directory is
// the same the the current link. The return value is true when they
// are the same.
// 
// virtual bool16 FindRelative(NameInfo *dirname, NameInfo *newname, ProgressParam *pp) = 0;
// FindRelative looks for the current link by looking relative to the 
// given directory. This operation should be fairly fast. Searching the 
// whole disk is currently too slow. 'pp' specifies a callback routine 
// that should be called to give the user feedback on slow operations. 
// When the link is found, true is returned and newname is filled in with 
// its name.
// 
// virtual StateType GetCurrentState(NameInfo *ni, uint64 *size, uint64 *time, uint32 *filetype, ProgressParam *pp) = 0;
// GetCurrentState gets the link's size, time and type by looking at the
// link on disk. When the ni parameter is 0, the current link is used,
// otherwise the link specified by ni is used. 'pp' specifies a callback 
// routine that should be called to give the user feedback on slow operations.
// If the routine takes a lot of time and the user cancels it, the
// StateType returned is the stored value (GetStoredState). The progress
// status (kContinue, kStopProcessing, kSkipItem) is returned in the pp parameter.
// All parameters are optional, pass 0 when the parameter is not 
// needed. The size parameter is the number of bytes of data that the 
// link represents. The time parameter is the Windows time value, the 
// number of milliseconds since January 1, 1601, the filetype parameter is
// the Macintosh file type or 0. 
// 
// virtual int32 Copy(NameInfo *dirname, ProgressParam *pp) = 0;
// Copy is used to make a copy of a link in the specified directory.
// pp' specifies a callback routine that should be called to give 
// the user feedback on slow operations.
// The return value is 0 when the routine is successful.
// 
// Normal names are used where directory parameters are specified.
// 
//========================================================================================

#ifndef __IDATALINK__
#define __IDATALINK__

class NameInfo;
class PMString;

#include "K2Vector.h"
#include "LinksID.h"

typedef enum {
 kContinue = 0,
 kStopProcessing,
 kSkipItem
} ProgressStatus;

typedef ProgressStatus ProgressProc(double total, double processed, int32 index, void *data);

typedef struct {
 ProgressProc *proc;
 void *data;
 int32 index;
 ProgressStatus status;
} ProgressParam;


class IDataLink : public IPMUnknown
{
public:
 enum { kDefaultIID = IID_IDATALINK };

 enum StateType {
 kLinkNormal = 0, 
 kLinkOutOfDate, 
 kLinkMissing, 
 kEmbedded};
 
 virtual void ReadWrite(IPMStream *s, ImplementationID prop) = 0;

 virtual int32 GetNameInfo(NameInfo *ni, PMString *formatName, uint32 *filetype) = 0;

 virtual StateType GetStoredState(uint64 *size, uint64 *time) = 0;

 virtual PMString *GetBaseName() = 0;

 virtual PMString *GetFullName() = 0;

 virtual int32 SetNameInfo(NameInfo *ni, PMString *formatName, uint32 filetype, const PMString *fullPath = nil) = 0;
 
 virtual int32 SetStoredState(uint64 *size, uint64 *time, StateType state) = 0;

 virtual int32 Combine(NameInfo *dirname, NameInfo *newname) = 0;

 virtual bool16 CompareBaseName(NameInfo *ni) = 0;

 virtual bool16 CompareDirectory(NameInfo *ni) = 0;

 virtual bool16 FindRelative(NameInfo *dirname, NameInfo *newname, ProgressParam *pp) = 0;

 virtual StateType GetCurrentState(NameInfo *ni, uint64 *size, uint64 *time, uint32 *filetype, ProgressParam *pp) = 0;

 virtual int32 Copy(NameInfo *dirname, ProgressParam *pp) = 0;
};
DECLARE_BASE_TYPE(IDataLink::StateType);

typedef K2Vector<IDataLink *> DataLinkPtrCollection;

#endif // __IDATALINK__