| XMP Toolkit SDK 6.0.0

TXMPFiles.hpp
Go to the documentation of this file.
1 #ifndef __TXMPFiles_hpp__
2 #define __TXMPFiles_hpp__ 1
3
4 #if ( ! __XMP_hpp__ )
5 #error "Do not directly include, use XMP.hpp"
6 #endif
7
8 // =================================================================================================
9 // Copyright Adobe
10 // Copyright 2002 Adobe
11 // All Rights Reserved
12 //
13 // NOTICE: Adobe permits you to use, modify, and distribute this file in accordance with the terms
14 // of the Adobe license agreement accompanying it. If you have received this file from a source other
15 // than Adobe, then your use, modification, or distribution of it requires the prior written permission
16 // of Adobe.
17 // =================================================================================================
18
19 // =================================================================================================
35 // =================================================================================================
36
37
38 // =================================================================================================
60 // =================================================================================================
61
62
63 #if XMP_StaticBuild // ! Client XMP_IO objects can only be used in static builds.
64 #include "XMP_IO.hpp"
65 #endif
66
67
68 template <class tStringObj>
69 class TXMPFiles {
70
71 public:
72
73 // =============================================================================================
78
79 // ---------------------------------------------------------------------------------------------
86
87 static void GetVersionInfo ( XMP_VersionInfo * versionInfo );
88
89 // ---------------------------------------------------------------------------------------------
98
99 static bool Initialize();
100
101 // ---------------------------------------------------------------------------------------------
115
116 static bool Initialize ( XMP_OptionBits options );
117
118 // ---------------------------------------------------------------------------------------------
135
136 static bool Initialize ( const char* pluginFolder, const char* plugins = NULL );
137
138 // ---------------------------------------------------------------------------------------------
156
157 static bool Initialize ( XMP_OptionBits options, const char* pluginFolder, const char* plugins = NULL );
158
159 // ---------------------------------------------------------------------------------------------
166
167 static void Terminate();
168
170
171 // =============================================================================================
177
178 // ---------------------------------------------------------------------------------------------
180
181 TXMPFiles();
182
183 // ---------------------------------------------------------------------------------------------
189
190 virtual ~TXMPFiles() throw();
191
192 // ---------------------------------------------------------------------------------------------
212
213 TXMPFiles ( XMP_StringPtr filePath,
214 XMP_FileFormat format = kXMP_UnknownFile,
215 XMP_OptionBits openFlags = 0 );
216
217 // ---------------------------------------------------------------------------------------------
223
224 TXMPFiles ( const tStringObj & filePath,
225 XMP_FileFormat format = kXMP_UnknownFile,
226 XMP_OptionBits openFlags = 0 );
227
228 // ---------------------------------------------------------------------------------------------
235
236 TXMPFiles ( const TXMPFiles<tStringObj> & original );
237
238 // ---------------------------------------------------------------------------------------------
244
245 void operator= ( const TXMPFiles<tStringObj> & rhs );
246
247 // ---------------------------------------------------------------------------------------------
257
258
259 TXMPFiles ( XMPFilesRef xmpFilesObj );
260
261 // ---------------------------------------------------------------------------------------------
272
273 XMPFilesRef GetInternalRef();
274
276
277 // =============================================================================================
283
284 // ---------------------------------------------------------------------------------------------
314
315
316 static bool GetFormatInfo ( XMP_FileFormat format,
317 XMP_OptionBits * handlerFlags = 0 );
318
320
321 // =============================================================================================
326
327 // ---------------------------------------------------------------------------------------------
338
339 static XMP_FileFormat CheckFileFormat ( XMP_StringPtr filePath );
340
341 // ---------------------------------------------------------------------------------------------
355
356 static XMP_FileFormat CheckPackageFormat ( XMP_StringPtr folderPath );
357
358 // ---------------------------------------------------------------------------------------------
378
379 static bool GetFileModDate ( XMP_StringPtr filePath,
380 XMP_DateTime * modDate,
381 XMP_FileFormat * format = 0,
382 XMP_OptionBits options = 0 );
383
384
385 // ---------------------------------------------------------------------------------------------
414
415 static bool GetAssociatedResources ( XMP_StringPtr filePath,
416 std::vector<tStringObj>* resourceList,
417 XMP_FileFormat format = kXMP_UnknownFile,
418 XMP_OptionBits options = 0);
419
420 // ---------------------------------------------------------------------------------------------
440
441 static bool IsMetadataWritable (XMP_StringPtr filePath,
442 bool * writable,
443 XMP_FileFormat format = kXMP_UnknownFile,
444 XMP_OptionBits options = 0 );
445
446 // ---------------------------------------------------------------------------------------------
501
502 bool OpenFile ( XMP_StringPtr filePath,
503 XMP_FileFormat format = kXMP_UnknownFile,
504 XMP_OptionBits openFlags = 0 );
505
506 // ---------------------------------------------------------------------------------------------
511
512 bool OpenFile ( const tStringObj & filePath,
513 XMP_FileFormat format = kXMP_UnknownFile,
514 XMP_OptionBits openFlags = 0 );
515
516 #if XMP_StaticBuild // ! Client XMP_IO objects can only be used in static builds.
517 // ---------------------------------------------------------------------------------------------
523
524 bool OpenFile ( XMP_IO * clientIO,
525 XMP_FileFormat format = kXMP_UnknownFile,
526 XMP_OptionBits openFlags = 0 );
527 #endif
528
529 // ---------------------------------------------------------------------------------------------
550
551 void CloseFile ( XMP_OptionBits closeFlags = 0 );
552
553 // ---------------------------------------------------------------------------------------------
570
571 bool GetFileInfo ( tStringObj * filePath = 0,
572 XMP_OptionBits * openFlags = 0,
573 XMP_FileFormat * format = 0,
574 XMP_OptionBits * handlerFlags = 0 );
575
576 // ---------------------------------------------------------------------------------------------
586
587 void SetAbortProc ( XMP_AbortProc abortProc,
588 void * abortArg );
589
591
592 // =============================================================================================
599
600 // ---------------------------------------------------------------------------------------------
627
628 bool GetXMP ( SXMPMeta * xmpObj = 0,
629 tStringObj * xmpPacket = 0,
630 XMP_PacketInfo * packetInfo = 0 );
631
632 // ---------------------------------------------------------------------------------------------
640
641 void PutXMP ( const SXMPMeta & xmpObj );
642
643 // ---------------------------------------------------------------------------------------------
651
652 void PutXMP ( const tStringObj & xmpPacket );
653
654 // ---------------------------------------------------------------------------------------------
665
666 void PutXMP ( XMP_StringPtr xmpPacket,
667 XMP_StringLen xmpLength = kXMP_UseNullTermination );
668
669 // ---------------------------------------------------------------------------------------------
703
704 bool CanPutXMP ( const SXMPMeta & xmpObj );
705
706 // ---------------------------------------------------------------------------------------------
714
715 bool CanPutXMP ( const tStringObj & xmpPacket );
716
717 // ---------------------------------------------------------------------------------------------
728
729 bool CanPutXMP ( XMP_StringPtr xmpPacket,
730 XMP_StringLen xmpLength = kXMP_UseNullTermination );
731
733
734 // =============================================================================================
743
744 // ---------------------------------------------------------------------------------------------
758
759 static void SetDefaultProgressCallback ( XMP_ProgressReportProc proc, void * context = 0,
760 float interval = 1.0, bool sendStartStop = false );
761
762 // ---------------------------------------------------------------------------------------------
775
776 void SetProgressCallback ( XMP_ProgressReportProc proc, void * context = 0,
777 float interval = 1.0, bool sendStartStop = false );
778
780
781 // =============================================================================================
782 // Error notifications
783 // ===================
784
785 // ---------------------------------------------------------------------------------------------
807
808 // --------------------------------------------------------------------------------------------
816
817 static void SetDefaultErrorCallback ( XMPFiles_ErrorCallbackProc proc, void* context = 0, XMP_Uns32 limit = 1 );
818
819 // --------------------------------------------------------------------------------------------
827
828 void SetErrorCallback ( XMPFiles_ErrorCallbackProc proc, void* context = 0, XMP_Uns32 limit = 1 );
829
830 // --------------------------------------------------------------------------------------------
835
836 void ResetErrorCallbackLimit ( XMP_Uns32 limit = 1 );
837
839
840 // =============================================================================================
841
842 private:
843
844 XMPFilesRef xmpFilesRef;
845
846 // These are used as callbacks from the library code to the client when returning values that
847 // involve heap allocations. This ensures the allocations occur within the client.
848 static void SetClientString ( void * clientPtr, XMP_StringPtr valuePtr, XMP_StringLen valueLen );
849 static void SetClientStringVector ( void * clientPtr, XMP_StringPtr* arrayPtr, XMP_Uns32 stringCount );
850 }; // class TXMPFiles
851
852 // =================================================================================================
853
854 #endif // __TXMPFiles_hpp__
TXMPFiles::SetAbortProc
void SetAbortProc(XMP_AbortProc abortProc, void *abortArg)
SetAbortProc() registers a callback function used to check for a user-signaled abort.
TXMPFiles::TXMPFiles
TXMPFiles()
Default constructor initializes an object that is associated with no file.
TXMPFiles::CheckPackageFormat
static XMP_FileFormat CheckPackageFormat(XMP_StringPtr folderPath)
CheckPackageFormat() tries to determine the format of a "package" folder.
TXMPFiles::GetFileModDate
static bool GetFileModDate(XMP_StringPtr filePath, XMP_DateTime *modDate, XMP_FileFormat *format=0, XMP_OptionBits options=0)
GetFileModDate() returns the last modification date of all files that are returned by GetAssociatedRe...
XMP_VersionInfo
XMP Toolkit version information.
Definition: XMP_Const.h:1565
XMPFiles_ErrorCallbackProc
bool(* XMPFiles_ErrorCallbackProc)(void *context, XMP_StringPtr filePath, XMP_ErrorSeverity severity, XMP_Int32 cause, XMP_StringPtr message)
The signature of a client-defined callback for TXMPFiles error notifications.
Definition: XMP_Const.h:1317
XMP_AbortProc
bool(* XMP_AbortProc)(void *arg)
The signature of a client-defined callback to check for a user request to abort a time-consuming oper...
Definition: XMP_Const.h:1527
XMPFilesRef
struct __XMPFiles__ * XMPFilesRef
An "ABI safe" pointer to the internal part of an XMP file-handling object. Use to pass an XMP file-ha...
Definition: XMP_Const.h:151
XMP_PacketInfo
XMP packet description.
Definition: XMP_Const.h:1081
kXMP_UnknownFile
@ kXMP_UnknownFile
Unknown file format constant: ' '.
Definition: XMP_Const.h:999
TXMPFiles::CheckFileFormat
static XMP_FileFormat CheckFileFormat(XMP_StringPtr filePath)
CheckFileFormat() tries to determine the format of a file.
XMP_IO.hpp
TXMPFiles::GetVersionInfo
static void GetVersionInfo(XMP_VersionInfo *versionInfo)
GetVersionInfo() retrieves version information for the XMPFiles component.
TXMPFiles::GetFileInfo
bool GetFileInfo(tStringObj *filePath=0, XMP_OptionBits *openFlags=0, XMP_FileFormat *format=0, XMP_OptionBits *handlerFlags=0)
GetFileInfo() retrieves basic information about an opened file.
TXMPFiles::SetDefaultProgressCallback
static void SetDefaultProgressCallback(XMP_ProgressReportProc proc, void *context=0, float interval=1.0, bool sendStartStop=false)
SetDefaultProgressCallback() sets a global default for progress tracking. This is used as a default f...
XMP_IO
Abstract base class for client-managed I/O with TXMPFiles.
Definition: XMP_IO.hpp:44
TXMPFiles::xmpFilesRef
XMPFilesRef xmpFilesRef
Definition: TXMPFiles.hpp:844
XMP_StringPtr
const typedef char * XMP_StringPtr
The type for input string parameters. A const char *, a null-terminated UTF-8 string.
Definition: XMP_Const.h:178
TXMPFiles::IsMetadataWritable
static bool IsMetadataWritable(XMP_StringPtr filePath, bool *writable, XMP_FileFormat format=kXMP_UnknownFile, XMP_OptionBits options=0)
IsMetadataWritable() returns true if metadata can be updated for the given media path.
TXMPFiles::operator=
void operator=(const TXMPFiles< tStringObj > &rhs)
Assignment operator.
XMP_ProgressReportProc
bool(* XMP_ProgressReportProc)(void *context, float elapsedTime, float fractionDone, float secondsToGo)
The signature of a client-defined callback for progress report notifications.
Definition: XMP_Const.h:1550
XMP_StringLen
XMP_Uns32 XMP_StringLen
The type for string length parameters. A 32-bit unsigned integer, as big as will be practically neede...
Definition: XMP_Const.h:179
TXMPFiles::~TXMPFiles
virtual ~TXMPFiles()
Destructor; typical virtual destructor.
TXMPFiles::SetClientString
static void SetClientString(void *clientPtr, XMP_StringPtr valuePtr, XMP_StringLen valueLen)
TXMPFiles::CanPutXMP
bool CanPutXMP(const SXMPMeta &xmpObj)
CanPutXMP() reports whether this file can be updated with a specific XMP packet.
kXMP_UseNullTermination
#define kXMP_UseNullTermination
Options macro sets string style.
Definition: XMP_Const.h:472
TXMPFiles::Initialize
static bool Initialize()
Initializes the XMPFiles library; must be called before creating an SXMPFiles object.
TXMPFiles::OpenFile
bool OpenFile(XMP_StringPtr filePath, XMP_FileFormat format=kXMP_UnknownFile, XMP_OptionBits openFlags=0)
OpenFile() opens a file for metadata access.
TXMPFiles::SetErrorCallback
void SetErrorCallback(XMPFiles_ErrorCallbackProc proc, void *context=0, XMP_Uns32 limit=1)
SetErrorCallback() registers an error notification callback.
TXMPFiles::Terminate
static void Terminate()
Terminates use of the XMPFiles library.
TXMPFiles::GetXMP
bool GetXMP(SXMPMeta *xmpObj=0, tStringObj *xmpPacket=0, XMP_PacketInfo *packetInfo=0)
GetXMP() retrieves the XMP metadata from an open file.
TXMPFiles::GetInternalRef
XMPFilesRef GetInternalRef()
GetInternalRef() retrieves an internal reference that can be safely passed across DLL boundaries and ...
TXMPFiles::SetProgressCallback
void SetProgressCallback(XMP_ProgressReportProc proc, void *context=0, float interval=1.0, bool sendStartStop=false)
SetProgressCallback() sets the progress notification callback for the associated XMPFiles (library) o...
TXMPFiles::CloseFile
void CloseFile(XMP_OptionBits closeFlags=0)
CloseFile() explicitly closes an opened file.
TXMPFiles::SetClientStringVector
static void SetClientStringVector(void *clientPtr, XMP_StringPtr *arrayPtr, XMP_Uns32 stringCount)
TXMPFiles::PutXMP
void PutXMP(const SXMPMeta &xmpObj)
PutXMP() updates the XMP metadata in this object without writing out the file.
XMP_OptionBits
XMP_Uns32 XMP_OptionBits
The type for a collection of 32 flag bits.
Definition: XMP_Const.h:181
TXMPFiles::GetAssociatedResources
static bool GetAssociatedResources(XMP_StringPtr filePath, std::vector< tStringObj > *resourceList, XMP_FileFormat format=kXMP_UnknownFile, XMP_OptionBits options=0)
GetAssociatedResources() returns a list of files and folders associated to filePath.
XMP_DateTime
The expanded type for a date and time.
Definition: XMP_Const.h:232
TXMPFiles::ResetErrorCallbackLimit
void ResetErrorCallbackLimit(XMP_Uns32 limit=1)
ResetErrorCallbackLimit() resets the error notification limit and counting. It has no effect if an er...
XMP_FileFormat
XMP_Uns32 XMP_FileFormat
Type for file format identification constants. See kXMP_PDFFile and following.
Definition: XMP_Const.h:1004
TXMPFiles
API for access to the main (document-level) metadata in a file.
Definition: TXMPFiles.hpp:69
TXMPFiles::GetFormatInfo
static bool GetFormatInfo(XMP_FileFormat format, XMP_OptionBits *handlerFlags=0)
GetFormatInfo() reports what features are supported for a specific file format.
TXMPFiles::SetDefaultErrorCallback
static void SetDefaultErrorCallback(XMPFiles_ErrorCallbackProc proc, void *context=0, XMP_Uns32 limit=1)
SetDefaultErrorCallback() registers a global default error notification callback.