|
Packit Service |
21b5d1 |
#ifndef __TXMPUtils_hpp__
|
|
Packit Service |
21b5d1 |
#define __TXMPUtils_hpp__ 1
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
#if ( ! __XMP_hpp__ )
|
|
Packit Service |
21b5d1 |
#error "Do not directly include, use XMPSDK.hpp"
|
|
Packit Service |
21b5d1 |
#endif
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
// =================================================================================================
|
|
Packit Service |
21b5d1 |
// ADOBE SYSTEMS INCORPORATED
|
|
Packit Service |
21b5d1 |
// Copyright 2002-2008 Adobe Systems Incorporated
|
|
Packit Service |
21b5d1 |
// All Rights Reserved
|
|
Packit Service |
21b5d1 |
//
|
|
Packit Service |
21b5d1 |
// NOTICE: Adobe permits you to use, modify, and distribute this file in accordance with the terms
|
|
Packit Service |
21b5d1 |
// of the Adobe license agreement accompanying it.
|
|
Packit Service |
21b5d1 |
// =================================================================================================
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
// =================================================================================================
|
|
Packit Service |
21b5d1 |
/// \file TXMPUtils.hpp
|
|
Packit Service |
21b5d1 |
/// \brief API for access to the XMP Toolkit utility services.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// \c TXMPUtils is the template class providing utility services for the XMP Toolkit. It must be
|
|
Packit Service |
21b5d1 |
/// instantiated with a string class such as \c std::string. See the instructions in XMPSDK.hpp, and
|
|
Packit Service |
21b5d1 |
/// the Overview for a discussion of the overall architecture of the XMP API.
|
|
Packit Service |
21b5d1 |
// =================================================================================================
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
// =================================================================================================
|
|
Packit Service |
21b5d1 |
/// \class TXMPUtils TXMPUtils.hpp
|
|
Packit Service |
21b5d1 |
/// @brief API for access to the XMP Toolkit utility services.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// \c TXMPUtils is a template class which must be instantiated with a string class such as
|
|
Packit Service |
21b5d1 |
/// \c std::string. See the instructions in XMPSDK.hpp, and the Overview for a discussion of the overall
|
|
Packit Service |
21b5d1 |
/// architecture of the XMP API.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// This class defines helper functions that support the basic metadata manipulation provided by
|
|
Packit Service |
21b5d1 |
/// \c TXMPMeta. All of the functions are static; that is, you call them directly from the concrete
|
|
Packit Service |
21b5d1 |
/// class (\c SXMPUtils), which is never itself instantiated.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// General categories of utilities include:
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// \li Composing complex path expressions, which you can then pass to the property access
|
|
Packit Service |
21b5d1 |
/// functions in \c TXMPMeta
|
|
Packit Service |
21b5d1 |
/// \li Converting between binary and string forms of property values
|
|
Packit Service |
21b5d1 |
/// \li Manipulating date/time values
|
|
Packit Service |
21b5d1 |
/// \li Encoding and decoding base-64 strings
|
|
Packit Service |
21b5d1 |
/// \li JPEG file handling
|
|
Packit Service |
21b5d1 |
/// \li Editing aids for creating a user interface for the XMP Toolkit
|
|
Packit Service |
21b5d1 |
// =================================================================================================
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
template <class tStringObj> class TXMPUtils {
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
public:
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
// =============================================================================================
|
|
Packit Service |
21b5d1 |
// No constructors or destructor declared or needed
|
|
Packit Service |
21b5d1 |
// ================================================
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
// ============================================================================================
|
|
Packit Service |
21b5d1 |
/// \name Path composition
|
|
Packit Service |
21b5d1 |
/// @{
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// These functions provide support for composing path expressions to deeply nested properties.
|
|
Packit Service |
21b5d1 |
/// The functions in \c TXMPMeta such as \c TXMPMeta::GetProperty(),
|
|
Packit Service |
21b5d1 |
/// \c TXMPMeta::GetArrayItem(), and \c TXMPMeta::GetStructField() provide easy access to top level
|
|
Packit Service |
21b5d1 |
/// simple properties, items in top level arrays, and fields of top level structs. They are
|
|
Packit Service |
21b5d1 |
/// not as convenient for more complex things, such as fields several levels deep in a complex
|
|
Packit Service |
21b5d1 |
/// struct, or fields within an array of structs, or items of an array that is a field of a
|
|
Packit Service |
21b5d1 |
/// struct. You can use these utility functions to compose these paths, which you can then pass
|
|
Packit Service |
21b5d1 |
/// to the property access functions. You can also compose paths to top-level array items or
|
|
Packit Service |
21b5d1 |
/// struct fields so that you can use the binary accessors such as
|
|
Packit Service |
21b5d1 |
/// \c TXMPMeta::GetProperty_Int().
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// You can use these functions is to compose a complete path expression, or all but the last
|
|
Packit Service |
21b5d1 |
/// component. For example, suppose you have a property that is an array of integers within a
|
|
Packit Service |
21b5d1 |
/// struct. You can access one of the array items like this:
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// SXMPUtils::ComposeStructFieldPath ( schemaNS, "Struct", fieldNS, "Array", &path );
|
|
Packit Service |
21b5d1 |
/// SXMPUtils::ComposeArrayItemPath ( schemaNS, path, index, &path );
|
|
Packit Service |
21b5d1 |
/// exists = xmpObj.GetProperty_Int ( schemaNS, path, &value, &options );
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// You could also use this code if you want the string form of the integer:
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// SXMPUtils::ComposeStructFieldPath ( schemaNS, "Struct", fieldNS, "Array", &path );
|
|
Packit Service |
21b5d1 |
/// xmpObj.GetArrayItem ( schemaNS, path, index, &value, &options );
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// \note It might look confusing that the \c schemaNS is passed in all of the calls above. This
|
|
Packit Service |
21b5d1 |
/// is because the XMP Toolkit keeps the top-level "schema" namespace separate from the rest of
|
|
Packit Service |
21b5d1 |
/// the path expression.
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
// ---------------------------------------------------------------------------------------------
|
|
Packit Service |
21b5d1 |
/// @brief \c ComposeArrayItemPath() composes the path expression for an item in an array.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// The returned string is in the form <tt>ns:arrayName[i]</tt>, where "ns" is the prefix for
|
|
Packit Service |
21b5d1 |
/// the specified namespace, and "i" is the decimal representation of specified item index.
|
|
Packit Service |
21b5d1 |
/// If the last item was specified, the path is <tt>ns:arrayName[last()]</tt>.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param schemaNS The namespace URI for the array; see \c GetProperty().
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param arrayName The name of the array. Can be a general path expression, must not be null
|
|
Packit Service |
21b5d1 |
/// or the empty string; see \c GetProperty() for namespace prefix usage.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param itemIndex The 1-based index of the desired item. Use the macro
|
|
Packit Service |
21b5d1 |
/// \c #kXMP_ArrayLastItem to specify the last existing array item.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param fullPath [out] A string in which to return the composed path.
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
static void ComposeArrayItemPath ( XMP_StringPtr schemaNS,
|
|
Packit Service |
21b5d1 |
XMP_StringPtr arrayName,
|
|
Packit Service |
21b5d1 |
XMP_Index itemIndex,
|
|
Packit Service |
21b5d1 |
tStringObj * fullPath );
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
// ---------------------------------------------------------------------------------------------
|
|
Packit Service |
21b5d1 |
/// @brief \c ComposeStructFieldPath() composes the path expression for a field in a struct.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// The returned string is in the form <tt>ns:structName/fNS:fieldName</tt>, where "ns" is the
|
|
Packit Service |
21b5d1 |
/// prefix for the schema namespace, and "fNS" is the prefix for field namespace.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param schemaNS The namespace URI for the struct; see \c GetProperty().
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param structName The name of the struct. Can be a general path expression, must not be null
|
|
Packit Service |
21b5d1 |
/// or the empty string; see \c GetProperty() for namespace prefix usage.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param fieldNS The namespace URI for the field. Same URI and prefix usage as the
|
|
Packit Service |
21b5d1 |
/// \c schemaNS and \c structName parameters.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param fieldName The name of the field. Must be a single XML name, must not be null or the
|
|
Packit Service |
21b5d1 |
/// empty string. Same URI and prefix usage as the \c schemaNS and \c structName parameters.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param fullPath [out] A string in which to return the composed path.
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
static void ComposeStructFieldPath ( XMP_StringPtr schemaNS,
|
|
Packit Service |
21b5d1 |
XMP_StringPtr structName,
|
|
Packit Service |
21b5d1 |
XMP_StringPtr fieldNS,
|
|
Packit Service |
21b5d1 |
XMP_StringPtr fieldName,
|
|
Packit Service |
21b5d1 |
tStringObj * fullPath );
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
// ---------------------------------------------------------------------------------------------
|
|
Packit Service |
21b5d1 |
/// @brief \c ComposeQualifierPath() composes the path expression for a qualifier.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// The returned string is in the form <tt>ns:propName/?qNS:qualName</tt>, where "ns" is the
|
|
Packit Service |
21b5d1 |
/// prefix for the schema namespace, and "qNS" is the prefix for the qualifier namespace.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param schemaNS The namespace URI; see \c GetProperty().
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param propName The name of the property to which the qualifier is attached. Can be a
|
|
Packit Service |
21b5d1 |
/// general path expression, must not be null or the empty string; see \c GetProperty() for
|
|
Packit Service |
21b5d1 |
/// namespace prefix usage.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param qualNS The namespace URI for the qualifier. Same URI and prefix usage as the
|
|
Packit Service |
21b5d1 |
/// \c schemaNS and \c propName parameters.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param qualName The name of the qualifier. Must be a single XML name, must not be null or the
|
|
Packit Service |
21b5d1 |
/// empty string. Same URI and prefix usage as the \c schemaNS and \c propName parameters.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param fullPath [out] A string in which to return the composed path.
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
static void ComposeQualifierPath ( XMP_StringPtr schemaNS,
|
|
Packit Service |
21b5d1 |
XMP_StringPtr propName,
|
|
Packit Service |
21b5d1 |
XMP_StringPtr qualNS,
|
|
Packit Service |
21b5d1 |
XMP_StringPtr qualName,
|
|
Packit Service |
21b5d1 |
tStringObj * fullPath );
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
// ---------------------------------------------------------------------------------------------
|
|
Packit Service |
21b5d1 |
/// @brief \c ComposeLangSelector() composes the path expression to select an alternate item by language.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// Path syntax allows two forms of "content addressing" to select an item in an array of
|
|
Packit Service |
21b5d1 |
/// alternatives. The form used in this function lets you select an item in an alt-text array
|
|
Packit Service |
21b5d1 |
/// based on the value of its \c xml:lang qualifier. The other form of content addressing is
|
|
Packit Service |
21b5d1 |
/// shown in \c ComposeFieldSelector().
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// The returned string is in the form <tt>ns:arrayName[\@xml:lang='langName']</tt>, where
|
|
Packit Service |
21b5d1 |
/// "ns" is the prefix for the schema namespace
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// This function provides a path expression that is explicitly and only for a specific
|
|
Packit Service |
21b5d1 |
/// language. In most cases, \c TXMPMeta::SetLocalizedText() and \c TXMPMeta::GetLocalizedText()
|
|
Packit Service |
21b5d1 |
/// are preferred, because they provide extra logic to choose the appropriate language and
|
|
Packit Service |
21b5d1 |
/// maintain consistency with the 'x-default' value.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param schemaNS The namespace URI for the array; see \c GetProperty().
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param arrayName The name of the array. Can be a general path expression, must not be null
|
|
Packit Service |
21b5d1 |
/// or the empty string; see \c GetProperty() for namespace prefix usage.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param langName The RFC 3066 code for the desired language, as a null-terminated UTF-8 string.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param fullPath [out] A string in which to return the composed path.
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
static void ComposeLangSelector ( XMP_StringPtr schemaNS,
|
|
Packit Service |
21b5d1 |
XMP_StringPtr arrayName,
|
|
Packit Service |
21b5d1 |
XMP_StringPtr langName,
|
|
Packit Service |
21b5d1 |
tStringObj * fullPath );
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
// ---------------------------------------------------------------------------------------------
|
|
Packit Service |
21b5d1 |
/// @brief \c ComposeLangSelector() composes a path expression to select an alternate item by language.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// Path syntax allows two forms of "content addressing" to select an item in an array of
|
|
Packit Service |
21b5d1 |
/// alternatives. The form used in this function lets you select an item in an alt-text array
|
|
Packit Service |
21b5d1 |
/// based on the value of its \c xml:lang qualifier. The other form of content addressing is
|
|
Packit Service |
21b5d1 |
/// shown in \c ComposeFieldSelector().
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// The returned string is in the form <tt>ns:arrayName[\@xml:lang='langName']</tt>, where
|
|
Packit Service |
21b5d1 |
/// "ns" is the prefix for the schema namespace
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// This function provides a path expression that is explicitly and only for a specific
|
|
Packit Service |
21b5d1 |
/// language. In most cases, \c TXMPMeta::SetLocalizedText() and \c TXMPMeta::GetLocalizedText()
|
|
Packit Service |
21b5d1 |
/// are preferred, because they provide extra logic to choose the appropriate language and
|
|
Packit Service |
21b5d1 |
/// maintain consistency with the 'x-default' value.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param schemaNS The namespace URI for the array; see \c GetProperty().
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param arrayName The name of the array. Can be a general path expression, must not be null
|
|
Packit Service |
21b5d1 |
/// or the empty string; see \c GetProperty() for namespace prefix usage.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param langName The RFC 3066 code for the desired language, as a string object.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param fullPath [out] A string in which to return the composed path.
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
static void ComposeLangSelector ( XMP_StringPtr schemaNS,
|
|
Packit Service |
21b5d1 |
XMP_StringPtr arrayName,
|
|
Packit Service |
21b5d1 |
const tStringObj & langName,
|
|
Packit Service |
21b5d1 |
tStringObj * fullPath );
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
// ---------------------------------------------------------------------------------------------
|
|
Packit Service |
21b5d1 |
/// @brief \c ComposeFieldSelector() composes a path expression to select an alternate item by a field's value.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// Path syntax allows two forms of "content addressing" to select an item in an array of
|
|
Packit Service |
21b5d1 |
/// alternatives. The form used in this function lets you select an item in an array of structs
|
|
Packit Service |
21b5d1 |
/// based on the value of one of the fields in the structs. The other form of content addressing
|
|
Packit Service |
21b5d1 |
/// is shown in \c ComposeLangSelector().
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// For example, consider a simple struct that has two fields, the name of a city and the URI of
|
|
Packit Service |
21b5d1 |
/// an FTP site in that city. Use this to create an array of download alternatives. You can show
|
|
Packit Service |
21b5d1 |
/// the user a popup built from the values of the city fields, then get the corresponding URI as
|
|
Packit Service |
21b5d1 |
/// follows:
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// ComposeFieldSelector ( schemaNS, "Downloads", fieldNS, "City", chosenCity, &path );
|
|
Packit Service |
21b5d1 |
/// exists = GetStructField ( schemaNS, path, fieldNS, "URI", &uri );
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// The returned string is in the form <tt>ns:arrayName[fNS:fieldName='fieldValue']</tt>, where
|
|
Packit Service |
21b5d1 |
/// "ns" is the prefix for the schema namespace and "fNS" is the prefix for the field namespace.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param schemaNS The namespace URI for the array; see \c GetProperty().
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param arrayName The name of the array. Can be a general path expression, must not be null
|
|
Packit Service |
21b5d1 |
/// or the empty string; see \c GetProperty() for namespace prefix usage.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param fieldNS The namespace URI for the field used as the selector. Same URI and prefix
|
|
Packit Service |
21b5d1 |
/// usage as the \c schemaNS and \c arrayName parameters.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param fieldName The name of the field used as the selector. Must be a single XML name, must
|
|
Packit Service |
21b5d1 |
/// not be null or the empty string. It must be the name of a field that is itself simple.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param fieldValue The desired value of the field, specified as a null-terminated UTF-8 string.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param fullPath [out] A string in which to return the composed path.
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
static void ComposeFieldSelector ( XMP_StringPtr schemaNS,
|
|
Packit Service |
21b5d1 |
XMP_StringPtr arrayName,
|
|
Packit Service |
21b5d1 |
XMP_StringPtr fieldNS,
|
|
Packit Service |
21b5d1 |
XMP_StringPtr fieldName,
|
|
Packit Service |
21b5d1 |
XMP_StringPtr fieldValue,
|
|
Packit Service |
21b5d1 |
tStringObj * fullPath );
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
// ---------------------------------------------------------------------------------------------
|
|
Packit Service |
21b5d1 |
/// @brief \c ComposeFieldSelector() composes a path expression to select an alternate item by a field's value.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// Path syntax allows two forms of "content addressing" to select an item in an array of
|
|
Packit Service |
21b5d1 |
/// alternatives. The form used in this function lets you select an item in an array of structs
|
|
Packit Service |
21b5d1 |
/// based on the value of one of the fields in the structs. The other form of content addressing
|
|
Packit Service |
21b5d1 |
/// is shown in \c ComposeLangSelector().
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// For example, consider a simple struct that has two fields, the name of a city and the URI of
|
|
Packit Service |
21b5d1 |
/// an FTP site in that city. Use this to create an array of download alternatives. You can show
|
|
Packit Service |
21b5d1 |
/// the user a popup built from the values of the city fields, then get the corresponding URI as
|
|
Packit Service |
21b5d1 |
/// follows:
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// ComposeFieldSelector ( schemaNS, "Downloads", fieldNS, "City", chosenCity, &path );
|
|
Packit Service |
21b5d1 |
/// exists = GetStructField ( schemaNS, path, fieldNS, "URI", &uri );
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// The returned string is in the form <tt>ns:arrayName[fNS:fieldName='fieldValue']</tt>, where
|
|
Packit Service |
21b5d1 |
/// "ns" is the prefix for the schema namespace and "fNS" is the prefix for the field namespace.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param schemaNS The namespace URI for the array; see \c GetProperty().
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param arrayName The name of the array. Can be a general path expression, must not be null
|
|
Packit Service |
21b5d1 |
/// or the empty string; see \c GetProperty() for namespace prefix usage.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param fieldNS The namespace URI for the field used as the selector. Same URI and prefix
|
|
Packit Service |
21b5d1 |
/// usage as the \c schemaNS and \c arrayName parameters.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param fieldName The name of the field used as the selector. Must be a single XML name, must
|
|
Packit Service |
21b5d1 |
/// not be null or the empty string. It must be the name of a field that is itself simple.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param fieldValue The desired value of the field, specified as a string object.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param fullPath [out] A string in which to return the composed path.
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
static void ComposeFieldSelector ( XMP_StringPtr schemaNS,
|
|
Packit Service |
21b5d1 |
XMP_StringPtr arrayName,
|
|
Packit Service |
21b5d1 |
XMP_StringPtr fieldNS,
|
|
Packit Service |
21b5d1 |
XMP_StringPtr fieldName,
|
|
Packit Service |
21b5d1 |
const tStringObj & fieldValue,
|
|
Packit Service |
21b5d1 |
tStringObj * fullPath );
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
/// @}
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
// =============================================================================================
|
|
Packit Service |
21b5d1 |
/// \name Conversion between binary types and strings
|
|
Packit Service |
21b5d1 |
/// @{
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// The main accessors in \c TXMPMeta set and retrieve property values as strings. additional
|
|
Packit Service |
21b5d1 |
/// functions, such as \c TXMPMeta::SetPropertyInt(), set and retrieve property values as
|
|
Packit Service |
21b5d1 |
/// explicit binary data types. Use these functions to convert between binary and string
|
|
Packit Service |
21b5d1 |
/// values.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// Strings can be specified as null-terminated UTF-8 (\c #XMP_StringPtr), or as string
|
|
Packit Service |
21b5d1 |
/// objects (\c tStringObj) of the type declared when instantiating the XMP classes; see
|
|
Packit Service |
21b5d1 |
/// \c XMPSDK.hpp. Alternate forms of each conversion function allow either type of string.
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
// ---------------------------------------------------------------------------------------------
|
|
Packit Service |
21b5d1 |
/// @brief \c ConvertFromBool() converts a Boolean value to a string.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// The string values of Booleans are returned by the macros \c #kXMP_TrueStr and
|
|
Packit Service |
21b5d1 |
/// \c #kXMP_FalseStr in \c XMP_Const.h.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param binValue The Boolean value to be converted.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param strValue [out] A buffer in which to return the string representation of the value.
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
static void ConvertFromBool ( bool binValue,
|
|
Packit Service |
21b5d1 |
tStringObj * strValue );
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
// ---------------------------------------------------------------------------------------------
|
|
Packit Service |
21b5d1 |
/// @brief \c ConvertFromInt() converts a 32-bit integer value to a string.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param binValue The integer value to be converted.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param format Optional. A C \c sprintf format for the conversion. Default is "%d".
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param strValue [out] A buffer in which to return the string representation of the value.
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
static void ConvertFromInt ( long binValue,
|
|
Packit Service |
21b5d1 |
XMP_StringPtr format,
|
|
Packit Service |
21b5d1 |
tStringObj * strValue );
|
|
Packit Service |
21b5d1 |
// ---------------------------------------------------------------------------------------------
|
|
Packit Service |
21b5d1 |
/// @brief \c ConvertFromInt64() converts a 64-bit integer value to a string.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param binValue The integer value to be converted.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param format Optional. A C \c sprintf format for the conversion. Default is "%d".
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param strValue [out] A buffer in which to return the string representation of the value.
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
static void ConvertFromInt64 ( long long binValue,
|
|
Packit Service |
21b5d1 |
XMP_StringPtr format,
|
|
Packit Service |
21b5d1 |
tStringObj * strValue );
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
// ---------------------------------------------------------------------------------------------
|
|
Packit Service |
21b5d1 |
/// @brief \c ConvertFromFloat() converts a floating-point value to a string.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param binValue The floating-point value to be converted.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param format Optional. A C \c sprintf format for the conversion. Default is "%d".
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param strValue [out] A buffer in which to return the string representation of the value.
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
static void ConvertFromFloat ( double binValue,
|
|
Packit Service |
21b5d1 |
XMP_StringPtr format,
|
|
Packit Service |
21b5d1 |
tStringObj * strValue );
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
// ---------------------------------------------------------------------------------------------
|
|
Packit Service |
21b5d1 |
/// @brief \c ConvertFromDate() converts a date/time value to a string.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// Formats a date according to the ISO 8601 profile in http://www.w3.org/TR/NOTE-datetime:
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// YYYY
|
|
Packit Service |
21b5d1 |
/// YYYY-MM
|
|
Packit Service |
21b5d1 |
/// YYYY-MM-DD
|
|
Packit Service |
21b5d1 |
/// YYYY-MM-DDThh:mmTZD
|
|
Packit Service |
21b5d1 |
/// YYYY-MM-DDThh:mm:ssTZD
|
|
Packit Service |
21b5d1 |
/// YYYY-MM-DDThh:mm:ss.sTZD
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// \c YYYY = four-digit year, formatted as "%.4d"
|
|
Packit Service |
21b5d1 |
/// \c MM = two-digit month (01=January)
|
|
Packit Service |
21b5d1 |
/// \c DD = two-digit day of month (01 through 31)
|
|
Packit Service |
21b5d1 |
/// \c hh = two digits of hour (00 through 23)
|
|
Packit Service |
21b5d1 |
/// \c mm = two digits of minute (00 through 59)
|
|
Packit Service |
21b5d1 |
/// \c ss = two digits of second (00 through 59)
|
|
Packit Service |
21b5d1 |
/// \c s = one or more digits representing a decimal fraction of a second
|
|
Packit Service |
21b5d1 |
/// \c TZD = time zone designator (Z or +hh:mm or -hh:mm)
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// Time-only input is allowed where the year, month, and day are all zero. This is output as
|
|
Packit Service |
21b5d1 |
/// "0000-00-00...".
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @note ISO 8601 does not allow years less than 1000 or greater than 9999. This API allows
|
|
Packit Service |
21b5d1 |
/// any year, even negative ones.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param binValue The date/time value to be converted.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param strValue [out] A buffer in which to return the ISO 8601 string representation of the date/time.
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
static void ConvertFromDate ( const XMP_DateTime & binValue,
|
|
Packit Service |
21b5d1 |
tStringObj * strValue );
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
// ---------------------------------------------------------------------------------------------
|
|
Packit Service |
21b5d1 |
/// @brief \c ConvertToBool() converts a string to a Boolean value.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// The preferred strings are those returned by the macros \c #kXMP_TrueStr and \c #kXMP_FalseStr.
|
|
Packit Service |
21b5d1 |
/// If these do not match, the function does a case insensitive comparison, then simply 't' or 'f',
|
|
Packit Service |
21b5d1 |
/// and finally non-zero and zero integer representations.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param strValue The string representation of the value, specified as a null-terminated UTF-8 string.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @return The appropriate C++ bool value for the string.
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
static bool ConvertToBool ( XMP_StringPtr strValue );
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
// ---------------------------------------------------------------------------------------------
|
|
Packit Service |
21b5d1 |
/// @brief \c ConvertToBool() converts a string to a Boolean value.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// Overloads the basic form of the function, allowing you to pass a string object,
|
|
Packit Service |
21b5d1 |
/// rather than a <tt>const * char</tt>. It is otherwise identical; see details in the canonical form.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param strValue The string representation of the value, specified as a string object.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @return The appropriate C++ bool value for the string.
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
static bool ConvertToBool ( const tStringObj & strValue );
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
// ---------------------------------------------------------------------------------------------
|
|
Packit Service |
21b5d1 |
/// @brief \c ConvertToInt() converts a string to a 32-bit integer value.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param strValue The string representation of the value, specified as a null-terminated UTF-8 string.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @return The 32-bit integer value.
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
static long ConvertToInt ( XMP_StringPtr strValue );
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
// ---------------------------------------------------------------------------------------------
|
|
Packit Service |
21b5d1 |
/// @brief \c ConvertToInt() converts a string to a 32-bit integer value.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// Overloads the basic form of the function, allowing you to pass a string object,
|
|
Packit Service |
21b5d1 |
/// rather than a <tt>const * char</tt>. It is otherwise identical.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param strValue The string representation of the value, specified as a string object.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @return The 32-bit integer value.
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
static long ConvertToInt ( const tStringObj & strValue );
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
// ---------------------------------------------------------------------------------------------
|
|
Packit Service |
21b5d1 |
/// @brief \c ConvertToInt64() converts a string to a 64-bit integer value.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param strValue The string representation of the value, specified as a null-terminated UTF-8 string.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @return The 64-bit integer value.
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
static long long ConvertToInt64 ( XMP_StringPtr strValue );
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
// ---------------------------------------------------------------------------------------------
|
|
Packit Service |
21b5d1 |
/// @brief \c ConvertToInt64() converts a string to a 64-bit integer value.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// Overloads the basic form of the function, allowing you to pass a string object,
|
|
Packit Service |
21b5d1 |
/// rather than a <tt>const * char</tt>. It is otherwise identical.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param strValue The string representation of the value, specified as a string object.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @return The 64-bit integer value.
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
static long long ConvertToInt64 ( const tStringObj & strValue );
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
// ---------------------------------------------------------------------------------------------
|
|
Packit Service |
21b5d1 |
/// @brief \c ConvertToFloat() converts a string to a floating-point value.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param strValue The string representation of the value, specified as a null-terminated UTF-8 string.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @return The floating-point value.
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
static double ConvertToFloat ( XMP_StringPtr strValue );
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
// ---------------------------------------------------------------------------------------------
|
|
Packit Service |
21b5d1 |
/// @brief \c ConvertToFloat() converts a string to a floating-point value.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// Overloads the basic form of the function, allowing you to pass a string object,
|
|
Packit Service |
21b5d1 |
/// rather than a <tt>const * char</tt>. It is otherwise identical.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param strValue The string representation of the value, specified as a string object.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @return The floating-point value.
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
static double ConvertToFloat ( const tStringObj & strValue );
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
// ---------------------------------------------------------------------------------------------
|
|
Packit Service |
21b5d1 |
/// @brief \c ConvertToDate() converts a string to a date/time value.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// Parses a date according to the ISO 8601 profile in http://www.w3.org/TR/NOTE-datetime:
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// YYYY
|
|
Packit Service |
21b5d1 |
/// YYYY-MM
|
|
Packit Service |
21b5d1 |
/// YYYY-MM-DD
|
|
Packit Service |
21b5d1 |
/// YYYY-MM-DDThh:mmTZD
|
|
Packit Service |
21b5d1 |
/// YYYY-MM-DDThh:mm:ssTZD
|
|
Packit Service |
21b5d1 |
/// YYYY-MM-DDThh:mm:ss.sTZD
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// \c YYYY = four-digit year, formatted as "%.4d"
|
|
Packit Service |
21b5d1 |
/// \c MM = two-digit month (01=January)
|
|
Packit Service |
21b5d1 |
/// \c DD = two-digit day of month (01 through 31)
|
|
Packit Service |
21b5d1 |
/// \c hh = two digits of hour (00 through 23)
|
|
Packit Service |
21b5d1 |
/// \c mm = two digits of minute (00 through 59)
|
|
Packit Service |
21b5d1 |
/// \c ss = two digits of second (00 through 59)
|
|
Packit Service |
21b5d1 |
/// \c s = one or more digits representing a decimal fraction of a second
|
|
Packit Service |
21b5d1 |
/// \c TZD = time zone designator (Z or +hh:mm or -hh:mm)
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// A missing date portion or missing TZD are tolerated. A missing date value can begin with
|
|
Packit Service |
21b5d1 |
/// "Thh:" or "hh:"; the year, month, and day are all set to zero in the \c #XMP_DateTime value.
|
|
Packit Service |
21b5d1 |
/// A missing TZD is assumed to be UTC.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @note ISO 8601 does not allow years less than 1000 or greater than 9999. This API allows
|
|
Packit Service |
21b5d1 |
/// any year, even negative ones.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param strValue The ISO 8601 string representation of the date/time, specified as a
|
|
Packit Service |
21b5d1 |
/// null-terminated UTF-8 string.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param binValue [out] A buffer in which to return the binary date/time value.
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
static void ConvertToDate ( XMP_StringPtr strValue,
|
|
Packit Service |
21b5d1 |
XMP_DateTime * binValue );
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
// ---------------------------------------------------------------------------------------------
|
|
Packit Service |
21b5d1 |
/// @brief \c ConvertToDate() converts a string to a date/time value.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// Overloads the basic form of the function, allowing you to pass a string object,
|
|
Packit Service |
21b5d1 |
/// rather than a <tt>const * char</tt>. It is otherwise identical.
|
|
Packit Service |
21b5d1 |
/// See details for the canonical form.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param strValue The ISO 8601 string representation of the date/time, specified as a string
|
|
Packit Service |
21b5d1 |
/// object.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param binValue [out] A buffer in which to return the binary date/time value.
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
static void ConvertToDate ( const tStringObj & strValue,
|
|
Packit Service |
21b5d1 |
XMP_DateTime * binValue );
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
/// @}
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
// =============================================================================================
|
|
Packit Service |
21b5d1 |
/// \name Date-time manipulation
|
|
Packit Service |
21b5d1 |
/// @{
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// In addition to the type-conversion functions that convert between strings and binary
|
|
Packit Service |
21b5d1 |
/// date-time values, these functions create, manipulate, and compare date-time values.
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
// ---------------------------------------------------------------------------------------------
|
|
Packit Service |
21b5d1 |
/// @brief \c CurrentDateTime() obtains the current date and time.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// Creates and returns a binary \c #XMP_DateTime value. The returned time is UTC, properly
|
|
Packit Service |
21b5d1 |
/// adjusted for the local time zone. The resolution of the time is not guaranteed to be finer
|
|
Packit Service |
21b5d1 |
/// than seconds.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param time [out] A buffer in which to return the date/time value.
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
static void CurrentDateTime ( XMP_DateTime * time );
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
// ---------------------------------------------------------------------------------------------
|
|
Packit Service |
21b5d1 |
/// @brief \c SetTimeZone() sets the time zone in a date/time value to the local time zone.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// Any existing time zone value is replaced. The other date/time fields are not adjusted in any way.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param time A pointer to the date-time value, which is modified in place.
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
static void SetTimeZone ( XMP_DateTime * time );
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
// ---------------------------------------------------------------------------------------------
|
|
Packit Service |
21b5d1 |
/// @brief \c ConvertToUTCTime() ensures that a time is UTC.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// If the time zone is not UTC, the time is adjusted and the time zone set to be UTC. If the
|
|
Packit Service |
21b5d1 |
/// time zone is already UTC, the value is not modified.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param time A pointer to the date-time value, which is modified in place.
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
static void ConvertToUTCTime ( XMP_DateTime * time );
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
// ---------------------------------------------------------------------------------------------
|
|
Packit Service |
21b5d1 |
/// @brief \c ConvertToLocalTime() ensures that a time is local.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// If the time zone is not the local zone, the time is adjusted and the time zone set to be local.
|
|
Packit Service |
21b5d1 |
/// If the time zone is already the local zone, the value is not modified.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param time A pointer to the date-time value, which is modified in place.
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
static void ConvertToLocalTime ( XMP_DateTime * time );
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
// ---------------------------------------------------------------------------------------------
|
|
Packit Service |
21b5d1 |
/// @brief \c CompareDateTime() compares the order of two date/time values.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param left The left-side date/time value.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param right The right-side date/time value.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @return An integer indicating the order:
|
|
Packit Service |
21b5d1 |
/// \li -1 if left is earlier than right
|
|
Packit Service |
21b5d1 |
/// \li 0 if left matches right
|
|
Packit Service |
21b5d1 |
/// \li +1 if left is later than right
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
static int CompareDateTime ( const XMP_DateTime & left,
|
|
Packit Service |
21b5d1 |
const XMP_DateTime & right );
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
/// @}
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
// =============================================================================================
|
|
Packit Service |
21b5d1 |
/// \name Base64 encoding and decoding
|
|
Packit Service |
21b5d1 |
/// @{
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// These functions convert between raw data values and Base64-encoded strings.
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
// ---------------------------------------------------------------------------------------------
|
|
Packit Service |
21b5d1 |
/// @brief \c EncodeToBase64() converts a raw data value to a Base64-encoded string.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param rawStr An \c #XMP_StringPtr (char *) string containing the raw data to be converted.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param rawLen The number of characters of raw data to be converted.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param encodedStr [out] A string object in which to return the encoded string.
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
static void EncodeToBase64 ( XMP_StringPtr rawStr,
|
|
Packit Service |
21b5d1 |
XMP_StringLen rawLen,
|
|
Packit Service |
21b5d1 |
tStringObj * encodedStr );
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
// ---------------------------------------------------------------------------------------------
|
|
Packit Service |
21b5d1 |
/// @brief \c EncodeToBase64() converts a raw data value passed in a string object to a Base64-encoded string.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// Overloads the basic form of the function, allowing you to pass a string object as input.
|
|
Packit Service |
21b5d1 |
/// It is otherwise identical.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param rawStr A string object containing the raw data to be converted.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param encodedStr [out] A string object in which to return the encoded string.
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
static void EncodeToBase64 ( const tStringObj & rawStr,
|
|
Packit Service |
21b5d1 |
tStringObj * encodedStr );
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
// ---------------------------------------------------------------------------------------------
|
|
Packit Service |
21b5d1 |
/// @brief \c DecodeFromBase64() Decodes a Base64-encoded string to raw data.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param encodedStr An \c #XMP_StringPtr (char *) string containing the encoded data to be converted.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param encodedLen The number of characters of raw data to be converted.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param rawStr [out] A string object in which to return the decoded data.
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
static void DecodeFromBase64 ( XMP_StringPtr encodedStr,
|
|
Packit Service |
21b5d1 |
XMP_StringLen encodedLen,
|
|
Packit Service |
21b5d1 |
tStringObj * rawStr );
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
// ---------------------------------------------------------------------------------------------
|
|
Packit Service |
21b5d1 |
/// @brief \c DecodeFromBase64() Decodes a Base64-encoded string, passed as a string object, to raw data.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// Overloads the basic form of the function, allowing you to pass a string object as input.
|
|
Packit Service |
21b5d1 |
/// It is otherwise identical.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param encodedStr An string object containing the encoded data to be converted.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param rawStr [out] A string object in which to return the decoded data.
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
static void DecodeFromBase64 ( const tStringObj & encodedStr,
|
|
Packit Service |
21b5d1 |
tStringObj * rawStr );
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
/// @}
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
// =============================================================================================
|
|
Packit Service |
21b5d1 |
// =============================================================================================
|
|
Packit Service |
21b5d1 |
/// \name JPEG file handling
|
|
Packit Service |
21b5d1 |
/// @{
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// These functions support the partitioning of XMP in JPEG files into standard and extended
|
|
Packit Service |
21b5d1 |
/// portions in order to work around the 64KB size limit of JPEG marker segments.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @note (Doc note) Add detail about how to write out and read back extended data
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
// ---------------------------------------------------------------------------------------------
|
|
Packit Service |
21b5d1 |
/// @brief \c PackageForJPEG() creates XMP serializations appropriate for a JPEG file.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// The standard XMP in a JPEG file is limited to 64K bytes. This function serializes the XMP
|
|
Packit Service |
21b5d1 |
/// metadata in an XMP object into a string of RDF (see \c TXMPMeta::SerializeToBuffer()). If
|
|
Packit Service |
21b5d1 |
/// the data does not fit into the 64K byte limit, it creates a second packet string with the
|
|
Packit Service |
21b5d1 |
/// extended data.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param xmpObj The XMP object containing the metadata.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param standardXMP [out] A string object in which to return the full standard XMP packet.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param extendedXMP [out] A string object in which to return the serialized extended XMP,
|
|
Packit Service |
21b5d1 |
/// empty if not needed.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param extendedDigest [out] A string object in which to return an MD5 digest of the serialized
|
|
Packit Service |
21b5d1 |
/// extended XMP, empty if not needed.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @see \c MergeFromJPEG()
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
static void PackageForJPEG ( const TXMPMeta<tStringObj> & xmpObj,
|
|
Packit Service |
21b5d1 |
tStringObj * standardXMP,
|
|
Packit Service |
21b5d1 |
tStringObj * extendedXMP,
|
|
Packit Service |
21b5d1 |
tStringObj * extendedDigest );
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
// ---------------------------------------------------------------------------------------------
|
|
Packit Service |
21b5d1 |
/// @brief \c MergeFromJPEG() merges standard and extended XMP retrieved from a JPEG file.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// When an extended partition stores properties that do not fit into the JPEG file limitation
|
|
Packit Service |
21b5d1 |
/// of 64K bytes, this function integrates those properties back into the same XMP object with
|
|
Packit Service |
21b5d1 |
/// those from the standard XMP packet.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param fullXMP [in, out] An XMP object which the caller has initialized from the standard
|
|
Packit Service |
21b5d1 |
/// XMP packet in a JPEG file. The extended XMP is added to this object.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param extendedXMP An XMP object which the caller has initialized from the extended XMP
|
|
Packit Service |
21b5d1 |
/// packet in a JPEG file.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @see \c PackageForJPEG()
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
static void MergeFromJPEG ( TXMPMeta<tStringObj> * fullXMP,
|
|
Packit Service |
21b5d1 |
const TXMPMeta<tStringObj> & extendedXMP );
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
/// @}
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
// =============================================================================================
|
|
Packit Service |
21b5d1 |
/// \name Editing utilities
|
|
Packit Service |
21b5d1 |
/// @{
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// These functions are useful in implementing a user interface for editing XMP. They
|
|
Packit Service |
21b5d1 |
/// convert sets of property values to and from displayable and manipulable strings, and perform
|
|
Packit Service |
21b5d1 |
/// operations on sets of metadata, such as those available from the File Info dialog box.
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
// ---------------------------------------------------------------------------------------------
|
|
Packit Service |
21b5d1 |
/// @brief \c CatenateArrayItems() creates a single edit string from a set of array item values.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// Collects the values of all items in an array into a single string, using a specified
|
|
Packit Service |
21b5d1 |
/// separation string. Each item in the specified array must be a simple string value.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param xmpObj The XMP object containing the array to be catenated.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param schemaNS The schema namespace URI for the array. Must not be null or the empty string.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param arrayName The name of the array. May be a general path expression, must not be null
|
|
Packit Service |
21b5d1 |
/// or the empty string.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param separator The string with which to separate the items in the catenated string.
|
|
Packit Service |
21b5d1 |
/// Defaults to "; ", ASCII semicolon and space (U+003B, U+0020).
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param quotes The character or characters to use as quotes around array items that contain a
|
|
Packit Service |
21b5d1 |
/// separator. Defaults to the double-quote character ("), ASCII quote (U+0022).
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param options Option flags to control the catenation. <<what options?>>
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param catedStr [out] A string object in which to return the catenated array items.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @see \c SeparateArrayItems()
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
static void CatenateArrayItems ( const TXMPMeta<tStringObj> & xmpObj,
|
|
Packit Service |
21b5d1 |
XMP_StringPtr schemaNS,
|
|
Packit Service |
21b5d1 |
XMP_StringPtr arrayName,
|
|
Packit Service |
21b5d1 |
XMP_StringPtr separator,
|
|
Packit Service |
21b5d1 |
XMP_StringPtr quotes,
|
|
Packit Service |
21b5d1 |
XMP_OptionBits options,
|
|
Packit Service |
21b5d1 |
tStringObj * catedStr );
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
// ---------------------------------------------------------------------------------------------
|
|
Packit Service |
21b5d1 |
/// @brief \c SeparateArrayItems() updates an array from a concatenated edit string of values.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// This reverses the action of \c CatenateArrayItems(), separating out individual array items
|
|
Packit Service |
21b5d1 |
/// from the edit string and updating the array with the new values. Each item in the array must
|
|
Packit Service |
21b5d1 |
/// be a simple string value.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param xmpObj The XMP object containing the array to be updated.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param schemaNS The schema namespace URI for the array. Must not be null or the empty string.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param arrayName The name of the array. May be a general path expression, must not be null
|
|
Packit Service |
21b5d1 |
/// or the empty string.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param options Option flags to control the separation. <<what options?>>
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param catedStr The concatenated array items, as created by \c CatenateArrayItems(),
|
|
Packit Service |
21b5d1 |
/// specified as a null-terminated UTF-8 string.
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
static void SeparateArrayItems ( TXMPMeta<tStringObj> * xmpObj,
|
|
Packit Service |
21b5d1 |
XMP_StringPtr schemaNS,
|
|
Packit Service |
21b5d1 |
XMP_StringPtr arrayName,
|
|
Packit Service |
21b5d1 |
XMP_OptionBits options,
|
|
Packit Service |
21b5d1 |
XMP_StringPtr catedStr );
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
// ---------------------------------------------------------------------------------------------
|
|
Packit Service |
21b5d1 |
/// @brief \c SeparateArrayItems() updates an array from a concatenated edit string of values.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// Overloads the basic form of the function, allowing you to pass a string object in which
|
|
Packit Service |
21b5d1 |
/// to return the concatenated string. It is otherwise identical; see details for the canonical form.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
static void SeparateArrayItems ( TXMPMeta<tStringObj> * xmpObj,
|
|
Packit Service |
21b5d1 |
XMP_StringPtr schemaNS,
|
|
Packit Service |
21b5d1 |
XMP_StringPtr arrayName,
|
|
Packit Service |
21b5d1 |
XMP_OptionBits options,
|
|
Packit Service |
21b5d1 |
const tStringObj & catedStr );
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
// ---------------------------------------------------------------------------------------------
|
|
Packit Service |
21b5d1 |
/// @brief \c RemoveProperties() removes multiple properties from an XMP object.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// The operation depends on how the namespace and property are specified:
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// \li Non-empty \c schemaNS and \c propName - The named property is removed if it is an
|
|
Packit Service |
21b5d1 |
/// external property, or if the \c #kXMPUtil_DoAllProperties option flag is set. It does not
|
|
Packit Service |
21b5d1 |
/// matter whether the named property is an actual property or an alias.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// \li Non-empty \c schemaNS and empty \c propName - All external properties in the named
|
|
Packit Service |
21b5d1 |
/// schema are removed. Internal properties are also removed if the
|
|
Packit Service |
21b5d1 |
/// \c #kXMPUtil_DoAllProperties option flag is set. In addition, aliases from the named schema
|
|
Packit Service |
21b5d1 |
/// are removed if the \c #kXMPUtil_IncludeAliases option flag is set.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// \li Empty \c schemaNS and empty \c propName - All external properties in all schemas are
|
|
Packit Service |
21b5d1 |
/// removed. Internal properties are also removed if the \c #kXMPUtil_DoAllProperties option
|
|
Packit Service |
21b5d1 |
/// flag is set. Aliases are handled implicitly, because the associated actuals are removed or
|
|
Packit Service |
21b5d1 |
/// not.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// \li It is an error to pass an empty \c schemaNS and non-empty \c propName.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param xmpObj The XMP object containing the properties to be removed.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param schemaNS Optional schema namespace URI for the properties to be removed.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param propName Optional path expression for the property to be removed.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param options Option flags to control the deletion operation. A logical OR of these
|
|
Packit Service |
21b5d1 |
/// bit-flag constants:
|
|
Packit Service |
21b5d1 |
/// \li \c #kXMPUtil_DoAllProperties - Delete internal properties in addition to external properties.
|
|
Packit Service |
21b5d1 |
/// \li \c #kXMPUtil_IncludeAliases - Include aliases if the schema is explicitly specified.
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
static void RemoveProperties ( TXMPMeta<tStringObj> * xmpObj,
|
|
Packit Service |
21b5d1 |
XMP_StringPtr schemaNS = 0,
|
|
Packit Service |
21b5d1 |
XMP_StringPtr propName = 0,
|
|
Packit Service |
21b5d1 |
XMP_OptionBits options = 0 );
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
// ---------------------------------------------------------------------------------------------
|
|
Packit Service |
21b5d1 |
/// @brief \c AppendProperties() adds or moves properties from one XMP object to another.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// The default operation is to append only external properties that do not already exist in the
|
|
Packit Service |
21b5d1 |
/// destination. Option flags allow you to add internal properties, and to merge values of
|
|
Packit Service |
21b5d1 |
/// properties that exist in both the source and destination.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// \li \c #kXMPUtil_DoAllProperties: Operate on all top-level properties, external and
|
|
Packit Service |
21b5d1 |
/// internal. You can use this flag together with \c #kXMPUtil_ReplaceOldValues to replace the
|
|
Packit Service |
21b5d1 |
/// values of existing top-level properties.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// \li \c #kXMPUtil_ReplaceOldValues: Propagate all top-level properties from the source to
|
|
Packit Service |
21b5d1 |
/// the destination, replacing any existing values. The values of properties in the
|
|
Packit Service |
21b5d1 |
/// destination that are not in the source are not modified.
|
|
Packit Service |
21b5d1 |
/// The keep-or-replace-old notion also applies within structs and arrays. Top-level
|
|
Packit Service |
21b5d1 |
/// properties are added to the destination if they do not already exist. If they do exist but
|
|
Packit Service |
21b5d1 |
/// differ in form (simple/struct/array) then the destination is not modified. If the forms
|
|
Packit Service |
21b5d1 |
/// match, simple properties are left unchanged, while structs and arrays are merged.
|
|
Packit Service |
21b5d1 |
/// Do not use this option when the processing is more complicated. <<than what??>>
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// \li \c #kXMPUtil_DeleteEmptyValues: An empty value in the source XMP causes the
|
|
Packit Service |
21b5d1 |
/// corresponding destination property to be deleted. By default, empty values are treated in
|
|
Packit Service |
21b5d1 |
/// the same way as non-empty values. An empty value is a simple empty string, an array with
|
|
Packit Service |
21b5d1 |
/// no items,or a struct with no fields. Qualifiers are ignored.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// The detailed behavior is defined by the following pseudo-code:
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// AppendProperties ( sourceXMP, destXMP, options ):
|
|
Packit Service |
21b5d1 |
/// doAll = options & kXMPUtil_DoAllProperties
|
|
Packit Service |
21b5d1 |
/// replaceOld = options & kXMPUtil_ReplaceOldValues
|
|
Packit Service |
21b5d1 |
/// deleteEmpty = options & kXMPUtil_DeleteEmptyValues
|
|
Packit Service |
21b5d1 |
/// for all source schema (top level namespaces):
|
|
Packit Service |
21b5d1 |
/// for all top level properties in sourceSchema:
|
|
Packit Service |
21b5d1 |
/// if doAll or prop is external:
|
|
Packit Service |
21b5d1 |
/// AppendSubtree ( sourceNode, destSchema, replaceOld, deleteEmpty )
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// AppendSubtree ( sourceNode, destParent, replaceOld, deleteEmpty ):
|
|
Packit Service |
21b5d1 |
/// if deleteEmpty and source value is empty:
|
|
Packit Service |
21b5d1 |
/// delete the corresponding child from destParent
|
|
Packit Service |
21b5d1 |
/// else if sourceNode not in destParent (by name):
|
|
Packit Service |
21b5d1 |
/// copy sourceNode's subtree to destParent
|
|
Packit Service |
21b5d1 |
/// else if replaceOld:
|
|
Packit Service |
21b5d1 |
/// delete subtree from destParent
|
|
Packit Service |
21b5d1 |
/// copy sourceNode's subtree to destParent
|
|
Packit Service |
21b5d1 |
/// else: // (Already exists in dest and not replacing, merge structs and arrays)
|
|
Packit Service |
21b5d1 |
/// if sourceNode and destNode forms differ:
|
|
Packit Service |
21b5d1 |
/// return, leave the destNode alone
|
|
Packit Service |
21b5d1 |
/// else if form is a struct:
|
|
Packit Service |
21b5d1 |
/// for each field in sourceNode:
|
|
Packit Service |
21b5d1 |
/// AppendSubtree ( sourceNode.field, destNode, replaceOld )
|
|
Packit Service |
21b5d1 |
/// else if form is an alt-text array:
|
|
Packit Service |
21b5d1 |
/// copy new items by xml:lang value into the destination
|
|
Packit Service |
21b5d1 |
/// else if form is an array:
|
|
Packit Service |
21b5d1 |
/// copy new items by value into the destination, ignoring order and duplicates
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// Array item checking is n-squared; this can be time-intensive if the replace-old options is
|
|
Packit Service |
21b5d1 |
/// not specified. Each source item is checked to see if it already exists in the destination,
|
|
Packit Service |
21b5d1 |
/// without regard to order or duplicates. Simple items are compared by value and \c xml:lang
|
|
Packit Service |
21b5d1 |
/// qualifier; other qualifiers are ignored. Structs are recursively compared by field names,
|
|
Packit Service |
21b5d1 |
/// without regard to field order. Arrays are compared by recursively comparing all items.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param source The source XMP object.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param dest The destination XMP object.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param options Option flags to control the copying. A logical OR of these bit-flag constants:
|
|
Packit Service |
21b5d1 |
/// \li \c kXMPUtil_DoAllProperties - Operate on internal properties in addition to external properties.
|
|
Packit Service |
21b5d1 |
/// \li \c kXMPUtil_ReplaceOldValues - Replace the values of existing properties.
|
|
Packit Service |
21b5d1 |
/// \li \c kXMPUtil_DeleteEmptyValues - Delete properties if the new value is empty.
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
static void AppendProperties ( const TXMPMeta<tStringObj> & source,
|
|
Packit Service |
21b5d1 |
TXMPMeta<tStringObj> * dest,
|
|
Packit Service |
21b5d1 |
XMP_OptionBits options = 0 );
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
// ---------------------------------------------------------------------------------------------
|
|
Packit Service |
21b5d1 |
/// @brief \c DuplicateSubtree() replicates a subtree from one XMP object into another.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// The destination can be a different namespace and root location in the same object, or the
|
|
Packit Service |
21b5d1 |
/// same or a different location in another XMP object.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param source The source XMP object.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param dest The destination XMP object.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param sourceNS The schema namespace URI for the source subtree.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param sourceRoot The root location for the source subtree. Can be a general path expression,
|
|
Packit Service |
21b5d1 |
/// must not be null or the empty string.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param destNS The schema namespace URI for the destination. Defaults to the source namespace.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param destRoot The root location for the destination. Can be a general path expression.
|
|
Packit Service |
21b5d1 |
/// Defaults to the source location.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param options Option flags to control the operation. <<options?>>
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
static void DuplicateSubtree ( const TXMPMeta<tStringObj> & source,
|
|
Packit Service |
21b5d1 |
TXMPMeta<tStringObj> * dest,
|
|
Packit Service |
21b5d1 |
XMP_StringPtr sourceNS,
|
|
Packit Service |
21b5d1 |
XMP_StringPtr sourceRoot,
|
|
Packit Service |
21b5d1 |
XMP_StringPtr destNS = 0,
|
|
Packit Service |
21b5d1 |
XMP_StringPtr destRoot = 0,
|
|
Packit Service |
21b5d1 |
XMP_OptionBits options = 0 );
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
/// @}
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
// =============================================================================================
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
// =============================================================================================
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
}; // class TXMPUtils
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
// =================================================================================================
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
#endif // __TXMPUtils_hpp__
|