| XMP Toolkit SDK 6.0.0

Static Private Member Functions | Private Attributes | List of all members
TXMPFiles< tStringObj > Class Template Reference

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 `OpenFile()`.
| 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
These functions allow you to retrieve XMP metadata from open files, so that you can use the `TXMPMeta` API to manipulate it. The `PutXMP()` functions update the XMP packet in memory. Changed XMP is not actually written out to the file until the file is closed.
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 `TXMPFiles` object must be initialized before use and can be terminated when done.
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, `SXMPFiles`, to obtain information about the file handlers for the XMPFiles component.
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
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. 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 `XMP_Error` exception. For the most part exceptions were thrown early and thus API calls aborted as soon as an error was detected. Starting in version 5.5, support has been added for notifications of errors arising in calls to `TXMPFiles` functions. A client can register an error notification callback function for a `TXMPFile` object. This can be done as a global default or individually to each object. The global default applies to all objects created after it is registered. Within the object there is no difference between the global default or explicitly registered callback. The callback function returns a `bool` value indicating if recovery should be attempted (true) or an exception thrown (false). If no callback is registered, a best effort at recovery and continuation will be made with an exception thrown if recovery is not possible. 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 `ResetErrorCallbackLimit`.
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...

## Detailed Description

### template<class tStringObj>
class TXMPFiles< tStringObj >

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 69 of file TXMPFiles.hpp.

## Constructor & Destructor Documentation

## ◆ TXMPFiles() [1/5]

template<class tStringObj >

TXMPFiles< tStringObj >::TXMPFiles | ( |  | ) |

Default constructor initializes an object that is associated with no file.

## ◆ ~TXMPFiles()

template<class tStringObj >

virtual TXMPFiles< tStringObj >::~TXMPFiles | ( |  | ) |
throw | ( |
| ) |  |
| virtual

Destructor; typical virtual destructor.

The destructor does not call `CloseFile()`; pending updates are lost when the destructor is run.

See also
  `OpenFile()`, `CloseFile()`

## ◆ TXMPFiles() [2/5]

template<class tStringObj >

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.

Parameters

  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() [3/5]

template<class tStringObj >

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() [4/5]

template<class tStringObj >

TXMPFiles< tStringObj >::TXMPFiles | ( | const TXMPFiles< tStringObj > & | original | ) |

Copy constructor.

Increments an internal reference count but does not perform a deep copy.

Parameters

  original | The existing `TXMPFiles` object to copy.

## ◆ TXMPFiles() [5/5]

template<class tStringObj >

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.

Parameters

  xmpFilesObj | The underlying reference object, obtained from some other XMP object with `TXMPFiles::GetInternalRef()`.

## Member Function Documentation

## ◆ CanPutXMP() [1/3]

template<class tStringObj >

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;
    }

Parameters

  xmpObj | The proposed new metadata as an XMP object.

## ◆ CanPutXMP() [2/3]

template<class tStringObj >

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.

Parameters

  xmpPacket | The proposed new metadata as a string object containing an XMP packet.

## ◆ CanPutXMP() [3/3]

template<class tStringObj >

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.

Parameters

  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.

## ◆ CheckFileFormat()

template<class tStringObj >

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.

Parameters

  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`.

Returns
  The file's format if a smart handler would be selected by `OpenFile()`, otherwise `kXMP_UnknownFile`.

## ◆ CheckPackageFormat()

template<class tStringObj >

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.

Parameters

  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".

Returns
  The package's format if it can be determined, otherwise `kXMP_UnknownFile`.

## ◆ CloseFile()

template<class tStringObj >

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()`.

Parameters

  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.

## ◆ GetAssociatedResources()

template<class tStringObj >

static bool TXMPFiles< tStringObj >::GetAssociatedResources | ( | XMP_StringPtr | filePath,
|  | std::vector< tStringObj > * | resourceList,
|  | XMP_FileFormat | format = `kXMP_UnknownFile`,
|  | XMP_OptionBits | options = `0`
| ) |  |
| 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.

Parameters

  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.

Returns
  Returns true if the file path is valid to select a smart handler, false for an invalid path or if fallback packet scanning would be selected. Can also return false for unexpected errors that prevent knowledge of the file usage.

## ◆ GetFileInfo()

template<class tStringObj >

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.

Parameters

  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.

Returns
  True if the file object is in the open state; that is, `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()`.

## ◆ GetFileModDate()

template<class tStringObj >

static bool TXMPFiles< tStringObj >::GetFileModDate | ( | XMP_StringPtr | filePath,
|  | XMP_DateTime * | modDate,
|  | XMP_FileFormat * | format = `0`,
|  | XMP_OptionBits | options = `0`
| ) |  |
| 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.

Parameters

  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.

Returns
  Returns true if the file path is valid to select a smart handler, false for an invalid path or if fallback packet scanning would be selected.

## ◆ GetFormatInfo()

template<class tStringObj >

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`).

Parameters

  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.

Returns
  True if the format has explicit "smart" support, false if the format is handled by the default packet scanning plus heuristics. *‍/

## ◆ GetInternalRef()

template<class tStringObj >

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`.

Returns
  The internal reference.

See also
  `TXMPMeta::GetInternalRef()` for usage.

## ◆ GetVersionInfo()

template<class tStringObj >

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`).

Parameters

  versionInfo | [out] A buffer in which to return the version information.

## ◆ GetXMP()

template<class tStringObj >

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.

Parameters

  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.

Returns
  True if the file has XMP, false otherwise.

## ◆ Initialize() [1/4]

template<class tStringObj >

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`).

Returns
  True on success.

## ◆ Initialize() [2/4]

template<class tStringObj >

static bool TXMPFiles< tStringObj >::Initialize | ( | const char * | pluginFolder,
|  | const char * | plugins = `NULL`
| ) |  |
| 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`).

Parameters

  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.

Returns
  True on success.

## ◆ Initialize() [3/4]

template<class tStringObj >

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`).

Parameters

  options | Option flags to control the initialization actions.

Returns
  True on success.

## ◆ Initialize() [4/4]

template<class tStringObj >

static bool TXMPFiles< tStringObj >::Initialize | ( | XMP_OptionBits | options,
|  | const char * | pluginFolder,
|  | const char * | plugins = `NULL`
| ) |  |
| 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`).

Parameters

  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.

Returns
  True on success.

## ◆ IsMetadataWritable()

template<class tStringObj >

static bool TXMPFiles< tStringObj >::IsMetadataWritable | ( | XMP_StringPtr | filePath,
|  | bool * | writable,
|  | XMP_FileFormat | format = `kXMP_UnknownFile`,
|  | XMP_OptionBits | options = `0`
| ) |  |
| 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.

Parameters

  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.

Returns
  Returns true if the file path is valid to select a smart handler, false for an invalid path or if fallback packet scanning would be selected.

## ◆ OpenFile() [1/2]

template<class tStringObj >

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.

## ◆ OpenFile() [2/2]

template<class tStringObj >

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.

Parameters

  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.
  Returns
    True if the file is succesfully opened and attached to a file handler. False for anticipated problems, such as passing `kXMPFiles_OpenUseSmartHandler` but not having an appropriate smart handler. Throws an exception for serious problems.

## ◆ operator=()

template<class tStringObj >

void TXMPFiles< tStringObj >::operator= | ( | const TXMPFiles< tStringObj > & | rhs | ) |

Assignment operator.

Increments an internal reference count but does not perform a deep copy.

Parameters

  rhs | The existing `TXMPFiles` object.

## ◆ PutXMP() [1/3]

template<class tStringObj >

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.

Parameters

  xmpObj | The new metadata as an XMP object.

## ◆ PutXMP() [2/3]

template<class tStringObj >

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.

Parameters

  xmpPacket | The new metadata as a string object containing a complete XMP packet.

## ◆ PutXMP() [3/3]

template<class tStringObj >

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.

Parameters

  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.

## ◆ ResetErrorCallbackLimit()

template<class tStringObj >

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.

Parameters

  limit | A limit on the number of notifications to be delivered.

## ◆ SetAbortProc()

template<class tStringObj >

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.

Parameters

  abortProc | The callback function.
  abortArg | A pointer to caller-defined data to pass to the callback function.

## ◆ SetClientString()

template<class tStringObj >

static void TXMPFiles< tStringObj >::SetClientString | ( | void * | clientPtr,
|  | XMP_StringPtr | valuePtr,
|  | XMP_StringLen | valueLen
| ) |  |
| static private

## ◆ SetClientStringVector()

template<class tStringObj >

static void TXMPFiles< tStringObj >::SetClientStringVector | ( | void * | clientPtr,
|  | XMP_StringPtr * | arrayPtr,
|  | XMP_Uns32 | stringCount
| ) |  |
| static private

## ◆ SetDefaultErrorCallback()

template<class tStringObj >

static void TXMPFiles< tStringObj >::SetDefaultErrorCallback | ( | XMPFiles_ErrorCallbackProc | proc,
|  | void * | context = `0`,
|  | XMP_Uns32 | limit = `1`
| ) |  |
| static

SetDefaultErrorCallback() registers a global default error notification callback.

Parameters

  proc | The client's callback function.
  context | Client-provided context for the callback.
  limit | A limit on the number of notifications to be delivered.

## ◆ SetDefaultProgressCallback()

template<class tStringObj >

static void TXMPFiles< tStringObj >::SetDefaultProgressCallback | ( | XMP_ProgressReportProc | proc,
|  | void * | context = `0`,
|  | float | interval = `1.0`,
|  | bool | sendStartStop = `false`
| ) |  |
| 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.

Parameters

  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.

## ◆ SetErrorCallback()

template<class tStringObj >

void TXMPFiles< tStringObj >::SetErrorCallback | ( | XMPFiles_ErrorCallbackProc | proc,
|  | void * | context = `0`,
|  | XMP_Uns32 | limit = `1`
| ) |  |

SetErrorCallback() registers an error notification callback.

Parameters

  proc | The client's callback function.
  context | Client-provided context for the callback.
  limit | A limit on the number of notifications to be delivered.

## ◆ SetProgressCallback()

template<class tStringObj >

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.

Parameters

  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.

## ◆ Terminate()

template<class tStringObj >

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`).

## Member Data Documentation

## ◆ xmpFilesRef

template<class tStringObj >

XMPFilesRef TXMPFiles< tStringObj >::xmpFilesRef
| private

Definition at line 844 of file TXMPFiles.hpp.

The documentation for this class was generated from the following file:

- public/include/TXMPFiles.hpp