|
Packit Service |
21b5d1 |
#ifndef __TXMPIterator_hpp__
|
|
Packit Service |
21b5d1 |
#define __TXMPIterator_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-2007 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 TXMPIterator.hpp
|
|
Packit Service |
21b5d1 |
/// \brief API for access to the XMP Toolkit iteration services.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// \c TXMPIterator is the template class providing iteration services for the XMP Toolkit. It must
|
|
Packit Service |
21b5d1 |
/// be 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 TXMPIterator TXMPIterator.hpp
|
|
Packit Service |
21b5d1 |
/// @brief API for access to the XMP Toolkit iteration services.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// \c TXMPIterator provides a uniform means to iterate over the schema and properties within an XMP
|
|
Packit Service |
21b5d1 |
/// object. \c TXMPIterator is a template class which must be instantiated with a string class such
|
|
Packit Service |
21b5d1 |
/// as \c std::string. See the instructions in XMPSDK.hpp, and the Overview for a discussion of the
|
|
Packit Service |
21b5d1 |
/// overall architecture of the XMP API. Access these functions through the concrete class,
|
|
Packit Service |
21b5d1 |
/// \c SXMPIterator.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @note Only XMP object iteration is currently available. Future development may include iteration
|
|
Packit Service |
21b5d1 |
/// over global tables, such as registered namespaces.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// To understand how iteration works, you should have a thorough understanding of the XMP data
|
|
Packit Service |
21b5d1 |
/// tree, as described in the XMP Specification Part 1. You might also find it helpful to create
|
|
Packit Service |
21b5d1 |
/// some complex XMP and examine the output of \c TXMPMeta::DumpObject().
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// \li The top of the XMP data tree is a single root node. This does not explicitly appear in the
|
|
Packit Service |
21b5d1 |
/// dump and is never visited by an iterator; that is, it is never returned from
|
|
Packit Service |
21b5d1 |
/// \c TXMPIterator::Next().
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// \li Beneath the root are schema nodes; these collect the top-level properties in the same
|
|
Packit Service |
21b5d1 |
/// namespace. They are created and destroyed implicitly.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// \li Beneath the schema nodes are the property nodes. The nodes below a property node depend on
|
|
Packit Service |
21b5d1 |
/// its type (simple, struct, or array) and whether it has qualifiers.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// A \c TXMPIterator constructor defines a starting point for the iteration, and options that
|
|
Packit Service |
21b5d1 |
/// control how it proceeds. By default, iteration starts at the root and visits all nodes beneath
|
|
Packit Service |
21b5d1 |
/// it in a depth-first manner. The root node iteself is not visited; the first visited node is a
|
|
Packit Service |
21b5d1 |
/// schema node. You can provide a schema name or property path to select a different starting node.
|
|
Packit Service |
21b5d1 |
/// By default, this visits the named root node first then all nodes beneath it in a depth-first
|
|
Packit Service |
21b5d1 |
/// manner.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// The function \c TXMPIterator::Next() delivers the schema URI, path, and option flags for the
|
|
Packit Service |
21b5d1 |
/// node being visited. If the node is simple, it also delivers the value. Qualifiers for this node
|
|
Packit Service |
21b5d1 |
/// are visited next. The fields of a struct or items of an array are visited after the qualifiers
|
|
Packit Service |
21b5d1 |
/// of the parent.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// You can specify options when constructing the iteration object to control how the iteration is
|
|
Packit Service |
21b5d1 |
/// performed.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// \li \c #kXMP_IterJustChildren - Visit just the immediate children of the root. Skip the root
|
|
Packit Service |
21b5d1 |
/// itself and all nodes below the immediate children. This omits the qualifiers of the immediate
|
|
Packit Service |
21b5d1 |
/// children, the qualifier nodes being below what they qualify.
|
|
Packit Service |
21b5d1 |
/// \li \c #kXMP_IterJustLeafNodes - Visit just the leaf property nodes and their qualifiers.
|
|
Packit Service |
21b5d1 |
/// \li \c #kXMP_IterJustLeafName - Return just the leaf component of the node names. The default
|
|
Packit Service |
21b5d1 |
/// is to return the full path name.
|
|
Packit Service |
21b5d1 |
/// \li \c #kXMP_IterIncludeAliases - Include aliases as part of the iteration. Since aliases are
|
|
Packit Service |
21b5d1 |
/// not actual nodes the default iteration does not visit them.
|
|
Packit Service |
21b5d1 |
/// \li \c #kXMP_IterOmitQualifiers - Do not visit the qualifiers of a node.
|
|
Packit Service |
21b5d1 |
// =================================================================================================
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
#include "client-glue/WXMPIterator.hpp"
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
template <class tStringObj> class TXMPIterator {
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
public:
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
// ---------------------------------------------------------------------------------------------
|
|
Packit Service |
21b5d1 |
/// @brief Assignment operator, assigns the internal ref and increments the ref count.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// Assigns the internal reference from an existing object and increments the reference count on
|
|
Packit Service |
21b5d1 |
/// the underlying internal XMP iterator.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param rhs An existing iteration object.
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
void operator= ( const TXMPIterator<tStringObj> & rhs );
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
// ---------------------------------------------------------------------------------------------
|
|
Packit Service |
21b5d1 |
/// @brief Copy constructor, creates a client object refering to the same internal object.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// Creates a new client iterator that refers to the same underlying iterator as an existing object.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param original An existing iteration object to copy.
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
TXMPIterator ( const TXMPIterator<tStringObj> & original );
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
// ---------------------------------------------------------------------------------------------
|
|
Packit Service |
21b5d1 |
/// @brief Constructs an iterator for properties within a schema in an XMP object.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// See the class description for the general operation of an XMP object iterator.
|
|
Packit Service |
21b5d1 |
/// Overloaded forms are provided to iterate the entire data tree,
|
|
Packit Service |
21b5d1 |
/// a subtree rooted at a specific node, or properties within a specific schema.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param xmpObj The XMP object over which to iterate.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param schemaNS Optional schema namespace URI to restrict the iteration. To visit all of the
|
|
Packit Service |
21b5d1 |
/// schema, pass 0 or the empty string "".
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param propName Optional property name to restrict the iteration. May be an arbitrary path
|
|
Packit Service |
21b5d1 |
/// expression. If provided, a schema URI must also be provided. To visit all properties, pass 0
|
|
Packit Service |
21b5d1 |
/// or the empty string "".
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param options Option flags to control the iteration. A logical OR of these bit flag constants:
|
|
Packit Service |
21b5d1 |
/// \li \c #kXMP_IterJustChildren - Visit only the immediate children of the root; default visits subtrees.
|
|
Packit Service |
21b5d1 |
/// \li \c #kXMP_IterJustLeafNodes - Visit only the leaf nodes; default visits all nodes.
|
|
Packit Service |
21b5d1 |
/// \li \c #kXMP_IterJustLeafName - Return just the leaf part of the path; default returns the full path.
|
|
Packit Service |
21b5d1 |
/// \li \c #kXMP_IterOmitQualifiers - Omit all qualifiers.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @return The new TXMPIterator object.
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
TXMPIterator ( const TXMPMeta<tStringObj> & xmpObj,
|
|
Packit Service |
21b5d1 |
XMP_StringPtr schemaNS,
|
|
Packit Service |
21b5d1 |
XMP_StringPtr propName,
|
|
Packit Service |
21b5d1 |
XMP_OptionBits options = 0 );
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
// ---------------------------------------------------------------------------------------------
|
|
Packit Service |
21b5d1 |
/// @brief Constructs an iterator for a subtree of properties within an XMP object.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// See the class description for the general operation of an XMP object iterator. Overloaded
|
|
Packit Service |
21b5d1 |
/// forms are provided to iterate the entire data tree, a subtree rooted at a specific node, or
|
|
Packit Service |
21b5d1 |
/// properties within a specific schema.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param xmpObj The XMP object over which to iterate.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param schemaNS Optional schema namespace URI to restrict the iteration. To visit all of the
|
|
Packit Service |
21b5d1 |
/// schema, pass 0 or the empty string "".
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param options Option flags to control the iteration. A logical OR of these bit flag constants:
|
|
Packit Service |
21b5d1 |
/// \li \c #kXMP_IterJustChildren - Visit only the immediate children of the root; default visits subtrees.
|
|
Packit Service |
21b5d1 |
/// \li \c #kXMP_IterJustLeafNodes - Visit only the leaf nodes; default visits all nodes.
|
|
Packit Service |
21b5d1 |
/// \li \c #kXMP_IterJustLeafName - Return just the leaf part of the path; default returns the full path.
|
|
Packit Service |
21b5d1 |
/// \li \c #kXMP_IterOmitQualifiers - Omit all qualifiers.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @return The new TXMPIterator object.
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
TXMPIterator ( const TXMPMeta<tStringObj> & xmpObj,
|
|
Packit Service |
21b5d1 |
XMP_StringPtr schemaNS,
|
|
Packit Service |
21b5d1 |
XMP_OptionBits options = 0 );
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
// ---------------------------------------------------------------------------------------------
|
|
Packit Service |
21b5d1 |
/// @brief Constructs an iterator for the entire data tree within an XMP object.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// See the class description for the general operation of an XMP object iterator. Overloaded
|
|
Packit Service |
21b5d1 |
/// forms are provided to iterate the entire data tree, a subtree rooted at a specific node, or
|
|
Packit Service |
21b5d1 |
/// properties within a specific schema.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param xmpObj The XMP object over which to iterate.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param options Option flags to control the iteration. A logical OR of these bit flag constants:
|
|
Packit Service |
21b5d1 |
/// \li \c #kXMP_IterJustChildren - Visit only the immediate children of the root; default visits subtrees.
|
|
Packit Service |
21b5d1 |
/// \li \c #kXMP_IterJustLeafNodes - Visit only the leaf nodes; default visits all nodes.
|
|
Packit Service |
21b5d1 |
/// \li \c #kXMP_IterJustLeafName - Return just the leaf part of the path; default returns the full path.
|
|
Packit Service |
21b5d1 |
/// \li \c #kXMP_IterOmitQualifiers - Omit all qualifiers.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @return The new \c TXMPIterator object.
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
TXMPIterator ( const TXMPMeta<tStringObj> & xmpObj,
|
|
Packit Service |
21b5d1 |
XMP_OptionBits options = 0 );
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
// ---------------------------------------------------------------------------------------------
|
|
Packit Service |
21b5d1 |
/// @brief Constructs an iterator for the global tables of the XMP toolkit. Not implemented.
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
TXMPIterator ( XMP_StringPtr schemaNS,
|
|
Packit Service |
21b5d1 |
XMP_StringPtr propName,
|
|
Packit Service |
21b5d1 |
XMP_OptionBits options );
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
// ---------------------------------------------------------------------------------------------
|
|
Packit Service |
21b5d1 |
/// @brief Destructor, typical virtual destructor.
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
virtual ~TXMPIterator() throw();
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
// ---------------------------------------------------------------------------------------------
|
|
Packit Service |
21b5d1 |
/// @brief \c Next() visits the next node in the iteration.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// Proceeds to the next node according to the options specified on creation of this object, and
|
|
Packit Service |
21b5d1 |
/// delivers the schema URI, path, and option flags for the node being visited. If the node is
|
|
Packit Service |
21b5d1 |
/// simple, it also delivers the value.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param schemaNS [out] A string object in which to return the assigned the schema namespace
|
|
Packit Service |
21b5d1 |
/// URI of the current property. Can be null if the value is not wanted.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param propPath [out] A string object in which to return the XPath name of the current
|
|
Packit Service |
21b5d1 |
/// property. Can be null if the value is not wanted.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param propValue [out] A string object in which to return the value of the current
|
|
Packit Service |
21b5d1 |
/// property. Can be null if the value is not wanted.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param options [out] A buffer in which to return the flags describing the current property,
|
|
Packit Service |
21b5d1 |
/// which are a logical OR of \c #XMP_OptionBits bit-flag constants.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @return True if there was another node to visit, false if the iteration is complete.
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
bool Next ( tStringObj * schemaNS = 0,
|
|
Packit Service |
21b5d1 |
tStringObj * propPath = 0,
|
|
Packit Service |
21b5d1 |
tStringObj * propValue = 0,
|
|
Packit Service |
21b5d1 |
XMP_OptionBits * options = 0 );
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
// ---------------------------------------------------------------------------------------------
|
|
Packit Service |
21b5d1 |
/// @brief \c Skip() skips some portion of the remaining iterations.
|
|
Packit Service |
21b5d1 |
///
|
|
Packit Service |
21b5d1 |
/// @param options Option flags to control the iteration, a logical OR of these bit-flag
|
|
Packit Service |
21b5d1 |
/// constants:
|
|
Packit Service |
21b5d1 |
/// \li \c #kXMP_IterSkipSubtree - Skip the subtree below the current node.
|
|
Packit Service |
21b5d1 |
/// \li \c #kXMP_IterSkipSiblings - Skip the subtree below and remaining siblings of the current node.
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
void Skip ( XMP_OptionBits options );
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
private:
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
XMPIteratorRef iterRef;
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
TXMPIterator(); // ! Hidden, must choose property or table iteration.
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
}; // class TXMPIterator
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
// =================================================================================================
|
|
Packit Service |
21b5d1 |
|
|
Packit Service |
21b5d1 |
#endif // __TXMPIterator_hpp__
|