API for access to the main (document-level) metadata in a file. More...
#include <TXMPFiles.hpp>
Public Member Functions | |
Constructors and destructor | |
The default constructor initializes an object that is associated with no file. The alternate constructors call | |
| TXMPFiles () | |
| Default constructor initializes an object that is associated with no file. More... | |
| virtual | ~TXMPFiles () throw () |
| Destructor; typical virtual destructor. More... | |
| TXMPFiles (XMP_StringPtr filePath, XMP_FileFormat format=kXMP_UnknownFile, XMP_OptionBits openFlags=0) | |
Alternate constructor associates the new XMPFiles object with a specific file. More... | |
| TXMPFiles (const tStringObj &filePath, XMP_FileFormat format=kXMP_UnknownFile, XMP_OptionBits openFlags=0) | |
Alternate constructor associates the new XMPFiles object with a specific file, using a string object. More... | |
| TXMPFiles (const TXMPFiles< tStringObj > &original) | |
| Copy constructor. More... | |
| void | operator= (const TXMPFiles< tStringObj > &rhs) |
| Assignment operator. More... | |
| TXMPFiles (XMPFilesRef xmpFilesObj) | |
Reconstructs a TXMPFiles object from an internal reference. More... | |
| XMPFilesRef | GetInternalRef () |
| GetInternalRef() retrieves an internal reference that can be safely passed across DLL boundaries and reconstructed. More... | |
Accessing metadata | |
| bool | GetXMP (SXMPMeta *xmpObj=0, tStringObj *xmpPacket=0, XMP_PacketInfo *packetInfo=0) |
GetXMP() retrieves the XMP metadata from an open file. More... | |
| void | PutXMP (const SXMPMeta &xmpObj) |
PutXMP() updates the XMP metadata in this object without writing out the file. More... | |
| void | PutXMP (const tStringObj &xmpPacket) |
PutXMP() updates the XMP metadata in this object without writing out the file, using a string object for input. More... | |
| void | PutXMP (XMP_StringPtr xmpPacket, XMP_StringLen xmpLength=kXMP_UseNullTermination) |
PutXMP() updates the XMP metadata in this object without writing out the file, More... | |
| bool | CanPutXMP (const SXMPMeta &xmpObj) |
CanPutXMP() reports whether this file can be updated with a specific XMP packet. More... | |
| bool | CanPutXMP (const tStringObj &xmpPacket) |
CanPutXMP() reports whether this file can be updated with a specific XMP packet, passed in a string object. More... | |
| bool | CanPutXMP (XMP_StringPtr xmpPacket, XMP_StringLen xmpLength=kXMP_UseNullTermination) |
CanPutXMP() reports whether this file can be updated with a specific XMP packet, passed in a string object. More... | |
Static Public Member Functions | |
Initialization and termination | |
A | |
| static void | GetVersionInfo (XMP_VersionInfo *versionInfo) |
GetVersionInfo() retrieves version information for the XMPFiles component. More... | |
| static bool | Initialize () |
Initializes the XMPFiles library; must be called before creating an SXMPFiles object. More... | |
| static bool | Initialize (XMP_OptionBits options) |
Initializes the XMPFiles library; must be called before creating an SXMPFiles object. More... | |
| static bool | Initialize (const char *pluginFolder, const char *plugins=NULL) |
Initializes the XMPFiles library; must be called before creating an SXMPFiles object. More... | |
| static bool | Initialize (XMP_OptionBits options, const char *pluginFolder, const char *plugins=NULL) |
Initializes the XMPFiles library; must be called before creating an SXMPFiles object. More... | |
| static void | Terminate () |
| Terminates use of the XMPFiles library. More... | |
File handler information | |
Call this static function from the concrete class, | |
| *static bool | GetFormatInfo (XMP_FileFormat format, XMP_OptionBits *handlerFlags=0) |
| GetFormatInfo() reports what features are supported for a specific file format. More... | |
Static Private Member Functions | |
| static void | SetClientString (void *clientPtr, XMP_StringPtr valuePtr, XMP_StringLen valueLen) |
| static void | SetClientStringVector (void *clientPtr, XMP_StringPtr *arrayPtr, XMP_Uns32 stringCount) |
Private Attributes | |
| XMPFilesRef | xmpFilesRef |
File operations | |
| static XMP_FileFormat | CheckFileFormat (XMP_StringPtr filePath) |
CheckFileFormat() tries to determine the format of a file. More... | |
| static XMP_FileFormat | CheckPackageFormat (XMP_StringPtr folderPath) |
CheckPackageFormat() tries to determine the format of a "package" folder. More... | |
| 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 GetAssociatedResources() More... | |
| 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. More... | |
| 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. More... | |
| bool | OpenFile (XMP_StringPtr filePath, XMP_FileFormat format=kXMP_UnknownFile, XMP_OptionBits openFlags=0) |
OpenFile() opens a file for metadata access. More... | |
| bool | OpenFile (const tStringObj &filePath, XMP_FileFormat format=kXMP_UnknownFile, XMP_OptionBits openFlags=0) |
OpenFile() opens a file for metadata access, using a string object More... | |
| void | CloseFile (XMP_OptionBits closeFlags=0) |
| CloseFile() explicitly closes an opened file. More... | |
| 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. More... | |
| void | SetAbortProc (XMP_AbortProc abortProc, void *abortArg) |
SetAbortProc() registers a callback function used to check for a user-signaled abort. More... | |
Progress notifications | |
These functions allow track the progress of file operations. Initially only file updates are tracked, these all occur within calls to SXMPFiles::CloseFile. There are no plans to track other operations at this time. Tracking support must be added to specific file handlers, there are no guarantees about which handlers will have support. To simplify the logic only file writes will be estimated and measured. | |
| 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 for XMPFiles (library) objects created after the default is set. This does not affect the callback for new SXMPFiles (client) objects with an existing XMPFiles object. More... | |
| 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) object. More... | |
Error notifications | |
From the beginning through version 5.5, XMP Toolkit errors result in throwing an A client can register an error notification callback function for a The number of notifications delivered for a given TXMPFiles object can be limited. This is intended to reduce chatter from multiple or cascading errors. The limit is set when the callback function is registered. This limits the number of notifications of the highest severity delivered or less. If a higher severity error occurs, the counting starts again. The limit and counting can be reset at any time, see | |
| static void | SetDefaultErrorCallback (XMPFiles_ErrorCallbackProc proc, void *context=0, XMP_Uns32 limit=1) |
| SetDefaultErrorCallback() registers a global default error notification callback. More... | |
| void | SetErrorCallback (XMPFiles_ErrorCallbackProc proc, void *context=0, XMP_Uns32 limit=1) |
| SetErrorCallback() registers an error notification callback. More... | |
| void | ResetErrorCallbackLimit (XMP_Uns32 limit=1) |
| ResetErrorCallbackLimit() resets the error notification limit and counting. It has no effect if an error notification callback function is not registered. More... | |
API for access to the main (document-level) metadata in a file.
TXMPFiles is a template class that provides the API for the Adobe XMP Toolkit's XMPFiles component. This provides convenient access to the main, or document level, XMP for a file. Use it to obtain metadata from a file, which you can then manipulate with the XMP Core component (the classes TXMPMeta, TXMPUtils, and TXMPIterator); and to write new or changed metadata back out to a file.
The functions allow you to open a file, read and write the metadata, then close the file. While open, portions of the file might be maintained in RAM data structures. Memory usage can vary considerably depending onfile format and access options.
A file can be opened for read-only or read-write access, with typical exclusion for both modes. Errors result in the throw of an XMPError exception.
TXMPFiles is the template class. It must be instantiated with a string class such as std::string. Read the Toolkit Overview for information about the overall architecture of the XMP API, and the documentation for XMP.hpp for specific instantiation instructions.
Access these functions through the concrete class, SXMPFiles.
Definition at line 67 of file TXMPFiles.hpp.
Default constructor initializes an object that is associated with no file.
Destructor; typical virtual destructor.
The destructor does not call CloseFile(); pending updates are lost when the destructor is run.
OpenFile(), CloseFile() | TXMPFiles< tStringObj >::TXMPFiles | ( | XMP_StringPtr | filePath, |
| XMP_FileFormat | format = kXMP_UnknownFile, |
||
| XMP_OptionBits | openFlags = 0 |
||
| ) |
Alternate constructor associates the new XMPFiles object with a specific file.
Calls OpenFile() to open the specified file after performing a default construct.
| filePath | The path for the file, specified as a nul-terminated UTF-8 string. |
| format | A format hint for the file, if known. |
| openFlags | Options for how the file is to be opened (for read or read/write, for example). Use a logical OR of these bit-flag constants: |
kXMPFiles_OpenForRead kXMPFiles_OpenForUpdate kXMPFiles_OpenOnlyXMP kXMPFiles_OpenStrictly kXMPFiles_OpenUseSmartHandler kXMPFiles_OpenUsePacketScanning kXMPFiles_OpenLimitedScanning TXMPFiles object. | TXMPFiles< tStringObj >::TXMPFiles | ( | const tStringObj & | filePath, |
| XMP_FileFormat | format = kXMP_UnknownFile, |
||
| XMP_OptionBits | openFlags = 0 |
||
| ) |
Alternate constructor associates the new XMPFiles object with a specific file, using a string object.
Overloads the basic form of the function, allowing you to pass a string object for the file path. It is otherwise identical; see details in the canonical form.
| TXMPFiles< tStringObj >::TXMPFiles | ( | XMPFilesRef | xmpFilesObj | ) |
Reconstructs a TXMPFiles object from an internal reference.
This constructor creates a new TXMPFiles object that refers to the underlying reference object of an existing TXMPFiles object. Use to safely pass SXMPFiles references across DLL boundaries.
| xmpFilesObj | The underlying reference object, obtained from some other XMP object with TXMPFiles::GetInternalRef(). |
| bool TXMPFiles< tStringObj >::CanPutXMP | ( | const SXMPMeta & | xmpObj | ) |
CanPutXMP() reports whether this file can be updated with a specific XMP packet.
Use to determine if the file can probably be updated with a given set of XMP metadata. This depends on the size of the packet, the options with which the file was opened, and the capabilities of the handler for the file format. The function obtains the length of the serialized packet for the provided XMP, but does not keep it or modify it, and does not cause the file to be written when closed. This is implemented roughly as follows:
bool CanPutXMP ( XMP_StringPtr xmpPacket )
{
XMP_FileFormat format;
this->GetFileInfo ( 0, &format, 0 );XMP_OptionBits formatFlags; GetFormatInfo ( format, &formatFlags );
if ( (formatFlags & kXMPFiles_CanInjectXMP) && (formatFlags & kXMPFiles_CanExpand) ) return true;
XMP_PacketInfo packetInfo; bool hasXMP = this->GetXMP ( 0, 0, &packetInfo );
if ( ! hasXMP ) {
if ( formatFlags & kXMPFiles_CanInjectXMP ) return true;
} else {
if ( (formatFlags & kXMPFiles_CanExpand) ||
(packetInfo.length >= strlen(xmpPacket)) ) return true;
}
return false;
}
| xmpObj | The proposed new metadata as an XMP object. |
| bool TXMPFiles< tStringObj >::CanPutXMP | ( | const tStringObj & | xmpPacket | ) |
CanPutXMP() reports whether this file can be updated with a specific XMP packet, passed in a string object.
Overloads the basic form of the function, allowing you to pass the metadata as a string object instead of an XMP object. It is otherwise identical; see details in the canonical form.
| xmpPacket | The proposed new metadata as a string object containing an XMP packet. |
| bool TXMPFiles< tStringObj >::CanPutXMP | ( | XMP_StringPtr | xmpPacket, |
| XMP_StringLen | xmpLength = kXMP_UseNullTermination |
||
| ) |
CanPutXMP() reports whether this file can be updated with a specific XMP packet, passed in a string object.
Overloads the basic form of the function, allowing you to pass the metadata as a string object instead of an XMP object. It is otherwise identical; see details in the canonical form.
| xmpPacket | The proposed new metadata as a const char * string containing an XMP packet. |
| xmpLength | Optional. The number of bytes in the string. If not supplied, the string is assumed to be nul-terminated. |
|
static |
CheckFileFormat() tries to determine the format of a file.
Tries to determine the format of a file, returning an XMP_FileFormat value. Uses the same logic as OpenFile() to select a smart handler.
| filePath | The path for the file, appropriate for the local operating system. Passed as a nul-terminated UTF-8 string. The path is the same as would be passed to OpenFile. |
OpenFile(), otherwise kXMP_UnknownFile.
|
static |
CheckPackageFormat() tries to determine the format of a "package" folder.
Tries to determine the format of a package, given the name of the top-level folder. Returns an XMP_FileFormat value. Examples of recognized packages include the video formats P2, XDCAM, or Sony HDV. These packages contain collections of "clips", stored as multiple files in specific subfolders.
| folderPath | The path for the top-level folder, appropriate for the local operating system. Passed as a nul-terminated UTF-8 string. This is not the same path you would pass to OpenFile(). For example, the top-level path for a package might be ".../MyMovie", while the path to a file you wish to open would be ".../MyMovie/SomeClip". |
kXMP_UnknownFile. | void TXMPFiles< tStringObj >::CloseFile | ( | XMP_OptionBits | closeFlags = 0 | ) |
CloseFile() explicitly closes an opened file.
Performs any necessary output to the file and closes it. Files that are opened for update are written to only when closing.
If the file is opened for read-only access (passing kXMPFiles_OpenForRead), the disk file is closed immediately after reading the data from it; the XMPFiles object, however, remains in the open state. You must call CloseFile() when finished using it. Other methods, such as GetXMP(), can only be used between the OpenFile() and CloseFile() calls. The XMPFiles destructor does not call CloseFile(); if you call it without closing, any pending updates are lost.
If the file is opened for update (passing kXMPFiles_OpenForUpdate), the disk file remains open until CloseFile() is called. The disk file is only updated once, when CloseFile() is called, regardless of how many calls are made to PutXMP().
| closeFlags | Option flags for optional closing actions. This bit-flag constant is defined: |
kXMPFiles_UpdateSafely - Write into a temporary file then swap for crash safety.
|
static |
GetAssociatedResources() returns a list of files and folders associated to filePath.
GetAssociatedResources is provided to locate all files that are associated to the given filePath such as sidecar-based XMP or folder-based video packages.If a smart handler can be selected (not fallback packet scanning) then a list of file/folder paths is returned for the related files that can be safely copied/imported to a different location, keeping intact metadata(XMP and non-XMP),content and the necessary folder structure of the format. The necessary folder structure here is the structure that is needed to uniquely identify a folder-based format.The filePath and format parameters are exactly as would be used for OpenFile. In the simple embedded XMP case just one path is returned. In the simple sidecar case one or two paths will be returned, one if there is no sidecar XMP and two if sidecar XMP exists. For folder-based handlers paths to all associated files is returned, including the files and folders necessary to identify the format.In general, all the returned paths are existent.In case of folder based video formats the first associated resource in the resourceList is the root folder.
| filePath | A path exactly as would be passed to OpenFile. |
| resourceList | Address of a vector of strings to receive all associated resource paths. |
| format | A format hint as would be passed to OpenFile. |
| options | An optional set of option flags. The only defined one is kXMPFiles_ForceGivenHandler, used to shortcut the handler selection logic if the caller is certain of the format. |
| bool TXMPFiles< tStringObj >::GetFileInfo | ( | tStringObj * | filePath = 0, |
| XMP_OptionBits * | openFlags = 0, |
||
| XMP_FileFormat * | format = 0, |
||
| XMP_OptionBits * | handlerFlags = 0 |
||
| ) |
GetFileInfo() retrieves basic information about an opened file.
| filePath | [out] A buffer in which to return the path passed to OpenFile(). Can be null if value is not wanted. |
| openFlags | [out] A buffer in which to return the option flags passed to OpenFile(). Can be null if value is not wanted. |
| format | [out] A buffer in which to return the file format. Can be null if value is not wanted. |
| handlerFlags | [out] A buffer in which to return the handler's capability flags. Can be null if value is not wanted. |
OpenFile() has been called but CloseFile() has not. False otherwise. Even if the file object is open, the actual disk file might be closed in the host file-system sense; see OpenFile().
|
static |
GetFileModDate() returns the last modification date of all files that are returned by GetAssociatedResources()
Returns the most recent O/S file modification date of all associated files. In the typical case of a single file containing embedded XMP, returned date value is the modification date of the same file. For sidecar and folder based video packages, returned date value is the modification date of that associated file which was updated last.
| filePath | A path exactly as would be passed to OpenFile. |
| modDate | A required pointer to return the last modification date. |
| format | A format hint as would be passed to OpenFile. |
| options | An optional set of option flags. The only defined one is kXMPFiles_ForceGivenHandler, used to shortcut the handler selection logic if the caller is certain of the format. |
|
static |
GetFormatInfo() reports what features are supported for a specific file format.
The file handlers for different file formats vary considerably in what features they support. Support depends on both the general capabilities of the format and the implementation of the handler for that format.
This function is static; make the call directly from the concrete class (SXMPFiles).
| format | The file format whose support flags are desired. |
| handlerFlags | [out] A buffer in which to return a logical OR of option bit flags. The following constants are defined: |
kXMPFiles_CanInjectXMP - Can inject first-time XMP into an existing file. kXMPFiles_CanExpand - Can expand XMP or other metadata in an existing file. kXMPFiles_CanRewrite - Can copy one file to another, writing new metadata (as in SaveAs) kXMPFiles_CanReconcile - Supports reconciliation between XMP and other forms. kXMPFiles_AllowsOnlyXMP - Allows access to just the XMP, ignoring other forms. This is only meaningful if kXMPFiles_CanReconcile is set. kXMPFiles_ReturnsRawPacket - File handler returns raw XMP packet information and string.Even if kXMPFiles_ReturnsRawPacket is set, the returned packet information might have an offset of -1 to indicate an unknown offset. While all file handlers should be able to return the raw packet, some might not know the offset of the packet within the file. This is typical in cases where external libraries are used. These cases might not even allow return of the raw packet.
| XMPFilesRef TXMPFiles< tStringObj >::GetInternalRef | ( | ) |
GetInternalRef() retrieves an internal reference that can be safely passed across DLL boundaries and reconstructed.
Use with the reconstruction constructor to safely pass SXMPFiles references across DLL boundaries where the clients might have used different string types when instantiating TXMPFiles.
TXMPMeta::GetInternalRef() for usage.
|
static |
GetVersionInfo() retrieves version information for the XMPFiles component.
Can be called before Initialize(). This function is static; make the call directly from the concrete class (SXMPFiles).
| versionInfo | [out] A buffer in which to return the version information. |
| bool TXMPFiles< tStringObj >::GetXMP | ( | SXMPMeta * | xmpObj = 0, |
| tStringObj * | xmpPacket = 0, |
||
| XMP_PacketInfo * | packetInfo = 0 |
||
| ) |
GetXMP() retrieves the XMP metadata from an open file.
The function reports whether XMP is present in the file; you can choose to retrieve any or all of the parsed XMP, the raw XMP packet,or information about the raw XMP packet. The options provided when the file was opened determine if reconciliation is done with other forms of metadata.
| xmpObj | [out] An XMP object in which to return the parsed XMP metadata. Can be null. |
| xmpPacket | [out] An string object in which to return the raw XMP packet as stored in the file. Can be null. The encoding of the packet is given in the packetInfo. Returns an empty string if the low level file handler does not provide the raw packet. |
| packetInfo | [out] An string object in which to return the location and form of the raw XMP in the file. XMP_PacketInfo::charForm and XMP_PacketInfo::writeable reflect the raw XMP in the file. The parsed XMP property values are always UTF-8. The writeable flag is taken from the packet trailer; it applies only to "format ignorant" writing. The XMP_PacketInfo structure always reflects the state of the XMP in the file. The offset, length, and character form do not change as a result of calling PutXMP() unless the file is also written. Some file handlers might not return location or contents of the raw packet string. To determine whether one does, check the kXMPFiles_ReturnsRawPacket bit returned by GetFormatInfo(). If the low-level file handler does not provide the raw packet location, XMP_PacketInfo::offset and XMP_PacketInfo::length are both 0, XMP_PacketInfo::charForm is UTF-8, and XMP_PacketInfo::writeable is false. |
|
static |
Initializes the XMPFiles library; must be called before creating an SXMPFiles object.
The main action is to activate the available smart file handlers. Must be called before using any methods except GetVersionInfo().
This function is static; make the call directly from the concrete class (SXMPFiles).
|
static |
Initializes the XMPFiles library; must be called before creating an SXMPFiles object.
This overload of TXMPFiles::Initialize() accepts option bits to customize the initialization actions. At this time no option is defined.
The main action is to activate the available smart file handlers. Must be called before using any methods except GetVersionInfo().
This function is static; make the call directly from the concrete class (SXMPFiles).
| options | Option flags to control the initialization actions. |
|
static |
Initializes the XMPFiles library; must be called before creating an SXMPFiles object.
This overload of TXMPFiles::Initialize() accepts plugin directory and name of the plug-ins as a comma separated list to load the file handler plug-ins. If plugins == NULL, then all plug-ins present in the plug-in directory will be loaded.
The main action is to activate the available smart file handlers. Must be called before using any methods except GetVersionInfo().
This function is static; make the call directly from the concrete class (SXMPFiles).
| pluginFolder | Pugin directorty to load the file handler plug-ins. |
| plugins | Comma sepearted list of plug-ins which should be loaded from the plug-in directory. If plugin == NULL, then all plug-ins availbale in the plug-in directory will be loaded. |
|
static |
Initializes the XMPFiles library; must be called before creating an SXMPFiles object.
This overload of TXMPFiles::Initialize( XMP_OptionBits options ) accepts plugin directory and name of the plug-ins as a comma separated list to load the file handler plug-ins. If plugins == NULL, then all plug-ins present in the plug-in directory will be loaded.
The main action is to activate the available smart file handlers. Must be called before using any methods except GetVersionInfo().
This function is static; make the call directly from the concrete class (SXMPFiles).
| options | Option flags to control the initialization actions. |
| pluginFolder | Pugin directorty to load the file handler plug-ins. |
| plugins | Comma sepearted list of plug-ins which should be loaded from the plug-in directory. If plugin == NULL, then all plug-ins availbale in the plug-in directory will be loaded. |
|
static |
IsMetadataWritable() returns true if metadata can be updated for the given media path.
IsMetadataWritable is provided to check if metadata can be updated or written to the format.In the case of folder-based video formats only if all the metadata files can be written to, true is returned.In other words, false is returned for a partial-write state of metadata files in folder-based media formats.
| filePath | A path exactly as would be passed to OpenFile. |
| writable | A pointer to the result flag. Is true if the metadata can be updated in the format, otherwise false. |
| format | A format hint as would be passed to OpenFile. |
| options | An optional set of option flags. The only defined one is kXMPFiles_ForceGivenHandler, used to shortcut the handler selection logic if the caller is certain of the format. |
| bool TXMPFiles< tStringObj >::OpenFile | ( | XMP_StringPtr | filePath, |
| XMP_FileFormat | format = kXMP_UnknownFile, |
||
| XMP_OptionBits | openFlags = 0 |
||
| ) |
OpenFile() opens a file for metadata access.
Opens a file for the requested forms of metadata access. Opening the file at a minimum causes the raw XMP packet to be read from the file. If the file handler supports legacy metadata reconciliation then legacy metadata is also read, unless kXMPFiles_OpenOnlyXMP is passed.
If the file is opened for read-only access (passing kXMPFiles_OpenForRead), the disk file is closed immediately after reading the data from it; the XMPFiles object, however, remains in the open state. You must call CloseFile() when finished using it. Other methods, such as GetXMP(), can only be used between the OpenFile() and CloseFile() calls. The XMPFiles destructor does not call CloseFile(); if you call it without closing, any pending updates are lost.
If the file is opened for update (passing kXMPFiles_OpenForUpdate), the disk file remains open until CloseFile() is called. The disk file is only updated once, when CloseFile() is called, regardless of how many calls are made to PutXMP().
Typically, the XMP is not parsed and legacy reconciliation is not performed until GetXMP() is called, but this is not guaranteed. Specific file handlers might do earlier parsing of the XMP. Delayed parsing and early disk file close for read-only access are optimizations to help clients implementing file browsers, so that they can access the file briefly and possibly display a thumbnail, then postpone more expensive XMP processing until later.
| filePath | The path for the file, appropriate for the local operating system. Passed as a nul-terminated UTF-8 string. |
| format | The format of the file. If the format is unknown (kXMP_UnknownFile) the format is determined from the file content. The first handler to check is guessed from the file's extension. Passing a specific format value is generally just a hint about what file handler to try first (instead of the one based on the extension). If kXMPFiles_OpenStrictly is set, then any format other than kXMP_UnknownFile requires that the file actually be that format; otherwise an exception is thrown. |
| openFlags | A set of option flags that describe the desired access. By default (zero) the file is opened for read-only access and the format handler decides on the level of reconciliation that will be performed. A logical OR of these bit-flag constants: |
kXMPFiles_OpenForRead - Open for read-only access. kXMPFiles_OpenForUpdate - Open for reading and writing. kXMPFiles_OpenOnlyXMP - Only the XMP is wanted, no reconciliation. kXMPFiles_OpenStrictly - Be strict about locating XMP and reconciling with other forms. By default, a best effort is made to locate the correct XMP and to reconcile XMP with other forms (if reconciliation is done). This option forces stricter rules, resulting in exceptions for errors. The definition of strictness is specific to each handler, there might be no difference. kXMPFiles_OpenUseSmartHandler - Require the use of a smart handler. kXMPFiles_OpenUsePacketScanning - Force packet scanning, do not use a smart handler. kXMPFiles_OptimizeFileLayout - When updating a file, spend the effort necessary to optimize file layout. kXMPFiles_OpenUseSmartHandler but not having an appropriate smart handler. Throws an exception for serious problems. | bool TXMPFiles< tStringObj >::OpenFile | ( | const tStringObj & | filePath, |
| XMP_FileFormat | format = kXMP_UnknownFile, |
||
| XMP_OptionBits | openFlags = 0 |
||
| ) |
OpenFile() opens a file for metadata access, using a string object
Overloads the basic form of the function, allowing you to pass a string object for the file path. It is otherwise identical; see details in the canonical form.
| void TXMPFiles< tStringObj >::operator= | ( | const TXMPFiles< tStringObj > & | rhs | ) |
Assignment operator.
Increments an internal reference count but does not perform a deep copy.
| rhs | The existing TXMPFiles object. |
| void TXMPFiles< tStringObj >::PutXMP | ( | const SXMPMeta & | xmpObj | ) |
PutXMP() updates the XMP metadata in this object without writing out the file.
This function supplies new XMP for the file. However, the disk file is not written until the object is closed with CloseFile(). The options provided when the file was opened determine if reconciliation is done with other forms of metadata.
| xmpObj | The new metadata as an XMP object. |
| void TXMPFiles< tStringObj >::PutXMP | ( | const tStringObj & | xmpPacket | ) |
PutXMP() updates the XMP metadata in this object without writing out the file, using a string object for input.
Overloads the basic form of the function, allowing you to pass the metadata as a string object instead of an XMP object. It is otherwise identical; see details in the canonical form.
| xmpPacket | The new metadata as a string object containing a complete XMP packet. |
| void TXMPFiles< tStringObj >::PutXMP | ( | XMP_StringPtr | xmpPacket, |
| XMP_StringLen | xmpLength = kXMP_UseNullTermination |
||
| ) |
PutXMP() updates the XMP metadata in this object without writing out the file,
using a string object and optional length. Overloads the basic form of the function, allowing you to pass the metadata as a string object instead of an XMP object. It is otherwise identical; see details in the canonical form.
| xmpPacket | The new metadata as a const char * string containing an XMP packet. |
| xmpLength | Optional. The number of bytes in the string. If not supplied, the string is assumed to be nul-terminated. |
| void TXMPFiles< tStringObj >::ResetErrorCallbackLimit | ( | XMP_Uns32 | limit = 1 | ) |
ResetErrorCallbackLimit() resets the error notification limit and counting. It has no effect if an error notification callback function is not registered.
| limit | A limit on the number of notifications to be delivered. |
| void TXMPFiles< tStringObj >::SetAbortProc | ( | XMP_AbortProc | abortProc, |
| void * | abortArg | ||
| ) |
SetAbortProc() registers a callback function used to check for a user-signaled abort.
The specified procedure is called periodically to allow a user to cancel time-consuming operations. The callback function should return true to signal an abort, which results in an exception being thrown.
| abortProc | The callback function. |
| abortArg | A pointer to caller-defined data to pass to the callback function. |
|
staticprivate |
|
staticprivate |
|
static |
SetDefaultErrorCallback() registers a global default error notification callback.
| proc | The client's callback function. |
| context | Client-provided context for the callback. |
| limit | A limit on the number of notifications to be delivered. |
|
static |
SetDefaultProgressCallback() sets a global default for progress tracking. This is used as a default for XMPFiles (library) objects created after the default is set. This does not affect the callback for new SXMPFiles (client) objects with an existing XMPFiles object.
| proc | The client's callback function. Can be zero to disable notifications. |
| context | A pointer used to carry client-private context. |
| interval | The desired number of seconds between notifications. Ideally the first notification is sent after this interval, then at each following multiple of this interval. |
| sendStartStop | A Boolean value indicating if initial and final notifications are wanted in addition to those at the reporting intervals. |
| void TXMPFiles< tStringObj >::SetErrorCallback | ( | XMPFiles_ErrorCallbackProc | proc, |
| void * | context = 0, |
||
| XMP_Uns32 | limit = 1 |
||
| ) |
SetErrorCallback() registers an error notification callback.
| proc | The client's callback function. |
| context | Client-provided context for the callback. |
| limit | A limit on the number of notifications to be delivered. |
| void TXMPFiles< tStringObj >::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) object.
| proc | The client's callback function. Can be zero to disable notifications. |
| context | A pointer used to carry client-private context. |
| interval | The desired number of seconds between notifications. Ideally the first notification is sent after this interval, then at each following multiple of this interval. |
| sendStartStop | A Boolean value indicating if initial and final notifications are wanted in addition to those at the reporting intervals. |
|
static |
Terminates use of the XMPFiles library.
Optional. Deallocates global data structures created by intialization. Its main action is to deallocate heap-allocated global storage, for the benefit of client leak checkers.
This function is static; make the call directly from the concrete class (SXMPFiles).
|
private |
Definition at line 844 of file TXMPFiles.hpp.