TXMPUtils< tStringObj > Class Template Reference

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

#include <TXMPUtils.hpp>

List of all members.

Static Public Member Functions

Path composition

These functions provide support for composing path expressions to deeply nested properties. The functions in TXMPMeta such as TXMPMeta::GetProperty(), TXMPMeta::GetArrayItem(), and TXMPMeta::GetStructField() provide easy access to top level simple properties, items in top level arrays, and fields of top level structs. They are not as convenient for more complex things, such as fields several levels deep in a complex struct, or fields within an array of structs, or items of an array that is a field of a struct. You can use these utility functions to compose these paths, which you can then pass to the property access functions. You can also compose paths to top-level array items or struct fields so that you can use the binary accessors such as TXMPMeta::GetProperty_Int().

You can use these functions is to compose a complete path expression, or all but the last component. For example, suppose you have a property that is an array of integers within a struct. You can access one of the array items like this:

          SXMPUtils::ComposeStructFieldPath ( schemaNS, "Struct", fieldNS, "Array", &path );
          SXMPUtils::ComposeArrayItemPath ( schemaNS, path, index, &path );
          exists = xmpObj.GetProperty_Int ( schemaNS, path, &value, &options );
        

You could also use this code if you want the string form of the integer:

          SXMPUtils::ComposeStructFieldPath ( schemaNS, "Struct", fieldNS, "Array", &path );
          xmpObj.GetArrayItem ( schemaNS, path, index, &value, &options );
        
Note:
It might look confusing that the schemaNS is passed in all of the calls above. This is because the XMP Toolkit keeps the top-level "schema" namespace separate from the rest of the path expression.
static void ComposeArrayItemPath (XMP_StringPtr schemaNS, XMP_StringPtr arrayName, XMP_Index itemIndex, tStringObj *fullPath)
 ComposeArrayItemPath() composes the path expression for an item in an array.
static void ComposeStructFieldPath (XMP_StringPtr schemaNS, XMP_StringPtr structName, XMP_StringPtr fieldNS, XMP_StringPtr fieldName, tStringObj *fullPath)
 ComposeStructFieldPath() composes the path expression for a field in a struct.
static void ComposeQualifierPath (XMP_StringPtr schemaNS, XMP_StringPtr propName, XMP_StringPtr qualNS, XMP_StringPtr qualName, tStringObj *fullPath)
 ComposeQualifierPath() composes the path expression for a qualifier.
static void ComposeLangSelector (XMP_StringPtr schemaNS, XMP_StringPtr arrayName, XMP_StringPtr langName, tStringObj *fullPath)
 ComposeLangSelector() composes the path expression to select an alternate item by language.
static void ComposeLangSelector (XMP_StringPtr schemaNS, XMP_StringPtr arrayName, const tStringObj &langName, tStringObj *fullPath)
 ComposeLangSelector() composes a path expression to select an alternate item by language.
static void ComposeFieldSelector (XMP_StringPtr schemaNS, XMP_StringPtr arrayName, XMP_StringPtr fieldNS, XMP_StringPtr fieldName, XMP_StringPtr fieldValue, tStringObj *fullPath)
 ComposeFieldSelector() composes a path expression to select an alternate item by a field's value.
static void ComposeFieldSelector (XMP_StringPtr schemaNS, XMP_StringPtr arrayName, XMP_StringPtr fieldNS, XMP_StringPtr fieldName, const tStringObj &fieldValue, tStringObj *fullPath)
 ComposeFieldSelector() composes a path expression to select an alternate item by a field's value.
Conversion between binary types and strings

The main accessors in TXMPMeta set and retrieve property values as strings. additional functions, such as TXMPMeta::SetPropertyInt(), set and retrieve property values as explicit binary data types. Use these functions to convert between binary and string values.

Strings can be specified as null-terminated UTF-8 (XMP_StringPtr), or as string objects (tStringObj) of the type declared when instantiating the XMP classes; see XMP.hpp. Alternate forms of each conversion function allow either type of string.

static void ConvertFromBool (bool binValue, tStringObj *strValue)
 ConvertFromBool() converts a Boolean value to a string.
static void ConvertFromInt (long binValue, XMP_StringPtr format, tStringObj *strValue)
 ConvertFromInt() converts a 32-bit integer value to a string.
static void ConvertFromInt64 (long long binValue, XMP_StringPtr format, tStringObj *strValue)
 ConvertFromInt64() converts a 64-bit integer value to a string.
static void ConvertFromFloat (double binValue, XMP_StringPtr format, tStringObj *strValue)
 ConvertFromFloat() converts a floating-point value to a string.
static void ConvertFromDate (const XMP_DateTime &binValue, tStringObj *strValue)
 ConvertFromDate() converts a date/time value to a string.
static bool ConvertToBool (XMP_StringPtr strValue)
 ConvertToBool() converts a string to a Boolean value.
static bool ConvertToBool (const tStringObj &strValue)
 ConvertToBool() converts a string to a Boolean value.
static long ConvertToInt (XMP_StringPtr strValue)
 ConvertToInt() converts a string to a 32-bit integer value.
static long ConvertToInt (const tStringObj &strValue)
 ConvertToInt() converts a string to a 32-bit integer value.
static long long ConvertToInt64 (XMP_StringPtr strValue)
 ConvertToInt64() converts a string to a 64-bit integer value.
static long long ConvertToInt64 (const tStringObj &strValue)
 ConvertToInt64() converts a string to a 64-bit integer value.
static double ConvertToFloat (XMP_StringPtr strValue)
 ConvertToFloat() converts a string to a floating-point value.
static double ConvertToFloat (const tStringObj &strValue)
 ConvertToFloat() converts a string to a floating-point value.
static void ConvertToDate (XMP_StringPtr strValue, XMP_DateTime *binValue)
 ConvertToDate() converts a string to a date/time value.
static void ConvertToDate (const tStringObj &strValue, XMP_DateTime *binValue)
 ConvertToDate() converts a string to a date/time value.
Date-time manipulation

In addition to the type-conversion functions that convert between strings and binary date-time values, these functions create, manipulate, and compare date-time values.

static void CurrentDateTime (XMP_DateTime *time)
 CurrentDateTime() obtains the current date and time.
static void SetTimeZone (XMP_DateTime *time)
 SetTimeZone() sets the time zone in a date/time value to the local time zone.
static void ConvertToUTCTime (XMP_DateTime *time)
 ConvertToUTCTime() ensures that a time is UTC.
static void ConvertToLocalTime (XMP_DateTime *time)
 ConvertToLocalTime() ensures that a time is local.
static int CompareDateTime (const XMP_DateTime &left, const XMP_DateTime &right)
 CompareDateTime() compares the order of two date/time values.
Base64 encoding and decoding

These functions convert between raw data values and Base64-encoded strings.

static void EncodeToBase64 (XMP_StringPtr rawStr, XMP_StringLen rawLen, tStringObj *encodedStr)
 EncodeToBase64() converts a raw data value to a Base64-encoded string.
static void EncodeToBase64 (const tStringObj &rawStr, tStringObj *encodedStr)
 EncodeToBase64() converts a raw data value passed in a string object to a Base64-encoded string.
static void DecodeFromBase64 (XMP_StringPtr encodedStr, XMP_StringLen encodedLen, tStringObj *rawStr)
 DecodeFromBase64() Decodes a Base64-encoded string to raw data.
static void DecodeFromBase64 (const tStringObj &encodedStr, tStringObj *rawStr)
 DecodeFromBase64() Decodes a Base64-encoded string, passed as a string object, to raw data.
JPEG file handling

These functions support the partitioning of XMP in JPEG files into standard and extended portions in order to work around the 64KB size limit of JPEG marker segments.

Note:
(Doc note) Add detail about how to write out and read back extended data
static void PackageForJPEG (const TXMPMeta< tStringObj > &xmpObj, tStringObj *standardXMP, tStringObj *extendedXMP, tStringObj *extendedDigest)
 PackageForJPEG() creates XMP serializations appropriate for a JPEG file.
static void MergeFromJPEG (TXMPMeta< tStringObj > *fullXMP, const TXMPMeta< tStringObj > &extendedXMP)
 MergeFromJPEG() merges standard and extended XMP retrieved from a JPEG file.
Editing utilities

These functions are useful in implementing a user interface for editing XMP. They convert sets of property values to and from displayable and manipulable strings, and perform operations on sets of metadata, such as those available from the File Info dialog box.

static void CatenateArrayItems (const TXMPMeta< tStringObj > &xmpObj, XMP_StringPtr schemaNS, XMP_StringPtr arrayName, XMP_StringPtr separator, XMP_StringPtr quotes, XMP_OptionBits options, tStringObj *catedStr)
 CatenateArrayItems() creates a single edit string from a set of array item values.
static void SeparateArrayItems (TXMPMeta< tStringObj > *xmpObj, XMP_StringPtr schemaNS, XMP_StringPtr arrayName, XMP_OptionBits options, XMP_StringPtr catedStr)
 SeparateArrayItems() updates an array from a concatenated edit string of values.
static void SeparateArrayItems (TXMPMeta< tStringObj > *xmpObj, XMP_StringPtr schemaNS, XMP_StringPtr arrayName, XMP_OptionBits options, const tStringObj &catedStr)
 SeparateArrayItems() updates an array from a concatenated edit string of values.
static void ApplyTemplate (TXMPMeta< tStringObj > *workingXMP, const TXMPMeta< tStringObj > &templateXMP, XMP_OptionBits actions)
 ApplyTemplate() modifies a working XMP object according to a template object.
static void RemoveProperties (TXMPMeta< tStringObj > *xmpObj, XMP_StringPtr schemaNS=0, XMP_StringPtr propName=0, XMP_OptionBits options=0)
 RemoveProperties() removes multiple properties from an XMP object.
static void DuplicateSubtree (const TXMPMeta< tStringObj > &source, TXMPMeta< tStringObj > *dest, XMP_StringPtr sourceNS, XMP_StringPtr sourceRoot, XMP_StringPtr destNS=0, XMP_StringPtr destRoot=0, XMP_OptionBits options=0)
 DuplicateSubtree() replicates a subtree from one XMP object into another.

Detailed Description

template<class tStringObj>
class TXMPUtils< tStringObj >

API for access to the XMP Toolkit utility services.

TXMPUtils is a template class which must be instantiated with a string class such as std::string. See the instructions in XMP.hpp, and the Overview for a discussion of the overall architecture of the XMP API.

This class defines helper functions that support the basic metadata manipulation provided by TXMPMeta. All of the functions are static; that is, you call them directly from the concrete class (SXMPUtils), which is never itself instantiated.

General categories of utilities include:


Member Function Documentation

template<class tStringObj >
static void TXMPUtils< tStringObj >::ApplyTemplate ( TXMPMeta< tStringObj > *  workingXMP,
const TXMPMeta< tStringObj > &  templateXMP,
XMP_OptionBits  actions 
) [static]

ApplyTemplate() modifies a working XMP object according to a template object.

The XMP template can be used to add, replace or delete properties from the working XMP object. This function replaces the previous AppendProperties() function, which is no longer available. The actions that you specify determine how the template is applied. Each action can be applied individually or combined; if you do not specify any actions, the properties and values in the working XMP object do not change.

These actions are available:

  • Clear (kXMPTemplate_ClearUnnamedProperties): Deletes top-level properties. Any top-level property that is present in the template (even with empty value) is retained. All other top-level properties in the working object are deleted.
  • Add (kXMPTemplate_AddNewProperties): Adds new properties to the working object if the template properties have values. See additional detail below.
  • Replace (kXMPTemplate_ReplaceExistingProperties): Replaces the values of existing top-level properties in the working XMP if the value forms match those in the template. Properties with empty values in the template are ignored. If combined with Clear or Add actions, those take precedence; values are cleared or added, rather than replaced.
  • Replace/Delete empty (kXMPTemplate_ReplaceWithDeleteEmpty): Replaces values in the same way as the simple Replace action, and also deletes properties if the value in the template is empty. If combined with Clear or Add actions, those take precedence; values are cleared or added, rather than replaced.
  • Include internal (kXMPTemplate_IncludeInternalProperties): Performs specified action on internal properties as well as external properties. By default, internal properties are ignored for all actions.

The Add behavior depends on the type of property:

  • If a top-level property is not in the working XMP, and has a value in the template, the property and value are added. Empty properties are not added.
  • If a property is in both the working XMP and template, the value forms must match, otherwise the template is ignored for that property.
  • If a struct is present in both the working XMP and template, the individual fields of the template struct are added as appropriate; that is, the logic is recursively applied to the fields. Struct values are equivalent if they have the same fields with equivalent values.
  • If an array is present in both the working XMP and template, items from the template are added if the value forms match. Array values match if they have sets of equivalent items, regardless of order.
  • Alt-text arrays use the xml:lang qualifier as a key, adding languages that are missing.

Array item checking is n-squared; this can be time-intensive if the Replace option is not specified. Each source item is checked to see if it already exists in the destination, without regard to order or duplicates. Simple items are compared by value and xml:lang qualifier; other qualifiers are ignored. Structs are recursively compared by field names, without regard to field order. Arrays are compared by recursively comparing all items.

Parameters:
workingXMP The destination XMP object.
templateXMP The template to apply to the destination XMP object.
actions Option flags to control the copying. If none are specified, the properties and values in the working XMP do not change. A logical OR of these bit-flag constants:

template<class tStringObj >
static void TXMPUtils< tStringObj >::CatenateArrayItems ( const TXMPMeta< tStringObj > &  xmpObj,
XMP_StringPtr  schemaNS,
XMP_StringPtr  arrayName,
XMP_StringPtr  separator,
XMP_StringPtr  quotes,
XMP_OptionBits  options,
tStringObj *  catedStr 
) [static]

CatenateArrayItems() creates a single edit string from a set of array item values.

Collects the values of all items in an array into a single string, using a specified separation string. Each item in the specified array must be a simple string value.

Parameters:
xmpObj The XMP object containing the array to be catenated.
schemaNS The schema namespace URI for the array. Must not be null or the empty string.
arrayName The name of the array. May be a general path expression, must not be null or the empty string.
separator The string with which to separate the items in the catenated string. Defaults to "; ", ASCII semicolon and space (U+003B, U+0020).
quotes The character or characters to use as quotes around array items that contain a separator. Defaults to the double-quote character ("), ASCII quote (U+0022).
options Option flags to control the catenation. <<what options?>>
catedStr [out] A string object in which to return the catenated array items.
See also:
SeparateArrayItems()
template<class tStringObj >
static int TXMPUtils< tStringObj >::CompareDateTime ( const XMP_DateTime left,
const XMP_DateTime right 
) [static]

CompareDateTime() compares the order of two date/time values.

Both values are treated as in the same time zone if either has no time zone.

Parameters:
left The left-side date/time value.
right The right-side date/time value.
Returns:
An integer indicating the order:
  • -1 if left is earlier than right
  • 0 if left matches right
  • +1 if left is later than right
template<class tStringObj >
static void TXMPUtils< tStringObj >::ComposeArrayItemPath ( XMP_StringPtr  schemaNS,
XMP_StringPtr  arrayName,
XMP_Index  itemIndex,
tStringObj *  fullPath 
) [static]

ComposeArrayItemPath() composes the path expression for an item in an array.

The returned string is in the form ns:arrayName[i], where "ns" is the prefix for the specified namespace, and "i" is the decimal representation of specified item index. If the last item was specified, the path is ns:arrayName[last()].

Parameters:
schemaNS The namespace URI for the array; see GetProperty().
arrayName The name of the array. Can be a general path expression, must not be null or the empty string; see GetProperty() for namespace prefix usage.
itemIndex The 1-based index of the desired item. Use the macro kXMP_ArrayLastItem to specify the last existing array item.
fullPath [out] A string in which to return the composed path.
template<class tStringObj >
static void TXMPUtils< tStringObj >::ComposeFieldSelector ( XMP_StringPtr  schemaNS,
XMP_StringPtr  arrayName,
XMP_StringPtr  fieldNS,
XMP_StringPtr  fieldName,
const tStringObj &  fieldValue,
tStringObj *  fullPath 
) [static]

ComposeFieldSelector() composes a path expression to select an alternate item by a field's value.

Path syntax allows two forms of "content addressing" to select an item in an array of alternatives. The form used in this function lets you select an item in an array of structs based on the value of one of the fields in the structs. The other form of content addressing is shown in ComposeLangSelector().

For example, consider a simple struct that has two fields, the name of a city and the URI of an FTP site in that city. Use this to create an array of download alternatives. You can show the user a popup built from the values of the city fields, then get the corresponding URI as follows:

          ComposeFieldSelector ( schemaNS, "Downloads", fieldNS, "City", chosenCity, &path );
          exists = GetStructField ( schemaNS, path, fieldNS, "URI", &uri );
        

The returned string is in the form ns:arrayName[fNS:fieldName='fieldValue'], where "ns" is the prefix for the schema namespace and "fNS" is the prefix for the field namespace.

Parameters:
schemaNS The namespace URI for the array; see GetProperty().
arrayName The name of the array. Can be a general path expression, must not be null or the empty string; see GetProperty() for namespace prefix usage.
fieldNS The namespace URI for the field used as the selector. Same URI and prefix usage as the schemaNS and arrayName parameters.
fieldName The name of the field used as the selector. Must be a single XML name, must not be null or the empty string. It must be the name of a field that is itself simple.
fieldValue The desired value of the field, specified as a string object.
fullPath [out] A string in which to return the composed path.
template<class tStringObj >
static void TXMPUtils< tStringObj >::ComposeFieldSelector ( XMP_StringPtr  schemaNS,
XMP_StringPtr  arrayName,
XMP_StringPtr  fieldNS,
XMP_StringPtr  fieldName,
XMP_StringPtr  fieldValue,
tStringObj *  fullPath 
) [static]

ComposeFieldSelector() composes a path expression to select an alternate item by a field's value.

Path syntax allows two forms of "content addressing" to select an item in an array of alternatives. The form used in this function lets you select an item in an array of structs based on the value of one of the fields in the structs. The other form of content addressing is shown in ComposeLangSelector().

For example, consider a simple struct that has two fields, the name of a city and the URI of an FTP site in that city. Use this to create an array of download alternatives. You can show the user a popup built from the values of the city fields, then get the corresponding URI as follows:

          ComposeFieldSelector ( schemaNS, "Downloads", fieldNS, "City", chosenCity, &path );
          exists = GetStructField ( schemaNS, path, fieldNS, "URI", &uri );
        

The returned string is in the form ns:arrayName[fNS:fieldName='fieldValue'], where "ns" is the prefix for the schema namespace and "fNS" is the prefix for the field namespace.

Parameters:
schemaNS The namespace URI for the array; see GetProperty().
arrayName The name of the array. Can be a general path expression, must not be null or the empty string; see GetProperty() for namespace prefix usage.
fieldNS The namespace URI for the field used as the selector. Same URI and prefix usage as the schemaNS and arrayName parameters.
fieldName The name of the field used as the selector. Must be a single XML name, must not be null or the empty string. It must be the name of a field that is itself simple.
fieldValue The desired value of the field, specified as a null-terminated UTF-8 string.
fullPath [out] A string in which to return the composed path.
template<class tStringObj >
static void TXMPUtils< tStringObj >::ComposeLangSelector ( XMP_StringPtr  schemaNS,
XMP_StringPtr  arrayName,
const tStringObj &  langName,
tStringObj *  fullPath 
) [static]

ComposeLangSelector() composes a path expression to select an alternate item by language.

Path syntax allows two forms of "content addressing" to select an item in an array of alternatives. The form used in this function lets you select an item in an alt-text array based on the value of its xml:lang qualifier. The other form of content addressing is shown in ComposeFieldSelector().

The returned string is in the form ns:arrayName[@xml:lang='langName'], where "ns" is the prefix for the schema namespace

This function provides a path expression that is explicitly and only for a specific language. In most cases, TXMPMeta::SetLocalizedText() and TXMPMeta::GetLocalizedText() are preferred, because they provide extra logic to choose the appropriate language and maintain consistency with the 'x-default' value.

Parameters:
schemaNS The namespace URI for the array; see GetProperty().
arrayName The name of the array. Can be a general path expression, must not be null or the empty string; see GetProperty() for namespace prefix usage.
langName The RFC 3066 code for the desired language, as a string object.
fullPath [out] A string in which to return the composed path.
template<class tStringObj >
static void TXMPUtils< tStringObj >::ComposeLangSelector ( XMP_StringPtr  schemaNS,
XMP_StringPtr  arrayName,
XMP_StringPtr  langName,
tStringObj *  fullPath 
) [static]

ComposeLangSelector() composes the path expression to select an alternate item by language.

Path syntax allows two forms of "content addressing" to select an item in an array of alternatives. The form used in this function lets you select an item in an alt-text array based on the value of its xml:lang qualifier. The other form of content addressing is shown in ComposeFieldSelector().

The returned string is in the form ns:arrayName[@xml:lang='langName'], where "ns" is the prefix for the schema namespace

This function provides a path expression that is explicitly and only for a specific language. In most cases, TXMPMeta::SetLocalizedText() and TXMPMeta::GetLocalizedText() are preferred, because they provide extra logic to choose the appropriate language and maintain consistency with the 'x-default' value.

Parameters:
schemaNS The namespace URI for the array; see GetProperty().
arrayName The name of the array. Can be a general path expression, must not be null or the empty string; see GetProperty() for namespace prefix usage.
langName The RFC 3066 code for the desired language, as a null-terminated UTF-8 string.
fullPath [out] A string in which to return the composed path.
template<class tStringObj >
static void TXMPUtils< tStringObj >::ComposeQualifierPath ( XMP_StringPtr  schemaNS,
XMP_StringPtr  propName,
XMP_StringPtr  qualNS,
XMP_StringPtr  qualName,
tStringObj *  fullPath 
) [static]

ComposeQualifierPath() composes the path expression for a qualifier.

The returned string is in the form ns:propName/?qNS:qualName, where "ns" is the prefix for the schema namespace, and "qNS" is the prefix for the qualifier namespace.

Parameters:
schemaNS The namespace URI; see GetProperty().
propName The name of the property to which the qualifier is attached. Can be a general path expression, must not be null or the empty string; see GetProperty() for namespace prefix usage.
qualNS The namespace URI for the qualifier. Same URI and prefix usage as the schemaNS and propName parameters.
qualName The name of the qualifier. Must be a single XML name, must not be null or the empty string. Same URI and prefix usage as the schemaNS and propName parameters.
fullPath [out] A string in which to return the composed path.
template<class tStringObj >
static void TXMPUtils< tStringObj >::ComposeStructFieldPath ( XMP_StringPtr  schemaNS,
XMP_StringPtr  structName,
XMP_StringPtr  fieldNS,
XMP_StringPtr  fieldName,
tStringObj *  fullPath 
) [static]

ComposeStructFieldPath() composes the path expression for a field in a struct.

The returned string is in the form ns:structName/fNS:fieldName, where "ns" is the prefix for the schema namespace, and "fNS" is the prefix for field namespace.

Parameters:
schemaNS The namespace URI for the struct; see GetProperty().
structName The name of the struct. Can be a general path expression, must not be null or the empty string; see GetProperty() for namespace prefix usage.
fieldNS The namespace URI for the field. Same URI and prefix usage as the schemaNS and structName parameters.
fieldName The name of the field. Must be a single XML name, must not be null or the empty string. Same URI and prefix usage as the schemaNS and structName parameters.
fullPath [out] A string in which to return the composed path.
template<class tStringObj >
static void TXMPUtils< tStringObj >::ConvertFromBool ( bool  binValue,
tStringObj *  strValue 
) [static]

ConvertFromBool() converts a Boolean value to a string.

The string values of Booleans are returned by the macros kXMP_TrueStr and kXMP_FalseStr in XMP_Const.h.

Parameters:
binValue The Boolean value to be converted.
strValue [out] A buffer in which to return the string representation of the value.
template<class tStringObj >
static void TXMPUtils< tStringObj >::ConvertFromDate ( const XMP_DateTime binValue,
tStringObj *  strValue 
) [static]

ConvertFromDate() converts a date/time value to a string.

Formats a date according to the ISO 8601 profile in http://www.w3.org/TR/NOTE-datetime:

          YYYY
          YYYY-MM
          YYYY-MM-DD
          YYYY-MM-DDThh:mmTZD
          YYYY-MM-DDThh:mm:ssTZD
          YYYY-MM-DDThh:mm:ss.sTZD
        

YYYY = four-digit year, formatted as "%.4d"
MM = two-digit month (01=January)
DD = two-digit day of month (01 through 31)
hh = two digits of hour (00 through 23)
mm = two digits of minute (00 through 59)
ss = two digits of second (00 through 59)
s = one or more digits representing a decimal fraction of a second
TZD = time zone designator (Z or +hh:mm or -hh:mm)

Time-only input is allowed where the year, month, and day are all zero. This is output as "0000-00-00...".

Note:
ISO 8601 does not allow years less than 1000 or greater than 9999. This API allows any year, even negative ones. The W3C profile also requires a time zone designator if a time is present, this API treats the time zone designator as optional. The XMP_DateTime type has an explicit notion of zone-less time.
Parameters:
binValue The date/time value to be converted.
strValue [out] A buffer in which to return the ISO 8601 string representation of the date/time.
template<class tStringObj >
static void TXMPUtils< tStringObj >::ConvertFromFloat ( double  binValue,
XMP_StringPtr  format,
tStringObj *  strValue 
) [static]

ConvertFromFloat() converts a floating-point value to a string.

Parameters:
binValue The floating-point value to be converted.
format Optional. A C sprintf format for the conversion. Default is "%d".
strValue [out] A buffer in which to return the string representation of the value.
template<class tStringObj >
static void TXMPUtils< tStringObj >::ConvertFromInt ( long  binValue,
XMP_StringPtr  format,
tStringObj *  strValue 
) [static]

ConvertFromInt() converts a 32-bit integer value to a string.

Parameters:
binValue The integer value to be converted.
format Optional. A C sprintf format for the conversion. Default is "%d".
strValue [out] A buffer in which to return the string representation of the value.
template<class tStringObj >
static void TXMPUtils< tStringObj >::ConvertFromInt64 ( long long  binValue,
XMP_StringPtr  format,
tStringObj *  strValue 
) [static]

ConvertFromInt64() converts a 64-bit integer value to a string.

Parameters:
binValue The integer value to be converted.
format Optional. A C sprintf format for the conversion. Default is "%d".
strValue [out] A buffer in which to return the string representation of the value.
template<class tStringObj >
static bool TXMPUtils< tStringObj >::ConvertToBool ( const tStringObj &  strValue  )  [static]

ConvertToBool() converts a string to a Boolean value.

Overloads the basic form of the function, allowing you to pass a string object, rather than a const * char. It is otherwise identical; see details in the canonical form.

Parameters:
strValue The string representation of the value, specified as a string object.
Returns:
The appropriate C++ bool value for the string.
template<class tStringObj >
static bool TXMPUtils< tStringObj >::ConvertToBool ( XMP_StringPtr  strValue  )  [static]

ConvertToBool() converts a string to a Boolean value.

The preferred strings are those returned by the macros kXMP_TrueStr and kXMP_FalseStr. If these do not match, the function does a case insensitive comparison, then simply 't' or 'f', and finally non-zero and zero integer representations.

Parameters:
strValue The string representation of the value, specified as a null-terminated UTF-8 string.
Returns:
The appropriate C++ bool value for the string.
template<class tStringObj >
static void TXMPUtils< tStringObj >::ConvertToDate ( const tStringObj &  strValue,
XMP_DateTime binValue 
) [static]

ConvertToDate() converts a string to a date/time value.

Overloads the basic form of the function, allowing you to pass a string object, rather than a const * char. It is otherwise identical. See details for the canonical form.

Parameters:
strValue The ISO 8601 string representation of the date/time, specified as a string object.
binValue [out] A buffer in which to return the binary date/time value.
template<class tStringObj >
static void TXMPUtils< tStringObj >::ConvertToDate ( XMP_StringPtr  strValue,
XMP_DateTime binValue 
) [static]

ConvertToDate() converts a string to a date/time value.

Parses a date according to the ISO 8601 profile in http://www.w3.org/TR/NOTE-datetime:

          YYYY
          YYYY-MM
          YYYY-MM-DD
          YYYY-MM-DDThh:mmTZD
          YYYY-MM-DDThh:mm:ssTZD
          YYYY-MM-DDThh:mm:ss.sTZD
        

YYYY = four-digit year, formatted as "%.4d"
MM = two-digit month (01=January)
DD = two-digit day of month (01 through 31)
hh = two digits of hour (00 through 23)
mm = two digits of minute (00 through 59)
ss = two digits of second (00 through 59)
s = one or more digits representing a decimal fraction of a second
TZD = time zone designator (Z or +hh:mm or -hh:mm)

A missing date portion or missing TZD are tolerated. A missing date value can begin with "Thh:" or "hh:"; the year, month, and day are all set to zero in the XMP_DateTime value. A missing TZD is assumed to be UTC.

Note:
ISO 8601 does not allow years less than 1000 or greater than 9999. This API allows any year, even negative ones. The W3C profile also requires a time zone designator if a time is present, this API treats the time zone designator as optional. The XMP_DateTime type has an explicit notion of zone-less time.
Parameters:
strValue The ISO 8601 string representation of the date/time, specified as a null-terminated UTF-8 string.
binValue [out] A buffer in which to return the binary date/time value.
template<class tStringObj >
static double TXMPUtils< tStringObj >::ConvertToFloat ( const tStringObj &  strValue  )  [static]

ConvertToFloat() converts a string to a floating-point value.

Overloads the basic form of the function, allowing you to pass a string object, rather than a const * char. It is otherwise identical.

Parameters:
strValue The string representation of the value, specified as a string object.
Returns:
The floating-point value.
template<class tStringObj >
static double TXMPUtils< tStringObj >::ConvertToFloat ( XMP_StringPtr  strValue  )  [static]

ConvertToFloat() converts a string to a floating-point value.

Parameters:
strValue The string representation of the value, specified as a null-terminated UTF-8 string.
Returns:
The floating-point value.
template<class tStringObj >
static long TXMPUtils< tStringObj >::ConvertToInt ( const tStringObj &  strValue  )  [static]

ConvertToInt() converts a string to a 32-bit integer value.

Overloads the basic form of the function, allowing you to pass a string object, rather than a const * char. It is otherwise identical.

Parameters:
strValue The string representation of the value, specified as a string object.
Returns:
The 32-bit integer value.
template<class tStringObj >
static long TXMPUtils< tStringObj >::ConvertToInt ( XMP_StringPtr  strValue  )  [static]

ConvertToInt() converts a string to a 32-bit integer value.

Parameters:
strValue The string representation of the value, specified as a null-terminated UTF-8 string.
Returns:
The 32-bit integer value.
template<class tStringObj >
static long long TXMPUtils< tStringObj >::ConvertToInt64 ( const tStringObj &  strValue  )  [static]

ConvertToInt64() converts a string to a 64-bit integer value.

Overloads the basic form of the function, allowing you to pass a string object, rather than a const * char. It is otherwise identical.

Parameters:
strValue The string representation of the value, specified as a string object.
Returns:
The 64-bit integer value.
template<class tStringObj >
static long long TXMPUtils< tStringObj >::ConvertToInt64 ( XMP_StringPtr  strValue  )  [static]

ConvertToInt64() converts a string to a 64-bit integer value.

Parameters:
strValue The string representation of the value, specified as a null-terminated UTF-8 string.
Returns:
The 64-bit integer value.
template<class tStringObj >
static void TXMPUtils< tStringObj >::ConvertToLocalTime ( XMP_DateTime time  )  [static]

ConvertToLocalTime() ensures that a time is local.

If the time zone is not the local zone, the time is adjusted and the time zone set to be local. The value is not modified if the time zone is already the local zone or if the value has no time zone.

Parameters:
time A pointer to the date-time value, which is modified in place.
template<class tStringObj >
static void TXMPUtils< tStringObj >::ConvertToUTCTime ( XMP_DateTime time  )  [static]

ConvertToUTCTime() ensures that a time is UTC.

If the time zone is not UTC, the time is adjusted and the time zone set to be UTC. The value is not modified if the time zone is already UTC or if the value has no time zone.

Parameters:
time A pointer to the date-time value, which is modified in place.
template<class tStringObj >
static void TXMPUtils< tStringObj >::CurrentDateTime ( XMP_DateTime time  )  [static]

CurrentDateTime() obtains the current date and time.

Creates and returns a binary XMP_DateTime value. The returned time is UTC, properly adjusted for the local time zone. The resolution of the time is not guaranteed to be finer than seconds.

Parameters:
time [out] A buffer in which to return the date/time value.
template<class tStringObj >
static void TXMPUtils< tStringObj >::DecodeFromBase64 ( const tStringObj &  encodedStr,
tStringObj *  rawStr 
) [static]

DecodeFromBase64() Decodes a Base64-encoded string, passed as a string object, to raw data.

Overloads the basic form of the function, allowing you to pass a string object as input. It is otherwise identical.

Parameters:
encodedStr An string object containing the encoded data to be converted.
rawStr [out] A string object in which to return the decoded data.
template<class tStringObj >
static void TXMPUtils< tStringObj >::DecodeFromBase64 ( XMP_StringPtr  encodedStr,
XMP_StringLen  encodedLen,
tStringObj *  rawStr 
) [static]

DecodeFromBase64() Decodes a Base64-encoded string to raw data.

Parameters:
encodedStr An XMP_StringPtr (char *) string containing the encoded data to be converted.
encodedLen The number of characters of raw data to be converted.
rawStr [out] A string object in which to return the decoded data.
template<class tStringObj >
static void TXMPUtils< tStringObj >::DuplicateSubtree ( const TXMPMeta< tStringObj > &  source,
TXMPMeta< tStringObj > *  dest,
XMP_StringPtr  sourceNS,
XMP_StringPtr  sourceRoot,
XMP_StringPtr  destNS = 0,
XMP_StringPtr  destRoot = 0,
XMP_OptionBits  options = 0 
) [static]

DuplicateSubtree() replicates a subtree from one XMP object into another.

The destination can be a different namespace and root location in the same object, or the same or a different location in another XMP object.

Parameters:
source The source XMP object.
dest The destination XMP object.
sourceNS The schema namespace URI for the source subtree.
sourceRoot The root location for the source subtree. Can be a general path expression, must not be null or the empty string.
destNS The schema namespace URI for the destination. Defaults to the source namespace.
destRoot The root location for the destination. Can be a general path expression. Defaults to the source location.
options Option flags to control the operation. <<options?>>
template<class tStringObj >
static void TXMPUtils< tStringObj >::EncodeToBase64 ( const tStringObj &  rawStr,
tStringObj *  encodedStr 
) [static]

EncodeToBase64() converts a raw data value passed in a string object to a Base64-encoded string.

Overloads the basic form of the function, allowing you to pass a string object as input. It is otherwise identical.

Parameters:
rawStr A string object containing the raw data to be converted.
encodedStr [out] A string object in which to return the encoded string.
template<class tStringObj >
static void TXMPUtils< tStringObj >::EncodeToBase64 ( XMP_StringPtr  rawStr,
XMP_StringLen  rawLen,
tStringObj *  encodedStr 
) [static]

EncodeToBase64() converts a raw data value to a Base64-encoded string.

Parameters:
rawStr An XMP_StringPtr (char *) string containing the raw data to be converted.
rawLen The number of characters of raw data to be converted.
encodedStr [out] A string object in which to return the encoded string.
template<class tStringObj >
static void TXMPUtils< tStringObj >::MergeFromJPEG ( TXMPMeta< tStringObj > *  fullXMP,
const TXMPMeta< tStringObj > &  extendedXMP 
) [static]

MergeFromJPEG() merges standard and extended XMP retrieved from a JPEG file.

When an extended partition stores properties that do not fit into the JPEG file limitation of 64K bytes, this function integrates those properties back into the same XMP object with those from the standard XMP packet.

Parameters:
fullXMP [in, out] An XMP object which the caller has initialized from the standard XMP packet in a JPEG file. The extended XMP is added to this object.
extendedXMP An XMP object which the caller has initialized from the extended XMP packet in a JPEG file.
See also:
PackageForJPEG()
template<class tStringObj >
static void TXMPUtils< tStringObj >::PackageForJPEG ( const TXMPMeta< tStringObj > &  xmpObj,
tStringObj *  standardXMP,
tStringObj *  extendedXMP,
tStringObj *  extendedDigest 
) [static]

PackageForJPEG() creates XMP serializations appropriate for a JPEG file.

The standard XMP in a JPEG file is limited to 64K bytes. This function serializes the XMP metadata in an XMP object into a string of RDF (see TXMPMeta::SerializeToBuffer()). If the data does not fit into the 64K byte limit, it creates a second packet string with the extended data.

Parameters:
xmpObj The XMP object containing the metadata.
standardXMP [out] A string object in which to return the full standard XMP packet.
extendedXMP [out] A string object in which to return the serialized extended XMP, empty if not needed.
extendedDigest [out] A string object in which to return an MD5 digest of the serialized extended XMP, empty if not needed.
See also:
MergeFromJPEG()
template<class tStringObj >
static void TXMPUtils< tStringObj >::RemoveProperties ( TXMPMeta< tStringObj > *  xmpObj,
XMP_StringPtr  schemaNS = 0,
XMP_StringPtr  propName = 0,
XMP_OptionBits  options = 0 
) [static]

RemoveProperties() removes multiple properties from an XMP object.

The operation depends on how the namespace and property are specified:

  • Non-empty schemaNS and propName - The named property is removed if it is an external property, or if the kXMPUtil_DoAllProperties option flag is set. It does not matter whether the named property is an actual property or an alias.
  • Non-empty schemaNS and empty propName - All external properties in the named schema are removed. Internal properties are also removed if the kXMPUtil_DoAllProperties option flag is set. In addition, aliases from the named schema are removed if the kXMPUtil_IncludeAliases option flag is set.
  • Empty schemaNS and empty propName - All external properties in all schemas are removed. Internal properties are also removed if the kXMPUtil_DoAllProperties option flag is set. Aliases are handled implicitly, because the associated actuals are removed or not.
  • It is an error to pass an empty schemaNS and non-empty propName.
Parameters:
xmpObj The XMP object containing the properties to be removed.
schemaNS Optional schema namespace URI for the properties to be removed.
propName Optional path expression for the property to be removed.
options Option flags to control the deletion operation. A logical OR of these bit-flag constants:

template<class tStringObj >
static void TXMPUtils< tStringObj >::SeparateArrayItems ( TXMPMeta< tStringObj > *  xmpObj,
XMP_StringPtr  schemaNS,
XMP_StringPtr  arrayName,
XMP_OptionBits  options,
const tStringObj &  catedStr 
) [static]

SeparateArrayItems() updates an array from a concatenated edit string of values.

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

template<class tStringObj >
static void TXMPUtils< tStringObj >::SeparateArrayItems ( TXMPMeta< tStringObj > *  xmpObj,
XMP_StringPtr  schemaNS,
XMP_StringPtr  arrayName,
XMP_OptionBits  options,
XMP_StringPtr  catedStr 
) [static]

SeparateArrayItems() updates an array from a concatenated edit string of values.

This reverses the action of CatenateArrayItems(), separating out individual array items from the edit string and updating the array with the new values. Each item in the array must be a simple string value.

Parameters:
xmpObj The XMP object containing the array to be updated.
schemaNS The schema namespace URI for the array. Must not be null or the empty string.
arrayName The name of the array. May be a general path expression, must not be null or the empty string.
options Option flags to control the separation. <<what options?>>
catedStr The concatenated array items, as created by CatenateArrayItems(), specified as a null-terminated UTF-8 string.
template<class tStringObj >
static void TXMPUtils< tStringObj >::SetTimeZone ( XMP_DateTime time  )  [static]

SetTimeZone() sets the time zone in a date/time value to the local time zone.

Any existing time zone value is replaced. The other date/time fields are not adjusted in any way.

Parameters:
time A pointer to the date-time value, which is modified in place.

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

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