XMP Toolkit SDK  6.0.0
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
workingXMPThe destination XMP object.
templateXMPThe template to apply to the destination XMP object.
actionsOption 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:

◆ 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
xmpObjThe XMP object containing the array to be catenated.
schemaNSThe schema namespace URI for the array. Must not be null or the empty string.
arrayNameThe name of the array. May be a general path expression, must not be null or the empty string.
separatorThe string with which to separate the items in the catenated string. Defaults to "; ", ASCII semicolon and space (U+003B, U+0020).
quotesThe character or characters to use as quotes around array items that contain a separator. Defaults to the double-quote character ("), ASCII quote (U+0022).
optionsOption 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
leftThe left-side date/time value.
rightThe 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
schemaNSThe namespace URI for the array; see GetProperty().
arrayNameThe name of the array. Can be a general path expression, must not be null or the empty string; see GetProperty() for namespace prefix usage.
itemIndexThe 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
schemaNSThe namespace URI for the array; see GetProperty().
arrayNameThe name of the array. Can be a general path expression, must not be null or the empty string; see GetProperty() for namespace prefix usage.
fieldNSThe namespace URI for the field used as the selector. Same URI and prefix usage as the schemaNS and arrayName parameters.
fieldNameThe 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.
fieldValueThe 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
schemaNSThe namespace URI for the array; see GetProperty().
arrayNameThe name of the array. Can be a general path expression, must not be null or the empty string; see GetProperty() for namespace prefix usage.
fieldNSThe namespace URI for the field used as the selector. Same URI and prefix usage as the schemaNS and arrayName parameters.
fieldNameThe 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.
fieldValueThe 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
schemaNSThe namespace URI for the array; see GetProperty().
arrayNameThe name of the array. Can be a general path expression, must not be null or the empty string; see GetProperty() for namespace prefix usage.
langNameThe 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
schemaNSThe namespace URI for the array; see GetProperty().
arrayNameThe name of the array. Can be a general path expression, must not be null or the empty string; see GetProperty() for namespace prefix usage.
langNameThe 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
schemaNSThe namespace URI; see GetProperty().
propNameThe 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.
qualNSThe namespace URI for the qualifier. Same URI and prefix usage as the schemaNS and propName parameters.
qualNameThe 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
schemaNSThe namespace URI for the struct; see GetProperty().
structNameThe name of the struct. Can be a general path expression, must not be null or the empty string; see GetProperty() for namespace prefix usage.
fieldNSThe namespace URI for the field. Same URI and prefix usage as the schemaNS and structName parameters.
fieldNameThe 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
binValueThe 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
binValueThe 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
binValueThe floating-point value to be converted.
formatOptional. 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
binValueThe integer value to be converted.
formatOptional. 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
binValueThe integer value to be converted.
formatOptional. 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
strValueThe 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
strValueThe 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
strValueThe 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
strValueThe 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
strValueThe 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
strValueThe 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
strValueThe 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
strValueThe 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
strValueThe 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
strValueThe 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
timeA 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
timeA 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
encodedStrAn 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
encodedStrAn XMP_StringPtr (char *) string containing the encoded data to be converted.
encodedLenThe 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
sourceThe source XMP object.
destThe destination XMP object.
sourceNSThe schema namespace URI for the source subtree.
sourceRootThe root location for the source subtree. Can be a general path expression, must not be null or the empty string.
destNSThe schema namespace URI for the destination. Defaults to the source namespace.
destRootThe root location for the destination. Can be a general path expression. Defaults to the source location.
optionsOption 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
rawStrA 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
rawStrAn XMP_StringPtr (char *) string containing the raw data to be converted.
rawLenThe 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.
extendedXMPAn 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
xmpObjThe 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
xmpObjThe XMP object containing the properties to be removed.
schemaNSOptional schema namespace URI for the properties to be removed.
propNameOptional path expression for the property to be removed.
optionsOption flags to control the deletion operation. A logical OR of these bit-flag constants:

◆ 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
xmpObjThe XMP object containing the array to be updated.
schemaNSThe schema namespace URI for the array. Must not be null or the empty string.
arrayNameThe name of the array. May be a general path expression, must not be null or the empty string.
optionsOption flags to control the separation. <<what options?>>
catedStrThe 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 
)
staticprivate

◆ 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
timeA pointer to the date-time value, which is modified in place.

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