Main Page | Modules | Compound List | File List | Compound Members | File Members

TXMPMeta< tStringObj > Class Template Reference

Template class for the XMP Toolkit core services. More...

#include <TXMPMeta.hpp>

List of all members.

Public Member Functions

bool GetLocalizedText (XMP_StringPtr schemaNS, XMP_StringPtr altTextName, XMP_StringPtr genericLang, XMP_StringPtr specificLang, tStringObj *actualLang, tStringObj *itemValue, XMP_OptionBits *options) const
 GetLocalizedText returns information about a selected item in an alt-text array. The array item is selected according to the rules given above.

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. Creates an appropriate array item if necessary, and handles special cases for the x-default item.

void SetLocalizedText (XMP_StringPtr schemaNS, XMP_StringPtr altTextName, XMP_StringPtr genericLang, XMP_StringPtr specificLang, const tStringObj &itemValue, XMP_OptionBits options=0)
 This form of SetLocalizedText is a simple overload in the template that calls the above form passing itemValue.c_str().

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 ref and increments the ref count.

 TXMPMeta (XMPMetaRef xmpRef)
 Reconstruct an XMP object from an internal ref.

 TXMPMeta (XMP_StringPtr buffer, XMP_StringLen xmpSize)
 Construct an object and parse one buffer of RDF into it.

virtual ~TXMPMeta () throw ()
 Destructor, typical virtual destructor.

Functions for getting property values
The property value "getters" all take a property specification, The first two parameters are always 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 return a Boolean result telling if the property exists, and if it does they also return option flags describing the property. If the property exists and has a value, the string value is also returned. The string is Unicode in UTF-8 encoding. Arrays and the non-leaf levels of structs do not have values. The possible option flags that describe properties are:

  • kXMP_PropValueIsURI - The property value is a URI. It is serialized to RDF using the rdf:resource attribute. Not mandatory for URIs, but considered RDF-savvy.
  • kXMP_PropHasQualifiers - The property has qualifiers. These could be an xml:lang attribute, an rdf:type property, or a general qualifier. See the introductory discussion of qualified properties for more information.
  • kXMP_PropIsQualifier - This property is a qualifier for some other property. Note that if the qualifier itself has a structured value, this flag is only set for the top node of the qualifier's subtree. Qualifiers may have arbitrary structure, and may even have qualifiers.
  • kXMP_PropHasLang - This property has an xml:lang qualifier.
  • kXMP_PropHasType - This property has an rdf:type qualifier.
  • kXMP_PropValueIsStruct - This property contains nested fields (models a C struct).
  • kXMP_PropValueIsArray - This property is an array. By itself (no ...ArrayIs... flags), this indicates a general unordered array. It is serialized using an rdf:Bag container.
  • kXMP_PropArrayIsOrdered - This property is an ordered array. Appears in conjunction with kXMP_PropValueIsArray. It is serialized using an rdf:Seq container.
  • kXMP_PropArrayIsAlternate - This property is an alternative array. Appears in conjunction with kXMP_PropValueIsArray. It is serialized using an rdf:Alt container.
  • kXMP_PropArrayIsAltText - This property is an alt-text array. Appears in conjunction with kXMP_PropArrayIsAlternate. It is serialized using an rdf:Alt container. Each array element is a simple property with an xml:lang attribute.
  • kXMP_PropIsAlias - The given property name is an alias. This is only returned by GetProperty and then only if the property name is simple, not an path expression.
  • kXMP_PropHasAliases - The given property name has aliases. This is only returned by GetProperty and then only if the property name is simple, not an path expression.
  • kXMP_PropIsStable - The value of this property is not related to the document content.
  • kXMP_PropIsDerived - The value of this property is derived from the document content.
  • kXMP_PropIsInternal - The value of this property is "owned" by the application, it should not generally be editable in a UI.
  • kXMP_PropIsStale - This is a derived property and the document content is known to have changed since the property value was set.


bool GetProperty (XMP_StringPtr schemaNS, XMP_StringPtr propName, tStringObj *propValue, XMP_OptionBits *options) const
 GetProperty is the simplest property getter, mainly for top level simple properties or after using the path composition functions in TXMPUtils.

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. The index is passed as an integer, you need not worry about the path string syntax for array items, convert a loop index to a string, etc.

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. The namespace for the field is passed as a URI, you need not worry about the path string syntax.

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. The namespace for the qualifier is passed as a URI, you need not worry about the path string syntax. In many regards qualifiers are like struct fields. See the introductory discussion of qualified properties for more information.

Functions for setting property values
The property value "setters" all take a property specification, their differences are in the form of this. The first two parameters are always 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 string value for the property and option flags describing the property. The value must be Unicode in UTF-8 encoding. Arrays and non-leaf levels of structs do not have values. Empty arrays and structs may be created using appropriate option flags. All levels of structs that is assigned implicitly are created if necessary. AppendArayItem implicitly creates the named array if necessary.

The canonical form of these functions take the value as an XMP_StringPtr, a pointer to a null terminated string. (XMP_StringPtr is a typedef for const char *.) They also have overloaded forms that take a string object. These are implemented in the template instantiation as a call to the canonical form, using value.c_str() to obtain the XMP_StringPtr.

The possible option flags are:

  • kXMP_PropValueIsURI - The property value is a URI. It is serialized to RDF using the rdf:resource attribute. Not mandatory for URIs, but considered RDF-savvy.
  • kXMP_PropValueIsStruct - This property contains nested fields (models a C struct). Not necessary, may be used to create an empty struct. A struct is implicitly created when first field is set.
  • kXMP_PropValueIsArray - This property is an array. By itself (no ...ArrayIs... flags), this indicates a general unordered array. It is serialized using an rdf:Bag container.
  • kXMP_PropArrayIsOrdered - This property is an ordered array. Implies kXMP_PropValueIsArray, may be used together. It is serialized using an rdf:Seq container.
  • kXMP_PropArrayIsAlternate - This property is an alternative array. Implies kXMP_PropArrayIsOrdered, may be used together. It is serialized using an rdf:Alt container.
  • kXMP_PropArrayIsAltText - This property is an alt-text array. Implies kXMP_PropArrayIsAlternate, may be used together. It is serialized using an rdf:Alt container. Each array element must be a simple property with an xml:lang attribute.


void SetProperty (XMP_StringPtr schemaNS, XMP_StringPtr propName, XMP_StringPtr propValue, XMP_OptionBits options=0)
 SetProperty is the simplest property setter, mainly for top level simple properties or after using the path composition functions in TXMPUtils.

void SetProperty (XMP_StringPtr schemaNS, XMP_StringPtr propName, const tStringObj &propValue, XMP_OptionBits options=0)
 This form of SetProperty is a simple overload in the template that calls the above form passing propValue.c_str().

void SetArrayItem (XMP_StringPtr schemaNS, XMP_StringPtr arrayName, XMP_Index itemIndex, XMP_StringPtr itemValue, XMP_OptionBits options=0)
 SetArrayItem provides access to items within an array. The index is passed as an integer, you need not worry about the path string syntax for array items, convert a loop index to a string, etc. The array passed to SetArrayItem must already exist. See also AppendArrayItem.

void SetArrayItem (XMP_StringPtr schemaNS, XMP_StringPtr arrayName, XMP_Index itemIndex, const tStringObj &itemValue, XMP_OptionBits options=0)
 This form of SetArrayItem is a simple overload in the template that calls the above form passing itemValue.c_str().

void AppendArrayItem (XMP_StringPtr schemaNS, XMP_StringPtr arrayName, XMP_OptionBits arrayOptions, XMP_StringPtr itemValue, XMP_OptionBits itemOptions=0)
 AppendArrayItem 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. Each call to AppendArrayItem appends an item to the array. The corresponding parameters have the same use as SetArrayItem. The arrayOptions parameter is used to specify what kind of array. If the array exists, it must have the specified form.

void AppendArrayItem (XMP_StringPtr schemaNS, XMP_StringPtr arrayName, XMP_OptionBits arrayOptions, const tStringObj &itemValue, XMP_OptionBits itemOptions=0)
 This form of AppendArrayItem is a simple overload in the template that calls the above form passing itemValue.c_str().

void SetStructField (XMP_StringPtr schemaNS, XMP_StringPtr structName, XMP_StringPtr fieldNS, XMP_StringPtr fieldName, XMP_StringPtr fieldValue, XMP_OptionBits options=0)
 SetStructField provides access to fields within a nested structure. The namespace for the field is passed as a URI, you need not worry about the path string syntax.

void SetStructField (XMP_StringPtr schemaNS, XMP_StringPtr structName, XMP_StringPtr fieldNS, XMP_StringPtr fieldName, const tStringObj &fieldValue, XMP_OptionBits options=0)
 This form of SetStructField is a simple overload in the template that calls the above form passing fieldValue.c_str().

void SetQualifier (XMP_StringPtr schemaNS, XMP_StringPtr propName, XMP_StringPtr qualNS, XMP_StringPtr qualName, XMP_StringPtr qualValue, XMP_OptionBits options=0)
 SetQualifier provides access to a qualifier attached to a property. The namespace for the qualifier is passed as a URI, you need not worry about the path string syntax. In many regards qualifiers are like struct fields. See the introductory discussion of qualified properties for more information.

void SetQualifier (XMP_StringPtr schemaNS, XMP_StringPtr propName, XMP_StringPtr qualNS, XMP_StringPtr qualName, const tStringObj &qualValue, XMP_OptionBits options=0)
 This form of SetQualifier is a simple overload in the template that calls the above form passing qualValue.c_str().

Functions for deleting and detecting properties.
These should be obvious from the descriptions of the getters and setters.

void DeleteProperty (XMP_StringPtr schemaNS, XMP_StringPtr propName)
 DeleteProperty deletes the given XMP subtree rooted at the given property. It is not an error if the property does not exist.

void DeleteArrayItem (XMP_StringPtr schemaNS, XMP_StringPtr arrayName, XMP_Index itemIndex)
 DeleteArrayItem deletes the given XMP subtree rooted at the given array item. It is not an error if the array item does not exist.

void DeleteStructField (XMP_StringPtr schemaNS, XMP_StringPtr structName, XMP_StringPtr fieldNS, XMP_StringPtr fieldName)
 DeleteStructField deletes the given XMP subtree rooted at the given struct field. It is not an error if the field does not exist.

void DeleteQualifier (XMP_StringPtr schemaNS, XMP_StringPtr propName, XMP_StringPtr qualNS, XMP_StringPtr qualName)
 DeleteQualifier deletes the given XMP subtree rooted at the given qualifier. It is not an error if the qualifier does not exist.

bool DoesPropertyExist (XMP_StringPtr schemaNS, XMP_StringPtr propName) const
 DoesPropertyExist tells if the property exists.

bool DoesArrayItemExist (XMP_StringPtr schemaNS, XMP_StringPtr arrayName, XMP_Index itemIndex) const
 DoesArrayItemExist tells if the array item exists.

bool DoesStructFieldExist (XMP_StringPtr schemaNS, XMP_StringPtr structName, XMP_StringPtr fieldNS, XMP_StringPtr fieldName) const
 DoesStructFieldExist tells if the struct field exists.

bool DoesQualifierExist (XMP_StringPtr schemaNS, XMP_StringPtr propName, XMP_StringPtr qualNS, XMP_StringPtr qualName) const
 DoesQualifierExist tells if the qualifier exists.

Functions accessing properties as binary values.
These are very similar to GetProperty and SetProperty above, but the value is returned or provided in binary form instead of as a UTF-8 string. The path composition functions in TXMPUtils may be used to compose an path expression for fields in nested structures, items in arrays, or qualifiers.

bool GetProperty_Bool (XMP_StringPtr schemaNS, XMP_StringPtr propName, bool *propValue, XMP_OptionBits *options) const
 GetProperty_Bool returns the value of a Boolean property as a C++ bool.

bool GetProperty_Int (XMP_StringPtr schemaNS, XMP_StringPtr propName, long *propValue, XMP_OptionBits *options) const
 GetProperty_Int returns the value of an integer property as a C long integer.

bool GetProperty_Int64 (XMP_StringPtr schemaNS, XMP_StringPtr propName, long long *propValue, XMP_OptionBits *options) const
 GetProperty_Int64 returns 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 returns the value of a flaoting 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 returns the value of a date/time property as an XMP_DateTime struct.

void SetProperty_Bool (XMP_StringPtr schemaNS, XMP_StringPtr propName, bool propValue, XMP_OptionBits options=0)
 SetProperty_Bool sets the value of a Boolean property from a C++ bool.

void SetProperty_Int (XMP_StringPtr schemaNS, XMP_StringPtr propName, long propValue, XMP_OptionBits options=0)
 SetProperty_Int sets the value of an integer property from a C long integer.

void SetProperty_Int64 (XMP_StringPtr schemaNS, XMP_StringPtr propName, long long propValue, XMP_OptionBits options=0)
 SetProperty_Int64 sets the value of an integer property from 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 from 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 from an XMP_DateTime struct.

Misceallaneous functions.
XMPMetaRef GetInternalRef () const
 GetInternalRef Returns an internal reference that may be safely passed across DLL boundaries and reconstructed.

void GetObjectName (tStringObj *name) const
 GetObjectName --TBD--.

void SetObjectName (XMP_StringPtr name)
 SetObjectName --TBD--.

void SetObjectName (tStringObj name)
 SetObjectName --TBD--.

XMP_OptionBits GetObjectOptions () const
 GetObjectOptions --TBD--.

void SetObjectOptions (XMP_OptionBits options)
 SetObjectOptions --TBD--.

TXMPMeta Clone (XMP_OptionBits options=0) const
 Clone creates a deep clone of the XMP object.

XMP_Index CountArrayItems (XMP_StringPtr schemaNS, XMP_StringPtr arrayName) const
 CountArrayItems --TBD--.

void MarkStaleProperties (XMP_OptionBits options=0)
 MarkStaleProperties --TBD--.

XMP_Status DumpObject (XMP_TextOutputProc outProc, void *refCon) const
 DumpObject dumps the content of an XMP object.

Functions for parsing and serializing.
These functions support parsing serialized RDF into an XMP object, and serailizing an XMP object into RDF. The input for parsing may 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. The buffers may be any length. The buffer boundaries need not respect XML tokens or even Unicode characters.

void SerializeToBuffer (tStringObj *rdfString, XMP_OptionBits options, XMP_StringLen padding, XMP_StringPtr newline, XMP_StringPtr indent="", XMP_Index baseIndent=0) const
 SerializeToBuffer serializes an XMP object into a string as RDF.

void SerializeToBuffer (tStringObj *rdfString, XMP_OptionBits options=0, XMP_StringLen padding=0) const
 This form of SerializeToBuffer is a simple overload in the template that calls the above form passing default values for the newline, indent, and baseIndent parameters.


Static Public Member Functions

void RegisterPropertyTraits (XMP_StringPtr schemaNS, XMP_StringPtr propName, XMP_OptionBits options)
 Registers special traits for a property.

Initialization and termination
void GetVersionInfo (XMP_VersionInfo *info)
 Obtain version information.

bool Initialize (XMP_AllocateProc AllocateProc=0, XMP_DeleteProc DeleteProc=0)
 Initialize the XMP Toolkit.

void Terminate ()
 Terminate the XMP Toolkit.

Global option flags
The global option flags affect the overall behavior of the XMP Toolkit. The available options are declared in XMP_Const.h. (There are none at present.)

XMP_OptionBits GetGlobalOptions ()
 GetGlobalOptions returns the set of global option flags.

void SetGlobalOptions (XMP_OptionBits options)
 SetGlobalOptions updates the set of global option flags. The entire set is replaced with the new values. If only one flag is to be modified, use GetGlobalOptions to obtain the current set, modify the desired flag, then use SetGlobalOptions.

void GetMemProcs (XMP_AllocateProc *AllocateProc, XMP_DeleteProc *DeleteProc)
 GetMemProcs returns the internal memory allocation routines used by XMP. These are either standard C malloc and free, or those passed to Initialize. This is not intended as a general client utility. It is a utility for DLLs layered on top of XMP, so they can use the same client provided memory routines, if any.

Assert failure notifications
void RegisterAssertNotify (XMP_AssertNotifyProc notifyProc, void *refCon)
 RegisterAssertNotify registers a callback function to provide user notification of debugging assertion failures. See the XMP_AssertNotifyProc declaration in XMP_Const.h for more information.

void UnregisterAssertNotify (XMP_AssertNotifyProc notifyProc)
 UnregisterAssertNotify unregisters a notification function if it is the active one. Passing a null pointer unregisters any active notification function.

void SendAssertNotify (XMP_StringPtr message)
 SendAssertNotify sends an assert notification with the given message. This is not intended as a general client utility. It is a utility for DLLs layered on top of XMP, allowing them to support assert notifications without forcing the client app to separately register the callback.

Internal data structure dump utilities
These are debugging utilities that dump internal data structures. The output callback is described in XMP_Const.h.

XMP_Status DumpNamespaces (XMP_TextOutputProc outProc, void *refCon)
 DumpNamespaces dumps the list of registered namespace URIs and prefixes.

XMP_Status DumpAliases (XMP_TextOutputProc outProc, void *refCon)
 DumpAliases dumps the list of registered aliases and corresponding actuals.

XMP_Status DumpPropertyTraits (XMP_TextOutputProc outProc, void *refCon)
 DumpPropertyTraits dumps the list of registered property traits.

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.

bool RegisterNamespace (XMP_StringPtr namespaceURI, XMP_StringPtr suggestedPrefix, tStringObj *registeredPrefix)
 Register a namespace URI with a suggested prefix.

bool GetNamespacePrefix (XMP_StringPtr namespaceURI, tStringObj *namespacePrefix)
 Obtain the prefix for a registered namespace URI.

bool GetNamespaceURI (XMP_StringPtr namespacePrefix, tStringObj *namespaceURI)
 Obtain the URI for a registered namespace prefix.

void DeleteNamespace (XMP_StringPtr namespaceURI)
 Delete a namespace from the registry.

Alias Functions
Aliases in XMP serve the same purpose as Windows file shortcuts, Macintosh file aliases, or UNIX file symbolic links. The aliases are simply multiple names for the same property. One distinction of XMP aliases is that they are ordered, there is an alias name pointing to an actual name. The primary significance of the actual name is that it is the preferred name for output, generally the most widely recognized name.

The names that can be aliased in XMP are restricted. The alias must be a top level property name, not a field within a structure or an element within an array. The actual may be a top level property name, the first element within a top level array, or the default element in an alt-text array. This does not mean the alias can only be a simple property. It is OK to alias a top level structure or array to an identical top level structure or array, or to the first item of an array of structures.

void RegisterAlias (XMP_StringPtr aliasNS, XMP_StringPtr aliasProp, XMP_StringPtr actualNS, XMP_StringPtr actualProp, XMP_OptionBits arrayForm=kXMP_NoOptions)
 Associates an alias name with an actual name.

bool ResolveAlias (XMP_StringPtr aliasNS, XMP_StringPtr aliasProp, tStringObj *actualNS, tStringObj *actualProp, XMP_OptionBits *arrayForm)
 Determines if a name is an alias, and what it is aliased to.

void DeleteAlias (XMP_StringPtr aliasNS, XMP_StringPtr aliasProp)
 Delete an alias.

void RegisterStandardAliases (XMP_StringPtr schemaNS)
 Registers all of the built-in aliases for a standard namespace.


Detailed Description

template<class tStringObj>
class TXMPMeta< tStringObj >

Template class for 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. Please read the general toolkit usage notes for information about the overall architecture of the XMP API.

This template wraps a string object class around the raw XMP API. This provides two significant benefits, output strings are automatically copied and access is fully thread safe. The umbrella header, XMP.hpp, provides an SXMPMeta typedef for the instantiated template. String objects are only necessary for output strings. Input string are literals and passed as typical C const char *.

The template parameter, class tStringObj, must have the following member functions (which match those for std::string):

     tStringObj& assign ( const char * str, size_t len )
     size_t size() const
     const char * c_str() const

Be aware that 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 even 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. There is 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 GetInternalRef 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 );


Constructor & Destructor Documentation

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

Default constructor, creates an empty object.

The default constructor creates a new empty TXMPMeta 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.

template<class tStringObj>
TXMPMeta< tStringObj >::TXMPMeta XMPMetaRef  xmpRef  ) 
 

Reconstruct an XMP object from an internal ref.

This constructor creates a new TXMPMeta object that refers to the underlying xmpRef, which was obtained from some other XMP object by the GetInternalRef method. This is used to safely pass XMP objects across DLL boundaries.

template<class tStringObj>
TXMPMeta< tStringObj >::TXMPMeta XMP_StringPtr  buffer,
XMP_StringLen  xmpSize
 

Construct 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. Pass (0,0) to construct an empty TXMPMeta object. The result of an actual parse is identical to creating an empty object then calling TXMPMeta::ParseFromBuffer. The RDF must be complete. If you need to parse with multiple buffers, create an empty object and use TXMPMeta::ParseFromBuffer.

Parameters:
buffer A pointer to the buffer of RDF to be parsed. May be null if the length is 0.
xmpSize The length in bytes of the buffer.


Member Function Documentation

template<class tStringObj>
void TXMPMeta< tStringObj >::AppendArrayItem XMP_StringPtr  schemaNS,
XMP_StringPtr  arrayName,
XMP_OptionBits  arrayOptions,
XMP_StringPtr  itemValue,
XMP_OptionBits  itemOptions = 0
 

AppendArrayItem 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. Each call to AppendArrayItem appends an item to the array. The corresponding parameters have the same use as SetArrayItem. The arrayOptions parameter is used to specify what kind of array. If the array exists, it must have the specified form.

Parameters:
schemaNS The namespace URI for the array. Has the same usage as in GetProperty.
arrayName The name of the array. May be a general path expression, must not be null or the empty string. Has the same namespace prefix usage as propPath in GetProperty.
arrayOptions Option flags describing the array form. The only valid bits are those that are part of kXMP_PropArrayFormMask: kXMP_PropValueIsArray, kXMP_PropArrayIsOrdered, kXMP_PropArrayIsAlternate, or kXMP_PropArrayIsAltText.
itemValue A pointer to the null terminated UTF-8 string that is the value of the array item, if the array item has a value. Has the same usage as propValue in GetProperty.
itemOptions Option flags describing the item. See the earlier description.

template<class tStringObj>
TXMPMeta TXMPMeta< tStringObj >::Clone XMP_OptionBits  options = 0  )  const
 

Clone creates a deep clone of the XMP object.

This function creates a deep clone of the XMP object. Assignment and copy constructors do not, they just increment a reference count. Note that Clone returns an object, not a pointer. This is easy to misuse:

            SXMPMeta * clone1 = &sourceXMP.Clone();                  // ! This does not work!
            SXMPMeta * clone2 = new SXMPMeta ( sourceXMP.Clone() );  // This works.
            SXMPMeta   clone3 ( sourceXMP.Clone );  // This works also. (Not a pointer.)

In the code above, the assignment to clone1 creates a temporary object, initializes it with the clone, assigns the address of the temporary to clone1, then deletes the temporary. The clone3 example also works, you do not have to use an explicit pointer. This is good for local usage, you don't have to worry about memory leaks.

Parameters:
options Option flags, not are defined at present.
Returns:
An XMP object cloned from the original.

template<class tStringObj>
void TXMPMeta< tStringObj >::DeleteAlias XMP_StringPtr  aliasNS,
XMP_StringPtr  aliasProp
[static]
 

Delete an alias.

This only deletes the registration of the alias, it does not delete the actual property. It does delete any view of the property through the alias name. It is OK to attempt to delete an alias that does not exist, that is if the alias name is not registered as an alias.

Parameters:
aliasNS The namespace URI for the alias. Must not be null or the empty string.
aliasProp The name of the alias. Must be a simple name, not null or the empty string and not a general path expression.

template<class tStringObj>
void TXMPMeta< tStringObj >::DeleteArrayItem XMP_StringPtr  schemaNS,
XMP_StringPtr  arrayName,
XMP_Index  itemIndex
 

DeleteArrayItem deletes the given XMP subtree rooted at the given array item. It is not an error if the array item does not exist.

Parameters:
schemaNS The namespace URI for the array. Has the same usage as in GetProperty.
arrayName The name of the array. May be a general path expression, must not be null or the empty string. Has the same namespace prefix usage as propName in GetProperty.
itemIndex The index of the desired item. Arrays in XMP are indexed from 1. The constant kXMP_ArrayLastItem always refers to the last existing array item.

template<class tStringObj>
void TXMPMeta< tStringObj >::DeleteNamespace XMP_StringPtr  namespaceURI  )  [static]
 

Delete a namespace from the registry.

Does nothing if the URI is not registered, or if the namespaceURI parameter is null or the empty string.

Parameters:
namespaceURI The URI for the namespace.
Note:
Not yet implemented.

template<class tStringObj>
void TXMPMeta< tStringObj >::DeleteProperty XMP_StringPtr  schemaNS,
XMP_StringPtr  propName
 

DeleteProperty deletes the given XMP subtree rooted at the given property. It is not an error if the property does not exist.

Parameters:
schemaNS The namespace URI for the property. Has the same usage as in GetProperty.
propName The name of the property. Has the same usage as in GetProperty.

template<class tStringObj>
void TXMPMeta< tStringObj >::DeleteQualifier XMP_StringPtr  schemaNS,
XMP_StringPtr  propName,
XMP_StringPtr  qualNS,
XMP_StringPtr  qualName
 

DeleteQualifier deletes the given XMP subtree rooted at the given qualifier. It is not an error if the qualifier does not exist.

Parameters:
schemaNS The namespace URI for the struct. Has the same usage as in GetProperty.
propName The name of the property to which the qualifier is attached. Has the same usage as in GetProperty.
qualNS The namespace URI for the qualifier. Has the same URI and prefix usage as the schemaNS parameter.
qualName The name of the qualifier. Must be a single XML name, must not be null or the empty string. Has the same namespace prefix usage as the propName parameter.

template<class tStringObj>
void TXMPMeta< tStringObj >::DeleteStructField XMP_StringPtr  schemaNS,
XMP_StringPtr  structName,
XMP_StringPtr  fieldNS,
XMP_StringPtr  fieldName
 

DeleteStructField deletes the given XMP subtree rooted at the given struct field. It is not an error if the field does not exist.

Parameters:
schemaNS The namespace URI for the struct. Has the same usage as in GetProperty.
structName The name of the struct. May be a general path expression, must not be null or the empty string. Has the same namespace prefix usage as propName in GetProperty.
fieldNS The namespace URI for the field. Has the same URI and prefix usage as the schemaNS parameter.
fieldName The name of the field. Must be a single XML name, must not be null or the empty string. Has the same namespace prefix usage as the structName parameter.

template<class tStringObj>
bool TXMPMeta< tStringObj >::DoesArrayItemExist XMP_StringPtr  schemaNS,
XMP_StringPtr  arrayName,
XMP_Index  itemIndex
const
 

DoesArrayItemExist tells if the array item exists.

Returns:
Returns true if the array item exists.
Parameters:
schemaNS The namespace URI for the array. Has the same usage as in GetProperty.
arrayName The name of the array. May be a general path expression, must not be null or the empty string. Has the same namespace prefix usage as propName in GetProperty.
itemIndex The index of the desired item. Arrays in XMP are indexed from 1. The constant kXMP_ArrayLastItem always refers to the last existing array item.

template<class tStringObj>
bool TXMPMeta< tStringObj >::DoesPropertyExist XMP_StringPtr  schemaNS,
XMP_StringPtr  propName
const
 

DoesPropertyExist tells if the property exists.

Returns:
Returns true if the property exists.
Parameters:
schemaNS The namespace URI for the property. Has the same usage as in GetProperty.
propName The name of the property. Has the same usage as in GetProperty.

template<class tStringObj>
bool TXMPMeta< tStringObj >::DoesQualifierExist XMP_StringPtr  schemaNS,
XMP_StringPtr  propName,
XMP_StringPtr  qualNS,
XMP_StringPtr  qualName
const
 

DoesQualifierExist tells if the qualifier exists.

Returns:
Returns true if the qualifier exists.
Parameters:
schemaNS The namespace URI for the struct. Has the same usage as in GetProperty.
propName The name of the property to which the qualifier is attached. Has the same usage as in GetProperty.
qualNS The namespace URI for the qualifier. Has the same URI and prefix usage as the schemaNS parameter.
qualName The name of the qualifier. Must be a single XML name, must not be null or the empty string. Has the same namespace prefix usage as the propName parameter.

template<class tStringObj>
bool TXMPMeta< tStringObj >::DoesStructFieldExist XMP_StringPtr  schemaNS,
XMP_StringPtr  structName,
XMP_StringPtr  fieldNS,
XMP_StringPtr  fieldName
const
 

DoesStructFieldExist tells if the struct field exists.

Returns:
Returns true if the field exists.
Parameters:
schemaNS The namespace URI for the struct. Has the same usage as in GetProperty.
structName The name of the struct. May be a general path expression, must not be null or the empty string. Has the same namespace prefix usage as propName in GetProperty.
fieldNS The namespace URI for the field. Has the same URI and prefix usage as the schemaNS parameter.
fieldName The name of the field. Must be a single XML name, must not be null or the empty string. Has the same namespace prefix usage as the structName parameter.

template<class tStringObj>
XMP_Status TXMPMeta< tStringObj >::DumpPropertyTraits XMP_TextOutputProc  outProc,
void *  refCon
[static]
 

DumpPropertyTraits dumps the list of registered property traits.

Note:
Not yet implemented.

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. The index is passed as an integer, you need not worry about the path string syntax for array items, convert a loop index to a string, etc.

Returns:
Returns true if the array item exists.
Parameters:
schemaNS The namespace URI for the array. Has the same usage as in GetProperty.
arrayName The name of the array. May be a general path expression, must not be null or the empty string. Has the same namespace prefix usage as propName in GeProperty.
itemIndex The index of the desired item. Arrays in XMP are indexed from 1. The constant kXMP_ArrayLastItem always refers to the last existing array item.
itemValue A pointer to the string that is assigned the value of the array item, if the array item has a value. Arrays and non-leaf levels of structs do not have values. May be null if the value is not wanted.
options A pointer to the XMP_OptionBits variable that is assigned option flags describing the array item. May be null if the flags are not wanted.

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 returns information about a selected item in an alt-text array. The array item is selected according to the rules given above.

Returns:
Returns true if an appropriate array item exists.
Parameters:
schemaNS The namespace URI for the alt-text array. Has the same usage as in GetProperty.
altTextName The name of the alt-text array. May be a general path expression, must not be null or the empty string. Has the same namespace prefix usage as propName in GetProperty.
genericLang The name of the generic language as an RFC 3066 primary subtag. May be null or the empty string if no generic language is wanted.
specificLang The name of the specific language as an RFC 3066 tag. Must not be null or the empty string.
actualLang A pointer to the string that is assigned the language of the selected array item, if an appropriate array item is found. May be null if the language is not wanted.
itemValue A pointer to the string that is assigned the value of the array item, if an appropriate array item is found. May be null if the value is not wanted.
options A pointer to the XMP_OptionBits variable that is assigned option flags describing the array item. May be null if the flags are not wanted.

template<class tStringObj>
bool TXMPMeta< tStringObj >::GetNamespacePrefix XMP_StringPtr  namespaceURI,
tStringObj *  namespacePrefix
[static]
 

Obtain the prefix for a registered namespace URI.

It is not an error if the namespace URI is not registered. The output namespacePrefix string is not modified if the namespace URI is not registered.

Parameters:
namespaceURI The URI for the namespace. Must not be null or the empty string.
namespacePrefix Returns the prefix registered for this URI, with a terminating ':'.
Returns:
Returns true if the namespace URI is registered.

template<class tStringObj>
bool TXMPMeta< tStringObj >::GetNamespaceURI XMP_StringPtr  namespacePrefix,
tStringObj *  namespaceURI
[static]
 

Obtain the URI for a registered namespace prefix.

It is not an error if the namespace prefix is not registered. The output namespaceURI string is not modified if the namespace prefix is not registered.

Parameters:
namespacePrefix The prefix for the namespace. Must not be null or the empty string.
namespaceURI Returns the URI registered for this prefix.
Returns:
Returns true if the namespace prefix is registered.

template<class tStringObj>
bool TXMPMeta< tStringObj >::GetProperty XMP_StringPtr  schemaNS,
XMP_StringPtr  propName,
tStringObj *  propValue,
XMP_OptionBits options
const
 

GetProperty is the simplest property getter, mainly for top level simple properties or after using the path composition functions in TXMPUtils.

Returns:
Returns true if the property exists.
Parameters:
schemaNS The namespace URI for the property. May be null or the empty string if the first component of the propName path contains a namespace prefix. The URI must be for a registered namespace.
propName The name of the property. May be a general path expression, must not be null or the empty string. Using a namespace prefix on the first component is optional. If present without a schemaNS value then the prefix specifies the namespace. The prefix must be for a registered namespace. If both a schemaNS URI and propName prefix are present, they must be corresponding parts of a registered namespace.
propValue A pointer to the string that is assigned the value of the property, if the property has a value. Arrays and non-leaf levels of structs do not have values. May be null if the value is not wanted.
options A pointer to the XMP_OptionBits variable that is assigned option flags describing the property. May be null if the flags are not wanted.

template<class tStringObj>
bool TXMPMeta< tStringObj >::GetProperty_Bool XMP_StringPtr  schemaNS,
XMP_StringPtr  propName,
bool *  propValue,
XMP_OptionBits options
const
 

GetProperty_Bool returns the value of a Boolean property as a C++ bool.

Returns:
Returns true if the property exists.
Parameters:
schemaNS The namespace URI for the property. Has the same usage as in GetProperty.
propName The name of the property. Has the same usage as in GetProperty.
propValue A pointer to the bool variable that is assigned the value of the property. May be null if the value is not wanted.
options A pointer to the XMP_OptionBits variable that is assigned option flags describing the property. May be null if the flags are not wanted.

template<class tStringObj>
bool TXMPMeta< tStringObj >::GetProperty_Date XMP_StringPtr  schemaNS,
XMP_StringPtr  propName,
XMP_DateTime propValue,
XMP_OptionBits options
const
 

GetProperty_Date returns the value of a date/time property as an XMP_DateTime struct.

Returns:
Returns true if the property exists.
Parameters:
schemaNS The namespace URI for the property. Has the same usage as in GetProperty.
propName The name of the property. Has the same usage as in GetProperty.
propValue A pointer to the XMP_DateTime variable that is assigned the value of the property. May be null if the value is not wanted.
options A pointer to the XMP_OptionBits variable that is assigned option flags describing the property. May be null if the flags are not wanted.

template<class tStringObj>
bool TXMPMeta< tStringObj >::GetProperty_Float XMP_StringPtr  schemaNS,
XMP_StringPtr  propName,
double *  propValue,
XMP_OptionBits options
const
 

GetProperty_Float returns the value of a flaoting point property as a C double float.

Returns:
Returns true if the property exists.
Parameters:
schemaNS The namespace URI for the property. Has the same usage as in GetProperty.
propName The name of the property. Has the same usage as in GetProperty.
propValue A pointer to the double float variable that is assigned the value of the property. May be null if the value is not wanted.
options A pointer to the XMP_OptionBits variable that is assigned option flags describing the property. May be null if the flags are not wanted.

template<class tStringObj>
bool TXMPMeta< tStringObj >::GetProperty_Int XMP_StringPtr  schemaNS,
XMP_StringPtr  propName,
long *  propValue,
XMP_OptionBits options
const
 

GetProperty_Int returns the value of an integer property as a C long integer.

Returns:
Returns true if the property exists.
Parameters:
schemaNS The namespace URI for the property. Has the same usage as in GetProperty.
propName The name of the property. Has the same usage as in GetProperty.
propValue A pointer to the long integer variable that is assigned the value of the property. May be null if the value is not wanted.
options A pointer to the XMP_OptionBits variable that is assigned option flags describing the property. May be null if the flags are not wanted.

template<class tStringObj>
bool TXMPMeta< tStringObj >::GetProperty_Int64 XMP_StringPtr  schemaNS,
XMP_StringPtr  propName,
long long *  propValue,
XMP_OptionBits options
const
 

GetProperty_Int64 returns the value of an integer property as a C long long integer.

Returns:
Returns true if the property exists.
Parameters:
schemaNS The namespace URI for the property. Has the same usage as in GetProperty.
propName The name of the property. Has the same usage as in GetProperty.
propValue A pointer to the long long integer variable that is assigned the value of the property. May be null if the value is not wanted.
options A pointer to the XMP_OptionBits variable that is assigned option flags describing the property. May be null if the flags are not wanted.

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. The namespace for the qualifier is passed as a URI, you need not worry about the path string syntax. In many regards qualifiers are like struct fields. See the introductory discussion of qualified properties for more information.

The names of qualifiers should be XML qualified names, that is within an XML namespace. The path syntax for a qualified name uses the namespace prefix. This is unreliable since the prefix is never guaranteed. The URI is the formal name, the prefix is just a local shorthand in a given sequence of XML text.

Note:
Qualifiers are only supported for simple leaf properties at this time.
Returns:
Returns true if the qualifier exists.
Parameters:
schemaNS The namespace URI for the struct. Has the same usage as in GetProperty.
propName The name of the property to which the qualifier is attached. May be a general path expression, must not be null or the empty string. Has the same namespace prefix usage as in GetProperty.
qualNS The namespace URI for the qualifier. Has the same URI and prefix usage as the schemaNS parameter.
qualName The name of the qualifier. Must be a single XML name, must not be null or the empty string. Has the same namespace prefix usage as the propName parameter.
qualValue A pointer to the string that is assigned the value of the qualifier, if the qualifier has a value. Arrays and non-leaf levels of structs do not have values. May be null if the value is not wanted.
options A pointer to the XMP_OptionBits variable that is assigned option flags describing the qualifier. May be null if the flags are not wanted.

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. The namespace for the field is passed as a URI, you need not worry about the path string syntax.

The names of fields should be XML qualified names, that is within an XML namespace. The path syntax for a qualified name uses the namespace prefix. This is unreliable since the prefix is never guaranteed. The URI is the formal name, the prefix is just a local shorthand in a given sequence of XML text.

Returns:
Returns true if the field exists.
Parameters:
schemaNS The namespace URI for the struct. Has the same usage as in GetProperty.
structName The name of the struct. May be a general path expression, must not be null or the empty string. Has the same namespace prefix usage as propName in GetProperty.
fieldNS The namespace URI for the field. Has the same URI and prefix usage as the schemaNS parameter.
fieldName The name of the field. Must be a single XML name, must not be null or the empty string. Has the same namespace prefix usage as the structName parameter.
fieldValue A pointer to the string that is assigned the value of the field, if the field has a value. Arrays and non-leaf levels of structs do not have values. May be null if the value is not wanted.
options A pointer to the XMP_OptionBits variable that is assigned option flags describing the field. May be null if the flags are not wanted.

template<class tStringObj>
bool TXMPMeta< tStringObj >::Initialize XMP_AllocateProc  AllocateProc = 0,
XMP_DeleteProc  DeleteProc = 0
[static]
 

Initialize the XMP Toolkit.

The XMP Toolkit may be explicitly initialized before use. The allocate/delete parameters must be either both null (0), or both non-null.

template<class tStringObj>
void TXMPMeta< tStringObj >::MarkStaleProperties XMP_OptionBits  options = 0  ) 
 

MarkStaleProperties --TBD--.

Note:
Not yet implemented.

template<class tStringObj>
void TXMPMeta< tStringObj >::operator= const TXMPMeta< tStringObj > &  rhs  ) 
 

Assignment operator, assigns the internal ref and increments the ref 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. The buffers may be any length. The buffer boundaries need not respect XML tokens or even Unicode characters.

Parameters:
buffer A pointer to a buffer of input. May be null if bufferSize is 0.
bufferSize The length of this buffer in bytes. Zero is a valid value. Termination of an input loop is convenient by passing kXMP_ParseMoreBuffers for all real input, then having a final call with a zero length and kXMP_NoOptions.
options Options controlling the parsing.
The available options are:

  • kXMP_ParseMoreBuffers - This is not the last buffer of input, more calls follow.
  • kXMP_RequireXMPMeta - The x:xmpmeta XML element is required around rdf:RDF.
  • kXMP_StrictAliasing - Do not reconcile alias differences, throw an exception.
Note:
The kXMP_StrictAliasing option is not yet implemented.

template<class tStringObj>
void TXMPMeta< tStringObj >::RegisterAlias XMP_StringPtr  aliasNS,
XMP_StringPtr  aliasProp,
XMP_StringPtr  actualNS,
XMP_StringPtr  actualProp,
XMP_OptionBits  arrayForm = kXMP_NoOptions
[static]
 

Associates an alias name with an actual name.

Define a alias mapping from one namespace/property to another. Both property names must be simple names. An alias can be a direct mapping, where the alias and actual have the same data type. It is also possible to map a simple alias to an item in an array. This can either be to the first item in the array, or to the 'x-default' item in an alt-text array. Multiple alias names may map to the same actual, as long as the forms match. It is a no-op to reregister an alias in an identical fashion.

Parameters:
aliasNS The namespace URI for the alias. Must not be null or the empty string.
aliasProp The name of the alias. Must be a simple name, not null or the empty string and not a general path expression.
actualNS The namespace URI for the actual. Must not be null or the empty string.
actualProp The name of the actual. Must be a simple name, not null or the empty string and not a general path expression.
arrayForm Provides the array form for simple aliases to an array item. This is needed to know what kind of array to create if set for the first time via the simple alias. Pass kXMP_NoOptions, the default value, for all direct aliases regardless of whether the actual data type is an array or not.
Constants for the arrayForm parameter:

  • kXMP_NoOptions - This is a direct mapping. The actual data type does not matter.
  • kXMP_PropValueIsArray - The actual is an unordered array, the alias is to the first element of the array.
  • kXMP_PropArrayIsOrdered - The actual is an ordered array, the alias is to the first element of the array.
  • kXMP_PropArrayIsAlternate - The actual is an alternate array, the alias is to the first element of the array.
  • kXMP_PropArrayIsAltText - The actual is an alternate text array, the alias is to the 'x-default' element of the array.

template<class tStringObj>
bool TXMPMeta< tStringObj >::RegisterNamespace XMP_StringPtr  namespaceURI,
XMP_StringPtr  suggestedPrefix,
tStringObj *  registeredPrefix
[static]
 

Register a namespace URI with a suggested prefix.

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

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 Returns the prefix actually registered for this URI.
Returns:
Returns true if the registered prefix matches the suggested prefix.
Note:
No checking is presently done on either the URI or the prefix.

template<class tStringObj>
void TXMPMeta< tStringObj >::RegisterPropertyTraits XMP_StringPtr  schemaNS,
XMP_StringPtr  propName,
XMP_OptionBits  options
[static]
 

Registers special traits for a property.

A property may have a variety of special traits

Parameters:
schemaNS The namespace URI for the property. Must not be null or the empty string.
propName The name of the property. May be a general path expression, must not be null or the empty string.
options Flags for the traits to be applied to this property.
Note:
Not yet implemented.

template<class tStringObj>
void TXMPMeta< tStringObj >::RegisterStandardAliases XMP_StringPtr  schemaNS  )  [static]
 

Registers all of the built-in aliases for a standard namespace.

The built-in aliases are documented in the XMP Specification. This registers the aliases in the given namespace, that is the aliases from this namespace to actuals in other namespaces.

Parameters:
schemaNS The namespace URI for the aliases. Must not be null or the empty string.

template<class tStringObj>
bool TXMPMeta< tStringObj >::ResolveAlias XMP_StringPtr  aliasNS,
XMP_StringPtr  aliasProp,
tStringObj *  actualNS,
tStringObj *  actualProp,
XMP_OptionBits arrayForm
[static]
 

Determines if a name is an alias, and what it is aliased to.

Parameters:
aliasNS The namespace URI for the alias. Must not be null or the empty string.
aliasProp The name of the alias. May be an arbitrary path expression path, must not null or the empty string.
actualNS Untouched if aliasNS:aliasProp is not an alias. Otherwise returns the namespace URI for the actual. May be null if the namespace URI is not wanted.
actualProp Untouched if aliasNS:aliasProp is not an alias. Otherwise returns the path of the actual. May be null if the actual's path is not wanted.
arrayForm Untouched if aliasNS:aliasProp is not an alias. Otherwise returns the form of the actual. This is 0 (kXMP_NoOptions) if the alias and actual forms match, otherwise it is the options passed to TXMPMeta::RegisterAlias. May be null if the actual's form is not wanted.
Returns:
Returns true if the input is an alias.
Note:
The client output strings are not written until return, so a call like the following may be used to "reduce" a path to the base form:
         isAlias = SXMPMeta::ResolveAlias ( ns.c_str(), path.c_str(), &ns, &path, 0 );

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 an XMP object into a string as RDF.

Parameters:
rdfString A pointer to the string to receive the serialized RDF. Must not be null.
options Option flags to control the serialization.
padding The amount of padding to be added if a writeable XML packet is created. If zero is passed (the default) an appropriate amount of padding is computed.
newline The string to be used as a line terminator. If empty it 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 it 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.
The available option flags are:

  • kXMP_OmitPacketWrapper - Do not include an XML packet wrapper.
  • kXMP_ReadOnlyPacket - Create a read-only XML packet wapper.
  • kXMP_UseCompactFormat - Use a highly compact RDF syntax and layout.
  • kXMP_WriteAliasComments - Include XML comments for aliases.
  • kXMP_IncludeThumbnailPad - Include typical space for a JPEG thumbnail in the padding if no xmp:Thumbnails property is present.
  • 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.
The specified options must be logically consistent, an exception is thrown if not. You cannot specify both kXMP_OmitPacketWrapper along with kXMP_ReadOnlyPacket, kXMP_IncludeThumbnailPad, or kXMP_ExactPacketLength.

In addition, one of the following encoding options may be included:

  • kXMP_EncodeUTF8 - Encode as UTF-8, the default.
  • kXMP_EncodeUTF16Big - Encode as big-endian UTF-16.
  • kXMP_EncodeUTF16Little - Encode as little-endian UTF-16.
  • kXMP_EncodeUTF32Big - Encode as big-endian UTF-32.
  • kXMP_EncodeUTF32Little - Encode as little-endian UTF-32.

template<class tStringObj>
void TXMPMeta< tStringObj >::SetArrayItem XMP_StringPtr  schemaNS,
XMP_StringPtr  arrayName,
XMP_Index  itemIndex,
XMP_StringPtr  itemValue,
XMP_OptionBits  options = 0
 

SetArrayItem provides access to items within an array. The index is passed as an integer, you need not worry about the path string syntax for array items, convert a loop index to a string, etc. The array passed to SetArrayItem must already exist. See also AppendArrayItem.

In normal usage the selected array item is modified. A new item is automatically appended if the index is the array size plus 1. A new item may be inserted before or after any item by using one of the following option flags:

  • kXMP_InsertBeforeItem - Insert a new array item before the selected one.
  • kXMP_InsertAfterItem - Insert a new array item after the selected one.
Parameters:
schemaNS The namespace URI for the array. Has the same usage as in GetProperty.
arrayName The name of the array. May be a general path expression, must not be null or the empty string. Has the same namespace prefix usage as propName in GetProperty.
itemIndex The index of the desired item. Arrays in XMP are indexed from 1. The constant kXMP_ArrayLastItem always refers to the last existing array item.
itemValue A pointer to the null terminated UTF-8 string that is the value of the array item, if the array item has a value. Has the same usage as propValue in GetProperty.
options Option flags describing the item. See the earlier description.

template<class tStringObj>
void TXMPMeta< tStringObj >::SetGlobalOptions XMP_OptionBits  options  )  [static]
 

SetGlobalOptions updates the set of global option flags. The entire set is replaced with the new values. If only one flag is to be modified, use GetGlobalOptions to obtain the current set, modify the desired flag, then use SetGlobalOptions.

Note:
There are no options to set yet.

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.

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. Has the same usage as in GetProperty.
altTextName The name of the alt-text array. May be a general path expression, must not be null or the empty string. Has the same namespace prefix usage as propName in GetProperty.
genericLang The name of the generic language as an RFC 3066 primary subtag. May be null or the empty string if no generic language is wanted.
specificLang The name of the specific language as an RFC 3066 tag. Must not be null or the empty string.
itemValue A pointer to the null terminated UTF-8 string that is the new value for the appropriate array item.
options Option flags, none are defined at present.

template<class tStringObj>
void TXMPMeta< tStringObj >::SetObjectOptions XMP_OptionBits  options  ) 
 

SetObjectOptions --TBD--.

Note:
Not yet implemented. File a bug if you need this.

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

SetProperty is the simplest property setter, mainly for top level simple properties or after using the path composition functions in TXMPUtils.

Parameters:
schemaNS The namespace URI for the property. Has the same usage as in GetProperty.
propName The name of the property. Has the same usage as in GetProperty.
propValue A pointer to the null terminated UTF-8 string that is the value of the property, if the property has a value. Arrays and non-leaf levels of structs do not have values. Must be null if the value is not relevant.
options Option flags describing the property. See the earlier description.

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 from a C++ bool.

Parameters:
schemaNS The namespace URI for the property. Has the same usage as in GetProperty.
propName The name of the property. Has the same usage as in GetProperty.
propValue The bool value to be assigned to the property.
options A pointer to the XMP_OptionBits variable that is assigned option flags describing the property. May be null if the flags are not wanted.

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 from an XMP_DateTime struct.

Parameters:
schemaNS The namespace URI for the property. Has the same usage as in GetProperty.
propName The name of the property. Has the same usage as in GetProperty.
propValue The XMP_DateTime value to be assigned to the property.
options Option flags describing the property.

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 from a C double float.

Parameters:
schemaNS The namespace URI for the property. Has the same usage as in GetProperty.
propName The name of the property. Has the same usage as in GetProperty.
propValue The double float value to be assigned to the property.
options Option flags describing the property.

template<class tStringObj>
void TXMPMeta< tStringObj >::SetProperty_Int XMP_StringPtr  schemaNS,
XMP_StringPtr  propName,
long  propValue,
XMP_OptionBits  options = 0
 

SetProperty_Int sets the value of an integer property from a C long integer.

Parameters:
schemaNS The namespace URI for the property. Has the same usage as in GetProperty.
propName The name of the property. Has the same usage as in GetProperty.
propValue The long integer value to be assigned to the property.
options Option flags describing the property.

template<class tStringObj>
void TXMPMeta< tStringObj >::SetProperty_Int64 XMP_StringPtr  schemaNS,
XMP_StringPtr  propName,
long long  propValue,
XMP_OptionBits  options = 0
 

SetProperty_Int64 sets the value of an integer property from a C long long integer.

Parameters:
schemaNS The namespace URI for the property. Has the same usage as in GetProperty.
propName The name of the property. Has the same usage as in GetProperty.
propValue The long long integer value to be assigned to the property.
options Option flags describing the property.

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 provides access to a qualifier attached to a property. The namespace for the qualifier is passed as a URI, you need not worry about the path string syntax. In many regards qualifiers are like struct fields. See the introductory discussion of qualified properties for more information.

The names of qualifiers should be XML qualified names, that is within an XML namespace. The path syntax for a qualified name uses the namespace prefix, which is unreliable because the prefix is never guaranteed. The URI is the formal name, the prefix is just a local shorthand in a given sequence of XML text.

Parameters:
schemaNS The namespace URI for the struct. Has the same usage as in GetProperty.
propName The name of the property to which the qualifier is attached. Has the same usage as in GetProperty.
qualNS The namespace URI for the qualifier. Has the same URI and prefix usage as the schemaNS parameter.
qualName The name of the qualifier. Must be a single XML name, must not be null or the empty string. Has the same namespace prefix usage as the propName parameter.
qualValue A pointer to the null terminated UTF-8 string that is the value of the qualifier, if the qualifier has a value. Has the same usage as propValue in GetProperty.
options Option flags describing the qualifier. See the earlier description.

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 provides access to fields within a nested structure. The namespace for the field is passed as a URI, you need not worry about the path string syntax.

The names of fields should be XML qualified names, that is within an XML namespace. The path syntax for a qualified name uses the namespace prefix, which is unreliable because the prefix is never guaranteed. The URI is the formal name, the prefix is just a local shorthand in a given sequence of XML text.

Parameters:
schemaNS The namespace URI for the struct. Has the same usage as in GetProperty.
structName The name of the struct. May be a general path expression, must not be null or the empty string. Has the same namespace prefix usage as propName in GetProperty.
fieldNS The namespace URI for the field. Has the same URI and prefix usage as the schemaNS parameter.
fieldName The name of the field. Must be a single XML name, must not be null or the empty string. Has the same namespace prefix usage as the structName parameter.
fieldValue A pointer to the null terminated UTF-8 string that is the value of the field, if the field has a value. Has the same usage as propValue in GetProperty.
options Option flags describing the field. See the earlier description.


The documentation for this class was generated from the following file:
Generated on Mon Jan 2 12:25:55 2006 for Adobe XMP Toolkit by doxygen 1.3.3