#include <TXMPUtils.hpp>
Static Public Member Functions | |
Path composition functions | |
These functions provide support for composing path expressions to deeply nested properties. The functions in TXMPMeta such as GetProperty , GetArrayItem , and GetStructField provide easy access to top level simple properties, items in top level arrays, and fields of top level structs. They do not provide convenient access to more complex things like 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. These functions can also be used to compose paths to top level array items or struct fields so that you can use the binary accessors like GetProperty_Int .You can use these functions is to compose a complete path expression, or all but the last component. 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) |
Compose 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) |
Compose 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) |
Compose the path expression for a qualifier. | |
static void | ComposeLangSelector (XMP_StringPtr schemaNS, XMP_StringPtr arrayName, XMP_StringPtr langName, tStringObj *fullPath) |
Compose the path expression to select an alternate item by language. | |
static void | ComposeLangSelector (XMP_StringPtr schemaNS, XMP_StringPtr arrayName, const tStringObj &langName, tStringObj *fullPath) |
This form of ComposeLangSelector is a simple overload in the template that calls the above form passing langName.c_str() . | |
static void | ComposeFieldSelector (XMP_StringPtr schemaNS, XMP_StringPtr arrayName, XMP_StringPtr fieldNS, XMP_StringPtr fieldName, XMP_StringPtr fieldValue, tStringObj *fullPath) |
Compose the 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) |
This form of ComposeFieldSelector is a simple overload in the template that calls the above form passing fieldValue.c_str() . | |
Binary-String conversion functions | |
static void | ConvertFromBool (bool binValue, tStringObj *strValue) |
Convert from Boolean to string. | |
static void | ConvertFromInt (long binValue, XMP_StringPtr format, tStringObj *strValue) |
Convert from integer to string. | |
static void | ConvertFromFloat (double binValue, XMP_StringPtr format, tStringObj *strValue) |
Convert from floating point to string. | |
static void | ConvertFromDate (const XMP_DateTime &binValue, tStringObj *strValue) |
Convert from date/time to string. | |
static bool | ConvertToBool (XMP_StringPtr strValue) |
Convert from string to Boolean. | |
static bool | ConvertToBool (const tStringObj &strValue) |
This form of ConvertToBool is a simple overload in the template that calls the above form passing strValue.c_str() . | |
static long | ConvertToInt (XMP_StringPtr strValue) |
Convert from string to integer. | |
static long | ConvertToInt (const tStringObj &strValue) |
This form of ConvertToInt is a simple overload in the template that calls the above form passing strValue.c_str() . | |
static long long | ConvertToInt64 (XMP_StringPtr strValue) |
Convert from string to 64 bit integer. | |
static long long | ConvertToInt64 (const tStringObj &strValue) |
This form of ConvertToInt64 is a simple overload in the template that calls the above form passing strValue.c_str() . | |
static double | ConvertToFloat (XMP_StringPtr strValue) |
Convert from string to floating point. | |
static double | ConvertToFloat (const tStringObj &strValue) |
This form of ConvertToFloat is a simple overload in the template that calls the above form passing strValue.c_str() . | |
static void | ConvertToDate (XMP_StringPtr strValue, XMP_DateTime *binValue) |
Convert from string to date/time. | |
static void | ConvertToDate (const tStringObj &strValue, XMP_DateTime *binValue) |
This form of ConvertToDate is a simple overload in the template that calls the above form passing sstrValue.c_str() . | |
Date/Time functions | |
static void | CurrentDateTime (XMP_DateTime *time) |
Obtain the current date and time. | |
static void | SetTimeZone (XMP_DateTime *time) |
Set the local time zone. | |
static void | ConvertToUTCTime (XMP_DateTime *time) |
Make sure a time is UTC. | |
static void | ConvertToLocalTime (XMP_DateTime *time) |
Make sure a time is local. | |
static int | CompareDateTime (const XMP_DateTime &left, const XMP_DateTime &right) |
Compare the order of two date/time values. | |
Base 64 Encoding and Decoding | |
static void | EncodeToBase64 (XMP_StringPtr rawStr, XMP_StringLen rawLen, tStringObj *encodedStr) |
Convert from raw data to Base64 encoded string. | |
static void | EncodeToBase64 (const tStringObj &rawStr, tStringObj *encodedStr) |
This form of EncodeToBase64 is a simple overload in the template that calls the above form passing rawStr.c_str() , and rawStr.size() . | |
static void | DecodeFromBase64 (XMP_StringPtr encodedStr, XMP_StringLen encodedLen, tStringObj *rawStr) |
Decode from Base64 encoded string to raw data. | |
static void | DecodeFromBase64 (const tStringObj &encodedStr, tStringObj *rawStr) |
This form of DecodeFromBase64 is a simple overload in the template that calls the above form passing encodedStr.c_str() , and encodedStr.size() . | |
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) |
Create XMP serializations appropriate for a JPEG file. The standard XMP in a JPEG file is limited to about 65500 bytes. PackageForJPEG attempts to fit the serialization within that limit. If necessary it will partition the XMP into 2 serializations. | |
static void | MergeFromJPEG (TXMPMeta< tStringObj > *fullXMP, const TXMPMeta< tStringObj > &extendedXMP) |
Put the extended XMP properties back into the full XMP. | |
UI helper functions | |
These functions are mainly of interest in implementing a user interface for editing XMP. | |
static void | CatenateArrayItems (const TXMPMeta< tStringObj > &xmpObj, XMP_StringPtr schemaNS, XMP_StringPtr arrayName, XMP_StringPtr separator, XMP_StringPtr quotes, XMP_OptionBits options, tStringObj *catedStr) |
Create a single edit string from an array of strings. | |
static void | SeparateArrayItems (TXMPMeta< tStringObj > *xmpObj, XMP_StringPtr schemaNS, XMP_StringPtr arrayName, XMP_OptionBits options, XMP_StringPtr catedStr) |
Separate a single edit string into an array of strings. | |
static void | SeparateArrayItems (TXMPMeta< tStringObj > *xmpObj, XMP_StringPtr schemaNS, XMP_StringPtr arrayName, XMP_OptionBits options, const tStringObj &catedStr) |
This form of SeparateArrayItems is a simple overload in the template that calls the aboveform passing catedStr.c_str() . | |
static void | RemoveProperties (TXMPMeta< tStringObj > *xmpObj, XMP_StringPtr schemaNS=0, XMP_StringPtr propName=0, XMP_OptionBits options=0) |
Remove multiple properties from an XMP object. | |
static void | AppendProperties (const TXMPMeta< tStringObj > &source, TXMPMeta< tStringObj > *dest, XMP_OptionBits options=0) |
Append properties from one XMP object to another. | |
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) |
Replicate a subtree from one XMP object into another, possibly at a different location. |
TXMPUtils
is the template class providing utility services for the XMP Toolkit. It should be instantiated with a string class such as std::string
. Please read the general toolkit usage notes for information about the overall architecture of the XMP API.
This is a class for C++ scoping purposes only. It has only static functions, you cannot create an object. These are all functions that layer cleanly on top of the core XMP toolkit. The template wraps a string class around the raw XMP API, so that output strings are automatically copied and access is fully thread safe. String objects are only necessary for output strings. Input strings are literals and passed as typical C const char *
.
The template parameter, class TtStringObj
, is described in the XMP.hpp umbrella header.
static void TXMPUtils< tStringObj >::ComposeArrayItemPath | ( | XMP_StringPtr | schemaNS, | |
XMP_StringPtr | arrayName, | |||
XMP_Index | itemIndex, | |||
tStringObj * | fullPath | |||
) | [static] |
Compose the path expression for an item in an array.
schemaNS | The 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. | |
itemIndex | The index of the desired item. Arrays in XMP are indexed from 1. The constant kXMP_ArrayLastItem always refers to the last existing array item. | |
fullPath | A pointer to the string that will be assigned the composed path. This will be of the form ns:arrayName[i] , where "ns" is the prefix for schemaNS and "i" is the decimal representation of itemIndex . If the value of itemIndex is kXMP_ArrayLastItem , the path is ns:arrayName[last()] . |
static void TXMPUtils< tStringObj >::ComposeStructFieldPath | ( | XMP_StringPtr | schemaNS, | |
XMP_StringPtr | structName, | |||
XMP_StringPtr | fieldNS, | |||
XMP_StringPtr | fieldName, | |||
tStringObj * | fullPath | |||
) | [static] |
Compose the path expression for a field in a struct.
schemaNS | The namespace URI for the struct. Must not be null or the empty string. | |
structName | The name of the struct. May be a general path expression, must not be null or the empty string. | |
fieldNS | The namespace URI for the field. Must not be null or the empty string. | |
fieldName | The name of the field. Must be a simple XML name, must not be null or the empty string. | |
fullPath | A pointer to the string that will be assigned the composed path. This will be of the form ns:structName/fNS:fieldName , where "ns" is the prefix for schemaNS and "fNS" is the prefix for fieldNS . |
static void TXMPUtils< tStringObj >::ComposeQualifierPath | ( | XMP_StringPtr | schemaNS, | |
XMP_StringPtr | propName, | |||
XMP_StringPtr | qualNS, | |||
XMP_StringPtr | qualName, | |||
tStringObj * | fullPath | |||
) | [static] |
Compose the path expression for a qualifier.
schemaNS | The namespace URI for the property to which the qualifier is attached. Must not be null or the empty string. | |
propName | The name of the property to which the qualifier is attached. May be a general path expression, must not be null or the empty string. | |
qualNS | The namespace URI for the qualifier. May be null or the empty string if the qualifier is in the XML empty namespace. | |
qualName | The name of the qualifier. Must be a simple XML name, must not be null or the empty string. | |
fullPath | A pointer to the string that will be assigned the composed path. This will be of the form ns:propName/?qNS:qualName , where "ns" is the prefix for schemaNS and "qNS" is the prefix for qualNS . |
static void TXMPUtils< tStringObj >::ComposeLangSelector | ( | XMP_StringPtr | schemaNS, | |
XMP_StringPtr | arrayName, | |||
XMP_StringPtr | langName, | |||
tStringObj * | fullPath | |||
) | [static] |
Compose the path expression to select an alternate item by language.
The path syntax allows two forms of "content addressing" that may be used to select an item in an array of alternatives. The form used in ComposeLangSelector
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
.
ComposeLangSelector
does not supplant SetLocalizedText
or GetLocalizedText
. They should generally be used, as they provide extra logic to choose the appropriate language and maintain consistency with the 'x-default' value. ComposeLangSelector
gives you an path expression that is explicitly and only for the language given in the langName
parameter.schemaNS | The 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. | |
langName | The RFC 3066 code for the desired language. | |
fullPath | A pointer to the string that will be assigned the composed path. This will be of the form ns:arrayName[@xml:lang='langName'] , where "ns" is the prefix for schemaNS . |
static void TXMPUtils< tStringObj >::ComposeFieldSelector | ( | XMP_StringPtr | schemaNS, | |
XMP_StringPtr | arrayName, | |||
XMP_StringPtr | fieldNS, | |||
XMP_StringPtr | fieldName, | |||
XMP_StringPtr | fieldValue, | |||
tStringObj * | fullPath | |||
) | [static] |
Compose the path expression to select an alternate item by a field's value.
The path syntax allows two forms of "content addressing" that may be used to select an item in an array of alternatives. The form used in ComposeFieldSelector
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. You can then get the corresponding URI as follows:
/// ComposeFieldSelector ( schemaNS, "Downloads", fieldNS, "City", chosenCity, &path ); /// exists = GetStructField ( schemaNS, path, fieldNS, "URI", &uri ); ///
schemaNS | The 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. | |
fieldNS | The namespace URI for the field used as the selector. Must not be null or the empty string. | |
fieldName | The name of the field used as the selector. Must be a simple 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. | |
fullPath | A pointer to the string that will be assigned the composed path. This will be of the form ns:arrayName[fNS:fieldName='fieldValue'] , where "ns" is the prefix for schemaNS and "fNS" is the prefix for fieldNS . |
static void TXMPUtils< tStringObj >::ConvertFromBool | ( | bool | binValue, | |
tStringObj * | strValue | |||
) | [static] |
Convert from Boolean to string.
binValue | The Boolean value to be converted. | |
strValue | The string representation of the Boolean. The values used are given by the macros kXMP_TrueStr and kXMP_FalseStr found in XMP_Const.h . |
static void TXMPUtils< tStringObj >::ConvertFromInt | ( | long | binValue, | |
XMP_StringPtr | format, | |||
tStringObj * | strValue | |||
) | [static] |
Convert from integer to string.
binValue | The integer value to be converted. | |
format | Optional C sprintf format for the conversion. Defaults to "%d". | |
strValue | The string representation of the integer. |
static void TXMPUtils< tStringObj >::ConvertFromFloat | ( | double | binValue, | |
XMP_StringPtr | format, | |||
tStringObj * | strValue | |||
) | [static] |
Convert from floating point to string.
binValue | The floating point value to be converted. | |
format | Optional C sprintf format for the conversion. Defaults to "%f". | |
strValue | The string representation of the floating point value. |
static void TXMPUtils< tStringObj >::ConvertFromDate | ( | const XMP_DateTime & | binValue, | |
tStringObj * | strValue | |||
) | [static] |
Convert from date/time to string.
Format 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 MM = two-digit month (01=January, etc.) 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)
As a compatibility "tactic" (OK, a hack), so-called time-only input is allowed where the year, month, and day are all zero. This is output as "0000-00-00...".
binValue | The XMP_DateTime value to be converted. | |
strValue | The ISO 8601 string representation of the date/time. |
static bool TXMPUtils< tStringObj >::ConvertToBool | ( | XMP_StringPtr | strValue | ) | [static] |
Convert from string to Boolean.
strValue | The string representation of the Boolean. |
kXMP_TrueStr
and kXMP_FalseStr
. If these do not match, a case insensitive comparison is tried, then simply 't' or 'f', and finally non-zero and zero integer representations. static long TXMPUtils< tStringObj >::ConvertToInt | ( | XMP_StringPtr | strValue | ) | [static] |
Convert from string to integer.
strValue | The string representation of the integer. |
static long long TXMPUtils< tStringObj >::ConvertToInt64 | ( | XMP_StringPtr | strValue | ) | [static] |
Convert from string to 64 bit integer.
strValue | The string representation of the integer. |
static double TXMPUtils< tStringObj >::ConvertToFloat | ( | XMP_StringPtr | strValue | ) | [static] |
Convert from string to floating point.
strValue | The string representation of the floating point value. |
static void TXMPUtils< tStringObj >::ConvertToDate | ( | XMP_StringPtr | strValue, | |
XMP_DateTime * | binValue | |||
) | [static] |
Convert from string to date/time.
Parse 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 MM = two-digit month (01=January, etc.) 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)
As compatibility "tactics" (OK, hacks), a missing date portion or missing TZD are tolerated. A missing date value may 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. | |
binValue | A pointer to the XMP_DateTime variable to be assigned the date/time components. |
static void TXMPUtils< tStringObj >::CurrentDateTime | ( | XMP_DateTime * | time | ) | [static] |
Obtain the current date and time.
time | A pointer to the XMP_DateTime variable to be assigned the current date and time. 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. |
static void TXMPUtils< tStringObj >::SetTimeZone | ( | XMP_DateTime * | time | ) | [static] |
Set the local time zone.
time | A pointer to the XMP_DateTime variable containing the value to be modified. Any existing time zone value is replaced, the other date/time fields are not adjusted in any way. |
static void TXMPUtils< tStringObj >::ConvertToUTCTime | ( | XMP_DateTime * | time | ) | [static] |
Make sure a time is UTC.
time | A pointer to the XMP_DateTime variable containing the time to be modified. If the time zone is not UTC, the time is adjusted and the time zone set to be UTC. |
static void TXMPUtils< tStringObj >::ConvertToLocalTime | ( | XMP_DateTime * | time | ) | [static] |
Make sure a time is local.
time | A pointer to the XMP_DateTime variable containing the time to be modified. If the time zone is not the local zone, the time is adjusted and the time zone set to be local. |
static int TXMPUtils< tStringObj >::CompareDateTime | ( | const XMP_DateTime & | left, | |
const XMP_DateTime & | right | |||
) | [static] |
Compare the order of two date/time values.
left | The "lefthand" date/time. | |
right | The "righthand" date/time. |
static void TXMPUtils< tStringObj >::EncodeToBase64 | ( | XMP_StringPtr | rawStr, | |
XMP_StringLen | rawLen, | |||
tStringObj * | encodedStr | |||
) | [static] |
Convert from raw data to Base64 encoded string.
rawStr | The pointer to raw data to be converted. | |
rawLen | The length of raw data to be converted. | |
encodedStr | The XMP object to contain the encoded string. |
static void TXMPUtils< tStringObj >::DecodeFromBase64 | ( | XMP_StringPtr | encodedStr, | |
XMP_StringLen | encodedLen, | |||
tStringObj * | rawStr | |||
) | [static] |
Decode from Base64 encoded string to raw data.
encodedStr | The pointer to encoded data to be converted. | |
encodedLen | The length of encoded datavto be converted. | |
rawStr | The XMP object to contain the decoded string. |
static void TXMPUtils< tStringObj >::PackageForJPEG | ( | const TXMPMeta< tStringObj > & | xmpObj, | |
tStringObj * | standardXMP, | |||
tStringObj * | extendedXMP, | |||
tStringObj * | extendedDigest | |||
) | [static] |
Create XMP serializations appropriate for a JPEG file. The standard XMP in a JPEG file is limited to about 65500 bytes. PackageForJPEG
attempts to fit the serialization within that limit. If necessary it will partition the XMP into 2 serializations.
xmpObj | The XMP for the JPEG file. | |
standardXMP | The full standard XMP packet. | |
extendedXMP | The serialized extended XMP, empty if not needed. | |
extendedDigest | An MD5 digest of the serialized extended XMP, empty if not needed. |
static void TXMPUtils< tStringObj >::MergeFromJPEG | ( | TXMPMeta< tStringObj > * | fullXMP, | |
const TXMPMeta< tStringObj > & | extendedXMP | |||
) | [static] |
Put the extended XMP properties back into the full XMP.
fullXMP | The full XMP, presumed to be initialized from the standard XMP packet. | |
extendedXMP | The properties that were partitioned into the extended XMP. |
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] |
Create a single edit string from an array of strings.
TBD - needs more description
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. Each item in the array must be a simple string value. | |
separator | The string to be used to separate the items in the catenated string. Defaults to "; ", ASCII semicolon and space (U+003B, U+0020). | |
quotes | The characters to be used as quotes around array items that contain a separator. Defaults to '"', ASCII quote (U+0022). | |
options | Option flags to control the catenation. | |
catedStr | A pointer to the string to be assigned the catenated array items. |
static void TXMPUtils< tStringObj >::SeparateArrayItems | ( | TXMPMeta< tStringObj > * | xmpObj, | |
XMP_StringPtr | schemaNS, | |||
XMP_StringPtr | arrayName, | |||
XMP_OptionBits | options, | |||
XMP_StringPtr | catedStr | |||
) | [static] |
Separate a single edit string into an array of strings.
TBD - needs more description
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. Each item in the array must be a simple string value. | |
options | Option flags to control the separation. | |
catedStr | The string to be separated into the array items. |
static void TXMPUtils< tStringObj >::RemoveProperties | ( | TXMPMeta< tStringObj > * | xmpObj, | |
XMP_StringPtr | schemaNS = 0 , |
|||
XMP_StringPtr | propName = 0 , |
|||
XMP_OptionBits | options = 0 | |||
) | [static] |
Remove multiple properties from an XMP object.
RemoveProperties
was created to support the File Info dialog's Delete button, and has been been generalized somewhat from those specific needs. It operates in one of three main modes depending on the schemaNS and propName parameters:
schemaNS
and propName
- The named property is removed if it is an external property, or if the kXMPUtil_DoAllProperties
option is passed. It does not matter whether the named property is an actual property or an alias.schemaNS
and empty propName
- The all external properties in the named schema are removed. Internal properties are also removed if the kXMPUtil_DoAllProperties
option is passed. In addition, aliases from the named schema will be removed if the kXMPUtil_IncludeAliases
option is passed.schemaNS
and empty propName
- All external properties in all schema are removed. Internal properties are also removed if the kXMPUtil_DoAllProperties
option is passed. Aliases are implicitly handled because the associated actuals are.
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. The defined flags are:
|
static void TXMPUtils< tStringObj >::AppendProperties | ( | const TXMPMeta< tStringObj > & | source, | |
TXMPMeta< tStringObj > * | dest, | |||
XMP_OptionBits | options = 0 | |||
) | [static] |
Append properties from one XMP object to another.
AppendProperties
was created to support the File Info dialog's Append button, and has been been generalized somewhat from those specific needs. It appends information from one XMP object (source
) to another (dest
). The default operation is to append only external properties that do not already exist in the destination. The kXMPUtil_DoAllProperties option can be used to operate on all properties, external and internal. The kXMPUtil_ReplaceOldValues option can be used to replace the values of existing properties. The notion of external versus internal applies only to top level properties. The keep-or-replace-old notion applies within structs and arrays as described below.
If kXMPUtil_ReplaceOldValues is passed then the processing is restricted to the top level properties. The processed properties from the source (according to kXMPUtil_DoAllProperties) are propagated to the destination, replacing any existing values. Properties in the destination that are not in the source are left alone.
If kXMPUtil_ReplaceOldValues is not passed then the processing is more complicated. Top level properties are added to the destination if they do not already exist. If they do exist but differ in form (simple/struct/array) then the destination is left alone. If the forms match, simple properties are left unchanged while structs and arrays are merged.
If kXMPUtil_DeleteEmptyValues is passed then an empty value in the source XMP causes the corresponding Dest XMP property to be deleted. The default is to treat empty values the same as non-empty values. An empty value is any of a simple empty string, an array with no items, or a struct with no fields. Qualifiers are ignored.
The detailed behavior is defined by the following pseudo-code:
/// AppendProperties ( sourceXMP, destXMP, options ): /// doAll = options & kXMPUtil_DoAllProperties /// replaceOld = options & kXMPUtil_ReplaceOldValues /// deleteEmpty = options & kXMPUtil_DeleteEmptyValues /// for all source schema (top level namespaces): /// for all top level properties in sourceSchema: /// if doAll or prop is external: /// AppendSubtree ( sourceNode, destSchema, replaceOld, deleteEmpty ) /// /// AppendSubtree ( sourceNode, destParent, replaceOld, deleteEmpty ): /// if deleteEmpty and source value is empty: /// delete the corresponding child from destParent /// else if sourceNode not in destParent (by name): /// copy sourceNode's subtree to destParent /// else if replaceOld: /// delete subtree from destParent /// copy sourceNode's subtree to destParent /// else: /// // Already exists in dest and not replacing, merge structs and arrays /// if sourceNode and destNode forms differ: /// return, leave the destNode alone /// else if form is a struct: /// for each field in sourceNode: /// AppendSubtree ( sourceNode.field, destNode, replaceOld ) /// else if form is an alt-text array: /// copy new items by xml:lang value into the destination /// else if form is an array: /// copy new items by value into the destination, ignoring order and duplicates ///
AppendProperties
can be expensive if replaceOld is not passed and the XMP contains large arrays. The array item checking described above is n-squared. 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.source | The source XMP object. | |
dest | The destination XMP object. | |
options | Option flags to control the copying.
|
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] |
Replicate a subtree from one XMP object into another, possibly at a different location.
TBD - needs more description
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. May 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. May be a general path expression. Defaults to the source location. | |
options | Option flags to control the separation. |