1 // ================================================================================================= 2 // ADOBE SYSTEMS INCORPORATED 3 // Copyright 2011 Adobe Systems Incorporated 4 // All Rights Reserved 5 // 6 // NOTICE: Adobe permits you to use, modify, and distribute this file in accordance with the terms 7 // of the Adobe license agreement accompanying it. 8 // ================================================================================================= 9 10 /************************************************************************** 11 * @file Plugin_Handler.h 12 * @brief Function prototypes for the XMP Plugin. 13 * 14 * This contains the prototype for the plug-in based File Handlers. Plug-in need 15 * to implement exported function InitializePlugin. 16 * 17 ***************************************************************************/ 18 19 #ifndef __Plugin_Handler_hpp__ 20 #define __Plugin_Handler_hpp__ 1 21 #include "PluginConst.h" 22 #include "PluginUtils.h" 23 #include "source/XMP_ProgressTracker.hpp" 24 25 // versioning 26 #define XMP_PLUGIN_VERSION_1 1 // CS6 27 #define XMP_PLUGIN_VERSION_2 2 // 28 #define XMP_PLUGIN_VERSION_3 3 // CS7 29 #define XMP_PLUGIN_VERSION_4 4 30 31 #define XMP_PLUGIN_VERSION XMP_PLUGIN_VERSION_4 32 33 namespace XMP_PLUGIN 34 { 35 36 #ifdef __cplusplus 37 extern "C" { 38 #endif 39 40 #if defined(__GNUC__) 41 #define DllExport __attribute__((visibility("default"))) 42 #else 43 #define DllExport __declspec( dllexport ) 44 #endif 45 46 struct PluginAPI; 47 struct HostAPI; 48 49 typedef PluginAPI* PluginAPIRef; 50 typedef HostAPI* HostAPIRef; 51 typedef void* SessionRef; 52 typedef void* XMP_IORef; 53 typedef int XMPErrorID; 54 55 /** @struct WXMP_Error 56 * 57 * This is used to pass error number and error message by the host(the XMPFiles) and the plugin. 58 * All plugin APIs and host APIs return kXMPErr_NoError on success otherwise return error id. 59 * All such APIs also take 'WXMP_Error wError' as the last argument. This structure will be filled 60 * by the error id and message if any error is encountered. The return value and wError->mErrorID 61 * contains the same number. 62 */ 63 struct WXMP_Error 64 { 65 XMPErrorID mErrorID; 66 XMP_StringPtr mErrorMsg; WXMP_ErrorWXMP_Error67 WXMP_Error() : mErrorID( kXMPErr_NoError ), mErrorMsg( NULL ) {} 68 }; 69 70 71 /** 72 * Function pointer to the function TerminatePlugin which will be called 73 * at the time of unloading of the plugin. 74 * 75 * @param wError WXMP_Error structure which will be filled by the API if any error occurs. 76 * @return kXMPErr_NoError on success otherwise error id of the failure. 77 */ 78 typedef XMPErrorID (*TerminatePluginProc)( WXMP_Error * wError ); 79 80 /** 81 * Function pointer to the function SetHostAPIProc which will be called to 82 * set the hostAPI. These host APIs will be used in the plugin to use the Host(the XMPFiles) functionality. 83 * 84 * @param hostAPI An API that is provided by the host (the XMPFiles) that can be used by a plugin implementaion. 85 * @param wError WXMP_Error structure which will be filled by the API if any error occurs. 86 * @return kXMPErr_NoError on success otherwise error id of the failure. 87 */ 88 typedef XMPErrorID (*SetHostAPIProc)( HostAPIRef hostAPI, WXMP_Error * wError ); 89 90 /** 91 * Function pointer to the function InitializeSession which will be called 92 * at the time of creating instance of the file handler with /param uid for file /param filePath. 93 * 94 * @param uid Unique identifier string (uid) of the file handler whose instance is to be created. 95 * @param filePath FilePath of the file which is to be opened. 96 * @param format File format id for the session 97 * @param handlerFlags Handler flags as defined in the plugin manifest 98 * @param openFlags Flags that describe the desired access. 99 * @param session Pointer to a file Handler instance. 100 * @return kXMPErr_NoError on success otherwise error id of the failure. 101 */ 102 typedef XMPErrorID (*InitializeSessionProc)( XMP_StringPtr uid, XMP_StringPtr filePath, XMP_Uns32 format, XMP_Uns32 handlerFlags, XMP_Uns32 openFlags, SessionRef * session, WXMP_Error * wError ); 103 104 /** 105 * Function pointer to the function InitializeSession which will be called 106 * at the time of creating instance of the file handler with /param uid for file /param filePath. 107 * 108 * @param uid Unique identifier string (uid) of the file handler whose instance is to be created. 109 * @param filePath FilePath of the file which is to be opened. 110 * @param format File format id for the session 111 * @param handlerFlags Handler flags as defined in the plugin manifest 112 * @param openFlags Flags that describe the desired access. 113 * @param session Pointer to a file Handler instance. 114 * @param errorCallback Pointer to error callback info 115 * @param progCBInfoPtr Points to the progress callback notification information 116 * @return kXMPErr_NoError on success otherwise error id of the failure. 117 */ 118 typedef XMPErrorID (*InitializeSessionV2Proc)( XMP_StringPtr uid, XMP_StringPtr filePath, XMP_Uns32 format, XMP_Uns32 handlerFlags, XMP_Uns32 openFlags, SessionRef * session, WXMP_Error * wError, 119 ErrorCallbackBox errorCallbackBox, XMP_ProgressTracker::CallbackInfo * progCBInfo ); 120 121 /** 122 * Function pointer to the function TerminateSession which will be called 123 * at the time of terminating instance of the file handler. 124 * 125 * @param session File Handler instance. 126 * @param wError WXMP_Error structure which will be filled by the API if any error occurs. 127 * @return kXMPErr_NoError on success otherwise error id of the failure. 128 */ 129 typedef XMPErrorID (*TerminateSessionProc)( SessionRef session, WXMP_Error * wError ); 130 131 /** 132 * Function pointer to the function CheckFileFormat which will be called to 133 * check whether the input file /param filePath is supported by the file handler with /param uid. 134 * 135 * @param uid Unique identifier string (uid) of the file handler. 136 * @param filePath FilePath of the file which is to be opened. 137 * @para fileRef File reference to the input file. 138 * @param result [out] pointer to a boolean which will be true if /param filePath is supported by the file handler. 139 * @param wError WXMP_Error structure which will be filled by the API if any error occurs. 140 * @return kXMPErr_NoError on success otherwise error id of the failure. 141 */ 142 typedef XMPErrorID (*CheckSessionFileFormatProc)( XMP_StringPtr uid, XMP_StringPtr filePath, XMP_IORef fileRef, XMP_Bool * result, WXMP_Error * wError ); 143 144 /** 145 * Function pointer to the function CheckFolderFormat which will be called to 146 * check whether the input folder name is supported by the file handler with /param uid. 147 * 148 * @param uid Unique identifier string (uid) of the file handler. 149 * @param rootPath 150 * @param gpName 151 * @param parentName 152 * @param leafName 153 * @param result [out] pointer to a boolen which will be true if it is supported by the file handler. 154 * @param wError WXMP_Error structure which will be filled by the API if any error occurs. 155 * @return kXMPErr_NoError on success otherwise error id of the failure. 156 */ 157 typedef XMPErrorID (*CheckSessionFolderFormatProc)( XMP_StringPtr uid, XMP_StringPtr rootPath, XMP_StringPtr gpName, XMP_StringPtr parentName, XMP_StringPtr leafName, XMP_Bool * result, WXMP_Error * wError ); 158 159 /** 160 * Function type for GetFileModDate. Returns the most recent file modification date for any file 161 * associated with the path that is read to obtain metadata. A static routine in XMPFiles. 162 * 163 * @param session File Handler instance. 164 * @param ok A pointer to a XMP_Bool for the eventual public API function result. 165 * @param modDate A pointer to the date to be returned. 166 * @param wError WXMP_Error structure which will be filled by the API if any error occurs. 167 */ 168 typedef XMPErrorID (*GetSessionFileModDateProc) ( SessionRef session, XMP_Bool * ok, XMP_DateTime * modDate, WXMP_Error * wError ); 169 170 /** 171 * Function pointer to the function CacheFileData which will be called to 172 * cache xmpData from the file format of the session. 173 * 174 * @param session File Handler instance. 175 * @param fileRef File reference of the file format which may be needed to read the data. 176 * @param xmpStr A pointer to a buffer where xmpData will be stored. 177 * @param wError WXMP_Error structure which will be filled by the API if any error occurs. 178 * @return kXMPErr_NoError on success otherwise error id of the failure. 179 */ 180 typedef XMPErrorID (*CacheFileDataProc)( SessionRef session, XMP_IORef fileRef, XMP_StringPtr* xmpStr, WXMP_Error * wError ); 181 182 /** 183 * Function pointer to the function UpdateFileData which will be called to 184 * update the file format of the session with the /param xmpPacket. 185 * 186 * @param session File Handler instance. 187 * @param fileRef File reference of the file format which may be needed to read the data. 188 * @param doSafeUpdate If true, file is saved in safe mode that means it write into a temporary file then swap for crash safety. 189 * @param xmpStr A pointer to a buffer which contain the xmpData. 190 * @param wError WXMP_Error structure which will be filled by the API if any error occurs. 191 * @return kXMPErr_NoError on success otherwise error id of the failure. 192 */ 193 typedef XMPErrorID (*UpdateFileProc)( SessionRef session, XMP_IORef fileRef, XMP_Bool doSafeUpdate, XMP_StringPtr xmpStr, WXMP_Error * wError ); 194 195 /** 196 * Function pointer to the function WriteTempFile. It write the entire file format into a 197 * temporary file /param fileRef. 198 * 199 * @param session File Handler instance. 200 * @param orgFileRef File reference to the original source file. 201 * @param fileRef File reference to a temporary file where file format will be written into. 202 * @param xmpStr A pointer to a buffer which contain the xmpData. 203 * @param wError WXMP_Error structure which will be filled by the API if any error occurs. 204 * @return kXMPErr_NoError on success otherwise error id of the failure. 205 */ 206 typedef XMPErrorID (*WriteTempFileProc)( SessionRef session, XMP_IORef orgFileRef, XMP_IORef fileRef, XMP_StringPtr xmpStr, WXMP_Error * wError ); 207 208 /** 209 * Function pointer to the function ImportToXMP. Any non metadata from a file that is supposed 210 * to be mapped into a XMP namespace should be added to the XMP packet using this function. 211 * 212 * @param session File Handler instance. 213 * @param xmp XMPMeta reference which will be filled by the function. 214 * @param wError WXMP_Error structure which will be filled by the API if any error occurs. 215 * @return kXMPErr_NoError on success otherwise error id of the failure. 216 */ 217 typedef XMPErrorID (*ImportToXMPProc)( SessionRef session, XMPMetaRef xmp, WXMP_Error * wError ); 218 219 /** 220 * Function pointer to the function ExportFromXMP. The XMP packet is supposed to be 221 * written to the file. If the packet contains any data that should be mapped back to 222 * native (non-XMP) metadata values then that should happen here. 223 * 224 * @param session File Handler instance. 225 * @param xmp XMPMeta reference where the xmpData will be picked from. 226 * @param wError WXMP_Error structure which will be filled by the API if any error occurs. 227 * @return kXMPErr_NoError on success otherwise error id of the failure. 228 */ 229 typedef XMPErrorID (*ExportFromXMPProc)( SessionRef session, XMPMetaRef xmp, WXMP_Error * wError ); 230 231 /** 232 * Function pointer to the function FillMetadataFiles. This function returns the list of file paths 233 * associated with storing the metadata information. 234 * 235 * @param session File Handler instance. 236 * @param metadataFiles pointer of std::vector of std::string 237 * @param SetClientStringVector pointer to client provided function to fill the vector with strings. 238 * @param wError WXMP_Error structure which will be filled by the API if any error occurs. 239 * @return kXMPErr_NoError on success otherwise error id of the failure. 240 */ 241 typedef XMPErrorID (*FillMetadataFilesProc)( SessionRef session, StringVectorRef metadataFiles, 242 SetStringVectorProc SetClientStringVector, WXMP_Error * wError ); 243 244 /** 245 * Function pointer to the function FillAssociatedResources. This function returns the list of all file paths 246 * associated to the opened session 247 * 248 * @param session File Handler instance. 249 * @param resourceList pointer of std::vector of std::string 250 * @param SetClientStringVector pointer to client provided function to fill the vector with strings. 251 * @param wError WXMP_Error structure which will be filled by the API if any error occurs. 252 * @return kXMPErr_NoError on success otherwise error id of the failure. 253 */ 254 typedef XMPErrorID (*FillAssociatedResourcesProc)( SessionRef session, StringVectorRef resourceList, 255 SetStringVectorProc SetClientStringVector, WXMP_Error * wError ); 256 257 /** 258 * Function pointer to the function ImportToXMP. Any non metadata from a file that is supposed 259 * to be mapped into a XMP namespace should be added to the XMP packet using this function. 260 * 261 * @param session File Handler instance. 262 * @param xmpStr A pointer to a buffer which contain the xmpData. 263 * @param wError WXMP_Error structure which will be filled by the API if any error occurs. 264 * @return kXMPErr_NoError on success otherwise error id of the failure. 265 */ 266 typedef XMPErrorID (*ImportToXMPStringProc)( SessionRef session, XMP_StringPtr* xmpStr , WXMP_Error * wError ); 267 268 /** 269 * Function pointer to the function ImportToXMP. Any non metadata from a file that is supposed 270 * to be mapped into a XMP namespace should be added to the XMP packet using this function. 271 * 272 * @param session File Handler instance. 273 * @param xmpStr A pointer to a buffer which contain the xmpData. 274 * @param wError WXMP_Error structure which will be filled by the API if any error occurs. 275 * @param packet Returns existed XMP packet present in the file, if available 276 * @param packetInfo Returns packet information of existed XMP packet in the file, if available 277 * @return kXMPErr_NoError on success otherwise error id of the failure. 278 */ 279 typedef XMPErrorID (*ImportToXMPStringWithPacketProc)( SessionRef session, XMP_StringPtr* xmpStr , WXMP_Error * wError, XMP_StringPtr* packet, XMP_PacketInfo * packetInfo ); 280 281 /** 282 * Function pointer to the function ExportFromXMP. The XMP packet is supposed to be 283 * written to the file. If the packet contains any data that should be mapped back to 284 * native (non-XMP) metadata values then that should happen here. 285 * 286 * @param session File Handler instance. 287 * @param xmpStr A pointer to a buffer which contain the xmpData. 288 * @param wError WXMP_Error structure which will be filled by the API if any error occurs. 289 * @return kXMPErr_NoError on success otherwise error id of the failure. 290 */ 291 typedef XMPErrorID (*ExportFromXMPStringProc)( SessionRef session, XMP_StringPtr xmpStr, WXMP_Error * wError ); 292 293 /** 294 * Function pointer to the function IsMetadataWritable. This function returns if the metadata can be updated 295 * for the opened session 296 * 297 * @param session File Handler instance. 298 * @param result [out] pointer to a boolen which will be true if the metadata can be updated. 299 * @return kXMPErr_NoError on success otherwise error id of the failure. 300 */ 301 typedef XMPErrorID (*IsMetadataWritableProc)( SessionRef session, XMP_Bool * result, WXMP_Error * wError ); 302 303 /** 304 * Function pointer to the function SetErrorCallback. This function will set ErrorCallbackNotification for the plugins 305 * 306 * @param session File Handler instance. 307 * @param errorCallback Pointer to Error Callback notification. 308 * @return kXMPErr_NoError on success otherwise error id of the failure. 309 */ 310 typedef XMPErrorID (*SetErrorCallbackproc)( SessionRef session, ErrorCallbackBox errorCallbackBox, WXMP_Error * wError ); 311 312 /** 313 * Function pointer to the function SetProgressCallback. This function will set ProgressCallback for the plugins. This needs to be set by plugin 314 * 315 * @param session File Handler instance. 316 * @param progCBInfoPtr Pointer to Progress Callback information. 317 * @return kXMPErr_NoError on success otherwise error id of the failure. 318 */ 319 typedef XMPErrorID (*SetProgressCallbackproc)( SessionRef session, XMP_ProgressTracker::CallbackInfo * progCBInfoPtr, WXMP_Error * wError ); 320 321 /** @struct PluginAPI 322 * @brief This is a Plugin API structure. 323 * 324 * This will consists of init/term of the plugin, init/term of a file handler session, 325 * read from fie and update file. 326 */ 327 struct PluginAPI 328 { 329 /** 330 * Size of the PluginAPI structure. 331 */ 332 XMP_Uns32 mSize; 333 334 /** 335 * Version number of the plugin. 336 */ 337 XMP_Uns32 mVersion; 338 339 // version 1 340 TerminatePluginProc mTerminatePluginProc; 341 SetHostAPIProc mSetHostAPIProc; 342 343 InitializeSessionProc mInitializeSessionProc; 344 TerminateSessionProc mTerminateSessionProc; 345 346 CheckSessionFileFormatProc mCheckFileFormatProc; 347 CheckSessionFolderFormatProc mCheckFolderFormatProc; 348 GetSessionFileModDateProc mGetFileModDateProc; 349 350 CacheFileDataProc mCacheFileDataProc; 351 UpdateFileProc mUpdateFileProc; 352 WriteTempFileProc mWriteTempFileProc; 353 354 ImportToXMPProc mImportToXMPProc; // deprecated in version 2 in favour of mImportToXMPStringProc 355 ExportFromXMPProc mExportFromXMPProc; // deprecated in version 2 in favour of mExportFromXMPStringProc 356 357 // version 2 358 FillMetadataFilesProc mFillMetadataFilesProc; 359 ImportToXMPStringProc mImportToXMPStringProc; 360 ExportFromXMPStringProc mExportFromXMPStringProc; 361 FillAssociatedResourcesProc mFillAssociatedResourcesProc; 362 363 // version 3 364 IsMetadataWritableProc mIsMetadataWritableProc; 365 366 // version 4 367 ImportToXMPStringWithPacketProc mImportToXMPStringWithPacketProc; 368 SetErrorCallbackproc mSetErrorCallbackproc; 369 InitializeSessionV2Proc mInitializeSessionV2Proc; 370 SetProgressCallbackproc mSetProgressCallbackproc; 371 }; 372 373 374 /** @brief Plugin Entry point (legacy). 375 * 376 * This is the legacy entry point for the plugin. It will fill \param pluginAPI inside the plugin. 377 * 378 * @param moduleID It is the module identifier string which is present in plugin's resource 379 * file 'MODULE_IDENTIFIER.txt". It should be same as the one which is present in plugin's library. 380 * @param pluginAPI structure pointer to PluginAPI which will be filled by the plugin. 381 * @param wError structure pointer to WXMP_Error which will be filled in case of an error. 382 * @return kXMPErr_NoError on success otherwise error id of the failure. 383 */ 384 DllExport XMPErrorID InitializePlugin( XMP_StringPtr moduleID, PluginAPIRef pluginAPI, WXMP_Error * wError ); 385 typedef XMPErrorID (*InitializePluginProc)( XMP_StringPtr moduleID, PluginAPIRef pluginAPI, WXMP_Error * wError ); 386 387 /** @brief Plugin Entry point. 388 * 389 * This is the entry point for the plugin. It will fill \param pluginAPI inside the plugin. 390 * 391 * @param moduleID It is the module identifier string which is present in plugin's resource 392 * file 'MODULE_IDENTIFIER.txt". It should be same as the one which is present in plugin's library. 393 * @param hostAPI structure pointer to HostAPI which will be stored by the plugin. 394 * @param pluginAPI structure pointer to PluginAPI which will be filled by the plugin. 395 * @param wError structure pointer to WXMP_Error which will be filled in case of an error. 396 * @return kXMPErr_NoError on success otherwise error id of the failure. 397 */ 398 DllExport XMPErrorID InitializePlugin2( XMP_StringPtr moduleID, HostAPIRef hostAPI, PluginAPIRef pluginAPI, WXMP_Error * wError ); 399 typedef XMPErrorID (*InitializePlugin2Proc)( XMP_StringPtr moduleID, HostAPIRef hostAPI, PluginAPIRef pluginAPI, WXMP_Error * wError ); 400 401 #ifdef __cplusplus 402 } 403 #endif 404 405 } //namespace XMP_PLUGIN 406 #endif // __Plugin_Handler_hpp__ 407