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. | |
virtual | ~TXMPFiles () throw () |
Destructor; typical virtual destructor. | |
TXMPFiles (XMP_StringPtr filePath, XMP_FileFormat format=kXMP_UnknownFile, XMP_OptionBits openFlags=0) | |
Alternate constructor associates the new XMPFiles object with a specific file. | |
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. | |
TXMPFiles (const TXMPFiles< tStringObj > &original) | |
Copy constructor. | |
void | operator= (const TXMPFiles< tStringObj > &rhs) |
Assignment operator. | |
TXMPFiles (XMPFilesRef xmpFilesObj) | |
Reconstructs a TXMPFiles object from an internal reference. | |
XMPFilesRef | GetInternalRef () |
GetInternalRef() retrieves an internal reference that can be safely passed across DLL boundaries and reconstructed. | |
Accessing metadata | |
bool | GetXMP (SXMPMeta *xmpObj=0, tStringObj *xmpPacket=0, XMP_PacketInfo *packetInfo=0) |
GetXMP() retrieves the XMP metadata from an open file. | |
void | PutXMP (const SXMPMeta &xmpObj) |
PutXMP() updates the XMP metadata in this object without writing out the file. | |
void | PutXMP (const tStringObj &xmpPacket) |
PutXMP() updates the XMP metadata in this object without writing out the file, using a string object for input. | |
void | 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. | |
bool | CanPutXMP (const SXMPMeta &xmpObj) |
CanPutXMP() reports whether this file can be updated with a specific XMP packet. | |
bool | CanPutXMP (const tStringObj &xmpPacket) |
CanPutXMP() reports whether this file can be updated with a specific XMP packet, passed in a string object. | |
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. | |
Static Public Member Functions | |
Initialization and termination | |
A | |
static void | GetVersionInfo (XMP_VersionInfo *versionInfo) |
GetVersionInfo() retrieves version information for the XMPFiles component. | |
static bool | Initialize () |
Initializes the XMPFiles library; must be called before creating an SXMPFiles object. | |
static bool | Initialize (XMP_OptionBits options) |
Initializes the XMPFiles library; must be called before creating an SXMPFiles object. | |
static void | Terminate () |
Terminates use of the XMPFiles library. | |
File handler information | |
*static bool | GetFormatInfo (XMP_FileFormat format, XMP_OptionBits *handlerFlags=0) |
GetFormatInfo() reports what features are supported for a specific file format. | |
File operations | |
These functions allow you to open, close, and query files. | |
static XMP_FileFormat | CheckFileFormat (XMP_StringPtr filePath) |
CheckFileFormat() tries to determine the format of a file. | |
static XMP_FileFormat | CheckPackageFormat (XMP_StringPtr folderPath) |
CheckPackageFormat() tries to determine the format of a "package" folder. | |
bool | OpenFile (XMP_StringPtr filePath, XMP_FileFormat format=kXMP_UnknownFile, XMP_OptionBits openFlags=0) |
OpenFile() opens a file for metadata access. | |
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 | |
void | CloseFile (XMP_OptionBits closeFlags=0) |
CloseFile() explicitly closes an opened file. | |
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. | |
void | SetAbortProc (XMP_AbortProc abortProc, void *abortArg) |
SetAbortProc() registers a callback function used to check for a user-signaled abort. |
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
.
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 | ( | 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. |
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 | ( | 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. |
static XMP_FileFormat TXMPFiles< tStringObj >::CheckFileFormat | ( | XMP_StringPtr | filePath | ) | [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 XMP_FileFormat TXMPFiles< tStringObj >::CheckPackageFormat | ( | XMP_StringPtr | folderPath | ) | [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. 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 bool TXMPFiles< tStringObj >::GetFormatInfo | ( | XMP_FileFormat | format, | |
XMP_OptionBits * | handlerFlags = 0 | |||
) | [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 void TXMPFiles< tStringObj >::GetVersionInfo | ( | XMP_VersionInfo * | versionInfo | ) | [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 bool TXMPFiles< tStringObj >::Initialize | ( | XMP_OptionBits | options | ) | [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 bool TXMPFiles< tStringObj >::Initialize | ( | ) | [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
).
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.
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_OpenUseSmartHandler
but not having an appropriate smart handler. Throws an exception for serious problems. 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 | ( | 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 >::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 | ( | 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 >::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. |
static void TXMPFiles< tStringObj >::Terminate | ( | ) | [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
).