summaryrefslogtreecommitdiff
path: root/public/include/TXMPUtils.hpp
diff options
context:
space:
mode:
Diffstat (limited to 'public/include/TXMPUtils.hpp')
-rw-r--r--public/include/TXMPUtils.hpp1278
1 files changed, 699 insertions, 579 deletions
diff --git a/public/include/TXMPUtils.hpp b/public/include/TXMPUtils.hpp
index 95cdc9c..4c69edd 100644
--- a/public/include/TXMPUtils.hpp
+++ b/public/include/TXMPUtils.hpp
@@ -7,41 +7,46 @@
// =================================================================================================
// ADOBE SYSTEMS INCORPORATED
-// Copyright 2002-2007 Adobe Systems Incorporated
+// Copyright 2002-2008 Adobe Systems Incorporated
// All Rights Reserved
//
// NOTICE: Adobe permits you to use, modify, and distribute this file in accordance with the terms
// of the Adobe license agreement accompanying it.
// =================================================================================================
-// ================================================================================================
+// =================================================================================================
/// \file TXMPUtils.hpp
-/// \brief Template class for the XMP Toolkit utility services.
+/// \brief API for access to the XMP Toolkit utility services.
///
-/// \c TXMPUtils is the template class providing utility services for the XMP Toolkit. It should be
-/// instantiated with a string class such as <tt>std::string</tt>. Please read the general toolkit
-/// usage notes for information about the overall architecture of the XMP API.
-// ================================================================================================
+/// \c TXMPUtils is the template class providing utility services for the XMP Toolkit. It must be
+/// instantiated with a string class such as \c std::string. See the instructions in XMP.hpp, and
+/// the Overview for a discussion of the overall architecture of the XMP API.
+// =================================================================================================
-// ================================================================================================
+// =================================================================================================
/// \class TXMPUtils TXMPUtils.hpp
-/// \brief Template class for the XMP Toolkit utility services.
+/// @brief API for access to the XMP Toolkit utility services.
///
-/// \c TXMPUtils is the template class providing utility services for the XMP Toolkit. It should be
-/// instantiated with a string class such as <tt>std::string</tt>. Please read the general toolkit
-/// usage notes for information about the overall architecture of the XMP API.
+/// \c TXMPUtils is a template class which must be instantiated with a string class such as
+/// \c std::string. See the instructions in XMP.hpp, and the Overview for a discussion of 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 <tt>const char *</tt>.
+/// This class defines helper functions that support the basic metadata manipulation provided by
+/// \c TXMPMeta. All of the functions are static; that is, you call them directly from the concrete
+/// class (\c SXMPUtils), which is never itself instantiated.
///
-/// The template parameter, class \c TtStringObj, is described in the XMP.hpp umbrella header.
-// ================================================================================================
+/// General categories of utilities include:
+///
+/// \li Composing complex path expressions, which you can then pass to the property access
+/// functions in \c TXMPMeta
+/// \li Converting between binary and string forms of property values
+/// \li Manipulating date/time values
+/// \li Encoding and decoding base-64 strings
+/// \li JPEG file handling
+/// \li Editing aids for creating a user interface for the XMP Toolkit
+// =================================================================================================
-template <class tStringObj>
-class TXMPUtils {
+template <class tStringObj> class TXMPUtils {
public:
@@ -49,795 +54,910 @@ public:
// No constructors or destructor declared or needed
// ================================================
- // =============================================================================================
- // =============================================================================================
-
// ============================================================================================
- /// \name Path composition functions
+ /// \name Path composition
/// @{
+ ///
/// These functions provide support for composing path expressions to deeply nested properties.
- /// The functions in \c TXMPMeta such as \c GetProperty, \c GetArrayItem, and \c 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 \c GetProperty_Int.
+ /// The functions in \c TXMPMeta such as \c TXMPMeta::GetProperty(),
+ /// \c TXMPMeta::GetArrayItem(), and \c 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
+ /// struct fields so that you can use the binary accessors such as
+ /// \c TXMPMeta::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:
+ /// 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:
///
- /// \verbatim
- /// SXMPUtils::ComposeStructFieldPath ( schemaNS, "Struct", fieldNS, "Array", &path );
- /// SXMPUtils::ComposeArrayItemPath ( schemaNS, path, index, &path );
- /// exists = xmpObj.GetProperty_Int ( schemaNS, path, &value, &options );
- /// \endverbatim
+ /// <pre>
+ /// SXMPUtils::ComposeStructFieldPath ( schemaNS, "Struct", fieldNS, "Array", &path );
+ /// SXMPUtils::ComposeArrayItemPath ( schemaNS, path, index, &path );
+ /// exists = xmpObj.GetProperty_Int ( schemaNS, path, &value, &options );
+ /// </pre>
///
/// You could also use this code if you want the string form of the integer:
///
- /// \verbatim
- /// SXMPUtils::ComposeStructFieldPath ( schemaNS, "Struct", fieldNS, "Array", &path );
- /// xmpObj.GetArrayItem ( schemaNS, path, index, &value, &options );
- /// \endverbatim
+ /// <pre>
+ /// SXMPUtils::ComposeStructFieldPath ( schemaNS, "Struct", fieldNS, "Array", &path );
+ /// xmpObj.GetArrayItem ( schemaNS, path, index, &value, &options );
+ /// </pre>
///
/// \note It might look confusing that the \c 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.
+ /// is because the XMP Toolkit keeps the top-level "schema" namespace separate from the rest of
+ /// the path expression.
- // --------------------------------------------------------------------------------------------
- /// \brief Compose the path expression for an item in an array.
+ // ---------------------------------------------------------------------------------------------
+ /// @brief \c ComposeArrayItemPath() composes the path expression for an item in an array.
///
- /// \param schemaNS The namespace URI for the array. Must not be null or the empty string.
+ /// The returned string is in the form <tt>ns:arrayName[i]</tt>, 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 <tt>ns:arrayName[last()]</tt>.
///
- /// \param arrayName The name of the array. May be a general path expression, must not be null
- /// or the empty string.
+ /// @param schemaNS The namespace URI for the array; see \c GetProperty().
+ ///
+ /// @param arrayName The name of the array. Can be a general path expression, must not be null
+ /// or the empty string; see \c GetProperty() for namespace prefix usage.
///
- /// \param itemIndex The index of the desired item. Arrays in XMP are indexed from 1. The
- /// constant \c kXMP_ArrayLastItem always refers to the last existing array item.
+ /// @param itemIndex The 1-based index of the desired item. Use the macro
+ /// \c #kXMP_ArrayLastItem to specify the last existing array item.
///
- /// \param fullPath A pointer to the string that will be assigned the composed path. This will
- /// be of the form <tt>ns:arrayName[i]</tt>, where "ns" is the prefix for \c schemaNS and "i"
- /// is the decimal representation of \c itemIndex. If the value of \c itemIndex is
- /// \c kXMP_ArrayLastItem, the path is <tt>ns:arrayName[last()]</tt>.
+ /// @param fullPath [out] A string in which to return the composed path.
- static void
- ComposeArrayItemPath ( XMP_StringPtr schemaNS,
- XMP_StringPtr arrayName,
- XMP_Index itemIndex,
- tStringObj * fullPath );
+ static void ComposeArrayItemPath ( XMP_StringPtr schemaNS,
+ XMP_StringPtr arrayName,
+ XMP_Index itemIndex,
+ tStringObj * fullPath );
- // --------------------------------------------------------------------------------------------
- /// \brief Compose the path expression for a field in a struct.
+ // ---------------------------------------------------------------------------------------------
+ /// @brief \c ComposeStructFieldPath() composes the path expression for a field in a struct.
///
- /// \param schemaNS The namespace URI for the struct. Must not be null or the empty string.
+ /// The returned string is in the form <tt>ns:structName/fNS:fieldName</tt>, where "ns" is the
+ /// prefix for the schema namespace, and "fNS" is the prefix for field namespace.
///
- /// \param structName The name of the struct. May be a general path expression, must not be null
- /// or the empty string.
+ /// @param schemaNS The namespace URI for the struct; see \c GetProperty().
///
- /// \param fieldNS The namespace URI for the field. Must not be null or the empty string.
+ /// @param structName The name of the struct. Can be a general path expression, must not be null
+ /// or the empty string; see \c GetProperty() for namespace prefix usage.
///
- /// \param fieldName The name of the field. Must be a simple XML name, must not be null or the
- /// empty string.
+ /// @param fieldNS The namespace URI for the field. Same URI and prefix usage as the
+ /// \c schemaNS and \c structName parameters.
///
- /// \param fullPath A pointer to the string that will be assigned the composed path. This will
- /// be of the form <tt>ns:structName/fNS:fieldName</tt>, where "ns" is the prefix for
- /// \c schemaNS and "fNS" is the prefix for \c fieldNS.
+ /// @param 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 \c schemaNS and \c structName parameters.
+ ///
+ /// @param fullPath [out] A string in which to return the composed path.
- static void
- ComposeStructFieldPath ( XMP_StringPtr schemaNS,
- XMP_StringPtr structName,
- XMP_StringPtr fieldNS,
- XMP_StringPtr fieldName,
- tStringObj * fullPath );
+ static void ComposeStructFieldPath ( XMP_StringPtr schemaNS,
+ XMP_StringPtr structName,
+ XMP_StringPtr fieldNS,
+ XMP_StringPtr fieldName,
+ tStringObj * fullPath );
- // --------------------------------------------------------------------------------------------
- /// \brief Compose the path expression for a qualifier.
+ // ---------------------------------------------------------------------------------------------
+ /// @brief \c ComposeQualifierPath() composes the path expression for a qualifier.
+ ///
+ /// The returned string is in the form <tt>ns:propName/?qNS:qualName</tt>, where "ns" is the
+ /// prefix for the schema namespace, and "qNS" is the prefix for the qualifier namespace.
///
- /// \param schemaNS The namespace URI for the property to which the qualifier is attached. Must
- /// not be null or the empty string.
+ /// @param schemaNS The namespace URI; see \c GetProperty().
///
- /// \param 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.
+ /// @param 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 \c GetProperty() for
+ /// namespace prefix usage.
///
- /// \param qualNS The namespace URI for the qualifier. May be null or the empty string if the
- /// qualifier is in the XML empty namespace.
+ /// @param qualNS The namespace URI for the qualifier. Same URI and prefix usage as the
+ /// \c schemaNS and \c propName parameters.
///
- /// \param qualName The name of the qualifier. Must be a simple XML name, must not be null or the
- /// empty string.
+ /// @param 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 \c schemaNS and \c propName parameters.
///
- /// \param fullPath A pointer to the string that will be assigned the composed path. This will
- /// be of the form <tt>ns:propName/?qNS:qualName</tt>, where "ns" is the prefix for \c schemaNS
- /// and "qNS" is the prefix for \c qualNS.
+ /// @param fullPath [out] A string in which to return the composed path.
- static void
- ComposeQualifierPath ( XMP_StringPtr schemaNS,
- XMP_StringPtr propName,
- XMP_StringPtr qualNS,
- XMP_StringPtr qualName,
- tStringObj * fullPath );
+ static void ComposeQualifierPath ( XMP_StringPtr schemaNS,
+ XMP_StringPtr propName,
+ XMP_StringPtr qualNS,
+ XMP_StringPtr qualName,
+ tStringObj * fullPath );
- // --------------------------------------------------------------------------------------------
- /// \brief Compose the path expression to select an alternate item by language.
+ // ---------------------------------------------------------------------------------------------
+ /// @brief \c ComposeLangSelector() composes 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 \c ComposeLangSelector lets you select an
- /// item in an alt-text array based on the value of its <tt>xml:lang</tt> qualifier. The other
- /// form of content addressing is shown in \c ComposeFieldSelector.
+ /// 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 \c xml:lang qualifier. The other form of content addressing is
+ /// shown in \c ComposeFieldSelector().
///
- /// \note \c ComposeLangSelector does not supplant \c SetLocalizedText or \c GetLocalizedText.
- /// They should generally be used, as they provide extra logic to choose the appropriate
- /// language and maintain consistency with the 'x-default' value. \c ComposeLangSelector gives
- /// you an path expression that is explicitly and only for the language given in the
- /// \c langName parameter.
+ /// The returned string is in the form <tt>ns:arrayName[\@xml:lang='langName']</tt>, where
+ /// "ns" is the prefix for the schema namespace
///
- /// \param schemaNS The namespace URI for the array. Must not be null or the empty string.
+ /// This function provides a path expression that is explicitly and only for a specific
+ /// language. In most cases, \c TXMPMeta::SetLocalizedText() and \c TXMPMeta::GetLocalizedText()
+ /// are preferred, because they provide extra logic to choose the appropriate language and
+ /// maintain consistency with the 'x-default' value.
///
- /// \param arrayName The name of the array. May be a general path expression, must not be null
- /// or the empty string.
+ /// @param schemaNS The namespace URI for the array; see \c GetProperty().
///
- /// \param langName The RFC 3066 code for the desired language.
+ /// @param arrayName The name of the array. Can be a general path expression, must not be null
+ /// or the empty string; see \c GetProperty() for namespace prefix usage.
///
- /// \param fullPath A pointer to the string that will be assigned the composed path. This will
- /// be of the form <tt>ns:arrayName[\@xml:lang='langName']</tt>,
- /// where "ns" is the prefix for \c schemaNS.
+ /// @param langName The RFC 3066 code for the desired language, as a null-terminated UTF-8 string.
+ ///
+ /// @param fullPath [out] A string in which to return the composed path.
- static void
- ComposeLangSelector ( XMP_StringPtr schemaNS,
- XMP_StringPtr arrayName,
- XMP_StringPtr langName,
- tStringObj * fullPath );
+ static void ComposeLangSelector ( XMP_StringPtr schemaNS,
+ XMP_StringPtr arrayName,
+ XMP_StringPtr langName,
+ tStringObj * fullPath );
- // --------------------------------------------------------------------------------------------
- /// \brief This form of \c ComposeLangSelector is a simple overload in the template that calls
- /// the above form passing <tt>langName.c_str()</tt>.
+ // ---------------------------------------------------------------------------------------------
+ /// @brief \c 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 \c xml:lang qualifier. The other form of content addressing is
+ /// shown in \c ComposeFieldSelector().
+ ///
+ /// The returned string is in the form <tt>ns:arrayName[\@xml:lang='langName']</tt>, 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, \c TXMPMeta::SetLocalizedText() and \c TXMPMeta::GetLocalizedText()
+ /// are preferred, because they provide extra logic to choose the appropriate language and
+ /// maintain consistency with the 'x-default' value.
+ ///
+ /// @param schemaNS The namespace URI for the array; see \c GetProperty().
+ ///
+ /// @param arrayName The name of the array. Can be a general path expression, must not be null
+ /// or the empty string; see \c GetProperty() for namespace prefix usage.
+ ///
+ /// @param langName The RFC 3066 code for the desired language, as a string object.
+ ///
+ /// @param fullPath [out] A string in which to return the composed path.
- static void
- ComposeLangSelector ( XMP_StringPtr schemaNS,
- XMP_StringPtr arrayName,
- const tStringObj & langName,
- tStringObj * fullPath );
+ static void ComposeLangSelector ( XMP_StringPtr schemaNS,
+ XMP_StringPtr arrayName,
+ const tStringObj & langName,
+ tStringObj * fullPath );
- // --------------------------------------------------------------------------------------------
- /// \brief Compose the path expression to select an alternate item by a field's value.
+ // ---------------------------------------------------------------------------------------------
+ /// @brief \c ComposeFieldSelector() composes a 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 \c 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 \c ComposeLangSelector.
+ /// 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 \c 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:
+ /// 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:
+ /// <pre>
+ /// ComposeFieldSelector ( schemaNS, "Downloads", fieldNS, "City", chosenCity, &path );
+ /// exists = GetStructField ( schemaNS, path, fieldNS, "URI", &uri );
+ /// </pre>
///
- /// \verbatim
- /// ComposeFieldSelector ( schemaNS, "Downloads", fieldNS, "City", chosenCity, &path );
- /// exists = GetStructField ( schemaNS, path, fieldNS, "URI", &uri );
- /// \endverbatim
+ /// The returned string is in the form <tt>ns:arrayName[fNS:fieldName='fieldValue']</tt>, where
+ /// "ns" is the prefix for the schema namespace and "fNS" is the prefix for the field namespace.
///
- /// \param schemaNS The namespace URI for the array. Must not be null or the empty string.
+ /// @param schemaNS The namespace URI for the array; see \c GetProperty().
///
- /// \param arrayName The name of the array. May be a general path expression, must not be null
- /// or the empty string.
+ /// @param arrayName The name of the array. Can be a general path expression, must not be null
+ /// or the empty string; see \c GetProperty() for namespace prefix usage.
///
- /// \param fieldNS The namespace URI for the field used as the selector. Must not be null or the
- /// empty string.
+ /// @param fieldNS The namespace URI for the field used as the selector. Same URI and prefix
+ /// usage as the \c schemaNS and \c arrayName parameters.
///
- /// \param fieldName The name of the field used as the selector. Must be a simple XML name, must
+ /// @param 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.
///
- /// \param fieldValue The desired value of the field.
+ /// @param fieldValue The desired value of the field, specified as a null-terminated UTF-8 string.
///
- /// \param fullPath A pointer to the string that will be assigned the composed path. This will
- /// be of the form <tt>ns:arrayName[fNS:fieldName='fieldValue']</tt>, where "ns" is the prefix
- /// for \c schemaNS and "fNS" is the prefix for \c fieldNS.
+ /// @param fullPath [out] A string in which to return the composed path.
- static void
- ComposeFieldSelector ( XMP_StringPtr schemaNS,
- XMP_StringPtr arrayName,
- XMP_StringPtr fieldNS,
- XMP_StringPtr fieldName,
- XMP_StringPtr fieldValue,
- tStringObj * fullPath );
+ static void ComposeFieldSelector ( XMP_StringPtr schemaNS,
+ XMP_StringPtr arrayName,
+ XMP_StringPtr fieldNS,
+ XMP_StringPtr fieldName,
+ XMP_StringPtr fieldValue,
+ tStringObj * fullPath );
- // --------------------------------------------------------------------------------------------
- /// \brief This form of ComposeFieldSelector is a simple overload in the template that calls the
- /// above form passing <tt>fieldValue.c_str()</tt>.
+ // ---------------------------------------------------------------------------------------------
+ /// @brief \c 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 \c 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:
+ /// <pre>
+ /// ComposeFieldSelector ( schemaNS, "Downloads", fieldNS, "City", chosenCity, &path );
+ /// exists = GetStructField ( schemaNS, path, fieldNS, "URI", &uri );
+ /// </pre>
+ ///
+ /// The returned string is in the form <tt>ns:arrayName[fNS:fieldName='fieldValue']</tt>, where
+ /// "ns" is the prefix for the schema namespace and "fNS" is the prefix for the field namespace.
+ ///
+ /// @param schemaNS The namespace URI for the array; see \c GetProperty().
+ ///
+ /// @param arrayName The name of the array. Can be a general path expression, must not be null
+ /// or the empty string; see \c GetProperty() for namespace prefix usage.
+ ///
+ /// @param fieldNS The namespace URI for the field used as the selector. Same URI and prefix
+ /// usage as the \c schemaNS and \c arrayName parameters.
+ ///
+ /// @param 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.
+ ///
+ /// @param fieldValue The desired value of the field, specified as a string object.
+ ///
+ /// @param fullPath [out] A string in which to return the composed path.
- static void
- ComposeFieldSelector ( XMP_StringPtr schemaNS,
- XMP_StringPtr arrayName,
- XMP_StringPtr fieldNS,
- XMP_StringPtr fieldName,
- const tStringObj & fieldValue,
- tStringObj * fullPath );
+ static void ComposeFieldSelector ( XMP_StringPtr schemaNS,
+ XMP_StringPtr arrayName,
+ XMP_StringPtr fieldNS,
+ XMP_StringPtr fieldName,
+ const tStringObj & fieldValue,
+ tStringObj * fullPath );
/// @}
// =============================================================================================
- // =============================================================================================
-
- // ============================================================================================
- /// \name Binary-String conversion functions
+ /// \name Conversion between binary types and strings
/// @{
+ ///
+ /// The main accessors in \c TXMPMeta set and retrieve property values as strings. additional
+ /// functions, such as \c 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 (\c #XMP_StringPtr), or as string
+ /// objects (\c tStringObj) of the type declared when instantiating the XMP classes; see
+ /// \c XMP.hpp. Alternate forms of each conversion function allow either type of string.
- // --------------------------------------------------------------------------------------------
- /// \brief Convert from Boolean to string.
+ // ---------------------------------------------------------------------------------------------
+ /// @brief \c ConvertFromBool() converts a Boolean value to a string.
///
- /// \param binValue The Boolean value to be converted.
+ /// The string values of Booleans are returned by the macros \c #kXMP_TrueStr and
+ /// \c #kXMP_FalseStr in \c XMP_Const.h.
///
- /// \param strValue The string representation of the Boolean. The values used are given by the
- /// macros \c kXMP_TrueStr and \c kXMP_FalseStr found in \c XMP_Const.h.
+ /// @param binValue The Boolean value to be converted.
+ ///
+ /// @param strValue [out] A buffer in which to return the string representation of the value.
- static void
- ConvertFromBool ( bool binValue,
- tStringObj * strValue );
+ static void ConvertFromBool ( bool binValue,
+ tStringObj * strValue );
- // --------------------------------------------------------------------------------------------
- /// \brief Convert from integer to string.
+ // ---------------------------------------------------------------------------------------------
+ /// @brief \c ConvertFromInt() converts a 32-bit integer value to a string.
///
- /// \param binValue The integer value to be converted.
+ /// @param binValue The integer value to be converted.
///
- /// \param format Optional C sprintf format for the conversion. Defaults to "%d".
+ /// @param format Optional. A C \c sprintf format for the conversion. Default is "%d".
///
- /// \param strValue The string representation of the integer.
+ /// @param strValue [out] A buffer in which to return the string representation of the value.
- static void
- ConvertFromInt ( long binValue,
- XMP_StringPtr format,
- tStringObj * strValue );
+ static void ConvertFromInt ( long binValue,
+ XMP_StringPtr format,
+ tStringObj * strValue );
+ // ---------------------------------------------------------------------------------------------
+ /// @brief \c ConvertFromInt64() converts a 64-bit integer value to a string.
+ ///
+ /// @param binValue The integer value to be converted.
+ ///
+ /// @param format Optional. A C \c sprintf format for the conversion. Default is "%d".
+ ///
+ /// @param strValue [out] A buffer in which to return the string representation of the value.
- static void
- ConvertFromInt64 ( long long binValue,
- XMP_StringPtr format,
- tStringObj * strValue );
+ static void ConvertFromInt64 ( long long binValue,
+ XMP_StringPtr format,
+ tStringObj * strValue );
- // --------------------------------------------------------------------------------------------
- /// \brief Convert from floating point to string.
+ // ---------------------------------------------------------------------------------------------
+ /// @brief \c ConvertFromFloat() converts a floating-point value to a string.
///
- /// \param binValue The floating point value to be converted.
+ /// @param binValue The floating-point value to be converted.
///
- /// \param format Optional C sprintf format for the conversion. Defaults to "%f".
+ /// @param format Optional. A C \c sprintf format for the conversion. Default is "%d".
///
- /// \param strValue The string representation of the floating point value.
+ /// @param strValue [out] A buffer in which to return the string representation of the value.
- static void
- ConvertFromFloat ( double binValue,
- XMP_StringPtr format,
- tStringObj * strValue );
+ static void ConvertFromFloat ( double binValue,
+ XMP_StringPtr format,
+ tStringObj * strValue );
- // --------------------------------------------------------------------------------------------
- /// \brief Convert from date/time to string.
+ // ---------------------------------------------------------------------------------------------
+ /// @brief \c ConvertFromDate() converts a date/time value to a 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
+ /// Formats a date according to the ISO 8601 profile in http://www.w3.org/TR/NOTE-datetime:
+ /// <pre>
+ /// YYYY
+ /// YYYY-MM
+ /// YYYY-MM-DD
+ /// YYYY-MM-DDThh:mmTZD
+ /// YYYY-MM-DDThh:mm:ssTZD
+ /// YYYY-MM-DDThh:mm:ss.sTZD
+ /// </pre>
///
- /// 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)
+ /// \c YYYY = four-digit year, formatted as "%.4d" <br>
+ /// \c MM = two-digit month (01=January) <br>
+ /// \c DD = two-digit day of month (01 through 31) <br>
+ /// \c hh = two digits of hour (00 through 23) <br>
+ /// \c mm = two digits of minute (00 through 59) <br>
+ /// \c ss = two digits of second (00 through 59) <br>
+ /// \c s = one or more digits representing a decimal fraction of a second <br>
+ /// \c TZD = time zone designator (Z or +hh:mm or -hh:mm)
///
- /// \note ISO 8601 does not seem to allow years less than 1000 or greater than 9999. We allow
- /// any year, even negative ones. The year is formatted as "%.4d".
+ /// Time-only input is allowed where the year, month, and day are all zero. This is output as
+ /// "0000-00-00...".
///
- /// \note 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...".
+ /// @note ISO 8601 does not allow years less than 1000 or greater than 9999. This API allows
+ /// any year, even negative ones.
///
- /// \param binValue The \c XMP_DateTime value to be converted.
+ /// @param binValue The date/time value to be converted.
///
- /// \param strValue The ISO 8601 string representation of the date/time.
+ /// @param strValue [out] A buffer in which to return the ISO 8601 string representation of the date/time.
- static void
- ConvertFromDate ( const XMP_DateTime & binValue,
- tStringObj * strValue );
+ static void ConvertFromDate ( const XMP_DateTime & binValue,
+ tStringObj * strValue );
- // --------------------------------------------------------------------------------------------
- /// \brief Convert from string to Boolean.
+ // ---------------------------------------------------------------------------------------------
+ /// @brief \c ConvertToBool() converts a string to a Boolean value.
+ ///
+ /// The preferred strings are those returned by the macros \c #kXMP_TrueStr and \c #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.
///
- /// \param strValue The string representation of the Boolean.
+ /// @param strValue The string representation of the value, specified as a null-terminated UTF-8 string.
///
- /// \result The appropriate C++ bool value for the string. The preferred strings are
- /// \c kXMP_TrueStr and \c 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.
+ /// @return The appropriate C++ bool value for the string.
- static bool
- ConvertToBool ( XMP_StringPtr strValue );
+ static bool ConvertToBool ( XMP_StringPtr strValue );
- // --------------------------------------------------------------------------------------------
- /// \brief This form of \c ConvertToBool is a simple overload in the template that calls the
- /// above form passing <tt>strValue.c_str()</tt>.
+ // ---------------------------------------------------------------------------------------------
+ /// @brief \c 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 <tt>const * char</tt>. It is otherwise identical; see details in the canonical form.
+ ///
+ /// @param strValue The string representation of the value, specified as a string object.
+ ///
+ /// @return The appropriate C++ bool value for the string.
- static bool
- ConvertToBool ( const tStringObj & strValue );
+ static bool ConvertToBool ( const tStringObj & strValue );
- // --------------------------------------------------------------------------------------------
- /// \brief Convert from string to integer.
+ // ---------------------------------------------------------------------------------------------
+ /// @brief \c ConvertToInt() converts a string to a 32-bit integer value.
///
- /// \param strValue The string representation of the integer.
+ /// @param strValue The string representation of the value, specified as a null-terminated UTF-8 string.
///
- /// \result The integer value as a C long.
+ /// @return The 32-bit integer value.
- static long
- ConvertToInt ( XMP_StringPtr strValue );
+ static long ConvertToInt ( XMP_StringPtr strValue );
- // --------------------------------------------------------------------------------------------
- /// \brief This form of \c ConvertToInt is a simple overload in the template that calls the above
- /// form passing <tt>strValue.c_str()</tt>.
+ // ---------------------------------------------------------------------------------------------
+ /// @brief \c 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 <tt>const * char</tt>. It is otherwise identical.
+ ///
+ /// @param strValue The string representation of the value, specified as a string object.
+ ///
+ /// @return The 32-bit integer value.
- static long
- ConvertToInt ( const tStringObj & strValue );
+ static long ConvertToInt ( const tStringObj & strValue );
- // --------------------------------------------------------------------------------------------
- /// \brief Convert from string to 64 bit integer.
+ // ---------------------------------------------------------------------------------------------
+ /// @brief \c ConvertToInt64() converts a string to a 64-bit integer value.
///
- /// \param strValue The string representation of the integer.
+ /// @param strValue The string representation of the value, specified as a null-terminated UTF-8 string.
///
- /// \result The integer value as a C long long.
+ /// @return The 64-bit integer value.
- static long long
- ConvertToInt64 ( XMP_StringPtr strValue );
+ static long long ConvertToInt64 ( XMP_StringPtr strValue );
- // --------------------------------------------------------------------------------------------
- /// \brief This form of ConvertToInt64 is a simple overload in the template that calls the above
- /// form passing <tt>strValue.c_str()</tt>.
+ // ---------------------------------------------------------------------------------------------
+ /// @brief \c 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 <tt>const * char</tt>. It is otherwise identical.
+ ///
+ /// @param strValue The string representation of the value, specified as a string object.
+ ///
+ /// @return The 64-bit integer value.
- static long long
- ConvertToInt64 ( const tStringObj & strValue );
+ static long long ConvertToInt64 ( const tStringObj & strValue );
- // --------------------------------------------------------------------------------------------
- /// \brief Convert from string to floating point.
+ // ---------------------------------------------------------------------------------------------
+ /// @brief \c ConvertToFloat() converts a string to a floating-point value.
///
- /// \param strValue The string representation of the floating point value.
+ /// @param strValue The string representation of the value, specified as a null-terminated UTF-8 string.
///
- /// \result The floating point value.
+ /// @return The floating-point value.
- static double
- ConvertToFloat ( XMP_StringPtr strValue );
+ static double ConvertToFloat ( XMP_StringPtr strValue );
- // --------------------------------------------------------------------------------------------
- /// \brief This form of \c ConvertToFloat is a simple overload in the template that calls the
- /// above form passing <tt>strValue.c_str()</tt>.
+ // ---------------------------------------------------------------------------------------------
+ /// @brief \c 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 <tt>const * char</tt>. It is otherwise identical.
+ ///
+ /// @param strValue The string representation of the value, specified as a string object.
+ ///
+ /// @return The floating-point value.
- static double
- ConvertToFloat ( const tStringObj & strValue );
+ static double ConvertToFloat ( const tStringObj & strValue );
- // --------------------------------------------------------------------------------------------
- /// \brief Convert from string to date/time.
+ // ---------------------------------------------------------------------------------------------
+ /// @brief \c ConvertToDate() converts a string to a date/time value.
///
- /// 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
+ /// Parses a date according to the ISO 8601 profile in http://www.w3.org/TR/NOTE-datetime:
+ /// <pre>
+ /// YYYY
+ /// YYYY-MM
+ /// YYYY-MM-DD
+ /// YYYY-MM-DDThh:mmTZD
+ /// YYYY-MM-DDThh:mm:ssTZD
+ /// YYYY-MM-DDThh:mm:ss.sTZD
+ /// </pre>
///
- /// 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)
+ /// \c YYYY = four-digit year, formatted as "%.4d" <br>
+ /// \c MM = two-digit month (01=January) <br>
+ /// \c DD = two-digit day of month (01 through 31) <br>
+ /// \c hh = two digits of hour (00 through 23) <br>
+ /// \c mm = two digits of minute (00 through 59) <br>
+ /// \c ss = two digits of second (00 through 59) <br>
+ /// \c s = one or more digits representing a decimal fraction of a second <br>
+ /// \c TZD = time zone designator (Z or +hh:mm or -hh:mm)
///
- /// \note ISO 8601 does not seem to allow years less than 1000 or greater than 9999. We allow
- /// any year, even negative ones. The year is assumed to be formatted as "%.4d".
+ /// 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 \c #XMP_DateTime value.
+ /// A missing TZD is assumed to be UTC.
///
- /// \note 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.
+ /// @note ISO 8601 does not allow years less than 1000 or greater than 9999. This API allows
+ /// any year, even negative ones.
///
- /// \param strValue The ISO 8601 string representation of the date/time.
+ /// @param strValue The ISO 8601 string representation of the date/time, specified as a
+ /// null-terminated UTF-8 string.
///
- /// \param binValue A pointer to the \c XMP_DateTime variable to be assigned the date/time components.
+ /// @param binValue [out] A buffer in which to return the binary date/time value.
- static void
- ConvertToDate ( XMP_StringPtr strValue,
- XMP_DateTime * binValue );
+ static void ConvertToDate ( XMP_StringPtr strValue,
+ XMP_DateTime * binValue );
- // --------------------------------------------------------------------------------------------
- /// \brief This form of \c ConvertToDate is a simple overload in the template that calls the above
- /// form passing s<tt>strValue.c_str()</tt>.
+ // ---------------------------------------------------------------------------------------------
+ /// @brief \c 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 <tt>const * char</tt>. It is otherwise identical.
+ /// See details for the canonical form.
+ ///
+ ///
+ /// @param strValue The ISO 8601 string representation of the date/time, specified as a string
+ /// object.
+ ///
+ /// @param binValue [out] A buffer in which to return the binary date/time value.
- static void
- ConvertToDate ( const tStringObj & strValue,
- XMP_DateTime * binValue );
+ static void ConvertToDate ( const tStringObj & strValue,
+ XMP_DateTime * binValue );
/// @}
// =============================================================================================
- // =============================================================================================
-
- // ============================================================================================
- /// \name Date/Time functions
+ /// \name Date-time manipulation
/// @{
+ ///
+ /// 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.
- // --------------------------------------------------------------------------------------------
- /// \brief Obtain the current date and time.
+ // ---------------------------------------------------------------------------------------------
+ /// @brief \c CurrentDateTime() obtains the current date and time.
+ ///
+ /// Creates and returns a binary \c #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.
///
- /// \param time A pointer to the \c 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.
+ /// @param time [out] A buffer in which to return the date/time value.
- static void
- CurrentDateTime ( XMP_DateTime * time );
+ static void CurrentDateTime ( XMP_DateTime * time );
- // --------------------------------------------------------------------------------------------
- /// \brief Set the local time zone.
+ // ---------------------------------------------------------------------------------------------
+ /// @brief \c 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.
///
- /// \param time A pointer to the \c 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.
+ /// @param time A pointer to the date-time value, which is modified in place.
- static void
- SetTimeZone ( XMP_DateTime * time );
+ static void SetTimeZone ( XMP_DateTime * time );
- // --------------------------------------------------------------------------------------------
- /// \brief Make sure a time is UTC.
+ // ---------------------------------------------------------------------------------------------
+ /// @brief \c ConvertToUTCTime() ensures that a time is UTC.
///
- /// \param time A pointer to the \c 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.
+ /// If the time zone is not UTC, the time is adjusted and the time zone set to be UTC. If the
+ /// time zone is already UTC, the value is not modified.
+ ///
+ /// @param time A pointer to the date-time value, which is modified in place.
- static void
- ConvertToUTCTime ( XMP_DateTime * time );
+ static void ConvertToUTCTime ( XMP_DateTime * time );
- // --------------------------------------------------------------------------------------------
- /// \brief Make sure a time is local.
+ // ---------------------------------------------------------------------------------------------
+ /// @brief \c 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.
+ /// If the time zone is already the local zone, the value is not modified.
///
- /// \param time A pointer to the \c 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.
+ /// @param time A pointer to the date-time value, which is modified in place.
- static void
- ConvertToLocalTime ( XMP_DateTime * time );
+ static void ConvertToLocalTime ( XMP_DateTime * time );
- // --------------------------------------------------------------------------------------------
- /// \brief Compare the order of two date/time values.
+ // ---------------------------------------------------------------------------------------------
+ /// @brief \c CompareDateTime() compares the order of two date/time values.
///
- /// \param left The "lefthand" date/time.
+ /// @param left The left-side date/time value.
///
- /// \param right The "righthand" date/time.
+ /// @param right The right-side date/time value.
///
- /// \result
- /// \li -1 if left is before right
- /// \li 0 if left matches right
- /// \li +1 if left is after right
+ /// @return An integer indicating the order:
+ /// \li -1 if left is earlier than right
+ /// \li 0 if left matches right
+ /// \li +1 if left is later than right
- static int
- CompareDateTime ( const XMP_DateTime & left,
- const XMP_DateTime & right );
+ static int CompareDateTime ( const XMP_DateTime & left,
+ const XMP_DateTime & right );
/// @}
// =============================================================================================
- // =============================================================================================
-
- // ============================================================================================
- /// \name Base 64 Encoding and Decoding
+ /// \name Base64 encoding and decoding
/// @{
+ ///
+ /// These functions convert between raw data values and Base64-encoded strings.
- // --------------------------------------------------------------------------------------------
- /// \brief Convert from raw data to Base64 encoded string.
+ // ---------------------------------------------------------------------------------------------
+ /// @brief \c EncodeToBase64() converts a raw data value to a Base64-encoded string.
///
- /// \param rawStr The pointer to raw data to be converted.
+ /// @param rawStr An \c #XMP_StringPtr (char *) string containing the raw data to be converted.
///
- /// \param rawLen The length of raw data to be converted.
+ /// @param rawLen The number of characters of raw data to be converted.
///
- /// \param encodedStr The XMP object to contain the encoded string.
+ /// @param encodedStr [out] A string object in which to return the encoded string.
- static void
- EncodeToBase64 ( XMP_StringPtr rawStr,
- XMP_StringLen rawLen,
- tStringObj * encodedStr );
+ static void EncodeToBase64 ( XMP_StringPtr rawStr,
+ XMP_StringLen rawLen,
+ tStringObj * encodedStr );
- // --------------------------------------------------------------------------------------------
- /// \brief This form of \c EncodeToBase64 is a simple overload in the template that calls the
- /// above form passing <tt>rawStr.c_str()</tt>, and <tt>rawStr.size()</tt>.
+ // ---------------------------------------------------------------------------------------------
+ /// @brief \c 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.
+ ///
+ /// @param rawStr A string object containing the raw data to be converted.
+ ///
+ /// @param encodedStr [out] A string object in which to return the encoded string.
- static void
- EncodeToBase64 ( const tStringObj & rawStr,
- tStringObj * encodedStr );
+ static void EncodeToBase64 ( const tStringObj & rawStr,
+ tStringObj * encodedStr );
- // --------------------------------------------------------------------------------------------
- /// \brief Decode from Base64 encoded string to raw data.
+ // ---------------------------------------------------------------------------------------------
+ /// @brief \c DecodeFromBase64() Decodes a Base64-encoded string to raw data.
///
- /// \param encodedStr The pointer to encoded data to be converted.
+ /// @param encodedStr An \c #XMP_StringPtr (char *) string containing the encoded data to be converted.
///
- /// \param encodedLen The length of encoded datavto be converted.
+ /// @param encodedLen The number of characters of raw data to be converted.
///
- /// \param rawStr The XMP object to contain the decoded string.
+ /// @param rawStr [out] A string object in which to return the decoded data.
- static void
- DecodeFromBase64 ( XMP_StringPtr encodedStr,
- XMP_StringLen encodedLen,
- tStringObj * rawStr );
+ static void DecodeFromBase64 ( XMP_StringPtr encodedStr,
+ XMP_StringLen encodedLen,
+ tStringObj * rawStr );
- // --------------------------------------------------------------------------------------------
- /// \brief This form of \c DecodeFromBase64 is a simple overload in the template that calls the
- /// above form passing <tt>encodedStr.c_str()</tt>, and <tt>encodedStr.size()</tt>.
+ // ---------------------------------------------------------------------------------------------
+ /// @brief \c 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.
+ ///
+ /// @param encodedStr An string object containing the encoded data to be converted.
+ ///
+ /// @param rawStr [out] A string object in which to return the decoded data.
- static void
- DecodeFromBase64 ( const tStringObj & encodedStr,
- tStringObj * rawStr );
+ static void DecodeFromBase64 ( const tStringObj & encodedStr,
+ tStringObj * rawStr );
/// @}
// =============================================================================================
// =============================================================================================
-
- // ============================================================================================
/// \name JPEG file handling
/// @{
- /// These functions support the partitioning of XMP in JPEG files into standard and extended
+ ///
+ /// 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.
+ ///
+ /// @note (Doc note) Add detail about how to write out and read back extended data
- // --------------------------------------------------------------------------------------------
- /// \brief Create XMP serializations appropriate for a JPEG file. The standard XMP in a JPEG
- /// file is limited to about 65500 bytes. \c PackageForJPEG attempts to fit the serialization
- /// within that limit. If necessary it will partition the XMP into 2 serializations.
+ // ---------------------------------------------------------------------------------------------
+ /// @brief \c PackageForJPEG() creates XMP serializations appropriate for a JPEG file.
///
- /// \param xmpObj The XMP for the 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 \c TXMPMeta::SerializeToBuffer()). If
+ /// the data does not fit into the 64K byte limit, it creates a second packet string with the
+ /// extended data.
///
- /// \param standardXMP The full standard XMP packet.
+ /// @param xmpObj The XMP object containing the metadata.
///
- /// \param extendedXMP The serialized extended XMP, empty if not needed.
+ /// @param standardXMP [out] A string object in which to return the full standard XMP packet.
///
- /// \param extendedDigest An MD5 digest of the serialized extended XMP, empty if not needed.
+ /// @param extendedXMP [out] A string object in which to return the serialized extended XMP,
+ /// empty if not needed.
+ ///
+ /// @param extendedDigest [out] A string object in which to return an MD5 digest of the serialized
+ /// extended XMP, empty if not needed.
+ ///
+ /// @see \c MergeFromJPEG()
- static void
- PackageForJPEG ( const TXMPMeta<tStringObj> & xmpObj,
- tStringObj * standardXMP,
- tStringObj * extendedXMP,
- tStringObj * extendedDigest );
+ static void PackageForJPEG ( const TXMPMeta<tStringObj> & xmpObj,
+ tStringObj * standardXMP,
+ tStringObj * extendedXMP,
+ tStringObj * extendedDigest );
- // --------------------------------------------------------------------------------------------
- /// \brief Put the extended XMP properties back into the full XMP.
+ // ---------------------------------------------------------------------------------------------
+ /// @brief \c 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.
///
- /// \param fullXMP The full XMP, presumed to be initialized from the standard XMP packet.
+ /// @param 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.
///
- /// \param extendedXMP The properties that were partitioned into the extended XMP.
+ /// @param extendedXMP An XMP object which the caller has initialized from the extended XMP
+ /// packet in a JPEG file.
+ ///
+ /// @see \c PackageForJPEG()
- static void
- MergeFromJPEG ( TXMPMeta<tStringObj> * fullXMP,
- const TXMPMeta<tStringObj> & extendedXMP );
+ static void MergeFromJPEG ( TXMPMeta<tStringObj> * fullXMP,
+ const TXMPMeta<tStringObj> & extendedXMP );
/// @}
// =============================================================================================
- // =============================================================================================
-
- // ============================================================================================
- /// \name UI helper functions
+ /// \name Editing utilities
/// @{
- /// These functions are mainly of interest in implementing a user interface for editing XMP.
+ ///
+ /// These functions are useful in implementing a user interface for editing XMP. They
+ /// 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.
- // --------------------------------------------------------------------------------------------
- /// \brief Create a single edit string from an array of strings.
+ // ---------------------------------------------------------------------------------------------
+ /// @brief \c CatenateArrayItems() creates a single edit string from a set of array item values.
///
- /// TBD - needs more description
+ /// 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.
///
- /// \param xmpObj The XMP object containing the array to be catenated.
+ /// @param xmpObj The XMP object containing the array to be catenated.
///
- /// \param schemaNS The schema namespace URI for the array. Must not be null or the empty string.
+ /// @param schemaNS The schema namespace URI for the array. Must not be null or the empty string.
///
- /// \param 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.
+ /// @param arrayName The name of the array. May be a general path expression, must not be null
+ /// or the empty string.
///
- /// \param separator The string to be used to separate the items in the catenated string.
+ /// @param separator The string with which to separate the items in the catenated string.
/// Defaults to "; ", ASCII semicolon and space (U+003B, U+0020).
///
- /// \param quotes The characters to be used as quotes around array items that contain a separator.
- /// Defaults to '"', ASCII quote (U+0022).
+ /// @param 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).
+ ///
+ /// @param options Option flags to control the catenation. <<what options?>>
///
- /// \param options Option flags to control the catenation.
+ /// @param catedStr [out] A string object in which to return the catenated array items.
///
- /// \param catedStr A pointer to the string to be assigned the catenated array items.
+ /// @see \c SeparateArrayItems()
- static void
- CatenateArrayItems ( const TXMPMeta<tStringObj> & xmpObj,
- XMP_StringPtr schemaNS,
- XMP_StringPtr arrayName,
- XMP_StringPtr separator,
- XMP_StringPtr quotes,
- XMP_OptionBits options,
- tStringObj * catedStr );
+ static void CatenateArrayItems ( const TXMPMeta<tStringObj> & xmpObj,
+ XMP_StringPtr schemaNS,
+ XMP_StringPtr arrayName,
+ XMP_StringPtr separator,
+ XMP_StringPtr quotes,
+ XMP_OptionBits options,
+ tStringObj * catedStr );
- // --------------------------------------------------------------------------------------------
- /// \brief Separate a single edit string into an array of strings.
+ // ---------------------------------------------------------------------------------------------
+ /// @brief \c SeparateArrayItems() updates an array from a concatenated edit string of values.
///
- /// TBD - needs more description
+ /// This reverses the action of \c 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.
///
- /// \param xmpObj The XMP object containing the array to be updated.
+ /// @param xmpObj The XMP object containing the array to be updated.
///
- /// \param schemaNS The schema namespace URI for the array. Must not be null or the empty string.
+ /// @param schemaNS The schema namespace URI for the array. Must not be null or the empty string.
///
- /// \param 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.
+ /// @param arrayName The name of the array. May be a general path expression, must not be null
+ /// or the empty string.
///
- /// \param options Option flags to control the separation.
+ /// @param options Option flags to control the separation. <<what options?>>
///
- /// \param catedStr The string to be separated into the array items.
+ /// @param catedStr The concatenated array items, as created by \c CatenateArrayItems(),
+ /// specified as a null-terminated UTF-8 string.
- static void
- SeparateArrayItems ( TXMPMeta<tStringObj> * xmpObj,
- XMP_StringPtr schemaNS,
- XMP_StringPtr arrayName,
- XMP_OptionBits options,
- XMP_StringPtr catedStr );
+ static void SeparateArrayItems ( TXMPMeta<tStringObj> * xmpObj,
+ XMP_StringPtr schemaNS,
+ XMP_StringPtr arrayName,
+ XMP_OptionBits options,
+ XMP_StringPtr catedStr );
- // --------------------------------------------------------------------------------------------
- /// \brief This form of \c SeparateArrayItems is a simple overload in the template that calls
- /// the aboveform passing <tt>catedStr.c_str()</tt>.
+ // ---------------------------------------------------------------------------------------------
+ /// @brief \c 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
- SeparateArrayItems ( TXMPMeta<tStringObj> * xmpObj,
- XMP_StringPtr schemaNS,
- XMP_StringPtr arrayName,
- XMP_OptionBits options,
- const tStringObj & catedStr );
+ static void SeparateArrayItems ( TXMPMeta<tStringObj> * xmpObj,
+ XMP_StringPtr schemaNS,
+ XMP_StringPtr arrayName,
+ XMP_OptionBits options,
+ const tStringObj & catedStr );
- // --------------------------------------------------------------------------------------------
- /// \brief Remove multiple properties from an XMP object.
+ // ---------------------------------------------------------------------------------------------
+ /// @brief \c RemoveProperties() removes multiple properties from an XMP object.
///
- /// \c 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:
+ /// The operation depends on how the namespace and property are specified:
///
- /// \li Non-empty \c schemaNS and \c propName - The named property is removed if it is an
- /// external property, or if the \c kXMPUtil_DoAllProperties option is passed. It does not
- /// matter whether the named property is an actual property or an alias.
+ /// \li Non-empty \c schemaNS and \c propName - The named property is removed if it is an
+ /// external property, or if the \c #kXMPUtil_DoAllProperties option flag is set. It does not
+ /// matter whether the named property is an actual property or an alias.
///
- /// \li Non-empty \c schemaNS and empty \c propName - The all external properties in the named
- /// schema are removed. Internal properties are also removed if the \c kXMPUtil_DoAllProperties
- /// option is passed. In addition, aliases from the named schema will be removed if the \c
- /// kXMPUtil_IncludeAliases option is passed.
+ /// \li Non-empty \c schemaNS and empty \c propName - All external properties in the named
+ /// schema are removed. Internal properties are also removed if the
+ /// \c #kXMPUtil_DoAllProperties option flag is set. In addition, aliases from the named schema
+ /// are removed if the \c #kXMPUtil_IncludeAliases option flag is set.
///
- /// \li Empty \c schemaNS and empty \c propName - All external properties in all schema are
- /// removed. Internal properties are also removed if the \c kXMPUtil_DoAllProperties option is
- /// passed. Aliases are implicitly handled because the associated actuals are.
+ /// \li Empty \c schemaNS and empty \c propName - All external properties in all schemas are
+ /// removed. Internal properties are also removed if the \c #kXMPUtil_DoAllProperties option
+ /// flag is set. Aliases are handled implicitly, because the associated actuals are removed or
+ /// not.
///
- /// It is an error to pass and empty schemaNS and non-empty propName.
+ /// \li It is an error to pass an empty \c schemaNS and non-empty \c propName.
///
- /// \param xmpObj The XMP object containing the properties to be removed.
+ /// @param xmpObj The XMP object containing the properties to be removed.
///
- /// \param schemaNS Optional schema namespace URI for the properties to be removed.
+ /// @param schemaNS Optional schema namespace URI for the properties to be removed.
///
- /// \param propName Optional path expression for the property to be removed.
+ /// @param propName Optional path expression for the property to be removed.
///
- /// \param options Option flags to control the deletion. The defined flags are:
- /// \li \c kXMPUtil_DoAllProperties - Do internal properties in addition to external properties.
- /// \li \c kXMPUtil_IncludeAliases - Include aliases in the "named schema" case above.
+ /// @param options Option flags to control the deletion operation. A logical OR of these
+ /// bit-flag constants:
+ /// \li \c #kXMPUtil_DoAllProperties - Delete internal properties in addition to external properties.
+ /// \li \c #kXMPUtil_IncludeAliases - Include aliases if the schema is explicitly specified.
- static void
- RemoveProperties ( TXMPMeta<tStringObj> * xmpObj,
- XMP_StringPtr schemaNS = 0,
- XMP_StringPtr propName = 0,
- XMP_OptionBits options = 0 );
+ static void RemoveProperties ( TXMPMeta<tStringObj> * xmpObj,
+ XMP_StringPtr schemaNS = 0,
+ XMP_StringPtr propName = 0,
+ XMP_OptionBits options = 0 );
- // --------------------------------------------------------------------------------------------
- /// \brief Append properties from one XMP object to another.
+ // ---------------------------------------------------------------------------------------------
+ /// @brief \c AppendProperties() adds or moves properties from one XMP object to another.
///
- /// \c 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 (\c source) to another (\c 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.
+ /// The default operation is to append only external properties that do not already exist in the
+ /// destination. Option flags allow you to add internal properties, and to merge values of
+ /// properties that exist in both the source and destination.
///
- /// 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.
+ /// \li \c #kXMPUtil_DoAllProperties: Operate on all top-level properties, external and
+ /// internal. You can use this flag together with \c #kXMPUtil_ReplaceOldValues to replace the
+ /// values of existing top-level properties.
///
- /// 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.
+ /// \li \c #kXMPUtil_ReplaceOldValues: Propogate all top-level properties from the source to
+ /// the destination, replacing any existing values. The values of properties in the
+ /// destination that are not in the source are not modified.<br>
+ /// The keep-or-replace-old notion also applies within structs and arrays. 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 not modified. If the forms
+ /// match, simple properties are left unchanged, while structs and arrays are merged.<br>
+ /// Do not use this option when the processing is more complicated. <<than what??>>
///
- /// 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.
+ /// \li \c #kXMPUtil_DeleteEmptyValues: An empty value in the source XMP causes the
+ /// corresponding destination property to be deleted. By default, empty values are treated in
+ /// the same way as non-empty values. An empty value is 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:
- /// \verbatim
- /// 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
- /// \endverbatim
- ///
- /// \note \c 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.
- ///
- /// \param source The source XMP object.
- ///
- /// \param dest The destination XMP object.
- ///
- /// \param options Option flags to control the copying.
- /// \li \c kXMPUtil_DoAllProperties - Do internal properties in addition to external properties.
- /// \li \c kXMPUtil_ReplaceOldValues - Replace the values of existing properties.
- /// \li \c kXMPUtil_DeleteEmptyValues - Delete properties if the new value is empty.
-
- static void
- AppendProperties ( const TXMPMeta<tStringObj> & source,
- TXMPMeta<tStringObj> * dest,
- XMP_OptionBits options = 0 );
-
- // --------------------------------------------------------------------------------------------
- /// \brief Replicate a subtree from one XMP object into another, possibly at a different location.
- ///
- /// TBD - needs more description
- ///
- /// \param source The source XMP object.
- ///
- /// \param dest The destination XMP object.
- ///
- /// \param sourceNS The schema namespace URI for the source subtree.
- ///
- /// \param sourceRoot The root location for the source subtree. May be a general path expression,
+ ///
+ /// <pre>
+ /// 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
+ /// </pre>
+ ///
+ /// Array item checking is n-squared; this can be time-intensive if the replace-old options 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 \c 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.
+ ///
+ /// @param source The source XMP object.
+ ///
+ /// @param dest The destination XMP object.
+ ///
+ /// @param options Option flags to control the copying. A logical OR of these bit-flag constants:
+ /// \li \c kXMPUtil_DoAllProperties - Operate on internal properties in addition to external properties.
+ /// \li \c kXMPUtil_ReplaceOldValues - Replace the values of existing properties.
+ /// \li \c kXMPUtil_DeleteEmptyValues - Delete properties if the new value is empty.
+
+ static void AppendProperties ( const TXMPMeta<tStringObj> & source,
+ TXMPMeta<tStringObj> * dest,
+ XMP_OptionBits options = 0 );
+
+ // ---------------------------------------------------------------------------------------------
+ /// @brief \c 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.
+ ///
+ /// @param source The source XMP object.
+ ///
+ /// @param dest The destination XMP object.
+ ///
+ /// @param sourceNS The schema namespace URI for the source subtree.
+ ///
+ /// @param sourceRoot The root location for the source subtree. Can be a general path expression,
/// must not be null or the empty string.
///
- /// \param destNS The schema namespace URI for the destination. Defaults to the source namespace.
+ /// @param destNS The schema namespace URI for the destination. Defaults to the source namespace.
///
- /// \param destRoot The root location for the destination. May be a general path expression.
+ /// @param destRoot The root location for the destination. Can be a general path expression.
/// Defaults to the source location.
///
- /// \param options Option flags to control the separation.
-
- 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 );
+ /// @param options Option flags to control the operation. <<options?>>
+ 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 );
/// @}
// =============================================================================================
+ // =============================================================================================
+
}; // class TXMPUtils
// =================================================================================================