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

# TXMPIterator< tStringObj > Class Template Reference

Template class for 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)
| Construct an iterator for the properties within an XMP object.
| TXMPIterator (XMP_StringPtr schemaNS, XMP_StringPtr propName, XMP_OptionBits options)
| Construct an iterator for the global tables of the XMP toolkit.
virtual | ~TXMPIterator () throw ()
| Destructor, typical virtual destructor.
bool | Next (tStringObj *schemaNS=0, tStringObj *propPath=0, tStringObj *propValue=0, XMP_OptionBits *options=0)
| Visit the next node in the iteration.
void | Skip (XMP_OptionBits options)
| Skip some portion of the remaining iterations.

## Detailed Description

### template<class tStringObj>
class TXMPIterator< tStringObj >

Template class for the XMP Toolkit iteration services.

This template class provides iteration services for the XMP Toolkit. It should be instantiated with a string class such as `std::string`. Please read the general usage notes for information on the overall architecture of the XMP API.

`TXMPIterator` provides a uniform means to iterate over several XMP data structures, including the schema and properties within an XMP object plus global tables such as registered namespaces. The template wraps a string class around the raw XMP API, so that output strings are automatically copied and access is fully thread safe. String objects are only necessary for output strings. Input string are literals and passed as typical C `const char *`.

The template parameter, class `TtStringObj`, must have the following member functions (which match those for `std::string`):

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

Note:
  Only XMP object iteration is implemented at this time. There are no table iterators yet.

Iteration over the schema and properties within an XMP object is the most important and complex use of `TTXMPIterator`. It is helpful to have a thorough understanding of the XMP data tree. One way to learn this is to create some complex XMP and examine the output of `TXMPMeta::DumpObject`. This is also described in the XMP Specification, in the XMP Data Model chapter.

The top of the XMP data tree is a single root node. This does not explicitly appear in the dump and is never visited by an iterator (that is, it is never returned from `TXMPIterator::Next`). Beneath the root are schema nodes. These are just collectors for top level properties in the same namespace. They are created and destroyed implicitly. Beneath the schema nodes are the property nodes. The nodes below a property node depend on its type (simple, struct, or array) and whether it has qualifiers.

A `TXMPIterator` constructor defines a starting point for the iteration and options that control how it proceeds. By default the iteration starts at the root and visits all nodes beneath it in a depth first manner. The root node 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 `TXMPIterator::Next` method 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.

The options to control the iteration are:

- `kXMP_IterJustChildren` - Visit just the immediate children of the root. Skip the root itself and all nodes below the immediate children. This omits the qualifiers of the immediate children, the qualifier nodes being below what they qualify.

- `kXMP_IterJustLeafNodes` - Visit just the leaf property nodes and their qualifiers.

- `kXMP_IterJustLeafName` - Return just the leaf component of the node names. The default is to return the full path name.

- `kXMP_IterIncludeAliases` - Include aliases as part of the iteration. Since aliases are not actual nodes the default iteration does not visit them.

- `kXMP_IterOmitQualifiers` - Do not visit the qualifiers of a node.

## 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. The copy constructor creates a new client iterator that refers to the same underlying iterator.

template<class tStringObj>
TXMPIterator< tStringObj >::TXMPIterator | ( | const TXMPMeta< tStringObj > & | xmpObj,
|  | XMP_StringPtr | schemaNS,
|  | XMP_StringPtr | propName,
|  | XMP_OptionBits | options = 0
| ) |

  | Construct an iterator for the properties within an XMP object. Construct an iterator for the properties within an XMP object. The general operation of an XMP object iterator was described above. Overloaded forms are provided to iterate the entire data tree, properties within a specific schema, or a subtree rooted at a specific node. Parameters:
  xmpObj | The XMP object over which to iterate.
  schemaNS | Optional schema namespace URI to restrict the iteration. Omitted (visit all schema) by passing 0 or "".
  propName | Optional property name to restrict the iteration. May be an arbitrary path expression. Omitted (visit all properties) by passing 0 or "". If not null/empty a schema URI must also be provided.
  options | Option flags to control the iteration.
The available option flags are: `kXMP_IterJustChildren` - Just visit the immediate children of the root, default is subtree. `kXMP_IterJustLeafNodes` - Just visit the leaf nodes, default visits all nodes. `kXMP_IterJustLeafName` - Return just the leaf part of the path, default is the full path. `kXMP_IterOmitQualifiers` - Omit all qualifiers.

template<class tStringObj>
TXMPIterator< tStringObj >::TXMPIterator | ( | XMP_StringPtr | schemaNS,
|  | XMP_StringPtr | propName,
|  | XMP_OptionBits | options
| ) |

| Construct an iterator for the global tables of the XMP toolkit. Note: Not yet implemented. File a bug if you need this.

## Member Function Documentation

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

  | Visit the next node in the iteration. Returns: Returns true if there was another node to visit, false if the iteration is done. Parameters:
  schemaNS | A pointer to the string that is assigned the schema namespace URI of the current property. May be null if the value is not wanted.
  propPath | A pointer to the string that is assigned the XPath name of the current property. May be null if the value is not wanted.
  propValue | A pointer to the string that is assigned the value of the current property. May be null if the value is not wanted.
  options | A pointer to the XMP_OptionBits variable that is assigned the flags describing the current property.

template<class tStringObj>
void TXMPIterator< tStringObj >::operator= | ( | const TXMPIterator< tStringObj > & | rhs | ) |

| Assignment operator, assigns the internal ref and increments the ref count. The assignment operator assigns the internal ref from the rhs object and increments the reference count on the underlying internal XMP iterator.

template<class tStringObj>
void TXMPIterator< tStringObj >::Skip | ( | XMP_OptionBits | options | ) |

  | Skip some portion of the remaining iterations. Parameters:
  options | Option flags to control the iteration.
The available option flags are: `kXMP_IterSkipSubtree` - Skip the subtree below the current node. `kXMP_IterSkipSiblings` - Skip the subtree below and remaining siblings of the current node.

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

- TXMPIterator.hpp