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. | |
* | 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 | |
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 | |
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 | |
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 | |
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:
| |
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 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 | |
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
| |
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 A client can register an error notification callback function for a 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 | |
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. |
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
.
Default constructor, creates an empty object.
The default constructor creates a new empty TXMPMeta
object.
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.
xmpRef | The underlying reference object, obtained from some other XMP object with TXMPMeta::GetInternalRef() . |
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()
.
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. |
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.
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.
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. |
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.
options | Option flags, not currently defined.. |
XMP_Index TXMPMeta< tStringObj >::CountArrayItems | ( | XMP_StringPtr | schemaNS, | |
XMP_StringPtr | arrayName | |||
) | const |
CountArrayItems()
reports the number of items currently defined in an array.
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. |
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.
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. |
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()
.
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. |
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
).
namespaceURI | The URI for the namespace. |
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.
schemaNS | The namespace URI for the property; see GetProperty() . | |
propName | The name of the property; see GetProperty() . |
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.
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() . |
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.
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() . |
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.
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. |
bool TXMPMeta< tStringObj >::DoesPropertyExist | ( | XMP_StringPtr | schemaNS, | |
XMP_StringPtr | propName | |||
) | const |
DoesPropertyExist()
reports whether a property currently exists.
schemaNS | The namespace URI for the property; see GetProperty() . | |
propName | The name of the property; see GetProperty() . |
bool TXMPMeta< tStringObj >::DoesQualifierExist | ( | XMP_StringPtr | schemaNS, | |
XMP_StringPtr | propName, | |||
XMP_StringPtr | qualNS, | |||
XMP_StringPtr | qualName | |||
) | const |
DoesQualifierExist()
reports whether a qualifier currently exists.
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() . |
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.
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() . |
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
).
outProc | The client-defined procedure to handle each line of output. | |
clientData | A pointer to client-defined data to pass to the handler. |
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.
outProc | The client-defined procedure to handle each line of output. | |
clientData | A pointer to client-defined data to pass to the handler. |
DumpNamespaces()
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.
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. |
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.
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:
CalleeMethod ( XMPMetaRef xmpRef );
SXMPMeta callerXMP; CalleeMethod ( callerXMP.GetInternalRef() );
SXMPMeta calleeXMP ( xmpRef );
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:
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.
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. |
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
).
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. |
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
).
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. |
void TXMPMeta< tStringObj >::GetObjectName | ( | tStringObj * | name | ) | const |
GetObjectName()
retrieves the client-assigned name of this XMP object.
Assign this name with SetObjectName()
.
name | [out] A string object in which to return the name. |
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):
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. |
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.
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. |
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.
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. |
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.
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. |
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.
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. |
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.
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. |
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.
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. |
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.
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. |
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()
.
info | [out] A buffer in which to return the version information. |
* 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
).
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.
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.
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:
|
TXMPFiles::GetXMP()
* 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
).
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. |
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.
limit | A limit on the number of notifications to be delivered. |
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.
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:
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. |
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()
.
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:
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. |
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.
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.
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
.
static void TXMPMeta< tStringObj >::SetDefaultErrorCallback | ( | XMPMeta_ErrorCallbackProc | proc, | |
void * | context = 0 , |
|||
XMP_Uns32 | limit = 1 | |||
) | [static] |
SetDefaultErrorCallback() registers a global default error notification callback.
proc | The client's callback function. | |
context | Client-provided context for the callback. | |
limit | A limit on the number of notifications to be delivered. |
void TXMPMeta< tStringObj >::SetErrorCallback | ( | XMPMeta_ErrorCallbackProc | proc, | |
void * | context = 0 , |
|||
XMP_Uns32 | limit = 1 | |||
) |
SetErrorCallback() registers an error notification callback.
proc | The client's callback function. | |
context | Client-provided context for the callback. | |
limit | A limit on the number of notifications to be delivered. |
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.
options | A logical OR of global option bit-flag constants. |
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:
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:
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. |
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:
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:
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. |
void TXMPMeta< tStringObj >::SetObjectName | ( | tStringObj | name | ) |
SetObjectName()
assigns a name to this XMP object.
Retrieve this client-assigned name with GetObjectName()
.
name | The name as a string object. |
void TXMPMeta< tStringObj >::SetObjectName | ( | XMP_StringPtr | name | ) |
SetObjectName()
assigns a name to this XMP object.
Retrieve this client-assigned name with GetObjectName()
.
name | The name as a null-terminated UTF-8 string. |
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.
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:
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 be a simple property with an xml:lang
attribute. This is the simplest property setter. Use it for top-level simple properties, or after using the path composition functions in TXMPUtils
.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. |
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.
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. |
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.
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. |
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.
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. |
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.
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. |
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.
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. |
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.
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.
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. <<??>> |
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.
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.
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. |
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.
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
).