API for access to the XMP Toolkit utility services. More...
#include <TXMPUtils.hpp>
Static Public Member Functions | |
Path composition | |
These functions provide support for composing path expressions to deeply nested properties. The functions in 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 );
| |
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 Strings can be specified as null-terminated UTF-8 ( | |
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 | |
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 | |
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 | |
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 | |
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. |
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:
TXMPMeta
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:
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.kXMPTemplate_AddNewProperties
): Adds new properties to the working object if the template properties have values. See additional detail below.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.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.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:
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.
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:
|
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.
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. |
SeparateArrayItems()
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.
left | The left-side date/time value. | |
right | The right-side date/time value. |
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()]
.
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. |
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.
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. |
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.
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. |
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.
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. |
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.
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. |
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.
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. |
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.
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. |
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
.
binValue | The Boolean value to be converted. | |
strValue | [out] A buffer in which to return the string representation of the value. |
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...".
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. |
static void TXMPUtils< tStringObj >::ConvertFromFloat | ( | double | binValue, | |
XMP_StringPtr | format, | |||
tStringObj * | strValue | |||
) | [static] |
ConvertFromFloat()
converts a floating-point value to a string.
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. |
static void TXMPUtils< tStringObj >::ConvertFromInt | ( | long | binValue, | |
XMP_StringPtr | format, | |||
tStringObj * | strValue | |||
) | [static] |
ConvertFromInt()
converts a 32-bit integer value to a string.
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. |
static void TXMPUtils< tStringObj >::ConvertFromInt64 | ( | long long | binValue, | |
XMP_StringPtr | format, | |||
tStringObj * | strValue | |||
) | [static] |
ConvertFromInt64()
converts a 64-bit integer value to a string.
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. |
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.
strValue | The string representation of the value, specified as a string object. |
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.
strValue | The string representation of the value, specified as a null-terminated UTF-8 string. |
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.
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. |
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.
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. |
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.
strValue | The string representation of the value, specified as a string object. |
static double TXMPUtils< tStringObj >::ConvertToFloat | ( | XMP_StringPtr | strValue | ) | [static] |
ConvertToFloat()
converts a string to a floating-point value.
strValue | The string representation of the value, specified as a null-terminated UTF-8 string. |
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.
strValue | The string representation of the value, specified as a string object. |
static long TXMPUtils< tStringObj >::ConvertToInt | ( | XMP_StringPtr | strValue | ) | [static] |
ConvertToInt()
converts a string to a 32-bit integer value.
strValue | The string representation of the value, specified as a null-terminated UTF-8 string. |
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.
strValue | The string representation of the value, specified as a string object. |
static long long TXMPUtils< tStringObj >::ConvertToInt64 | ( | XMP_StringPtr | strValue | ) | [static] |
ConvertToInt64()
converts a string to a 64-bit integer value.
strValue | The string representation of the value, specified as a null-terminated UTF-8 string. |
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.
time | A pointer to the date-time value, which is modified in place. |
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.
time | A pointer to the date-time value, which is modified in place. |
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.
time | [out] A buffer in which to return the date/time value. |
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.
encodedStr | An string object containing the encoded data to be converted. | |
rawStr | [out] A string object in which to return the decoded data. |
static void TXMPUtils< tStringObj >::DecodeFromBase64 | ( | XMP_StringPtr | encodedStr, | |
XMP_StringLen | encodedLen, | |||
tStringObj * | rawStr | |||
) | [static] |
DecodeFromBase64()
Decodes a Base64-encoded string to raw data.
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. |
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.
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?>> |
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.
rawStr | A string object containing the raw data to be converted. | |
encodedStr | [out] A string object in which to return the encoded string. |
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.
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. |
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.
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. |
PackageForJPEG()
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.
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. |
MergeFromJPEG()
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:
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.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.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.schemaNS
and non-empty propName
.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:
|
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.
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.
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. |
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.
time | A pointer to the date-time value, which is modified in place. |