InDesign SDK  20.5
 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Friends Groups Pages
IDatalink.h
1 //========================================================================================
2 //
3 // $File$
4 //
5 // Owner: Steve Flenniken
6 //
7 // $Author$
8 //
9 // $DateTime$
10 //
11 // $Revision$
12 //
13 // $Change$
14 //
15 // Copyright 1997-2010 Adobe Systems Incorporated. All rights reserved.
16 //
17 // NOTICE: Adobe permits you to use, modify, and distribute this file in accordance
18 // with the terms of the Adobe license agreement accompanying it. If you have received
19 // this file from a source other than Adobe, then your use, modification, or
20 // distribution of it requires the prior written permission of Adobe.
21 //
22 //
23 // This file defines an interface for linking to data. The links UI
24 // uses goes through this interface to get all the information it needs
25 // about the link. DataLink.cpp implements this interface for files
26 // (Macintosh and Windows files in a core way). Other implementations
27 // could be written. In the design I planned for URL files (files on
28 // the internet), OLE linked files, and "files" stored in a database.
29 //
30 // virtual int32 GetNameInfo(NameInfo *ni, PMString *formatName, uint32 *filetype) = 0;
31 // GetNameInfo gets the name and type of a link.
32 //
33 // The ni parameter contains the Name, Volume and DirID that identifies
34 // a link. For Windows file links, name is the complete path name to
35 // the file. For Macintosh file links, name is the filename, Volume is
36 // the volume name and DirID is the directory id of the file.
37 //
38 // The ni object contains the ClassID of the boss that implements this
39 // IDataLink interface. For file links this is kDataLinkBoss.
40 //
41 // The formatName parameter is a string that identifies the type of link.
42 // This is the type string shown in the links information dialog. For file
43 // links the type string is dependent on the filter used to import the
44 // data. The string pointer returned is maintained by this interface and
45 // must not be freed.
46 //
47 // For Macintosh file links, the filetype parameter is the file type. For
48 // Windows file links, filetype is 0.
49 //
50 // All parameters are optional, pass 0 when the information is not needed.
51 //
52 // The return value is 0 when the routine is successful.
53 //
54 // virtual StateType GetStoredState(uint64 *size, uint64 *time) = 0;
55 // GetStoredState retrieves the link's size, time and state. These values
56 // are stored with the object. Size and time are optional, pass 0 when
57 // they are not needed.
58 //
59 // virtual PMString *GetBaseName() = 0;
60 // GetBaseName returns a string pointer to a short name that identifies
61 // the link. This is the string shown in the links palette. For file
62 // links the base name is the filename without any directory information.
63 // The string pointer returned is maintained by this interface and must
64 // not be freed.
65 //
66 // virtual PMString *GetFullName() = 0;
67 // GetFullName returns a long name that identifies the link.
68 // This is the string shown in the links information dialog. For file
69 // links the full name is the complete path name.
70 // The string pointer returned is maintained by this interface and must
71 // not be freed.
72 //
73 // virtual int32 SetNameInfo(NameInfo *ni, PMString *formatName, uint32 filetype) = 0;
74 // Sets the name and type for the link.
75 // The return value is 0 when the routine is successful.
76 //
77 // virtual int32 SetStoredState(uint64 *size, uint64 *time, StateType state) = 0;
78 // Sets the size, time and state information that is stored with the object.
79 // The size and time parameters are optional, pass 0 and it will not
80 // be set.
81 // The return value is 0 when the routine is successful.
82 //
83 // virtual int32 Combine(NameInfo *dirname, NameInfo *newname) = 0;
84 // Combine creates new name information for a link by combining
85 // the current link's basename with the directory specified by the dirname
86 // parameter.
87 // Combine is used by the find missing command to look for missing
88 // links in other directories.
89 // The return value is 0 when the routine is successful.
90 //
91 // virtual bool16 CompareBaseName(NameInfo *ni) = 0;
92 // CompareBaseName determines whether the given name information
93 // has the same basename as the current link.
94 // Compare returns true when ni specifies the same basename.
95 //
96 // virtual bool16 CompareDirectory(NameInfo *ni) = 0;
97 // CompareDirectory determines whether the given directory is
98 // the same the the current link. The return value is true when they
99 // are the same.
100 //
101 // virtual bool16 FindRelative(NameInfo *dirname, NameInfo *newname, ProgressParam *pp) = 0;
102 // FindRelative looks for the current link by looking relative to the
103 // given directory. This operation should be fairly fast. Searching the
104 // whole disk is currently too slow. 'pp' specifies a callback routine
105 // that should be called to give the user feedback on slow operations.
106 // When the link is found, true is returned and newname is filled in with
107 // its name.
108 //
109 // virtual StateType GetCurrentState(NameInfo *ni, uint64 *size, uint64 *time, uint32 *filetype, ProgressParam *pp) = 0;
110 // GetCurrentState gets the link's size, time and type by looking at the
111 // link on disk. When the ni parameter is 0, the current link is used,
112 // otherwise the link specified by ni is used. 'pp' specifies a callback
113 // routine that should be called to give the user feedback on slow operations.
114 // If the routine takes a lot of time and the user cancels it, the
115 // StateType returned is the stored value (GetStoredState). The progress
116 // status (kContinue, kStopProcessing, kSkipItem) is returned in the pp parameter.
117 // All parameters are optional, pass 0 when the parameter is not
118 // needed. The size parameter is the number of bytes of data that the
119 // link represents. The time parameter is the Windows time value, the
120 // number of milliseconds since January 1, 1601, the filetype parameter is
121 // the Macintosh file type or 0.
122 //
123 // virtual int32 Copy(NameInfo *dirname, ProgressParam *pp) = 0;
124 // Copy is used to make a copy of a link in the specified directory.
125 // pp' specifies a callback routine that should be called to give
126 // the user feedback on slow operations.
127 // The return value is 0 when the routine is successful.
128 //
129 // Normal names are used where directory parameters are specified.
130 //
131 //========================================================================================
132 
133 #ifndef __IDATALINK__
134 #define __IDATALINK__
135 
136 class NameInfo;
137 class PMString;
138 
139 #include "K2Vector.h"
140 #include "LinksID.h"
141 
143 typedef enum {
145  kContinue = 0,
147  kStopProcessing,
149  kSkipItem
150 } ProgressStatus;
151 
152 typedef ProgressStatus ProgressProc(double total, double processed, int32 index, void *data);
153 
155 typedef struct {
157  ProgressProc *proc;
159  void *data;
161  int32 index;
163  ProgressStatus status;
164 } ProgressParam;
165 
166 
174 class IDataLink : public IPMUnknown
175 {
176 public:
177  enum { kDefaultIID = IID_IDATALINK };
178 
180  enum StateType {
189 
194  virtual void ReadWrite(IPMStream *s, ImplementationID prop) = 0;
195 
202  virtual int32 GetNameInfo(NameInfo *ni, PMString *formatName, uint32 *filetype) = 0;
203 
210  virtual StateType GetStoredState(uint64 *size, uint64 *time) = 0;
211 
218  virtual PMString *GetBaseName() = 0;
219 
226  virtual PMString *GetFullName() = 0;
227 
235  virtual int32 SetNameInfo(NameInfo *ni, PMString *formatName, uint32 filetype, const PMString *fullPath = nil) = 0;
236 
243  virtual int32 SetStoredState(uint64 *size, uint64 *time, StateType state) = 0;
244 
253  virtual int32 Combine(NameInfo *dirname, NameInfo *newname) = 0;
254 
260  virtual bool16 CompareBaseName(NameInfo *ni) = 0;
261 
266  virtual bool16 CompareDirectory(NameInfo *ni) = 0;
267 
276  virtual bool16 FindRelative(NameInfo *dirname, NameInfo *newname, ProgressParam *pp) = 0;
277 
287  virtual StateType GetCurrentState(NameInfo *ni, uint64 *size, uint64 *time, uint32 *filetype, ProgressParam *pp) = 0;
288 
294  virtual int32 Copy(NameInfo *dirname, ProgressParam *pp) = 0;
295 };
296 DECLARE_BASE_TYPE(IDataLink::StateType);
297 
299 
300 #endif // __IDATALINK__