Main Page | Modules | Compound List | File List | Compound Members | File Members

TXMPUtils< tStringObj > Class Template Reference

Template class for the XMP Toolkit utility services. More...

#include <TXMPUtils.hpp>

List of all members.

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 );
        

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.


void ComposeArrayItemPath (XMP_StringPtr schemaNS, XMP_StringPtr arrayName, XMP_Index itemIndex, tStringObj *fullPath)
 Compose the path expression for an item in an array.

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.

void ComposeQualifierPath (XMP_StringPtr schemaNS, XMP_StringPtr propName, XMP_StringPtr qualNS, XMP_StringPtr qualName, tStringObj *fullPath)
 Compose the path expression for a qualifier.

void ComposeLangSelector (XMP_StringPtr schemaNS, XMP_StringPtr arrayName, XMP_StringPtr langName, tStringObj *fullPath)
 Compose the path expression to select an alternate item by language.

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

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.

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
void ConvertFromBool (bool binValue, tStringObj *strValue)
 Convert from Boolean to string.

void ConvertFromInt (long binValue, XMP_StringPtr format, tStringObj *strValue)
 Convert from integer to string.

void ConvertFromFloat (double binValue, XMP_StringPtr format, tStringObj *strValue)
 Convert from floating point to string.

void ConvertFromDate (const XMP_DateTime &binValue, tStringObj *strValue)
 Convert from date/time to string.

bool ConvertToBool (XMP_StringPtr strValue)
 Convert from string to Boolean.

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

long ConvertToInt (XMP_StringPtr strValue)
 Convert from string to integer.

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

long long ConvertToInt64 (XMP_StringPtr strValue)
 Convert from string to 64 bit integer.

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

double ConvertToFloat (XMP_StringPtr strValue)
 Convert from string to floating point.

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

void ConvertToDate (XMP_StringPtr strValue, XMP_DateTime *binValue)
 Convert from string to date/time.

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
void CurrentDateTime (XMP_DateTime *time)
 Obtain the current date and time.

void SetTimeZone (XMP_DateTime *time)
 Set the local time zone.

void ConvertToUTCTime (XMP_DateTime *time)
 Make sure a time is UTC.

void ConvertToLocalTime (XMP_DateTime *time)
 Make sure a time is local.

int CompareDateTime (const XMP_DateTime &left, const XMP_DateTime &right)
 Compare the order of two date/time values.

Base 64 Encoding and Decoding
void EncodeToBase64 (XMP_StringPtr rawStr, XMP_StringLen rawLen, tStringObj *encodedStr)
 Convert from raw data to Base64 encoded string.

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

void DecodeFromBase64 (XMP_StringPtr encodedStr, XMP_StringLen encodedLen, tStringObj *rawStr)
 Decode from Base64 encoded string to raw data.

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


Detailed Description

template<class tStringObj>
class TXMPUtils< tStringObj >

Template class for the XMP Toolkit utility services.

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 tStringObj, must have the following member functions (which match those for std::string):

     tStringObj& assign ( const char * str, size_t len )
     size_t size() const
     const char * c_str() const


Member Function Documentation

template<class tStringObj>
int TXMPUtils< tStringObj >::CompareDateTime const XMP_DateTime left,
const XMP_DateTime right
[static]
 

Compare the order of two date/time values.

Parameters:
left The "lefthand" date/time.
right The "righthand" date/time.
Returns:
  • -1 if left is before right
  • 0 if left matches right
  • +1 if left is after right

template<class tStringObj>
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.

Parameters:
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()].

template<class tStringObj>
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 );
        

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

template<class tStringObj>
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.

Note:
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.
Parameters:
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.

template<class tStringObj>
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.

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

template<class tStringObj>
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.

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

template<class tStringObj>
void TXMPUtils< tStringObj >::ConvertFromBool bool  binValue,
tStringObj *  strValue
[static]
 

Convert from Boolean to string.

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

template<class tStringObj>
void TXMPUtils< tStringObj >::ConvertFromDate const XMP_DateTime binValue,
tStringObj *  strValue
[static]
 

Convert from date/time to string.

Parameters:
binValue The XMP_DateTime value to be converted.
strValue The ISO 8601 string representation of the date/time.

template<class tStringObj>
void TXMPUtils< tStringObj >::ConvertFromFloat double  binValue,
XMP_StringPtr  format,
tStringObj *  strValue
[static]
 

Convert from floating point to string.

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

template<class tStringObj>
void TXMPUtils< tStringObj >::ConvertFromInt long  binValue,
XMP_StringPtr  format,
tStringObj *  strValue
[static]
 

Convert from integer to string.

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

template<class tStringObj>
bool TXMPUtils< tStringObj >::ConvertToBool XMP_StringPtr  strValue  )  [static]
 

Convert from string to Boolean.

Parameters:
strValue The string representation of the Boolean.
Returns:
The appropriate C++ bool value for the string. The preferred strings are 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.

template<class tStringObj>
void TXMPUtils< tStringObj >::ConvertToDate XMP_StringPtr  strValue,
XMP_DateTime binValue
[static]
 

Convert from string to date/time.

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

template<class tStringObj>
double TXMPUtils< tStringObj >::ConvertToFloat XMP_StringPtr  strValue  )  [static]
 

Convert from string to floating point.

Parameters:
strValue The string representation of the floating point value.
Returns:
The floating point value.

template<class tStringObj>
long TXMPUtils< tStringObj >::ConvertToInt XMP_StringPtr  strValue  )  [static]
 

Convert from string to integer.

Parameters:
strValue The string representation of the integer.
Returns:
The integer value as a C long.

template<class tStringObj>
long long TXMPUtils< tStringObj >::ConvertToInt64 XMP_StringPtr  strValue  )  [static]
 

Convert from string to 64 bit integer.

Parameters:
strValue The string representation of the integer.
Returns:
The integer value as a C long long.

template<class tStringObj>
void TXMPUtils< tStringObj >::ConvertToLocalTime XMP_DateTime time  )  [static]
 

Make sure a time is local.

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

template<class tStringObj>
void TXMPUtils< tStringObj >::ConvertToUTCTime XMP_DateTime time  )  [static]
 

Make sure a time is UTC.

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

template<class tStringObj>
void TXMPUtils< tStringObj >::CurrentDateTime XMP_DateTime time  )  [static]
 

Obtain the current date and time.

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

template<class tStringObj>
void TXMPUtils< tStringObj >::DecodeFromBase64 XMP_StringPtr  encodedStr,
XMP_StringLen  encodedLen,
tStringObj *  rawStr
[static]
 

Decode from Base64 encoded string to raw data.

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

template<class tStringObj>
void TXMPUtils< tStringObj >::EncodeToBase64 XMP_StringPtr  rawStr,
XMP_StringLen  rawLen,
tStringObj *  encodedStr
[static]
 

Convert from raw data to Base64 encoded string.

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

template<class tStringObj>
void TXMPUtils< tStringObj >::SetTimeZone XMP_DateTime time  )  [static]
 

Set the local time zone.

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


The documentation for this class was generated from the following file:
Generated on Mon Jan 2 12:25:55 2006 for Adobe XMP Toolkit by doxygen 1.3.3