| XMP Toolkit SDK 6.0.0

Static Private Member Functions | List of all members
TXMPUtils Class Reference

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

`#include <TXMPMeta.hpp>`

## 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
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. More...
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. More...
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. More...
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. More...
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. More...
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. More...
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. More...
Conversion between binary types and strings
static void | ConvertFromBool (bool binValue, tStringObj *strValue)
| `ConvertFromBool()` converts a Boolean value to a string. More...
static void | ConvertFromInt (long binValue, XMP_StringPtr format, tStringObj *strValue)
| `ConvertFromInt()` converts a 32-bit integer value to a string. More...
static void | ConvertFromInt64 (long long binValue, XMP_StringPtr format, tStringObj *strValue)
| `ConvertFromInt64()` converts a 64-bit integer value to a string. More...
static void | ConvertFromFloat (double binValue, XMP_StringPtr format, tStringObj *strValue)
| `ConvertFromFloat()` converts a floating-point value to a string. More...
static void | ConvertFromDate (const XMP_DateTime &binValue, tStringObj *strValue)
| `ConvertFromDate()` converts a date/time value to a string. More...
static bool | ConvertToBool (XMP_StringPtr strValue)
| `ConvertToBool()` converts a string to a Boolean value. More...
static bool | ConvertToBool (const tStringObj &strValue)
| `ConvertToBool()` converts a string to a Boolean value. More...
static long | ConvertToInt (XMP_StringPtr strValue)
| `ConvertToInt()` converts a string to a 32-bit integer value. More...
static long | ConvertToInt (const tStringObj &strValue)
| `ConvertToInt()` converts a string to a 32-bit integer value. More...
static long long | ConvertToInt64 (XMP_StringPtr strValue)
| `ConvertToInt64()` converts a string to a 64-bit integer value. More...
static long long | ConvertToInt64 (const tStringObj &strValue)
| `ConvertToInt64()` converts a string to a 64-bit integer value. More...
static double | ConvertToFloat (XMP_StringPtr strValue)
| `ConvertToFloat()` converts a string to a floating-point value. More...
static double | ConvertToFloat (const tStringObj &strValue)
| `ConvertToFloat()` converts a string to a floating-point value. More...
static void | ConvertToDate (XMP_StringPtr strValue, XMP_DateTime *binValue)
| `ConvertToDate()` converts a string to a date/time value. More...
static void | ConvertToDate (const tStringObj &strValue, XMP_DateTime *binValue)
| `ConvertToDate()` converts a string to a date/time value. More...
Date-time manipulation
static void | CurrentDateTime (XMP_DateTime *time)
| `CurrentDateTime()` obtains the current date and time. More...
static void | SetTimeZone (XMP_DateTime *time)
| `SetTimeZone()` sets the time zone in a date/time value to the local time zone. More...
static void | ConvertToUTCTime (XMP_DateTime *time)
| `ConvertToUTCTime()` ensures that a time is UTC. More...
static void | ConvertToLocalTime (XMP_DateTime *time)
| `ConvertToLocalTime()` ensures that a time is local. More...
static int | CompareDateTime (const XMP_DateTime &left, const XMP_DateTime &right)
| `CompareDateTime()` compares the order of two date/time values. More...
Base64 encoding and decoding
static void | EncodeToBase64 (XMP_StringPtr rawStr, XMP_StringLen rawLen, tStringObj *encodedStr)
| These functions convert between raw data values and Base64-encoded strings. More...
static void | EncodeToBase64 (const tStringObj &rawStr, tStringObj *encodedStr)
| `EncodeToBase64()` converts a raw data value passed in a string object to a Base64-encoded string. More...
static void | DecodeFromBase64 (XMP_StringPtr encodedStr, XMP_StringLen encodedLen, tStringObj *rawStr)
| `DecodeFromBase64()` Decodes a Base64-encoded string to raw data. More...
static void | DecodeFromBase64 (const tStringObj &encodedStr, tStringObj *rawStr)
| `DecodeFromBase64()` Decodes a Base64-encoded string, passed as a string object, to raw data. More...
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.
static void | PackageForJPEG (const TXMPMeta< tStringObj > &xmpObj, tStringObj *standardXMP, tStringObj *extendedXMP, tStringObj *extendedDigest)
| `PackageForJPEG()` creates XMP serializations appropriate for a JPEG file. More...
static void | MergeFromJPEG (TXMPMeta< tStringObj > *fullXMP, const TXMPMeta< tStringObj > &extendedXMP)
| `MergeFromJPEG()` merges standard and extended XMP retrieved from a JPEG file. More...
Editing utilities
These functions are useful in implementing a user interface for editing XMP. They
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. More...
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. More...
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. More...
static void | ApplyTemplate (TXMPMeta< tStringObj > *workingXMP, const TXMPMeta< tStringObj > &templateXMP, XMP_OptionBits actions)
| `ApplyTemplate()` modifies a working XMP object according to a template object. More...
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. More...
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. More...

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

## Detailed Description

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:

- Composing complex path expressions, which you can then pass to the property access functions in `TXMPMeta`
- Converting between binary and string forms of property values
- Manipulating date/time values
- Encoding and decoding base-64 strings
- JPEG file handling
- Editing aids for creating a user interface for the XMP Toolkit

Definition at line 53 of file TXMPMeta.hpp.

## Member Function Documentation

## ◆ ApplyTemplate()

static void TXMPUtils::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: `kXMPTemplate_ClearUnnamedProperties` – Delete anything that is not in the template `kXMPTemplate_AddNewProperties` – Add properties; see detailed description. `kXMPTemplate_ReplaceExistingProperties` – Replace the values of existing properties. `kXMPTemplate_ReplaceWithDeleteEmpty` – Replace the values of existing properties and delete properties if the new value is empty. `kXMPTemplate_IncludeInternalProperties` – Operate on internal properties as well as external properties.

## ◆ CatenateArrayItems()

static void TXMPUtils::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.

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

## ◆ CompareDateTime()

static int TXMPUtils::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

## ◆ ComposeArrayItemPath()

static void TXMPUtils::ComposeArrayItemPath | ( | XMP_StringPtr | schemaNS,
|  | XMP_StringPtr | arrayName,
|  | XMP_Index | itemIndex,
|  | tStringObj * | fullPath
| ) |  |
| static

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

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

## ◆ ComposeFieldSelector() [1/2]

static void TXMPUtils::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.

## ◆ ComposeFieldSelector() [2/2]

static void TXMPUtils::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.

## ◆ ComposeLangSelector() [1/2]

static void TXMPUtils::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.

## ◆ ComposeLangSelector() [2/2]

static void TXMPUtils::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.

## ◆ ComposeQualifierPath()

static void TXMPUtils::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.

## ◆ ComposeStructFieldPath()

static void TXMPUtils::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.

## ◆ ConvertFromBool()

static void TXMPUtils::ConvertFromBool | ( | bool | binValue,
|  | tStringObj * | strValue
| ) |  |
| static

`ConvertFromBool()` converts a Boolean value to a string.

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

## ◆ ConvertFromDate()

static void TXMPUtils::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.

## ◆ ConvertFromFloat()

static void TXMPUtils::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.

## ◆ ConvertFromInt()

static void TXMPUtils::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.

## ◆ ConvertFromInt64()

static void TXMPUtils::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.

## ◆ ConvertToBool() [1/2]

static bool TXMPUtils::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.

## ◆ ConvertToBool() [2/2]

static bool TXMPUtils::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.

## ◆ ConvertToDate() [1/2]

static void TXMPUtils::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.

## ◆ ConvertToDate() [2/2]

static void TXMPUtils::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.

## ◆ ConvertToFloat() [1/2]

static double TXMPUtils::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.

## ◆ ConvertToFloat() [2/2]

static double TXMPUtils::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.

## ◆ ConvertToInt() [1/2]

static long TXMPUtils::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.

## ◆ ConvertToInt() [2/2]

static long TXMPUtils::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.

## ◆ ConvertToInt64() [1/2]

static long long TXMPUtils::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.

## ◆ ConvertToInt64() [2/2]

static long long TXMPUtils::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.

## ◆ ConvertToLocalTime()

static void TXMPUtils::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.

## ◆ ConvertToUTCTime()

static void TXMPUtils::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.

## ◆ CurrentDateTime()

static void TXMPUtils::CurrentDateTime | ( | XMP_DateTime * | time | ) |
| static

`CurrentDateTime()` obtains the current date and time.

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

## ◆ DecodeFromBase64() [1/2]

static void TXMPUtils::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.

## ◆ DecodeFromBase64() [2/2]

static void TXMPUtils::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.

## ◆ DuplicateSubtree()

static void TXMPUtils::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?>>

## ◆ EncodeToBase64() [1/2]

static void TXMPUtils::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.

## ◆ EncodeToBase64() [2/2]

static void TXMPUtils::EncodeToBase64 | ( | XMP_StringPtr | rawStr,
|  | XMP_StringLen | rawLen,
|  | tStringObj * | encodedStr
| ) |  |
| static

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

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

## ◆ MergeFromJPEG()

static void TXMPUtils::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()`

## ◆ PackageForJPEG()

static void TXMPUtils::PackageForJPEG | ( | const TXMPMeta< tStringObj > & | xmpObj,
|  | tStringObj * | standardXMP,
|  | tStringObj * | extendedXMP,
|  | tStringObj * | extendedDigest
| ) |  |
| static

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

Note
  (Doc note) Add detail about how to write out and read back extended data 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()`

## ◆ RemoveProperties()

static void TXMPUtils::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: `kXMPUtil_DoAllProperties` - Delete internal properties in addition to external properties. `kXMPUtil_IncludeAliases` - Include aliases if the schema is explicitly specified.

## ◆ SeparateArrayItems() [1/2]

static void TXMPUtils::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.

## ◆ SeparateArrayItems() [2/2]

static void TXMPUtils::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.

## ◆ SetClientString()

static void TXMPUtils::SetClientString | ( | void * | clientPtr,
|  | XMP_StringPtr | valuePtr,
|  | XMP_StringLen | valueLen
| ) |  |
| static private

## ◆ SetTimeZone()

static void TXMPUtils::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 files:

- public/include/TXMPMeta.hpp
- public/include/TXMPUtils.hpp