TXMPMeta< tStringObj > Class Template Reference

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

#include <TXMPMeta.hpp>

List of all members.

Public Member Functions

Constructors and destructor

TXMPMeta ()
 Default constructor, creates an empty object.
TXMPMeta (const TXMPMeta< tStringObj > &original)
 Copy constructor, creates a client object refering to the same internal object.
void operator= (const TXMPMeta< tStringObj > &rhs)
 Assignment operator, assigns the internal reference and increments the reference count.
 TXMPMeta (XMPMetaRef xmpRef)
 Reconstructs an XMP object from an internal reference.
 TXMPMeta (XMP_StringPtr buffer, XMP_StringLen xmpSize)
 Constructs an object and parse one buffer of RDF into it.
virtual ~TXMPMeta () throw ()
 Destructor, typical virtual destructor. */.
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.

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.

bool GetProperty (XMP_StringPtr schemaNS, XMP_StringPtr propName, tStringObj *propValue, XMP_OptionBits *options) const
 GetProperty() reports whether a property exists, and retrieves its value.
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.
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.
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.
Creating properties and setting their values

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

void SetProperty (XMP_StringPtr schemaNS, XMP_StringPtr propName, XMP_StringPtr propValue, XMP_OptionBits options=0)
 SetProperty() creates or sets a property value.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
void DeleteArrayItem (XMP_StringPtr schemaNS, XMP_StringPtr arrayName, XMP_Index itemIndex)
 DeleteArrayItem() deletes an XMP subtree rooted at a given array item.
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.
void DeleteQualifier (XMP_StringPtr schemaNS, XMP_StringPtr propName, XMP_StringPtr qualNS, XMP_StringPtr qualName)
 DeleteQualifier() deletes an XMP subtree rooted at a given qualifier.
bool DoesPropertyExist (XMP_StringPtr schemaNS, XMP_StringPtr propName) const
 DoesPropertyExist() reports whether a property currently exists.
bool DoesArrayItemExist (XMP_StringPtr schemaNS, XMP_StringPtr arrayName, XMP_Index itemIndex) const
 DoesArrayItemExist() reports whether an array item currently exists.
bool DoesStructFieldExist (XMP_StringPtr schemaNS, XMP_StringPtr structName, XMP_StringPtr fieldNS, XMP_StringPtr fieldName) const
 DoesStructFieldExist() reports whether a struct field currently exists.
bool DoesQualifierExist (XMP_StringPtr schemaNS, XMP_StringPtr propName, XMP_StringPtr qualNS, XMP_StringPtr qualName) const
 DoesQualifierExist() reports whether a qualifier currently exists.
Accessing properties as binary values.

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.

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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Accessing localized text (alt-text) properties.

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:

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.
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.
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.
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.
void DeleteLocalizedText (XMP_StringPtr schemaNS, XMP_StringPtr altTextName, XMP_StringPtr genericLang, XMP_StringPtr specificLang)
 DeleteLocalizedText() deletes specific language alternatives from an alt-text array.
Creating and reading serialized RDF.

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.

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.
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.
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.
Helper functions.

XMPMetaRef GetInternalRef () const
 Retrieves an internal reference that can be safely passed across DLL boundaries and reconstructed.
void GetObjectName (tStringObj *name) const
 GetObjectName() retrieves the client-assigned name of this XMP object.
void SetObjectName (XMP_StringPtr name)
 SetObjectName() assigns a name to this XMP object.
void SetObjectName (tStringObj name)
 SetObjectName() assigns a name to this XMP object.
void Sort ()
 Sort() sorts the data model tree of an XMP object.
void Erase ()
 Erase() restores the object to a "just constructed" state.
TXMPMeta Clone (XMP_OptionBits options=0) const
 Clone() creates a deep copy of an XMP object.
XMP_Index CountArrayItems (XMP_StringPtr schemaNS, XMP_StringPtr arrayName) const
 CountArrayItems() reports the number of items currently defined in an array.
XMP_Status DumpObject (XMP_TextOutputProc outProc, void *clientData) const
 DumpObject() outputs the content of an XMP object to a callback handler for debugging.
XMP_OptionBits GetObjectOptions () const
 Not implemented.
void SetObjectOptions (XMP_OptionBits options)
 Not implemented.

Static Public Member Functions

Initialization and termination

static void GetVersionInfo (XMP_VersionInfo *info)
 GetVersionInfo() retrieves runtime version information.
*static bool Initialize ()
 Initialize() explicitly initializes the XMP Toolkit before use. */
static void Terminate ()
 Terminate() explicitly terminates usage of the XMP Toolkit.
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.
static void SetGlobalOptions (XMP_OptionBits options)
 SetGlobalOptions() updates the set of global option flags. There are none in this version of the Toolkit.
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.

See also:
Member function TXMPMeta::DumpObject()
static XMP_Status DumpNamespaces (XMP_TextOutputProc outProc, void *clientData)
 DumpNamespaces() sends the list of registered namespace URIs and prefixes to a handler.
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.
static bool GetNamespacePrefix (XMP_StringPtr namespaceURI, tStringObj *namespacePrefix)
 GetNamespacePrefix() obtains the prefix for a registered namespace URI, and reports whether the URI is registered.
static bool GetNamespaceURI (XMP_StringPtr namespacePrefix, tStringObj *namespaceURI)
 GetNamespaceURI() obtains the URI for a registered namespace prefix, and reports whether the prefix is registered.
static void DeleteNamespace (XMP_StringPtr namespaceURI)
 Not implemented.

Error notifications

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.



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

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.


Constructor & Destructor Documentation

template<class tStringObj>
* TXMPMeta< tStringObj >::TXMPMeta (  ) 

Default constructor, creates an empty object.

The default constructor creates a new empty TXMPMeta object.

Returns:
The new object.
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.
Returns:
The new object.
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.
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.
Returns:
The new object.

Member Function Documentation

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.

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

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

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

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

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

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.

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:

See also:
TXMPFiles::GetXMP()
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.
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.
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:

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

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

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.

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.

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

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

SetProperty() creates or sets a property value.

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:

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

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

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

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


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

XMP-Toolkit-SDK-CC201306 documentation generated by doxygen 1.6.3