TXMPIterator< tStringObj > Class Template Reference

API for access to the XMP Toolkit iteration services. More...

#include <TXMPIterator.hpp>

List of all members.

Public Member Functions

void operator= (const TXMPIterator< tStringObj > &rhs)
 Assignment operator, assigns the internal ref and increments the ref count.
 TXMPIterator (const TXMPIterator< tStringObj > &original)
 Copy constructor, creates a client object refering to the same internal object.
 TXMPIterator (const TXMPMeta< tStringObj > &xmpObj, XMP_StringPtr schemaNS, XMP_StringPtr propName, XMP_OptionBits options=0)
 Constructs an iterator for properties within a schema in an XMP object.
 TXMPIterator (const TXMPMeta< tStringObj > &xmpObj, XMP_StringPtr schemaNS, XMP_OptionBits options=0)
 Constructs an iterator for a subtree of properties within an XMP object.
 TXMPIterator (const TXMPMeta< tStringObj > &xmpObj, XMP_OptionBits options=0)
 Constructs an iterator for the entire data tree within an XMP object.
 TXMPIterator (XMP_StringPtr schemaNS, XMP_StringPtr propName, XMP_OptionBits options)
 Constructs an iterator for the global tables of the XMP toolkit. Not implemented.
virtual ~TXMPIterator () throw ()
 Destructor, typical virtual destructor.
bool Next (tStringObj *schemaNS=0, tStringObj *propPath=0, tStringObj *propValue=0, XMP_OptionBits *options=0)
 Next() visits the next node in the iteration.
void Skip (XMP_OptionBits options)
 Skip() skips some portion of the remaining iterations.

Detailed Description

template<class tStringObj>
class TXMPIterator< tStringObj >

API for access to the XMP Toolkit iteration services.

TXMPIterator provides a uniform means to iterate over the schema and properties within an XMP object. TXMPIterator is a template class which must be instantiated with a string class such as std::string. See the instructions in XMP.hpp, and the Overview for a discussion of the overall architecture of the XMP API. Access these functions through the concrete class, SXMPIterator.

Note:
Only XMP object iteration is currently available. Future development may include iteration over global tables, such as registered namespaces.

To understand how iteration works, you should have a thorough understanding of the XMP data tree, as described in the XMP Specification Part 1. You might also find it helpful to create some complex XMP and examine the output of TXMPMeta::DumpObject().

A TXMPIterator constructor defines a starting point for the iteration, and options that control how it proceeds. By default, iteration starts at the root and visits all nodes beneath it in a depth-first manner. The root node iteself is not visited; the first visited node is a schema node. You can provide a schema name or property path to select a different starting node. By default, this visits the named root node first then all nodes beneath it in a depth-first manner.

The function TXMPIterator::Next() delivers the schema URI, path, and option flags for the node being visited. If the node is simple, it also delivers the value. Qualifiers for this node are visited next. The fields of a struct or items of an array are visited after the qualifiers of the parent.

You can specify options when contructing the iteration object to control how the iteration is performed.


Constructor & Destructor Documentation

template<class tStringObj>
TXMPIterator< tStringObj >::TXMPIterator ( const TXMPIterator< tStringObj > &  original  ) 

Copy constructor, creates a client object refering to the same internal object.

Creates a new client iterator that refers to the same underlying iterator as an existing object.

Parameters:
original An existing iteration object to copy.
template<class tStringObj>
TXMPIterator< tStringObj >::TXMPIterator ( const TXMPMeta< tStringObj > &  xmpObj,
XMP_StringPtr  schemaNS,
XMP_StringPtr  propName,
XMP_OptionBits  options = 0 
)

Constructs an iterator for properties within a schema in an XMP object.

See the class description for the general operation of an XMP object iterator. Overloaded forms are provided to iterate the entire data tree, a subtree rooted at a specific node, or properties within a specific schema.

Parameters:
xmpObj The XMP object over which to iterate.
schemaNS Optional schema namespace URI to restrict the iteration. To visit all of the schema, pass 0 or the empty string "".
propName Optional property name to restrict the iteration. May be an arbitrary path expression. If provided, a schema URI must also be provided. To visit all properties, pass 0 or the empty string "".
options Option flags to control the iteration. A logical OR of these bit flag constants:

Returns:
The new TXMPIterator object.
template<class tStringObj>
TXMPIterator< tStringObj >::TXMPIterator ( const TXMPMeta< tStringObj > &  xmpObj,
XMP_StringPtr  schemaNS,
XMP_OptionBits  options = 0 
)

Constructs an iterator for a subtree of properties within an XMP object.

See the class description for the general operation of an XMP object iterator. Overloaded forms are provided to iterate the entire data tree, a subtree rooted at a specific node, or properties within a specific schema.

Parameters:
xmpObj The XMP object over which to iterate.
schemaNS Optional schema namespace URI to restrict the iteration. To visit all of the schema, pass 0 or the empty string "".
options Option flags to control the iteration. A logical OR of these bit flag constants:

Returns:
The new TXMPIterator object.
template<class tStringObj>
TXMPIterator< tStringObj >::TXMPIterator ( const TXMPMeta< tStringObj > &  xmpObj,
XMP_OptionBits  options = 0 
)

Constructs an iterator for the entire data tree within an XMP object.

See the class description for the general operation of an XMP object iterator. Overloaded forms are provided to iterate the entire data tree, a subtree rooted at a specific node, or properties within a specific schema.

Parameters:
xmpObj The XMP object over which to iterate.
options Option flags to control the iteration. A logical OR of these bit flag constants:

Returns:
The new TXMPIterator object.

Member Function Documentation

template<class tStringObj>
bool TXMPIterator< tStringObj >::Next ( tStringObj *  schemaNS = 0,
tStringObj *  propPath = 0,
tStringObj *  propValue = 0,
XMP_OptionBits options = 0 
)

Next() visits the next node in the iteration.

Proceeds to the next node according to the options specified on creation of this object, and delivers the schema URI, path, and option flags for the node being visited. If the node is simple, it also delivers the value.

Parameters:
schemaNS [out] A string object in which to return the assigned the schema namespace URI of the current property. Can be null if the value is not wanted.
propPath [out] A string object in which to return the XPath name of the current property. Can be null if the value is not wanted.
propValue [out] A string object in which to return the value of the current property. Can be null if the value is not wanted.
options [out] A buffer in which to return the flags describing the current property, which are a logical OR of XMP_OptionBits bit-flag constants.
Returns:
True if there was another node to visit, false if the iteration is complete.
template<class tStringObj>
void TXMPIterator< tStringObj >::operator= ( const TXMPIterator< tStringObj > &  rhs  ) 

Assignment operator, assigns the internal ref and increments the ref count.

Assigns the internal reference from an existing object and increments the reference count on the underlying internal XMP iterator.

Parameters:
rhs An existing iteration object.
template<class tStringObj>
void TXMPIterator< tStringObj >::Skip ( XMP_OptionBits  options  ) 

Skip() skips some portion of the remaining iterations.

Parameters:
options Option flags to control the iteration, a logical OR of these bit-flag constants:


The documentation for this class was generated from the following file:

XMP-Toolkit-SDK-CC201306 documentation generated by doxygen 1.6.3