1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
|
#ifndef __TXMPIterator_hpp__
#define __TXMPIterator_hpp__ 1
#if ( ! __XMP_hpp__ )
#error "Do not directly include, use XMP.hpp"
#endif
// =================================================================================================
// ADOBE SYSTEMS INCORPORATED
// Copyright 2002 Adobe Systems Incorporated
// All Rights Reserved
//
// NOTICE: Adobe permits you to use, modify, and distribute this file in accordance with the terms
// of the Adobe license agreement accompanying it.
// =================================================================================================
// =================================================================================================
/// \file TXMPIterator.hpp
/// \brief API for access to the XMP Toolkit iteration services.
///
/// \c TXMPIterator is the template class providing iteration services for the XMP Toolkit. It must
/// be instantiated with a string class such as \c std::string. See the instructions in XMP.hpp, and
/// the Overview for a discussion of the overall architecture of the XMP API.
// =================================================================================================
// =================================================================================================
/// \class TXMPIterator TXMPIterator.hpp
/// @brief API for access to the XMP Toolkit iteration services.
///
/// \c TXMPIterator provides a uniform means to iterate over the schema and properties within an XMP
/// object. \c TXMPIterator is a template class which must be instantiated with a string class such
/// as \c std::string. See the instructions in XMP.hpp, and the Overview for a discussion of the
/// overall architecture of the XMP API. Access these functions through the concrete class,
/// \c 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 \c TXMPMeta::DumpObject().
///
/// \li 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
/// \c TXMPIterator::Next().
///
/// \li Beneath the root are schema nodes; these collect the top-level properties in the same
/// namespace. They are created and destroyed implicitly.
///
/// \li 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 \c 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 \c 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.
///
/// \li \c #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.
/// \li \c #kXMP_IterJustLeafNodes - Visit just the leaf property nodes and their qualifiers.
/// \li \c #kXMP_IterJustLeafName - Return just the leaf component of the node names. The default
/// is to return the full path name.
/// \li \c #kXMP_IterOmitQualifiers - Do not visit the qualifiers of a node.
// =================================================================================================
#include "client-glue/WXMPIterator.hpp"
template <class tStringObj> class TXMPIterator {
public:
// ---------------------------------------------------------------------------------------------
/// @brief 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.
///
/// @param rhs An existing iteration object.
void operator= ( const TXMPIterator<tStringObj> & rhs );
// ---------------------------------------------------------------------------------------------
/// @brief 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.
///
/// @param original An existing iteration object to copy.
TXMPIterator ( const TXMPIterator<tStringObj> & original );
// ---------------------------------------------------------------------------------------------
/// @brief 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.
///
/// @param xmpObj The XMP object over which to iterate.
///
/// @param schemaNS Optional schema namespace URI to restrict the iteration. To visit all of the
/// schema, pass 0 or the empty string "".
///
/// @param 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 "".
///
/// @param options Option flags to control the iteration. A logical OR of these bit flag constants:
/// \li \c #kXMP_IterJustChildren - Visit only the immediate children of the root; default visits subtrees.
/// \li \c #kXMP_IterJustLeafNodes - Visit only the leaf nodes; default visits all nodes.
/// \li \c #kXMP_IterJustLeafName - Return just the leaf part of the path; default returns the full path.
/// \li \c #kXMP_IterOmitQualifiers - Omit all qualifiers.
///
/// @return The new TXMPIterator object.
TXMPIterator ( const TXMPMeta<tStringObj> & xmpObj,
XMP_StringPtr schemaNS,
XMP_StringPtr propName,
XMP_OptionBits options = 0 );
// ---------------------------------------------------------------------------------------------
/// @brief 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.
///
/// @param xmpObj The XMP object over which to iterate.
///
/// @param schemaNS Optional schema namespace URI to restrict the iteration. To visit all of the
/// schema, pass 0 or the empty string "".
///
/// @param options Option flags to control the iteration. A logical OR of these bit flag constants:
/// \li \c #kXMP_IterJustChildren - Visit only the immediate children of the root; default visits subtrees.
/// \li \c #kXMP_IterJustLeafNodes - Visit only the leaf nodes; default visits all nodes.
/// \li \c #kXMP_IterJustLeafName - Return just the leaf part of the path; default returns the full path.
/// \li \c #kXMP_IterOmitQualifiers - Omit all qualifiers.
///
/// @return The new TXMPIterator object.
TXMPIterator ( const TXMPMeta<tStringObj> & xmpObj,
XMP_StringPtr schemaNS,
XMP_OptionBits options = 0 );
// ---------------------------------------------------------------------------------------------
/// @brief 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.
///
/// @param xmpObj The XMP object over which to iterate.
///
/// @param options Option flags to control the iteration. A logical OR of these bit flag constants:
/// \li \c #kXMP_IterJustChildren - Visit only the immediate children of the root; default visits subtrees.
/// \li \c #kXMP_IterJustLeafNodes - Visit only the leaf nodes; default visits all nodes.
/// \li \c #kXMP_IterJustLeafName - Return just the leaf part of the path; default returns the full path.
/// \li \c #kXMP_IterOmitQualifiers - Omit all qualifiers.
///
/// @return The new \c TXMPIterator object.
TXMPIterator ( const TXMPMeta<tStringObj> & xmpObj,
XMP_OptionBits options = 0 );
// ---------------------------------------------------------------------------------------------
/// @brief Constructs an iterator for the global tables of the XMP toolkit. Not implemented.
TXMPIterator ( XMP_StringPtr schemaNS,
XMP_StringPtr propName,
XMP_OptionBits options );
// ---------------------------------------------------------------------------------------------
/// @brief Destructor, typical virtual destructor.
virtual ~TXMPIterator() throw();
// ---------------------------------------------------------------------------------------------
/// @brief \c 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.
///
/// @param 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.
///
/// @param 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.
///
/// @param propValue [out] A string object in which to return the value of the current
/// property. Can be null if the value is not wanted.
///
/// @param options [out] A buffer in which to return the flags describing the current property,
/// which are a logical OR of \c #XMP_OptionBits bit-flag constants.
///
/// @return True if there was another node to visit, false if the iteration is complete.
bool Next ( tStringObj * schemaNS = 0,
tStringObj * propPath = 0,
tStringObj * propValue = 0,
XMP_OptionBits * options = 0 );
// ---------------------------------------------------------------------------------------------
/// @brief \c Skip() skips some portion of the remaining iterations.
///
/// @param options Option flags to control the iteration, a logical OR of these bit-flag
/// constants:
/// \li \c #kXMP_IterSkipSubtree - Skip the subtree below the current node.
/// \li \c #kXMP_IterSkipSiblings - Skip the subtree below and remaining siblings of the current node.
void Skip ( XMP_OptionBits options );
private:
XMPIteratorRef iterRef;
TXMPIterator(); // ! Hidden, must choose property or table iteration.
static void SetClientString ( void * clientPtr, XMP_StringPtr valuePtr, XMP_StringLen valueLen );
}; // class TXMPIterator
// =================================================================================================
#endif // __TXMPIterator_hpp__
|
