| XMP Toolkit SDK 6.0.0

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

API for access to the XMP Toolkit core services. More...

`#include <TXMPMeta.hpp>`

## Public Member Functions
Constructors and destructor
| TXMPMeta ()
| Default constructor, creates an empty object. More...
| TXMPMeta (const TXMPMeta< tStringObj > &original)
| Copy constructor, creates a client object refering to the same internal object. More...
void | operator= (const TXMPMeta< tStringObj > &rhs)
| Assignment operator, assigns the internal reference and increments the reference count. More...
| TXMPMeta (XMPMetaRef xmpRef)
| Reconstructs an XMP object from an internal reference. More...
| TXMPMeta (XMP_StringPtr buffer, XMP_StringLen xmpSize)
| Constructs an object and parse one buffer of RDF into it. More...
virtual | ~TXMPMeta () throw ()
| Destructor, typical virtual destructor. *‍/. More...
Accessing property values
The property value accessors all take a property specification; the top level namespace URI (the "schema" namespace) and the basic name of the property being referenced. See the introductory discussion of path expression usage for more information.
bool | GetProperty (XMP_StringPtr schemaNS, XMP_StringPtr propName, tStringObj *propValue, XMP_OptionBits *options) const
| `GetProperty()` reports whether a property exists, and retrieves its value. More...
bool | GetArrayItem (XMP_StringPtr schemaNS, XMP_StringPtr arrayName, XMP_Index itemIndex, tStringObj *itemValue, XMP_OptionBits *options) const
| `GetArrayItem()` provides access to items within an array. More...
bool | GetStructField (XMP_StringPtr schemaNS, XMP_StringPtr structName, XMP_StringPtr fieldNS, XMP_StringPtr fieldName, tStringObj *fieldValue, XMP_OptionBits *options) const
| `GetStructField()` provides access to fields within a nested structure. More...
bool | GetQualifier (XMP_StringPtr schemaNS, XMP_StringPtr propName, XMP_StringPtr qualNS, XMP_StringPtr qualName, tStringObj *qualValue, XMP_OptionBits *options) const
| `GetQualifier()` provides access to a qualifier attached to a property. More...
Creating properties and setting their values
void | SetProperty (XMP_StringPtr schemaNS, XMP_StringPtr propName, XMP_StringPtr propValue, XMP_OptionBits options=0)
| be a simple property with an `xml:lang` attribute. More...
void | SetProperty (XMP_StringPtr schemaNS, XMP_StringPtr propName, const tStringObj &propValue, XMP_OptionBits options=0)
| `SetProperty()` creates or sets a property value using a string object. More...
void | SetArrayItem (XMP_StringPtr schemaNS, XMP_StringPtr arrayName, XMP_Index itemIndex, XMP_StringPtr itemValue, XMP_OptionBits options=0)
| `SetArrayItem()` creates or sets the value of an item within an array. More...
void | SetArrayItem (XMP_StringPtr schemaNS, XMP_StringPtr arrayName, XMP_Index itemIndex, const tStringObj &itemValue, XMP_OptionBits options=0)
| `SetArrayItem()` creates or sets the value of an item within an array using a string object. More...
void | AppendArrayItem (XMP_StringPtr schemaNS, XMP_StringPtr arrayName, XMP_OptionBits arrayOptions, XMP_StringPtr itemValue, XMP_OptionBits itemOptions=0)
| `AppendArrayItem()` adds an item to an array, creating the array if necessary. More...
void | AppendArrayItem (XMP_StringPtr schemaNS, XMP_StringPtr arrayName, XMP_OptionBits arrayOptions, const tStringObj &itemValue, XMP_OptionBits itemOptions=0)
| `AppendArrayItem()` adds an item to an array using a string object value, creating the array if necessary. More...
void | SetStructField (XMP_StringPtr schemaNS, XMP_StringPtr structName, XMP_StringPtr fieldNS, XMP_StringPtr fieldName, XMP_StringPtr fieldValue, XMP_OptionBits options=0)
| `SetStructField()` creates or sets the value of a field within a nested structure. More...
void | SetStructField (XMP_StringPtr schemaNS, XMP_StringPtr structName, XMP_StringPtr fieldNS, XMP_StringPtr fieldName, const tStringObj &fieldValue, XMP_OptionBits options=0)
| `SetStructField()` creates or sets the value of a field within a nested structure, using a string object. More...
void | SetQualifier (XMP_StringPtr schemaNS, XMP_StringPtr propName, XMP_StringPtr qualNS, XMP_StringPtr qualName, XMP_StringPtr qualValue, XMP_OptionBits options=0)
| `SetQualifier()` creates or sets a qualifier attached to a property. More...
void | SetQualifier (XMP_StringPtr schemaNS, XMP_StringPtr propName, XMP_StringPtr qualNS, XMP_StringPtr qualName, const tStringObj &qualValue, XMP_OptionBits options=0)
| `SetQualifier()` creates or sets a qualifier attached to a property using a string object. More...
Detecting and deleting properties.
The namespace URI and prefix usage for property specifiers in these functions is the same as for `TXMPMeta::GetProperty()`.
void | DeleteProperty (XMP_StringPtr schemaNS, XMP_StringPtr propName)
| `DeleteProperty()` deletes an XMP subtree rooted at a given property. More...
void | DeleteArrayItem (XMP_StringPtr schemaNS, XMP_StringPtr arrayName, XMP_Index itemIndex)
| `DeleteArrayItem()` deletes an XMP subtree rooted at a given array item. More...
void | DeleteStructField (XMP_StringPtr schemaNS, XMP_StringPtr structName, XMP_StringPtr fieldNS, XMP_StringPtr fieldName)
| `DeleteStructField()` deletes an XMP subtree rooted at a given struct field. More...
void | DeleteQualifier (XMP_StringPtr schemaNS, XMP_StringPtr propName, XMP_StringPtr qualNS, XMP_StringPtr qualName)
| `DeleteQualifier()` deletes an XMP subtree rooted at a given qualifier. More...
bool | DoesPropertyExist (XMP_StringPtr schemaNS, XMP_StringPtr propName) const
| `DoesPropertyExist()` reports whether a property currently exists. More...
bool | DoesArrayItemExist (XMP_StringPtr schemaNS, XMP_StringPtr arrayName, XMP_Index itemIndex) const
| `DoesArrayItemExist()` reports whether an array item currently exists. More...
bool | DoesStructFieldExist (XMP_StringPtr schemaNS, XMP_StringPtr structName, XMP_StringPtr fieldNS, XMP_StringPtr fieldName) const
| `DoesStructFieldExist()` reports whether a struct field currently exists. More...
bool | DoesQualifierExist (XMP_StringPtr schemaNS, XMP_StringPtr propName, XMP_StringPtr qualNS, XMP_StringPtr qualName) const
| `DoesQualifierExist()` reports whether a qualifier currently exists. More...
Accessing properties as binary values.
bool | GetProperty_Bool (XMP_StringPtr schemaNS, XMP_StringPtr propName, bool *propValue, XMP_OptionBits *options) const
| `GetProperty_Bool()` retrieves the value of a Boolean property as a C++ bool. More...
bool | GetProperty_Int (XMP_StringPtr schemaNS, XMP_StringPtr propName, XMP_Int32 *propValue, XMP_OptionBits *options) const
| `GetProperty_Int()` retrieves the value of an integer property as a C long integer. More...
bool | GetProperty_Int64 (XMP_StringPtr schemaNS, XMP_StringPtr propName, XMP_Int64 *propValue, XMP_OptionBits *options) const
| `GetProperty_Int64()` retrieves the value of an integer property as a C long long integer. More...
bool | GetProperty_Float (XMP_StringPtr schemaNS, XMP_StringPtr propName, double *propValue, XMP_OptionBits *options) const
| `GetProperty_Float()` retrieves the value of a floating-point property as a C double float. More...
bool | GetProperty_Date (XMP_StringPtr schemaNS, XMP_StringPtr propName, XMP_DateTime *propValue, XMP_OptionBits *options) const
| `GetProperty_Date()` retrieves the value of a date-time property as an `XMP_DateTime` structure. More...
void | SetProperty_Bool (XMP_StringPtr schemaNS, XMP_StringPtr propName, bool propValue, XMP_OptionBits options=0)
| `SetProperty_Bool()` sets the value of a Boolean property using a C++ bool. More...
void | SetProperty_Int (XMP_StringPtr schemaNS, XMP_StringPtr propName, XMP_Int32 propValue, XMP_OptionBits options=0)
| `SetProperty_Int()` sets the value of an integer property using a C long integer. More...
void | SetProperty_Int64 (XMP_StringPtr schemaNS, XMP_StringPtr propName, XMP_Int64 propValue, XMP_OptionBits options=0)
| `SetProperty_Int64()` sets the value of an integer property using a C long long integer. More...
void | SetProperty_Float (XMP_StringPtr schemaNS, XMP_StringPtr propName, double propValue, XMP_OptionBits options=0)
| `SetProperty_Float()` sets the value of a floating-point property using a C double float. More...
void | SetProperty_Date (XMP_StringPtr schemaNS, XMP_StringPtr propName, const XMP_DateTime &propValue, XMP_OptionBits options=0)
| `SetProperty_Date()` sets the value of a date/time property using an `XMP_DateTime` structure. More...
Accessing localized text (alt-text) properties.
bool | GetLocalizedText (XMP_StringPtr schemaNS, XMP_StringPtr altTextName, XMP_StringPtr genericLang, XMP_StringPtr specificLang, tStringObj *actualLang, tStringObj *itemValue, XMP_OptionBits *options) const
| `GetLocalizedText()` retrieves information about a selected item in an alt-text array. More...
void | SetLocalizedText (XMP_StringPtr schemaNS, XMP_StringPtr altTextName, XMP_StringPtr genericLang, XMP_StringPtr specificLang, XMP_StringPtr itemValue, XMP_OptionBits options=0)
| `SetLocalizedText()` modifies the value of a selected item in an alt-text array. More...
void | SetLocalizedText (XMP_StringPtr schemaNS, XMP_StringPtr altTextName, XMP_StringPtr genericLang, XMP_StringPtr specificLang, const tStringObj &itemValue, XMP_OptionBits options=0)
| `SetLocalizedText()` modifies the value of a selected item in an alt-text array using a string object. More...
void | DeleteLocalizedText (XMP_StringPtr schemaNS, XMP_StringPtr altTextName, XMP_StringPtr genericLang, XMP_StringPtr specificLang)
| `DeleteLocalizedText()` deletes specific language alternatives from an alt-text array. More...
Creating and reading serialized RDF.
void | ParseFromBuffer (XMP_StringPtr buffer, XMP_StringLen bufferSize, XMP_OptionBits options=0)
| `ParseFromBuffer()` parses RDF from a series of input buffers into this XMP object. More...
void | SerializeToBuffer (tStringObj *rdfString, XMP_OptionBits options, XMP_StringLen padding, XMP_StringPtr newline, XMP_StringPtr indent="", XMP_Index baseIndent=0) const
| `SerializeToBuffer()` serializes metadata in this XMP object into a string as RDF. More...
void | SerializeToBuffer (tStringObj *rdfString, XMP_OptionBits options=0, XMP_StringLen padding=0) const
| `SerializeToBuffer()` serializes metadata in this XMP object into a string as RDF. More...
Helper functions.
XMPMetaRef | GetInternalRef () const
| Retrieves an internal reference that can be safely passed across DLL boundaries and reconstructed. More...
void | GetObjectName (tStringObj *name) const
| `GetObjectName()` retrieves the client-assigned name of this XMP object. More...
void | SetObjectName (XMP_StringPtr name)
| `SetObjectName()` assigns a name to this XMP object. More...
void | SetObjectName (tStringObj name)
| `SetObjectName()` assigns a name to this XMP object. More...
void | Sort ()
| `Sort()` sorts the data model tree of an XMP object. More...
void | Erase ()
| `Erase()` restores the object to a "just constructed" state. More...
TXMPMeta | Clone (XMP_OptionBits options=0) const
| `Clone()` creates a deep copy of an XMP object. More...
XMP_Index | CountArrayItems (XMP_StringPtr schemaNS, XMP_StringPtr arrayName) const
| `CountArrayItems()` reports the number of items currently defined in an array. More...
XMP_Status | DumpObject (XMP_TextOutputProc outProc, void *clientData) const
| `DumpObject()` outputs the content of an XMP object to a callback handler for debugging. More...
XMP_OptionBits | GetObjectOptions () const
| Not implemented. More...
void | SetObjectOptions (XMP_OptionBits options)
| Not implemented. More...

## Static Public Member Functions
Initialization and termination
static void | GetVersionInfo (XMP_VersionInfo *info)
| `GetVersionInfo()` retrieves runtime version information. More...
static bool | Initialize ()
| `Initialize()` explicitly initializes the XMP Toolkit before use. *‍/ More...
static void | Terminate ()
| `Terminate()` explicitly terminates usage of the XMP Toolkit. More...
Global option flags
Global option flags affect the overall behavior of the XMP Toolkit. The available options will be declared in `XMP_Const.h`. There are none in this version of the Toolkit.
static XMP_OptionBits | GetGlobalOptions ()
| `GetGlobalOptions()` retrieves the set of global option flags. There are none in this version of the Toolkit. More...
static void | SetGlobalOptions (XMP_OptionBits options)
| `SetGlobalOptions()` updates the set of global option flags. There are none in this version of the Toolkit. More...
Internal data structure dump utilities
These are debugging utilities that dump internal data structures, to be handled by client-defined callback described in `XMP_Const.h`.
static XMP_Status | DumpNamespaces (XMP_TextOutputProc outProc, void *clientData)
| `DumpNamespaces()` sends the list of registered namespace URIs and prefixes to a handler. More...
Namespace Functions
Namespaces must be registered before use in namespace URI parameters or path expressions. Within the XMP Toolkit the registered namespace URIs and prefixes must be unique. Additional namespaces encountered when parsing RDF are automatically registered. The namespace URI should always end in an XML name separator such as '/' or '#'. This is because some forms of RDF shorthand catenate a namespace URI with an element name to form a new URI.
static bool | RegisterNamespace (XMP_StringPtr namespaceURI, XMP_StringPtr suggestedPrefix, tStringObj *registeredPrefix)
| `RegisterNamespace()` registers a namespace URI with a suggested prefix. More...
static bool | GetNamespacePrefix (XMP_StringPtr namespaceURI, tStringObj *namespacePrefix)
| `GetNamespacePrefix()` obtains the prefix for a registered namespace URI, and reports whether the URI is registered. More...
static bool | GetNamespaceURI (XMP_StringPtr namespacePrefix, tStringObj *namespaceURI)
| `GetNamespaceURI()` obtains the URI for a registered namespace prefix, and reports whether the prefix is registered. More...
static void | DeleteNamespace (XMP_StringPtr namespaceURI)
| Not implemented. More...

## Public Attributes
XMPMetaRef | xmpRef

## Static Private Member Functions
static void | SetClientString (void *clientPtr, XMP_StringPtr valuePtr, XMP_StringLen valueLen)

## Error notifications
static void | SetDefaultErrorCallback (XMPMeta_ErrorCallbackProc proc, void *context=0, XMP_Uns32 limit=1)
| SetDefaultErrorCallback() registers a global default error notification callback. More...
void | SetErrorCallback (XMPMeta_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 TXMPMeta< tStringObj >

API for access to the XMP Toolkit core services.

`TXMPMeta` is the template class providing the core services of the XMP Toolkit. It should 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, `SXMPMeta`.

You can create `TXMPMeta` objects (also called XMP objects) from metadata that you construct, or that you obtain from files using the XMP Toolkit's XMPFiles component; see `TXMPFiles.hpp`.

Definition at line 57 of file TXMPMeta.hpp.

## Constructor & Destructor Documentation

## ◆ TXMPMeta() [1/4]

template<class tStringObj >

TXMPMeta< tStringObj >::TXMPMeta | ( |  | ) |

Default constructor, creates an empty object.

The default constructor creates a new empty `TXMPMeta` object.

## ◆ TXMPMeta() [2/4]

template<class tStringObj >

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

Copy constructor, creates a client object refering to the same internal object.

The copy constructor creates a new `TXMPMeta` object that refers to the same internal XMP object. as an existing `TXMPMeta` object.

Parameters

  original | The object to copy. new object is returned via Original only.

## ◆ TXMPMeta() [3/4]

template<class tStringObj >

TXMPMeta< tStringObj >::TXMPMeta | ( | XMPMetaRef | xmpRef | ) |

Reconstructs an XMP object from an internal reference.

This constructor creates a new `TXMPMeta` object that refers to the underlying reference object of an existing `TXMPMeta` object. Use to safely pass XMP objects across DLL boundaries.

Parameters

  xmpRef | The underlying reference object, obtained from some other XMP object with `TXMPMeta::GetInternalRef()`.returns The new object.

## ◆ TXMPMeta() [4/4]

template<class tStringObj >

TXMPMeta< tStringObj >::TXMPMeta | ( | XMP_StringPtr | buffer,
|  | XMP_StringLen | xmpSize
| ) |  |

Constructs an object and parse one buffer of RDF into it.

This constructor creates a new `TXMPMeta` object and populates it with metadata from a buffer containing serialized RDF. This buffer must be a complete RDF parse stream.

The result of passing serialized data to this function is identical to creating an empty object then calling `TXMPMeta::ParseFromBuffer()`. To use the constructor, however, the RDF must be complete. If you need to parse data from multiple buffers, create an empty object and use `TXMPMeta::ParseFromBuffer()`.

Parameters

  buffer | A pointer to the buffer of RDF to be parsed. Can be null if the length is 0; in this case, the function creates an empty object.
  xmpSize | The length in bytes of the buffer.

## ◆ ~TXMPMeta()

template<class tStringObj >

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

Destructor, typical virtual destructor. *‍/.

## Member Function Documentation

## ◆ AppendArrayItem() [1/2]

template<class tStringObj >

void TXMPMeta< tStringObj >::AppendArrayItem | ( | XMP_StringPtr | schemaNS,
|  | XMP_StringPtr | arrayName,
|  | XMP_OptionBits | arrayOptions,
|  | const tStringObj & | itemValue,
|  | XMP_OptionBits | itemOptions = `0`
| ) |  |

`AppendArrayItem()` adds an item to an array using a string object value, creating the array if necessary.

Overloads the basic form of the function, allowing you to pass a string object in which to return the item value. It is otherwise identical; see details in the canonical form.

## ◆ AppendArrayItem() [2/2]

template<class tStringObj >

void TXMPMeta< tStringObj >::AppendArrayItem | ( | XMP_StringPtr | schemaNS,
|  | XMP_StringPtr | arrayName,
|  | XMP_OptionBits | arrayOptions,
|  | XMP_StringPtr | itemValue,
|  | XMP_OptionBits | itemOptions = `0`
| ) |  |

`AppendArrayItem()` adds an item to an array, creating the array if necessary.

This function simplifies construction of an array by not requiring that you pre-create an empty array. The array that is assigned is created automatically if it does not yet exist. If the array exists, it must have the form specified by the options. Each call appends a new item to the array.

Use `TXMPUtils::ComposeArrayItemPath()` to create a complex path.

Parameters

  schemaNS | The namespace URI; see `GetProperty()`.
  arrayName | The name of the array. Can be a general path expression, must not be null or the empty string; see `GetProperty()` for namespace prefix usage.
  arrayOptions | Option flags describing the array type to create; a logical OR of allowed bit-flag constants, `kXMP_PropArrayIsOrdered`, `kXMP_PropArrayIsAlternate`, or `kXMP_PropArrayIsAltText`. If the array exists, must match the existing array type or be null (0 or `kXMP_NoOptions`).
  itemValue | The new item value, a null-terminated UTF-8 string, if the array item has a value.
  itemOptions | Option flags describing the item type to create; one of the bit-flag constants `kXMP_PropValueIsArray` or `kXMP_PropValueIsStruct` to create a complex array item.

## ◆ Clone()

template<class tStringObj >

TXMPMeta TXMPMeta< tStringObj >::Clone | ( | XMP_OptionBits | options = `0` | ) | const

`Clone()` creates a deep copy of an XMP object.

Use this function to copy an entire XMP metadata tree. Assignment and copy constructors only increment a reference count, they do not do a deep copy. This function returns an object, not a pointer. The following shows correct usage:

    SXMPMeta * clone1 = new SXMPMeta ( sourceXMP.Clone() );  // This works.
    SXMPMeta   clone2 ( sourceXMP.Clone );          // This works also. (Not a pointer.)

The `clone2` example does not use an explicit pointer. This is good for local usage, protecting against memory leaks.

This is an example of incorrect usage:

    SXMPMeta * clone3 = &sourceXMP.Clone();         // ! This does not work!

The assignment to `clone3` creates a temporary object, initializes it with the clone, assigns the address of the temporary to `clone3`, then deletes the temporary.

Parameters

  options | Option flags, not currently defined..

Returns
  An XMP object cloned from the original.

## ◆ CountArrayItems()

template<class tStringObj >

XMP_Index TXMPMeta< tStringObj >::CountArrayItems | ( | XMP_StringPtr | schemaNS,
|  | XMP_StringPtr | arrayName
| ) |  | const

`CountArrayItems()` reports the number of items currently defined in an array.

Parameters

  schemaNS | The namespace URI; see `GetProperty()`.
  arrayName | The name of the array. Can be a general path expression, must not be null or the empty string; see `GetProperty()` for namespace prefix usage.

Returns
  The number of items.

## ◆ DeleteArrayItem()

template<class tStringObj >

void TXMPMeta< tStringObj >::DeleteArrayItem | ( | XMP_StringPtr | schemaNS,
|  | XMP_StringPtr | arrayName,
|  | XMP_Index | itemIndex
| ) |  |

`DeleteArrayItem()` deletes an XMP subtree rooted at a given array item.

It is not an error if the array item does not exist. Use `TXMPUtils::ComposeArrayItemPath()` to create a complex path.

Parameters

  schemaNS | The namespace URI for the array; see `GetProperty()`.
  arrayName | The name of the array. Can be a general path expression, must not be null or the empty string; see `GetProperty()` for namespace prefix usage.
  itemIndex | The 1-based index of the desired item. Use the macro `kXMP_ArrayLastItem` to specify the last existing array item.

## ◆ DeleteLocalizedText()

template<class tStringObj >

void TXMPMeta< tStringObj >::DeleteLocalizedText | ( | XMP_StringPtr | schemaNS,
|  | XMP_StringPtr | altTextName,
|  | XMP_StringPtr | genericLang,
|  | XMP_StringPtr | specificLang
| ) |  |

`DeleteLocalizedText()` deletes specific language alternatives from an alt-text array.

    The rules for finding the language value to delete are similar to those for \c #SetLocalizedText().

Parameters

  schemaNS | The namespace URI for the alt-text array; see `GetProperty()`.
  altTextName | The name of the alt-text array. Can be a general path expression, must not be null or the empty string; see `GetProperty()` for namespace prefix usage.
  genericLang | The name of the generic language as an RFC 3066 primary subtag. Can be null or the empty string if no generic language is wanted.
  specificLang | The name of the specific language as an RFC 3066 tag, or "x-default". Must not be null or the empty string.

## ◆ DeleteNamespace()

template<class tStringObj >

static void TXMPMeta< tStringObj >::DeleteNamespace | ( | XMP_StringPtr | namespaceURI | ) |
| static

Not implemented.

Deletes a namespace from the registry. Does nothing if the URI is not registered, or if the parameter is null or the empty string.

This function is static; make the call directly from the concrete class (`SXMPMeta`).

Parameters

  namespaceURI | The URI for the namespace.

## ◆ DeleteProperty()

template<class tStringObj >

void TXMPMeta< tStringObj >::DeleteProperty | ( | XMP_StringPtr | schemaNS,
|  | XMP_StringPtr | propName
| ) |  |

`DeleteProperty()` deletes an XMP subtree rooted at a given property.

It is not an error if the property does not exist.

Parameters

  schemaNS | The namespace URI for the property; see `GetProperty()`.
  propName | The name of the property; see `GetProperty()`.

## ◆ DeleteQualifier()

template<class tStringObj >

void TXMPMeta< tStringObj >::DeleteQualifier | ( | XMP_StringPtr | schemaNS,
|  | XMP_StringPtr | propName,
|  | XMP_StringPtr | qualNS,
|  | XMP_StringPtr | qualName
| ) |  |

`DeleteQualifier()` deletes an XMP subtree rooted at a given qualifier.

It is not an error if the qualifier does not exist.

Parameters

  schemaNS | The namespace URI; see `GetProperty()`.
  propName | The name of the property to which the qualifier is attached. Can be a general path expression, must not be null or the empty string; see `GetProperty()` for namespace prefix usage.
  qualNS | The namespace URI for the qualifier. Same namespace and prefix usage as `GetProperty()`.
  qualName | The name of the qualifier. Must be a single XML name, must not be null or the empty string. Same namespace and prefix usage as `GetProperty()`.

## ◆ DeleteStructField()

template<class tStringObj >

void TXMPMeta< tStringObj >::DeleteStructField | ( | XMP_StringPtr | schemaNS,
|  | XMP_StringPtr | structName,
|  | XMP_StringPtr | fieldNS,
|  | XMP_StringPtr | fieldName
| ) |  |

`DeleteStructField()` deletes an XMP subtree rooted at a given struct field.

It is not an error if the field does not exist.

Parameters

  schemaNS | The namespace URI for the struct; see `GetProperty()`.
  structName | The name of the struct. Can be a general path expression, must not be null or the empty string; see `GetProperty()` for namespace prefix usage.
  fieldNS | The namespace URI for the field. Same namespace and prefix usage as `GetProperty()`.
  fieldName | The name of the field. Must be a single XML name, must not be null or the empty string. Same namespace and prefix usage as `GetProperty()`.

## ◆ DoesArrayItemExist()

template<class tStringObj >

bool TXMPMeta< tStringObj >::DoesArrayItemExist | ( | XMP_StringPtr | schemaNS,
|  | XMP_StringPtr | arrayName,
|  | XMP_Index | itemIndex
| ) |  | const

`DoesArrayItemExist()` reports whether an array item currently exists.

Use `TXMPUtils::ComposeArrayItemPath()` to create a complex path.

Parameters

  schemaNS | The namespace URI; see `GetProperty()`.
  arrayName | The name of the array. Can be a general path expression, must not be null or the empty string; see `GetProperty()` for namespace prefix usage.
  itemIndex | The 1-based index of the desired item. Use the macro `kXMP_ArrayLastItem` to specify the last existing array item.

Returns
  True if the array item exists.

## ◆ DoesPropertyExist()

template<class tStringObj >

bool TXMPMeta< tStringObj >::DoesPropertyExist | ( | XMP_StringPtr | schemaNS,
|  | XMP_StringPtr | propName
| ) |  | const

`DoesPropertyExist()` reports whether a property currently exists.

Parameters

  schemaNS | The namespace URI for the property; see `GetProperty()`.
  propName | The name of the property; see `GetProperty()`.

Returns
  True if the property exists.

## ◆ DoesQualifierExist()

template<class tStringObj >

bool TXMPMeta< tStringObj >::DoesQualifierExist | ( | XMP_StringPtr | schemaNS,
|  | XMP_StringPtr | propName,
|  | XMP_StringPtr | qualNS,
|  | XMP_StringPtr | qualName
| ) |  | const

`DoesQualifierExist()` reports whether a qualifier currently exists.

Parameters

  schemaNS | The namespace URI; see `GetProperty()`.
  propName | The name of the property to which the qualifier is attached. Can be a general path expression, must not be null or the empty string; see `GetProperty()` for namespace prefix usage.
  qualNS | The namespace URI for the qualifier. Same namespace and prefix usage as `GetProperty()`.
  qualName | The name of the qualifier. Must be a single XML name, must not be null or the empty string. Same namespace and prefix usage as `GetProperty()`.

Returns
  True if the qualifier exists.

## ◆ DoesStructFieldExist()

template<class tStringObj >

bool TXMPMeta< tStringObj >::DoesStructFieldExist | ( | XMP_StringPtr | schemaNS,
|  | XMP_StringPtr | structName,
|  | XMP_StringPtr | fieldNS,
|  | XMP_StringPtr | fieldName
| ) |  | const

`DoesStructFieldExist()` reports whether a struct field currently exists.

Use `TXMPUtils::ComposeStructFieldPath()` to create a complex path.

Parameters

  schemaNS | The namespace URI; see `GetProperty()`.
  structName | The name of the struct. Can be a general path expression, must not be null or the empty string; see `GetProperty()` for namespace prefix usage.
  fieldNS | The namespace URI for the field. Same namespace and prefix usage as `GetProperty()`.
  fieldName | The name of the field. Must be a single XML name, must not be null or the empty string. Same namespace and prefix usage as `GetProperty()`.

Returns
  True if the field exists.

## ◆ DumpNamespaces()

template<class tStringObj >

static XMP_Status TXMPMeta< tStringObj >::DumpNamespaces | ( | XMP_TextOutputProc | outProc,
|  | void * | clientData
| ) |  |
| static

`DumpNamespaces()` sends the list of registered namespace URIs and prefixes to a handler.

See also
  Member function `TXMPMeta::DumpObject()` For debugging. Invokes a client-defined callback for each line of output.

This function is static; make the call directly from the concrete class (`SXMPMeta`).

Parameters

  outProc | The client-defined procedure to handle each line of output.
  clientData | A pointer to client-defined data to pass to the handler.

Returns
  A success-fail status value, returned from the handler. Zero is success, failure values are client-defined.

## ◆ DumpObject()

template<class tStringObj >

XMP_Status TXMPMeta< tStringObj >::DumpObject | ( | XMP_TextOutputProc | outProc,
|  | void * | clientData
| ) |  | const

`DumpObject()` outputs the content of an XMP object to a callback handler for debugging.

Invokes a client-defined callback for each line of output.

Parameters

  outProc | The client-defined procedure to handle each line of output.
  clientData | A pointer to client-defined data to pass to the handler.

Returns
  A success-fail status value, returned from the handler. Zero is success, failure values are client-defined.

See also
  Static function `DumpNamespaces()`

## ◆ Erase()

template<class tStringObj >

void TXMPMeta< tStringObj >::Erase | ( |  | ) |

`Erase()` restores the object to a "just constructed" state.

## ◆ GetArrayItem()

template<class tStringObj >

bool TXMPMeta< tStringObj >::GetArrayItem | ( | XMP_StringPtr | schemaNS,
|  | XMP_StringPtr | arrayName,
|  | XMP_Index | itemIndex,
|  | tStringObj * | itemValue,
|  | XMP_OptionBits * | options
| ) |  | const

`GetArrayItem()` provides access to items within an array.

Reports whether the item exists; if it does, and if it has a value, the function retrieves the value. Items are accessed by an integer index, where the first item has index 1.

Parameters

  schemaNS | The namespace URI for the array; see `GetProperty()`.
  arrayName | The name of the array. Can be a general path expression, must not be null or the empty string; see `GetProperty()` for namespace prefix usage.
  itemIndex | The 1-based index of the desired item. Use the macro `kXMP_ArrayLastItem` to specify the last existing array item.
  itemValue | [out] A string object in which to return the value of the array item, if it has a value. Arrays and non-leaf levels of structs do not have values. Can be null if the value is not wanted.
  options | [out] A buffer in which to return the option flags describing the array item. Can be null if the flags are not wanted.

Returns
  True if the array item exists.

## ◆ GetGlobalOptions()

template<class tStringObj >

static XMP_OptionBits TXMPMeta< tStringObj >::GetGlobalOptions | ( |  | ) |
| static

`GetGlobalOptions()` retrieves the set of global option flags. There are none in this version of the Toolkit.

This function is static; you can make the call from the class without instantiating it.

Returns
  A logical OR of global option bit-flag constants.

## ◆ GetInternalRef()

template<class tStringObj >

XMPMetaRef TXMPMeta< tStringObj >::GetInternalRef | ( |  | ) | const

Retrieves an internal reference that can be safely passed across DLL boundaries and reconstructed.

The `TXMPMeta` class is a normal C++ template, it is instantiated and local to each client executable, as are the other `TXMP*` classes. Different clients might not use the same string type to instantiate `TXMPMeta`.

Because of this you should not pass `SXMPMeta` objects, or pointers to `SXMPMeta` objects, across DLL boundaries. Use this function to obtain a safe internal reference that you can pass, then construct a local object on the callee side. This construction does not create a cloned XMP tree, it is the same underlying XMP object safely wrapped in each client's `SXMPMeta` object.

Use this function and the associated constructor like this:

- The callee's header contains:

      CalleeMethod ( XMPMetaRef xmpRef );

- The caller's code contains:

      SXMPMeta callerXMP;
      CalleeMethod ( callerXMP.GetInternalRef() );

- The callee's code contains:

      SXMPMeta calleeXMP ( xmpRef );

Returns
  The reference object.

## ◆ GetLocalizedText()

template<class tStringObj >

bool TXMPMeta< tStringObj >::GetLocalizedText | ( | XMP_StringPtr | schemaNS,
|  | XMP_StringPtr | altTextName,
|  | XMP_StringPtr | genericLang,
|  | XMP_StringPtr | specificLang,
|  | tStringObj * | actualLang,
|  | tStringObj * | itemValue,
|  | XMP_OptionBits * | options
| ) |  | const

`GetLocalizedText()` retrieves information about a selected item in an alt-text array.

Localized text properties are stored in alt-text arrays. They allow multiple concurrent localizations of a property value, for example a document title or copyright in several languages. These functions provide convenient support for localized text properties, including a number of special and obscure aspects. The most important aspect of these functions is that they select an appropriate array item based on one or two RFC 3066 language tags. One of these languages, the "specific" language, is preferred and selected if there is an exact match. For many languages it is also possible to define a "generic" language that can be used if there is no specific language match. The generic language must be a valid RFC 3066 primary subtag, or the empty string.

For example, a specific language of "en-US" should be used in the US, and a specific language of "en-UK" should be used in England. It is also appropriate to use "en" as the generic language in each case. If a US document goes to England, the "en-US" title is selected by using the "en" generic language and the "en-UK" specific language.

It is considered poor practice, but allowed, to pass a specific language that is just an RFC 3066 primary tag. For example "en" is not a good specific language, it should only be used as a generic language. Passing "i" or "x" as the generic language is also considered poor practice but allowed.

Advice from the W3C about the use of RFC 3066 language tags can be found at:

- http://www.w3.org/International/articles/language-tags/

Note
  RFC 3066 language tags must be treated in a case insensitive manner. The XMP toolkit does this by normalizing their capitalization:
  - The primary subtag is lower case, the suggested practice of ISO 639.
  - All 2 letter secondary subtags are upper case, the suggested practice of ISO 3166.
  - All other subtags are lower case. The XMP specification defines an artificial language, "x-default", that is used to explicitly denote a default item in an alt-text array. The XMP toolkit normalizes alt-text arrays such that the x-default item is the first item. The `SetLocalizedText()` function has several special features related to the x-default item, see its description for details. The array item is selected according to these rules:
  - Look for an exact match with the specific language.
  - If a generic language is given, look for a partial match.
  - Look for an x-default item.
  - Choose the first item.
  A partial match with the generic language is where the start of the item's language matches the generic string and the next character is '-'. An exact match is also recognized as a degenerate case.

You can pass "x-default" as the specific language. In this case, selection of an `x-default` item is an exact match by the first rule, not a selection by the 3rd rule. The last 2 rules are fallbacks used when the specific and generic languages fail to produce a match.

The return value reports whether a match was successfully made.

Parameters

  schemaNS | The namespace URI for the alt-text array; see `GetProperty()`.
  altTextName | The name of the alt-text array. Can be a general path expression, must not be null or the empty string; see `GetProperty()` for namespace prefix usage.
  genericLang | The name of the generic language as an RFC 3066 primary subtag. Can be null or the empty string if no generic language is wanted.
  specificLang | The name of the specific language as an RFC 3066 tag, or "x-default". Must not be null or the empty string.
  actualLang | [out] A string object in which to return the language of the selected array item, if an appropriate array item is found. Can be null if the language is not wanted.
  itemValue | [out] A string object in which to return the value of the array item, if an appropriate array item is found. Can be null if the value is not wanted.
  options | A buffer in which to return the option flags that describe the array item, if an appropriate array item is found. Can be null if the flags are not wanted.

Returns
  True if an appropriate array item exists.

## ◆ GetNamespacePrefix()

template<class tStringObj >

static bool TXMPMeta< tStringObj >::GetNamespacePrefix | ( | XMP_StringPtr | namespaceURI,
|  | tStringObj * | namespacePrefix
| ) |  |
| static

`GetNamespacePrefix()` obtains the prefix for a registered namespace URI, and reports whether the URI is registered.

This function is static; make the call directly from the concrete class (`SXMPMeta`).

Parameters

  namespaceURI | The URI for the namespace. Must not be null or the empty string. It is not an error if the namespace URI is not registered.
  namespacePrefix | [out] A string object in which to return the prefix registered for this URI, with a terminating colon character, ':'. If the namespace is not registered, this string is not modified.

Returns
  True if the namespace URI is registered.

## ◆ GetNamespaceURI()

template<class tStringObj >

static bool TXMPMeta< tStringObj >::GetNamespaceURI | ( | XMP_StringPtr | namespacePrefix,
|  | tStringObj * | namespaceURI
| ) |  |
| static

`GetNamespaceURI()` obtains the URI for a registered namespace prefix, and reports whether the prefix is registered.

This function is static; make the call directly from the concrete class (`SXMPMeta`).

Parameters

  namespacePrefix | The prefix for the namespace. Must not be null or the empty string. It is not an error if the namespace prefix is not registered.
  namespaceURI | [out] A string object in which to return the URI registered for this prefix. If the prefix is not registered, this string is not modified.

Returns
  True if the namespace prefix is registered.

## ◆ GetObjectName()

template<class tStringObj >

void TXMPMeta< tStringObj >::GetObjectName | ( | tStringObj * | name | ) | const

`GetObjectName()` retrieves the client-assigned name of this XMP object.

Assign this name with `SetObjectName()`.

Parameters

  name | [out] A string object in which to return the name.

## ◆ GetObjectOptions()

template<class tStringObj >

XMP_OptionBits TXMPMeta< tStringObj >::GetObjectOptions | ( |  | ) | const

Not implemented.

## ◆ GetProperty()

template<class tStringObj >

bool TXMPMeta< tStringObj >::GetProperty | ( | XMP_StringPtr | schemaNS,
|  | XMP_StringPtr | propName,
|  | tStringObj * | propValue,
|  | XMP_OptionBits * | options
| ) |  | const

`GetProperty()` reports whether a property exists, and retrieves its value.

The accessor functions return true if the specified property exists. If it does, output parameters return the value (if any) and option flags describing the property. The option bit-flag constants that describe properties are `kXMP_PropXx` and `kXMP_ArrayIsXx`. See `kXMP_PropValueIsURI` and following, and macros `XMP_PropIsSimple` and following in `XMP_Const.h`. If the property exists and has a value, it is returned as a Unicode string in UTF-8 encoding. Arrays and the non-leaf levels of structs do not have values. This is the simplest property accessor. Use this to retrieve the values of top-level simple properties, or after using the path composition functions in `TXMPUtils`.

When specifying a namespace and path (in this and all other accessors):

- If a namespace URI is specified, it must be for a registered namespace.
- If the namespace is specified only by a prefix in the property name path, it must be a registered prefix.
- If both a URI and path prefix are present, they must be corresponding parts of a registered namespace.

Parameters

  schemaNS | The namespace URI for the property. The URI must be for a registered namespace. Must not be null or the empty string.
  propName | The name of the property. Can be a general path expression, must not be null or the empty string. The first component can be a namespace prefix; if present without a `schemaNS` value, the prefix specifies the namespace. The prefix must be for a registered namespace, and if a namespace URI is specified, must match the registered prefix for that namespace.
  propValue | [out] A string object in which to return the value of the property, if the property exists and has a value. Arrays and non-leaf levels of structs do not have values. Can be null if the value is not wanted.
  options | A buffer in which to return option flags describing the property. Can be null if the flags are not wanted.

Returns
  True if the property exists.

## ◆ GetProperty_Bool()

template<class tStringObj >

bool TXMPMeta< tStringObj >::GetProperty_Bool | ( | XMP_StringPtr | schemaNS,
|  | XMP_StringPtr | propName,
|  | bool * | propValue,
|  | XMP_OptionBits * | options
| ) |  | const

`GetProperty_Bool()` retrieves the value of a Boolean property as a C++ bool.

These are very similar to `TXMPMeta::GetProperty()` and `TXMPMeta::SetProperty()`, except that the value is returned or provided in binary form instead of as a UTF-8 string. `TXMPUtils` provides functions for converting between binary and string values. Use the path composition functions in `TXMPUtils` to compose complex path expressions for fields or items in nested structures or arrays, or for qualifiers. Reports whether a property exists, and retrieves its binary value and property type information.

Parameters

  schemaNS | The namespace URI; see `GetProperty()`.
  propName | The name of the property. Can be a general path expression, must not be null or the empty string; see `GetProperty()` for namespace prefix usage.
  propValue | [out] A buffer in which to return the binary value. Can be null if the value is not wanted. Must be null for arrays and non-leaf levels of structs that do not have values.
  options | [out] A buffer in which to return the option flags describing the property, a logical OR of allowed bit-flag constants; see `kXMP_PropValueIsStruct` and following. Can be null if flags are not wanted.

Returns
  True if the property exists.

## ◆ GetProperty_Date()

template<class tStringObj >

bool TXMPMeta< tStringObj >::GetProperty_Date | ( | XMP_StringPtr | schemaNS,
|  | XMP_StringPtr | propName,
|  | XMP_DateTime * | propValue,
|  | XMP_OptionBits * | options
| ) |  | const

`GetProperty_Date()` retrieves the value of a date-time property as an `XMP_DateTime` structure.

Reports whether a property exists, and retrieves its binary value and property type information.

Parameters

  schemaNS | The namespace URI; see `GetProperty()`.
  propName | The name of the property. Can be a general path expression, must not be null or the empty string; see `GetProperty()` for namespace prefix usage.
  propValue | [out] A buffer in which to return the binary value. Can be null if the value is not wanted. Must be null for arrays and non-leaf levels of structs that do not have values.
  options | [out] A buffer in which to return the option flags describing the property, a logical OR of allowed bit-flag constants; see `kXMP_PropValueIsStruct` and following. Can be null if flags are not wanted.

Returns
  True if the property exists.

## ◆ GetProperty_Float()

template<class tStringObj >

bool TXMPMeta< tStringObj >::GetProperty_Float | ( | XMP_StringPtr | schemaNS,
|  | XMP_StringPtr | propName,
|  | double * | propValue,
|  | XMP_OptionBits * | options
| ) |  | const

`GetProperty_Float()` retrieves the value of a floating-point property as a C double float.

Reports whether a property exists, and retrieves its binary value and property type information.

Parameters

  schemaNS | The namespace URI; see `GetProperty()`.
  propName | The name of the property. Can be a general path expression, must not be null or the empty string; see `GetProperty()` for namespace prefix usage.
  propValue | [out] A buffer in which to return the binary value. Can be null if the value is not wanted. Must be null for arrays and non-leaf levels of structs that do not have values.
  options | [out] A buffer in which to return the option flags describing the property, a logical OR of allowed bit-flag constants; see `kXMP_PropValueIsStruct` and following. Can be null if flags are not wanted.

Returns
  True if the property exists.

## ◆ GetProperty_Int()

template<class tStringObj >

bool TXMPMeta< tStringObj >::GetProperty_Int | ( | XMP_StringPtr | schemaNS,
|  | XMP_StringPtr | propName,
|  | XMP_Int32 * | propValue,
|  | XMP_OptionBits * | options
| ) |  | const

`GetProperty_Int()` retrieves the value of an integer property as a C long integer.

Reports whether a property exists, and retrieves its binary value and property type information.

Parameters

  schemaNS | The namespace URI; see `GetProperty()`.
  propName | The name of the property. Can be a general path expression, must not be null or the empty string; see `GetProperty()` for namespace prefix usage.
  propValue | [out] A buffer in which to return the binary value. Can be null if the value is not wanted. Must be null for arrays and non-leaf levels of structs that do not have values.
  options | [out] A buffer in which to return the option flags describing the property, a logical OR of allowed bit-flag constants; see `kXMP_PropValueIsStruct` and following. Can be null if flags are not wanted.

Returns
  True if the property exists.

## ◆ GetProperty_Int64()

template<class tStringObj >

bool TXMPMeta< tStringObj >::GetProperty_Int64 | ( | XMP_StringPtr | schemaNS,
|  | XMP_StringPtr | propName,
|  | XMP_Int64 * | propValue,
|  | XMP_OptionBits * | options
| ) |  | const

`GetProperty_Int64()` retrieves the value of an integer property as a C long long integer.

Reports whether a property exists, and retrieves its binary value and property type information.

Parameters

  schemaNS | The namespace URI; see `GetProperty()`.
  propName | The name of the property. Can be a general path expression, must not be null or the empty string; see `GetProperty()` for namespace prefix usage.
  propValue | [out] A buffer in which to return the binary value. Can be null if the value is not wanted. Must be null for arrays and non-leaf levels of structs that do not have values.
  options | [out] A buffer in which to return the option flags describing the property, a logical OR of allowed bit-flag constants; see `kXMP_PropValueIsStruct` and following. Can be null if flags are not wanted.

Returns
  True if the property exists.

## ◆ GetQualifier()

template<class tStringObj >

bool TXMPMeta< tStringObj >::GetQualifier | ( | XMP_StringPtr | schemaNS,
|  | XMP_StringPtr | propName,
|  | XMP_StringPtr | qualNS,
|  | XMP_StringPtr | qualName,
|  | tStringObj * | qualValue,
|  | XMP_OptionBits * | options
| ) |  | const

`GetQualifier()` provides access to a qualifier attached to a property.

Note
  In this version of the Toolkit, qualifiers are supported only for simple leaf properties.

Parameters

  schemaNS | The namespace URI; see `GetProperty()`.
  propName | The name of the property to which the qualifier is attached. Can be a general path expression, must not be null or the empty string; see `GetProperty()` for namespace prefix usage.
  qualNS | The namespace URI for the qualifier. Same URI and prefix usage as the `schemaNS` and `propName` parameters.
  qualName | The name of the qualifier. Must be a single XML name, must not be null or the empty string. Same URI and prefix usage as the `schemaNS` and `propName` parameters.
  qualValue | [out] A string object in which to return the value of the qualifier, if the qualifier has a value. Arrays and non-leaf levels of structs do not have values. Can be null if the value is not wanted.
  options | [out] A buffer in which to return the option flags describing the qualifier. Can be null if the flags are not wanted.

Returns
  True if the qualifier exists.

## ◆ GetStructField()

template<class tStringObj >

bool TXMPMeta< tStringObj >::GetStructField | ( | XMP_StringPtr | schemaNS,
|  | XMP_StringPtr | structName,
|  | XMP_StringPtr | fieldNS,
|  | XMP_StringPtr | fieldName,
|  | tStringObj * | fieldValue,
|  | XMP_OptionBits * | options
| ) |  | const

`GetStructField()` provides access to fields within a nested structure.

Reports whether the field exists; if it does, and if it has a value, the function retrieves the value.

Parameters

  schemaNS | The namespace URI for the struct; see `GetProperty()`.
  structName | The name of the struct. Can be a general path expression, must not be null or the empty string; see `GetProperty()` for namespace prefix usage.
  fieldNS | The namespace URI for the field. Same URI and prefix usage as the `schemaNS` and `structName` parameters.
  fieldName | The name of the field. Must be a single XML name, must not be null or the empty string. Same URI and prefix usage as the `schemaNS` and `structName` parameters.
  fieldValue | [out] A string object in which to return the value of the field, if the field has a value. Arrays and non-leaf levels of structs do not have values. Can be null if the value is not wanted.
  options | [out] A buffer in which to return the option flags describing the field. Can be null if the flags are not wanted.

Returns
  True if the field exists.

## ◆ GetVersionInfo()

template<class tStringObj >

static void TXMPMeta< tStringObj >::GetVersionInfo | ( | XMP_VersionInfo * | info | ) |
| static

`GetVersionInfo()` retrieves runtime version information.

The header `XMPVersion.hpp` defines a static version number for the XMP Toolkit, which describes the version of the API used at client compile time. It is not necessarily the same as the runtime version. Do not base runtime decisions on the static version alone; you can, however, compare the runtime and static versions.

This function is static; make the call directly from the concrete class (`SXMPMeta`). The function can be called before calling `TXMPMeta::Initialize()`.

Parameters

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

## ◆ Initialize()

template<class tStringObj >

static bool TXMPMeta< tStringObj >::Initialize | ( |  | ) |
| static

`Initialize()` explicitly initializes the XMP Toolkit before use. *‍/

Initializes the XMP Toolkit.

Call this function before making any other calls to the `TXMPMeta` functions, except `TXMPMeta::GetVersionInfo()`.

This function is static; make the call directly from the concrete class (`SXMPMeta`).

Returns
  True on success. *‍/

## ◆ operator=()

template<class tStringObj >

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

Assignment operator, assigns the internal reference and increments the reference count.

The assignment operator assigns the internal ref from the rhs object and increments the reference count on the underlying internal XMP object.

## ◆ ParseFromBuffer()

template<class tStringObj >

void TXMPMeta< tStringObj >::ParseFromBuffer | ( | XMP_StringPtr | buffer,
|  | XMP_StringLen | bufferSize,
|  | XMP_OptionBits | options = `0`
| ) |  |

`ParseFromBuffer()` parses RDF from a series of input buffers into this XMP object.

The metadata contained in an XMP object must be serialized as RDF for storage in an XMP packet and output to a file. Similarly, metadata in the form of serialized RDF (such as metadata read from a file using `TXMPFiles`) must be parsed into an XMP object for manipulation with the XMP Toolkit.

These functions support parsing serialized RDF into an XMP object, and serializing an XMP object into RDF. The input for parsing can be any valid Unicode encoding. ISO Latin-1 is also recognized, but its use is strongly discouraged. Serialization is always as UTF-8. Use this to convert metadata from serialized RDF form (as, for example, read from an XMP packet embedded in a file) into an XMP object that you can manipulate with the XMP Toolkit. If this XMP object is empty and the input buffer contains a complete XMP packet, this is the same as creating a new XMP object from that buffer with the constructor.

You can use this function to combine multiple buffers into a single metadata tree. To terminate an input loop conveniently, pass the option `kXMP_ParseMoreBuffers` for all real input, then make a final call with a zero length and `kXMP_NoOptions`. The buffers can be any length. The buffer boundaries need not respect XML tokens or even Unicode characters.

Parameters

  buffer | A pointer to a buffer of input. Can be null if `bufferSize` is 0.
  bufferSize | The length of the input buffer in bytes. Zero is a valid value.
  options | An options flag that controls how the parse operation is performed. A logical OR of these bit-flag constants: `kXMP_ParseMoreBuffers` - This is not the last buffer of input, more calls follow. `kXMP_RequireXMPMeta` - The `x:xmpmeta` XML element is required around `rdf:RDF`.

See also
  `TXMPFiles::GetXMP()`

## ◆ RegisterNamespace()

template<class tStringObj >

static bool TXMPMeta< tStringObj >::RegisterNamespace | ( | XMP_StringPtr | namespaceURI,
|  | XMP_StringPtr | suggestedPrefix,
|  | tStringObj * | registeredPrefix
| ) |  |
| static

`RegisterNamespace()` registers a namespace URI with a suggested prefix.

If the URI is not registered but the suggested prefix is in use, a unique prefix is created from the suggested one. The actual registered prefix is returned. The function result tells if the registered prefix is the suggested one. It is not an error if the URI is already registered, regardless of the prefix.

This function is static; make the call directly from the concrete class (`SXMPMeta`).

Parameters

  namespaceURI | The URI for the namespace. Must be a valid XML URI.
  suggestedPrefix | The suggested prefix to be used if the URI is not yet registered. Must be a valid XML name.
  registeredPrefix | [out] A string object in which to return the prefix actually registered for this URI.

Returns
  True if the registered prefix matches the suggested prefix.

Note
  No checking is done on either the URI or the prefix. *‍/

## ◆ ResetErrorCallbackLimit()

template<class tStringObj >

void TXMPMeta< 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.

## ◆ SerializeToBuffer() [1/2]

template<class tStringObj >

void TXMPMeta< tStringObj >::SerializeToBuffer | ( | tStringObj * | rdfString,
|  | XMP_OptionBits | options,
|  | XMP_StringLen | padding,
|  | XMP_StringPtr | newline,
|  | XMP_StringPtr | indent = `""`,
|  | XMP_Index | baseIndent = `0`
| ) |  | const

`SerializeToBuffer()` serializes metadata in this XMP object into a string as RDF.

Use this to prepare metadata for storage as an XMP packet embedded in a file. See `TXMPFiles::PutXMP()`.

Parameters

  rdfString | [out] A string object in which to return the serialized RDF. Must not be null.
  options | An options flag that controls how the serialization operation is performed. The specified options must be logically consistent; an exception is thrown if they are not. A logical OR of these bit-flag constants: `kXMP_OmitPacketWrapper` - Do not include an XML packet wrapper. This cannot be specified together with `kXMP_ReadOnlyPacket`, `kXMP_IncludeThumbnailPad`, or `kXMP_ExactPacketLength`. `kXMP_ReadOnlyPacket` - Create a read-only XML packet wapper. Cannot be specified together with `kXMP_OmitPacketWrapper`. `kXMP_UseCompactFormat` - Use a highly compact RDF syntax and layout. `kXMP_IncludeThumbnailPad` - Include typical space for a JPEG thumbnail in the padding if no `xmp:Thumbnails` property is present. Cannot be specified together with `kXMP_OmitPacketWrapper`. `kXMP_ExactPacketLength` - The padding parameter provides the overall packet length. The actual amount of padding is computed. An exception is thrown if the packet exceeds this length with no padding. Cannot be specified together with `kXMP_OmitPacketWrapper`. In addition to the above options, you can include one of the following encoding options: `kXMP_EncodeUTF8` - Encode as UTF-8, the default. `kXMP_EncodeUTF16Big` - Encode as big-endian UTF-16. `kXMP_EncodeUTF16Little` - Encode as little-endian UTF-16. `kXMP_EncodeUTF32Big` - Encode as big-endian UTF-32. `kXMP_EncodeUTF32Little` - Encode as little-endian UTF-32.
  padding | The amount of padding to be added if a writeable XML packet is created. If zero (the default) an appropriate amount of padding is computed.
  newline | The string to be used as a line terminator. If empty, defaults to linefeed, U+000A, the standard XML newline.
  indent | The string to be used for each level of indentation in the serialized RDF. If empty, defaults to two ASCII spaces, U+0020.
  baseIndent | The number of levels of indentation to be used for the outermost XML element in the serialized RDF. This is convenient when embedding the RDF in other text.

## ◆ SerializeToBuffer() [2/2]

template<class tStringObj >

void TXMPMeta< tStringObj >::SerializeToBuffer | ( | tStringObj * | rdfString,
|  | XMP_OptionBits | options = `0`,
|  | XMP_StringLen | padding = `0`
| ) |  | const

`SerializeToBuffer()` serializes metadata in this XMP object into a string as RDF.

This simpler form of the function uses default values for the `newline`, `indent`, and `baseIndent` parameters.

Parameters

  rdfString | [out] A string object in which to return the serialized RDF. Must not be null.
  options | An options flag that controls how the serialization operation is performed. The specified options must be logically consistent; an exception is thrown if they are not. A logical OR of these bit-flag constants: `kXMP_OmitPacketWrapper` - Do not include an XML packet wrapper. This cannot be specified together with `kXMP_ReadOnlyPacket`, `kXMP_IncludeThumbnailPad`, or `kXMP_ExactPacketLength`. `kXMP_ReadOnlyPacket` - Create a read-only XML packet wapper. Cannot be specified together with `kXMP_OmitPacketWrapper`. `kXMP_UseCompactFormat` - Use a highly compact RDF syntax and layout. `kXMP_IncludeThumbnailPad` - Include typical space for a JPEG thumbnail in the padding if no `xmp:Thumbnails` property is present. Cannot be specified together with `kXMP_OmitPacketWrapper`. `kXMP_ExactPacketLength` - The padding parameter provides the overall packet length. The actual amount of padding is computed. An exception is thrown if the packet exceeds this length with no padding. Cannot be specified together with `kXMP_OmitPacketWrapper`. In addition to the above options, you can include one of the following encoding options: `kXMP_EncodeUTF8` - Encode as UTF-8, the default. `kXMP_EncodeUTF16Big` - Encode as big-endian UTF-16. `kXMP_EncodeUTF16Little` - Encode as little-endian UTF-16. `kXMP_EncodeUTF32Big` - Encode as big-endian UTF-32. `kXMP_EncodeUTF32Little` - Encode as little-endian UTF-32.
  padding | The amount of padding to be added if a writeable XML packet is created. If zero (the default) an appropriate amount of padding is computed.

## ◆ SetArrayItem() [1/2]

template<class tStringObj >

void TXMPMeta< tStringObj >::SetArrayItem | ( | XMP_StringPtr | schemaNS,
|  | XMP_StringPtr | arrayName,
|  | XMP_Index | itemIndex,
|  | const tStringObj & | itemValue,
|  | XMP_OptionBits | options = `0`
| ) |  |

`SetArrayItem()` creates or sets the value of an item within an array using a string object.

Overloads the basic form of the function, allowing you to pass a string object in which to return the item value. It is otherwise identical; see details in the canonical form.

## ◆ SetArrayItem() [2/2]

template<class tStringObj >

void TXMPMeta< tStringObj >::SetArrayItem | ( | XMP_StringPtr | schemaNS,
|  | XMP_StringPtr | arrayName,
|  | XMP_Index | itemIndex,
|  | XMP_StringPtr | itemValue,
|  | XMP_OptionBits | options = `0`
| ) |  |

`SetArrayItem()` creates or sets the value of an item within an array.

Items are accessed by an integer index, where the first item has index 1. This function creates the item if necessary, but the array itself must already exist Use `AppendArrayItem()` to create arrays. A new item is automatically appended if the index is the array size plus 1. To insert a new item before or after an existing item, use option flags.

Use `TXMPUtils::ComposeArrayItemPath()` to create a complex path.

Parameters

  schemaNS | The namespace URI; see `GetProperty()`.
  arrayName | The name of the array. Can be a general path expression, must not be null or the empty string; see `GetProperty()` for namespace prefix usage.
  itemIndex | The 1-based index of the desired item. Use the macro `kXMP_ArrayLastItem` to specify the last existing array item.
  itemValue | The new item value, a null-terminated UTF-8 string, if the array item has a value.
  options | Option flags describing the array type and insertion location for a new item; a logical OR of allowed bit-flag constants. The type, if specified, must match the existing array type, `kXMP_PropArrayIsOrdered`, `kXMP_PropArrayIsAlternate`, or `kXMP_PropArrayIsAltText`. Default (0 or `kXMP_NoOptions`) matches the existing array type.

To insert a new item before or after the specified index, set flag `kXMP_InsertBeforeItem` or `kXMP_InsertAfterItem`.

## ◆ SetClientString()

template<class tStringObj >

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

## ◆ SetDefaultErrorCallback()

template<class tStringObj >

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

SetDefaultErrorCallback() registers a global default error notification callback.

From the beginning through version 5.5, XMP Tookit 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 `TXMPMeta` functions.

A client can register an error notification callback function for a `TXMPMeta` 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 TXMPMeta 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`.

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.

## ◆ SetErrorCallback()

template<class tStringObj >

void TXMPMeta< tStringObj >::SetErrorCallback | ( | XMPMeta_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.

## ◆ SetGlobalOptions()

template<class tStringObj >

static void TXMPMeta< tStringObj >::SetGlobalOptions | ( | XMP_OptionBits | options | ) |
| static

`SetGlobalOptions()` updates the set of global option flags. There are none in this version of the Toolkit.

The entire set is replaced with the new values. If only one flag is to be modified, use `TXMPMeta::GetGlobalOptions()` to obtain the current set, modify the desired flag, then use this function to reset the value.

This function is static; you can make the call from the class without instantiating it.

Parameters

  options | A logical OR of global option bit-flag constants.

## ◆ SetLocalizedText() [1/2]

template<class tStringObj >

void TXMPMeta< tStringObj >::SetLocalizedText | ( | XMP_StringPtr | schemaNS,
|  | XMP_StringPtr | altTextName,
|  | XMP_StringPtr | genericLang,
|  | XMP_StringPtr | specificLang,
|  | const tStringObj & | itemValue,
|  | XMP_OptionBits | options = `0`
| ) |  |

`SetLocalizedText()` modifies the value of a selected item in an alt-text array using a string object.

Creates an appropriate array item if necessary, and handles special cases for the x-default item.

The array item is selected according to these rules:

- Look for an exact match with the specific language.
- If a generic language is given, look for a partial match.
- Look for an x-default item.
- Choose the first item.

A partial match with the generic language is where the start of the item's language matches the generic string and the next character is '-'. An exact match is also recognized as a degenerate case.

You can pass "x-default" as the specific language. In this case, selection of an `x-default` item is an exact match by the first rule, not a selection by the 3rd rule. The last 2 rules are fallbacks used when the specific and generic languages fail to produce a match.

Item values are modified according to these rules:

- If the selected item is from a match with the specific language, the value of that item is modified. If the existing value of that item matches the existing value of the x-default item, the x-default item is also modified. If the array only has 1 existing item (which is not x-default), an x-default item is added with the given value.

- If the selected item is from a match with the generic language and there are no other generic matches, the value of that item is modified. If the existing value of that item matches the existing value of the x-default item, the x-default item is also modified. If the array only has 1 existing item (which is not x-default), an x-default item is added with the given value.

- If the selected item is from a partial match with the generic language and there are other partial matches, a new item is created for the specific language. The x-default item is not modified.

- If the selected item is from the last 2 rules then a new item is created for the specific language. If the array only had an x-default item, the x-default item is also modified. If the array was empty, items are created for the specific language and x-default.

Parameters

  schemaNS | The namespace URI for the alt-text array; see `GetProperty()`.
  altTextName | The name of the alt-text array. Can be a general path expression, must not be null or the empty string; see `GetProperty()` for namespace prefix usage.
  genericLang | The name of the generic language as an RFC 3066 primary subtag. Can be null or the empty string if no generic language is wanted.
  specificLang | The name of the specific language as an RFC 3066 tag, or "x-default". Must not be null or the empty string.
  itemValue | The new value for the matching array item, specified as a string object.
  options | Option flags, none currently defined.

## ◆ SetLocalizedText() [2/2]

template<class tStringObj >

void TXMPMeta< tStringObj >::SetLocalizedText | ( | XMP_StringPtr | schemaNS,
|  | XMP_StringPtr | altTextName,
|  | XMP_StringPtr | genericLang,
|  | XMP_StringPtr | specificLang,
|  | XMP_StringPtr | itemValue,
|  | XMP_OptionBits | options = `0`
| ) |  |

`SetLocalizedText()` modifies the value of a selected item in an alt-text array.

Creates an appropriate array item if necessary, and handles special cases for the x-default item.

The array item is selected according to these rules:

- Look for an exact match with the specific language.
- If a generic language is given, look for a partial match.
- Look for an x-default item.
- Choose the first item.

A partial match with the generic language is where the start of the item's language matches the generic string and the next character is '-'. An exact match is also recognized as a degenerate case.

You can pass "x-default" as the specific language. In this case, selection of an `x-default` item is an exact match by the first rule, not a selection by the 3rd rule. The last 2 rules are fallbacks used when the specific and generic languages fail to produce a match.

Item values are modified according to these rules:

- If the selected item is from a match with the specific language, the value of that item is modified. If the existing value of that item matches the existing value of the x-default item, the x-default item is also modified. If the array only has 1 existing item (which is not x-default), an x-default item is added with the given value.

- If the selected item is from a match with the generic language and there are no other generic matches, the value of that item is modified. If the existing value of that item matches the existing value of the x-default item, the x-default item is also modified. If the array only has 1 existing item (which is not x-default), an x-default item is added with the given value.

- If the selected item is from a partial match with the generic language and there are other partial matches, a new item is created for the specific language. The x-default item is not modified.

- If the selected item is from the last 2 rules then a new item is created for the specific language. If the array only had an x-default item, the x-default item is also modified. If the array was empty, items are created for the specific language and x-default.

Parameters

  schemaNS | The namespace URI for the alt-text array; see `GetProperty()`.
  altTextName | The name of the alt-text array. Can be a general path expression, must not be null or the empty string; see `GetProperty()` for namespace prefix usage.
  genericLang | The name of the generic language as an RFC 3066 primary subtag. Can be null or the empty string if no generic language is wanted.
  specificLang | The name of the specific language as an RFC 3066 tag, or "x-default". Must not be null or the empty string.
  itemValue | The new value for the matching array item, specified as a null-terminated UTF-8 string.
  options | Option flags, none currently defined.

## ◆ SetObjectName() [1/2]

template<class tStringObj >

void TXMPMeta< tStringObj >::SetObjectName | ( | tStringObj | name | ) |

`SetObjectName()` assigns a name to this XMP object.

Retrieve this client-assigned name with `GetObjectName()`.

Parameters

  name | The name as a string object.

## ◆ SetObjectName() [2/2]

template<class tStringObj >

void TXMPMeta< tStringObj >::SetObjectName | ( | XMP_StringPtr | name | ) |

`SetObjectName()` assigns a name to this XMP object.

Retrieve this client-assigned name with `GetObjectName()`.

Parameters

  name | The name as a null-terminated UTF-8 string.

## ◆ SetObjectOptions()

template<class tStringObj >

void TXMPMeta< tStringObj >::SetObjectOptions | ( | XMP_OptionBits | options | ) |

Not implemented.

## ◆ SetProperty() [1/2]

template<class tStringObj >

void TXMPMeta< tStringObj >::SetProperty | ( | XMP_StringPtr | schemaNS,
|  | XMP_StringPtr | propName,
|  | const tStringObj & | propValue,
|  | XMP_OptionBits | options = `0`
| ) |  |

`SetProperty()` creates or sets a property value using a string object.

Overloads the basic form of the function, allowing you to pass a string object for the item value. It is otherwise identical; see details in the canonical form.

## ◆ SetProperty() [2/2]

template<class tStringObj >

void TXMPMeta< tStringObj >::SetProperty | ( | XMP_StringPtr | schemaNS,
|  | XMP_StringPtr | propName,
|  | XMP_StringPtr | propValue,
|  | XMP_OptionBits | options = `0`
| ) |  |

be a simple property with an `xml:lang` attribute.

These functions all take a property specification; the top level namespace URI (the "schema" namespace) and the basic name of the property being referenced. See the introductory discussion of path expression usage for more information. All of the functions take a UTF-8 encoded Unicode string for the property value. Arrays and non-leaf levels of structs do not have values. The value can be passed as an `XMP_StringPtr` (a pointer to a null-terminated string), or as a string object (`tStringObj`). Each function takes an options flag that describes the property. You can use these functions to create empty arrays and structs by setting appropriate option flags. When you assign a value, all levels of a struct that are implicit in the assignment are created if necessary. `TXMPMeta::AppendArrayItem()` implicitly creates the named array if necessary.

The allowed option bit-flags include:

- `kXMP_PropValueIsStruct` - Can be used to create an empty struct. A struct is implicitly created when the first field is set.
- `kXMP_PropValueIsArray` - By default, a general unordered array (bag).
- `kXMP_PropArrayIsOrdered` - An ordered array.
- `kXMP_PropArrayIsAlternate` - An alternative array.
- `kXMP_PropArrayIsAltText` - An alt-text array. Each array element must

`SetProperty()` creates or sets a property value.

This is the simplest property setter. Use it for top-level simple properties, or after using the path composition functions in `TXMPUtils`.

Parameters

  schemaNS | The namespace URI; see `GetProperty()`.
  propName | The name of the property. Can be a general path expression, must not be null or the empty string; see `GetProperty()` for namespace prefix usage.
  propValue | The new value, a pointer to a null terminated UTF-8 string. Must be null for arrays and non-leaf levels of structs that do not have values.
  options | Option flags describing the property; a logical OR of allowed bit-flag constants; see `kXMP_PropValueIsStruct` and following. Must match the type of a property that already exists.

## ◆ SetProperty_Bool()

template<class tStringObj >

void TXMPMeta< tStringObj >::SetProperty_Bool | ( | XMP_StringPtr | schemaNS,
|  | XMP_StringPtr | propName,
|  | bool | propValue,
|  | XMP_OptionBits | options = `0`
| ) |  |

`SetProperty_Bool()` sets the value of a Boolean property using a C++ bool.

Sets a property with a binary value, creating it if necessary.

Parameters

  schemaNS | The namespace URI; see `GetProperty()`.
  propName | The name of the property. Can be a general path expression, must not be null or the empty string; see `GetProperty()` for namespace prefix usage.
  propValue | The new binary value. Can be null if creating the property. Must be null for arrays and non-leaf levels of structs that do not have values.
  options | Option flags describing the property; a logical OR of allowed bit-flag constants; see `kXMP_PropValueIsStruct` and following. Must match the type of a property that already exists.

## ◆ SetProperty_Date()

template<class tStringObj >

void TXMPMeta< tStringObj >::SetProperty_Date | ( | XMP_StringPtr | schemaNS,
|  | XMP_StringPtr | propName,
|  | const XMP_DateTime & | propValue,
|  | XMP_OptionBits | options = `0`
| ) |  |

`SetProperty_Date()` sets the value of a date/time property using an `XMP_DateTime` structure.

Sets a property with a binary value, creating it if necessary.

Parameters

  schemaNS | The namespace URI; see `GetProperty()`.
  propName | The name of the property. Can be a general path expression, must not be null or the empty string; see `GetProperty()` for namespace prefix usage.
  propValue | The new binary value. Can be null if creating the property. Must be null for arrays and non-leaf levels of structs that do not have values.
  options | Option flags describing the property; a logical OR of allowed bit-flag constants; see `kXMP_PropValueIsStruct` and following. Must match the type of a property that already exists.

## ◆ SetProperty_Float()

template<class tStringObj >

void TXMPMeta< tStringObj >::SetProperty_Float | ( | XMP_StringPtr | schemaNS,
|  | XMP_StringPtr | propName,
|  | double | propValue,
|  | XMP_OptionBits | options = `0`
| ) |  |

`SetProperty_Float()` sets the value of a floating-point property using a C double float.

Sets a property with a binary value, creating it if necessary.

Parameters

  schemaNS | The namespace URI; see `GetProperty()`.
  propName | The name of the property. Can be a general path expression, must not be null or the empty string; see `GetProperty()` for namespace prefix usage.
  propValue | The new binary value. Can be null if creating the property. Must be null for arrays and non-leaf levels of structs that do not have values.
  options | Option flags describing the property; a logical OR of allowed bit-flag constants; see `kXMP_PropValueIsStruct` and following. Must match the type of a property that already exists.

## ◆ SetProperty_Int()

template<class tStringObj >

void TXMPMeta< tStringObj >::SetProperty_Int | ( | XMP_StringPtr | schemaNS,
|  | XMP_StringPtr | propName,
|  | XMP_Int32 | propValue,
|  | XMP_OptionBits | options = `0`
| ) |  |

`SetProperty_Int()` sets the value of an integer property using a C long integer.

Sets a property with a binary value, creating it if necessary.

Parameters

  schemaNS | The namespace URI; see `GetProperty()`.
  propName | The name of the property. Can be a general path expression, must not be null or the empty string; see `GetProperty()` for namespace prefix usage.
  propValue | The new binary value. Can be null if creating the property. Must be null for arrays and non-leaf levels of structs that do not have values.
  options | Option flags describing the property; a logical OR of allowed bit-flag constants; see `kXMP_PropValueIsStruct` and following. Must match the type of a property that already exists.

## ◆ SetProperty_Int64()

template<class tStringObj >

void TXMPMeta< tStringObj >::SetProperty_Int64 | ( | XMP_StringPtr | schemaNS,
|  | XMP_StringPtr | propName,
|  | XMP_Int64 | propValue,
|  | XMP_OptionBits | options = `0`
| ) |  |

`SetProperty_Int64()` sets the value of an integer property using a C long long integer.

Sets a property with a binary value, creating it if necessary.

Parameters

  schemaNS | The namespace URI; see `GetProperty()`.
  propName | The name of the property. Can be a general path expression, must not be null or the empty string; see `GetProperty()` for namespace prefix usage.
  propValue | The new binary value. Can be null if creating the property. Must be null for arrays and non-leaf levels of structs that do not have values.
  options | Option flags describing the property; a logical OR of allowed bit-flag constants; see `kXMP_PropValueIsStruct` and following. Must match the type of a property that already exists.

## ◆ SetQualifier() [1/2]

template<class tStringObj >

void TXMPMeta< tStringObj >::SetQualifier | ( | XMP_StringPtr | schemaNS,
|  | XMP_StringPtr | propName,
|  | XMP_StringPtr | qualNS,
|  | XMP_StringPtr | qualName,
|  | const tStringObj & | qualValue,
|  | XMP_OptionBits | options = `0`
| ) |  |

`SetQualifier()` creates or sets a qualifier attached to a property using a string object.

Overloads the basic form of the function, allowing you to pass a string object for the qualifier value. It is otherwise identical; see details in the canonical form.

## ◆ SetQualifier() [2/2]

template<class tStringObj >

void TXMPMeta< tStringObj >::SetQualifier | ( | XMP_StringPtr | schemaNS,
|  | XMP_StringPtr | propName,
|  | XMP_StringPtr | qualNS,
|  | XMP_StringPtr | qualName,
|  | XMP_StringPtr | qualValue,
|  | XMP_OptionBits | options = `0`
| ) |  |

`SetQualifier()` creates or sets a qualifier attached to a property.

Use this to set a value for an existing qualifier, or create a new qualifier. <<how do options work? macro vs bit-flag? interaction w/XMP_PropHasQualifier?>> Use `TXMPUtils::ComposeQualifierPath()` to create a complex path.

Parameters

  schemaNS | The namespace URI; see `GetProperty()`.
  propName | The name of the property to which the qualifier is attached. Can be a general path expression, must not be null or the empty string; see `GetProperty()` for namespace prefix usage.
  qualNS | The namespace URI for the qualifier. Same namespace and prefix usage as `GetProperty()`.
  qualName | The name of the qualifier. Must be a single XML name, must not be null or the empty string. Same namespace and prefix usage as `GetProperty()`.
  qualValue | The new value, a null-terminated UTF-8 string, if the qualifier has a value. Null to create a new, empty qualifier.
  options | Option flags describing the <<qualified property? qualifier?>>, a logical OR of property-type bit-flag constants. Use the macro `XMP_PropIsQualifier` to create a qualifier. <<??>>

## ◆ SetStructField() [1/2]

template<class tStringObj >

void TXMPMeta< tStringObj >::SetStructField | ( | XMP_StringPtr | schemaNS,
|  | XMP_StringPtr | structName,
|  | XMP_StringPtr | fieldNS,
|  | XMP_StringPtr | fieldName,
|  | const tStringObj & | fieldValue,
|  | XMP_OptionBits | options = `0`
| ) |  |

`SetStructField()` creates or sets the value of a field within a nested structure, using a string object.

Overloads the basic form of the function, allowing you to pass a string object in which to return the field value. It is otherwise identical; see details in the canonical form.

## ◆ SetStructField() [2/2]

template<class tStringObj >

void TXMPMeta< tStringObj >::SetStructField | ( | XMP_StringPtr | schemaNS,
|  | XMP_StringPtr | structName,
|  | XMP_StringPtr | fieldNS,
|  | XMP_StringPtr | fieldName,
|  | XMP_StringPtr | fieldValue,
|  | XMP_OptionBits | options = `0`
| ) |  |

`SetStructField()` creates or sets the value of a field within a nested structure.

Use this to set a value within an existing structure, create a new field within an existing structure, or create an empty structure of any depth. If you set a field in a structure that does not exist, the structure is automatically created.

Use `TXMPUtils::ComposeStructFieldPath()` to create a complex path.

Parameters

  schemaNS | The namespace URI; see `GetProperty()`.
  structName | The name of the struct. Can be a general path expression, must not be null or the empty string; see `GetProperty()` for namespace prefix usage.
  fieldNS | The namespace URI for the field. Same namespace and prefix usage as `GetProperty()`.
  fieldName | The name of the field. Must be a single XML name, must not be null or the empty string. Same namespace and prefix usage as `GetProperty()`.
  fieldValue | The new value, a null-terminated UTF-8 string, if the field has a value. Null to create a new, empty struct or empty field in an existing struct.
  options | Option flags describing the property, in which the bit-flag `kXMP_PropValueIsStruct` must be set to create a struct.

## ◆ Sort()

template<class tStringObj >

void TXMPMeta< tStringObj >::Sort | ( |  | ) |

`Sort()` sorts the data model tree of an XMP object.

Use this function to sort the data model of an XMP object into a canonical order. This can be convenient when comparing data models, (e.g. by text comparison of DumpObject output).

At the top level the namespaces are sorted by their prefixes. Within a namespace, the top level properties are sorted by name. Within a struct, the fields are sorted by their qualified name, i.e. their XML prefix:local form. Unordered arrays of simple items are sorted by value. Language Alternative arrays are sorted by the xml:lang qualifiers, with the "x-default" item placed first.

## ◆ Terminate()

template<class tStringObj >

static void TXMPMeta< tStringObj >::Terminate | ( |  | ) |
| static

`Terminate()` explicitly terminates usage of the XMP Toolkit.

Frees structures created on initialization.

This function is static; make the call directly from the concrete class (`SXMPMeta`).

## Member Data Documentation

## ◆ xmpRef

template<class tStringObj >

XMPMetaRef TXMPMeta< tStringObj >::xmpRef

Definition at line 1742 of file TXMPMeta.hpp.

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

- public/include/TXMPMeta.hpp