Debian Codegraph @

core/libs/dngwriter/extra/xmp_sdk/public/include/TXMPMeta.hpp

raw
1 #ifndef __TXMPMeta_hpp__
2 #define __TXMPMeta_hpp__ 1
3
4 #if ( ! __XMP_hpp__ )
5 #error "Do not directly include, use XMP.hpp"
6 #endif
7
8 #include "XMPCore/XMPCoreDefines.h"
9 #if ENABLE_CPP_DOM_MODEL
10 #include "XMPCore/XMPCoreFwdDeclarations.h"
11 #endif
12
13 // =================================================================================================
14 // Copyright Adobe
15 // Copyright 2002 Adobe
16 // All Rights Reserved
17 //
18 // NOTICE: Adobe permits you to use, modify, and distribute this file in accordance with the terms
19 // of the Adobe license agreement accompanying it. If you have received this file from a source other
20 // than Adobe, then your use, modification, or distribution of it requires the prior written permission
21 // of Adobe.
22 // =================================================================================================
23
24 // =================================================================================================
25 /// \file TXMPMeta.hpp
26 /// \brief API for access to the XMP Toolkit core services.
27 ///
28 /// \c TXMPMeta is the template class providing the core services of the XMP Toolkit. It must be
29 /// instantiated with a string class such as \c std::string. Read the Toolkit Overview for
30 /// information about the overall architecture of the XMP API, and the documentation for \c XMP.hpp
31 /// for specific instantiation instructions. Please that you MUST NOT derive a class from this class,
32 /// consider this class FINAL, use it directly. [1279031]
33 ///
34 /// Access these functions through the concrete class, \c SXMPMeta.
35 // =================================================================================================
36
37 // =================================================================================================
38 /// \class TXMPMeta TXMPMeta.hpp
39 /// \brief API for access to the XMP Toolkit core services.
40 ///
41 /// \c TXMPMeta is the template class providing the core services of the XMP Toolkit. It should be
42 /// instantiated with a string class such as \c std::string. Read the Toolkit Overview for
43 /// information about the overall architecture of the XMP API, and the documentation for \c XMP.hpp
44 /// for specific instantiation instructions.
45 ///
46 /// Access these functions through the concrete class, \c SXMPMeta.
47 ///
48 /// You can create \c TXMPMeta objects (also called XMP objects) from metadata that you construct,
49 /// or that you obtain from files using the XMP Toolkit's XMPFiles component; see \c TXMPFiles.hpp.
50 // =================================================================================================
51
52 template <class tStringObj> class TXMPIterator;
53 template <class tStringObj> class TXMPUtils;
54
55 // -------------------------------------------------------------------------------------------------
56
57 template <class tStringObj> class TXMPMeta {
58
59 public:
60
61 // =============================================================================================
62 // Initialization and termination
63 // ==============================
64
65 // ---------------------------------------------------------------------------------------------
66 /// \name Initialization and termination
67 ///
68 /// @{
69
70 // ---------------------------------------------------------------------------------------------
71 /// @brief \c GetVersionInfo() retrieves runtime version information.
72 ///
73 /// The header \c XMPVersion.hpp defines a static version number for the XMP Toolkit, which
74 /// describes the version of the API used at client compile time. It is not necessarily the same
75 /// as the runtime version. Do not base runtime decisions on the static version alone; you can,
76 /// however, compare the runtime and static versions.
77 ///
78 /// This function is static; make the call directly from the concrete class (\c SXMPMeta). The
79 /// function can be called before calling \c TXMPMeta::Initialize().
80 ///
81 /// @param info [out] A buffer in which to return the version information.
82
83 static void GetVersionInfo ( XMP_VersionInfo * info );
84
85 // ---------------------------------------------------------------------------------------------
86 /// @brief \c Initialize() explicitly initializes the XMP Toolkit before use. */
87
88 #if ! AdobePrivate
89 /// Initializes the XMP Toolkit.
90 ///
91 /// Call this function before making any other calls to the \c TXMPMeta functions, except
92 /// \c TXMPMeta::GetVersionInfo().
93 ///
94 /// This function is static; make the call directly from the concrete class (\c SXMPMeta).
95 ///
96 /// @return True on success. */
97 static bool Initialize();
98 #else
99
100 //******* DEPRECATED *************************//
101 //******* SEE : CTECHXMP-4169971 *************//
102
103
104 /// @brief Internal. Initializes the XMP Toolkit with an optional memory allocation mechanism.
105 /// The parameters must be either both null (0), or both non-null.
106 ///
107 /// @param AllocateProc An optional memory allocation procedure. If provided, the \c DeleteProc
108 /// must also be provided.
109 ///
110 /// @param DeleteProc An optional memory deallocation procedure. If provided, the \c AllocateProc
111 /// must also be provided.
112 ///
113 /// @return True on success.
114
115 static bool Initialize ( XMP_AllocateProc AllocateProc = 0,
116 XMP_DeleteProc DeleteProc = 0 );
117
118
119 #if ENABLE_CPP_DOM_MODEL
120 // ---------------------------------------------------------------------------------------------
121 /// @brief \c Use_CPP_DOM_APIs() when passed true, will rout the SXMPMeta functions to their
122 /// implementation done using new XMP Core APIs.
123 /// When false is passed to Use_CPP_DOM_APIs(), the SXMPMeta functions are routed to the old XMP Core APIs
124 /// Use_CPP_DOM_APIs() should be always called before the use of a SXMPMeta object, otherwise an exception might be thrown.
125 /// This function is static; make the call directly from the concrete class (\c SXMPMeta).
126 static void Use_CPP_DOM_APIs(XMP_Bool useNewCoreAPIs);
127 #endif
128 #endif
129 // ---------------------------------------------------------------------------------------------
130 /// @brief \c Terminate() explicitly terminates usage of the XMP Toolkit.
131 ///
132 /// Frees structures created on initialization.
133 ///
134 /// This function is static; make the call directly from the concrete class (\c SXMPMeta).
135
136 static void Terminate();
137
138 /// @}
139
140 // =============================================================================================
141 // Constuctors and destructor
142 // ==========================
143
144 // ---------------------------------------------------------------------------------------------
145 /// \name Constructors and destructor
146 /// @{
147
148 // ---------------------------------------------------------------------------------------------
149 /// @brief Default constructor, creates an empty object.
150 ///
151 /// The default constructor creates a new empty \c TXMPMeta object.
152 TXMPMeta();
153
154 // ---------------------------------------------------------------------------------------------
155 /// @brief Copy constructor, creates a client object refering to the same internal object.
156 ///
157 /// The copy constructor creates a new \c TXMPMeta object that refers to the same internal XMP
158 /// object. as an existing \c TXMPMeta object.
159 ///
160 /// @param original The object to copy. new object is returned via Original only.
161 ///
162
163 TXMPMeta ( const TXMPMeta<tStringObj> & original );
164
165 // ---------------------------------------------------------------------------------------------
166 /// @brief Assignment operator, assigns the internal reference and increments the reference count.
167 ///
168 /// The assignment operator assigns the internal ref from the rhs object and increments the
169 /// reference count on the underlying internal XMP object.
170
171 void operator= ( const TXMPMeta<tStringObj> & rhs );
172
173 // ---------------------------------------------------------------------------------------------
174 /// @brief Reconstructs an XMP object from an internal reference.
175 ///
176 /// This constructor creates a new \c TXMPMeta object that refers to the underlying reference object
177 /// of an existing \c TXMPMeta object. Use to safely pass XMP objects across DLL boundaries.
178 ///
179 /// @param xmpRef The underlying reference object, obtained from some other XMP object with
180 /// \c TXMPMeta::GetInternalRef().returns The new object.
181 ///
182 ///
183
184 TXMPMeta ( XMPMetaRef xmpRef );
185
186 // ---------------------------------------------------------------------------------------------
187 /// @brief Constructs an object and parse one buffer of RDF into it.
188 ///
189 /// This constructor creates a new \c TXMPMeta object and populates it with metadata from a
190 /// buffer containing serialized RDF. This buffer must be a complete RDF parse stream.
191 ///
192 /// The result of passing serialized data to this function is identical to creating an empty
193 /// object then calling \c TXMPMeta::ParseFromBuffer(). To use the constructor, however, the RDF
194 /// must be complete. If you need to parse data from multiple buffers, create an empty object
195 /// and use \c TXMPMeta::ParseFromBuffer().
196 ///
197 /// @param buffer A pointer to the buffer of RDF to be parsed. Can be null if the length is 0;
198 /// in this case, the function creates an empty object.
199 ///
200 /// @param xmpSize The length in bytes of the buffer.
201 ///
202
203
204 TXMPMeta ( XMP_StringPtr buffer,
205 XMP_StringLen xmpSize );
206
207 // ---------------------------------------------------------------------------------------------
208 /// @brief Destructor, typical virtual destructor. */
209 virtual ~TXMPMeta() throw();
210
211 /// @}
212
213 // =============================================================================================
214 // Global state functions
215 // ======================
216
217 // ---------------------------------------------------------------------------------------------
218 /// \name Global option flags
219 /// @{
220 /// Global option flags affect the overall behavior of the XMP Toolkit. The available options
221 /// will be declared in \c XMP_Const.h. There are none in this version of the Toolkit.
222
223 // ---------------------------------------------------------------------------------------------
224 /// @brief \c GetGlobalOptions() retrieves the set of global option flags. There are none in
225 /// this version of the Toolkit.
226 ///
227 /// This function is static; you can make the call from the class without instantiating it.
228 ///
229 /// @return A logical OR of global option bit-flag constants.
230
231 static XMP_OptionBits GetGlobalOptions();
232
233 // ---------------------------------------------------------------------------------------------
234 /// @brief \c SetGlobalOptions() updates the set of global option flags. There are none in this
235 /// version of the Toolkit.
236 ///
237 /// The entire set is replaced with the new values. If only one flag is to be modified, use
238 /// \c TXMPMeta::GetGlobalOptions() to obtain the current set, modify the desired flag, then use
239 /// this function to reset the value.
240 ///
241 /// This function is static; you can make the call from the class without instantiating it.
242 ///
243 /// @param options A logical OR of global option bit-flag constants.
244
245 static void SetGlobalOptions ( XMP_OptionBits options );
246
247 #if AdobePrivate
248
249 //******* DEPRECATED *************************//
250 //******* SEE : CTECHXMP-4169971 *************//
251
252 /// @brief Internal. Retrieves the internal memory allocation routines used by XMP.
253 ///
254 /// These are either standard C \c malloc() and \c free(), or the procedures passed to
255 /// \c TXMPMeta::Initialize(). This is not intended as a general client utility. It is a utility
256 /// for DLLs layered on top of XMP, so they can use the same client-provided memory routines, if
257 /// any.
258 ///
259 /// This function is static; you can make the call from the class without instantiating it.
260 ///
261 /// @param AllocateProc [out] A buffer in which to return the memory allocation function.
262 ///
263 /// @param DeleteProc [out] A buffer in which to return the memory de-allocation function.
264
265 static void GetMemProcs ( XMP_AllocateProc * AllocateProc,
266 XMP_DeleteProc * DeleteProc );
267 #endif
268
269 /// @}
270
271 #if AdobePrivate
272 // ---------------------------------------------------------------------------------------------
273 /// \deprecated Assert failure notifications is deprecated, users are encouraged to use Error Notification mechanism.
274 //
275 /// \name Assert failure notifications
276 /// @{
277
278 // ---------------------------------------------------------------------------------------------
279 /// @brief Internal. Registers a callback function to provide user notification of debugging
280 /// assertion failures.
281 ///
282 /// See the \c XMP_AssertNotifyProc declaration in \c XMP_Const.h for more information.
283 ///
284 /// This function is static; make the call directly from the concrete class (\c SXMPMeta).
285 ///
286 /// @param notifyProc The client-provided callback function.
287 ///
288 /// @param clientData A pointer to client-defined data to pass to the callback procedure.
289
290 static void RegisterAssertNotify ( XMP_AssertNotifyProc notifyProc,
291 void * clientData );
292
293 // ---------------------------------------------------------------------------------------------
294 /// @brief Internal. Unregisters a notification function if it is the active one.
295 ///
296 /// This function is static; make the call directly from the concrete class (\c SXMPMeta).
297 ///
298 /// @param notifyProc The callback to unregister, or null to unregister any active notification function.
299
300 static void UnregisterAssertNotify ( XMP_AssertNotifyProc notifyProc );
301
302 /// @}
303 #endif
304
305 // ---------------------------------------------------------------------------------------------
306 /// \name Internal data structure dump utilities
307 /// @{
308 ///
309 /// These are debugging utilities that dump internal data structures, to be handled by
310 /// client-defined callback described in \c XMP_Const.h.
311 ///
312 /// @see Member function \c TXMPMeta::DumpObject()
313
314 // ---------------------------------------------------------------------------------------------
315 /// @brief \c DumpNamespaces() sends the list of registered namespace URIs and prefixes to a handler.
316 ///
317 /// For debugging. Invokes a client-defined callback for each line of output.
318 ///
319 /// This function is static; make the call directly from the concrete class (\c SXMPMeta).
320 ///
321 /// @param outProc The client-defined procedure to handle each line of output.
322 ///
323 /// @param clientData A pointer to client-defined data to pass to the handler.
324 ///
325 /// @return A success-fail status value, returned from the handler. Zero is success, failure
326 /// values are client-defined.
327
328 static XMP_Status DumpNamespaces ( XMP_TextOutputProc outProc,
329 void * clientData );
330
331 #if AdobePrivate
332 // ---------------------------------------------------------------------------------------------
333 /// \deprecated Internal. <b>Not implemented.</b>
334 /// @brief Dumps the list of registered property traits to standard output, for debugging.
335 ///
336 /// Invokes a client-defined callback for each line of output.
337 ///
338 /// This function is static; make the call directly from the concrete class (\c SXMPMeta).
339 ///
340 /// @param outProc The client-defined procedure to handle each line of output.
341 ///
342 /// @param clientData A pointer to client-defined data to pass to the handler.
343 ///
344 /// @return A success-fail status value, returned from the handler. Zero is success, failure
345 /// values are client-defined.
346
347 static XMP_Status DumpPropertyTraits ( XMP_TextOutputProc outProc,
348 void * clientData ) __AVAILABILITY_INTERNAL_DEPRECATED_XMP;
349 #endif
350 /// @}
351
352 // ---------------------------------------------------------------------------------------------
353 /// \name Namespace Functions
354 /// @{
355 ///
356 /// Namespaces must be registered before use in namespace URI parameters or path expressions.
357 /// Within the XMP Toolkit the registered namespace URIs and prefixes must be unique. Additional
358 /// namespaces encountered when parsing RDF are automatically registered.
359 ///
360 /// The namespace URI should always end in an XML name separator such as '/' or '#'. This is
361 /// because some forms of RDF shorthand catenate a namespace URI with an element name to form a
362 /// new URI.
363
364 // ---------------------------------------------------------------------------------------------
365 /// @brief \c RegisterNamespace() registers a namespace URI with a suggested prefix.
366 ///
367 /// If the URI is not registered but the suggested prefix is in use, a unique prefix is created
368 /// from the suggested one. The actual registered prefix is returned. The function result tells
369 /// if the registered prefix is the suggested one. It is not an error if the URI is already
370 /// registered, regardless of the prefix.
371 ///
372 /// This function is static; make the call directly from the concrete class (\c SXMPMeta).
373 ///
374 /// @param namespaceURI The URI for the namespace. Must be a valid XML URI.
375 ///
376 /// @param suggestedPrefix The suggested prefix to be used if the URI is not yet registered.
377 /// Must be a valid XML name.
378 ///
379 /// @param registeredPrefix [out] A string object in which to return the prefix actually
380 /// registered for this URI.
381 ///
382 /// @return True if the registered prefix matches the suggested prefix.
383 ///
384 /// @note No checking is done on either the URI or the prefix. */
385
386 static bool RegisterNamespace ( XMP_StringPtr namespaceURI,
387 XMP_StringPtr suggestedPrefix,
388 tStringObj * registeredPrefix );
389
390 // ---------------------------------------------------------------------------------------------
391 /// @brief \c GetNamespacePrefix() obtains the prefix for a registered namespace URI, and
392 /// reports whether the URI is registered.
393 ///
394 /// This function is static; make the call directly from the concrete class (\c SXMPMeta).
395 ///
396 /// @param namespaceURI The URI for the namespace. Must not be null or the empty string. It is
397 /// not an error if the namespace URI is not registered.
398 ///
399 /// @param namespacePrefix [out] A string object in which to return the prefix registered for
400 /// this URI, with a terminating colon character, ':'. If the namespace is not registered, this
401 /// string is not modified.
402 ///
403 /// @return True if the namespace URI is registered.
404
405 static bool GetNamespacePrefix ( XMP_StringPtr namespaceURI,
406 tStringObj * namespacePrefix );
407
408 // ---------------------------------------------------------------------------------------------
409 /// @brief \c GetNamespaceURI() obtains the URI for a registered namespace prefix, and reports
410 /// whether the prefix is registered.
411 ///
412 /// This function is static; make the call directly from the concrete class (\c SXMPMeta).
413 ///
414 /// @param namespacePrefix The prefix for the namespace. Must not be null or the empty string.
415 /// It is not an error if the namespace prefix is not registered.
416 ///
417 /// @param namespaceURI [out] A string object in which to return the URI registered for this
418 /// prefix. If the prefix is not registered, this string is not modified.
419 ///
420 /// @return True if the namespace prefix is registered.
421
422 static bool GetNamespaceURI ( XMP_StringPtr namespacePrefix,
423 tStringObj * namespaceURI );
424
425 // ---------------------------------------------------------------------------------------------
426 /// @brief Not implemented.
427 ///
428 /// Deletes a namespace from the registry. Does nothing if the URI is not registered, or if the
429 /// parameter is null or the empty string.
430 ///
431 /// This function is static; make the call directly from the concrete class (\c SXMPMeta).
432 ///
433 /// @param namespaceURI The URI for the namespace.
434
435 static void DeleteNamespace ( XMP_StringPtr namespaceURI );
436
437 /// @}
438
439 #if AdobePrivate
440 // ---------------------------------------------------------------------------------------------
441 /// \deprecated <b>Not implemented.</b>
442 /// \brief Registers special traits for a property.
443 ///
444 /// A property can have a variety of special traits
445 ///
446 /// \param schemaNS The namespace URI for the property. Must not be null or the empty string.
447 ///
448 /// \param propName The name of the property. Can be a general path expression, must not be null
449 /// or the empty string.
450 ///
451 /// \param options Flags for the traits to be applied to this property.
452
453 static void RegisterPropertyTraits ( XMP_StringPtr schemaNS,
454 XMP_StringPtr propName,
455 XMP_OptionBits options ) __AVAILABILITY_INTERNAL_DEPRECATED_XMP;
456 #endif
457
458 // =============================================================================================
459 // Basic property manipulation functions
460 // =====================================
461
462 // *** Should add discussion of schemaNS and propName prefix usage.
463
464 // ---------------------------------------------------------------------------------------------
465 /// \name Accessing property values
466 /// @{
467 ///
468 /// The property value accessors all take a property specification; the top level namespace URI
469 /// (the "schema" namespace) and the basic name of the property being referenced. See the
470 /// introductory discussion of path expression usage for more information.
471 ///
472 /// The accessor functions return true if the specified property exists. If it does, output
473 /// parameters return the value (if any) and option flags describing the property. The option
474 /// bit-flag constants that describe properties are \c kXMP_PropXx and
475 /// \c kXMP_ArrayIsXx. See \c #kXMP_PropValueIsURI and following, and macros \c #XMP_PropIsSimple
476 /// and following in \c XMP_Const.h. If the property exists and has a value, it is returned as a
477 /// Unicode string in UTF-8 encoding. Arrays and the non-leaf levels of structs do not have
478 /// values.
479
480 // ---------------------------------------------------------------------------------------------
481 /// @brief \c GetProperty() reports whether a property exists, and retrieves its value.
482 ///
483 /// This is the simplest property accessor. Use this to retrieve the values of top-level simple
484 /// properties, or after using the path composition functions in \c TXMPUtils.
485 ///
486 /// When specifying a namespace and path (in this and all other accessors):
487 /// \li If a namespace URI is specified, it must be for a registered namespace.
488 /// \li If the namespace is specified only by a prefix in the property name path,
489 /// it must be a registered prefix.
490 /// \li If both a URI and path prefix are present, they must be corresponding
491 /// parts of a registered namespace.
492 ///
493 /// @param schemaNS The namespace URI for the property. The URI must be for a registered
494 /// namespace. Must not be null or the empty string.
495 ///
496 /// @param propName The name of the property. Can be a general path expression, must not be null
497 /// or the empty string. The first component can be a namespace prefix; if present without a
498 /// \c schemaNS value, the prefix specifies the namespace. The prefix must be for a registered
499 /// namespace, and if a namespace URI is specified, must match the registered prefix for that
500 /// namespace.
501 ///
502 /// @param propValue [out] A string object in which to return the value of the property, if the
503 /// property exists and has a value. Arrays and non-leaf levels of structs do not have values.
504 /// Can be null if the value is not wanted.
505 ///
506 /// @param options A buffer in which to return option flags describing the property. Can be null
507 /// if the flags are not wanted.
508 ///
509 /// @return True if the property exists.
510
511 bool GetProperty ( XMP_StringPtr schemaNS,
512 XMP_StringPtr propName,
513 tStringObj * propValue,
514 XMP_OptionBits * options ) const;
515
516 // ---------------------------------------------------------------------------------------------
517 /// @brief \c GetArrayItem() provides access to items within an array.
518 ///
519 /// Reports whether the item exists; if it does, and if it has a value, the function retrieves
520 /// the value. Items are accessed by an integer index, where the first item has index 1.
521 ///
522 /// @param schemaNS The namespace URI for the array; see \c GetProperty().
523 ///
524 /// @param arrayName The name of the array. Can be a general path expression, must not be null
525 /// or the empty string; see \c GetProperty() for namespace prefix usage.
526 ///
527 /// @param itemIndex The 1-based index of the desired item. Use the macro \c #kXMP_ArrayLastItem
528 /// to specify the last existing array item.
529 ///
530 /// @param itemValue [out] A string object in which to return the value of the array item, if it
531 /// has a value. Arrays and non-leaf levels of structs do not have values. Can be null if the
532 /// value is not wanted.
533 ///
534 /// @param options [out] A buffer in which to return the option flags describing the array item.
535 /// Can be null if the flags are not wanted.
536 ///
537 /// @return True if the array item exists.
538
539 bool GetArrayItem ( XMP_StringPtr schemaNS,
540 XMP_StringPtr arrayName,
541 XMP_Index itemIndex,
542 tStringObj * itemValue,
543 XMP_OptionBits * options ) const;
544
545 // ---------------------------------------------------------------------------------------------
546 /// @brief \c GetStructField() provides access to fields within a nested structure.
547 ///
548 /// Reports whether the field exists; if it does, and if it has a value, the function retrieves
549 /// the value.
550 ///
551 /// @param schemaNS The namespace URI for the struct; see \c GetProperty().
552 ///
553 /// @param structName The name of the struct. Can be a general path expression, must not be null
554 /// or the empty string; see \c GetProperty() for namespace prefix usage.
555 ///
556 /// @param fieldNS The namespace URI for the field. Same URI and prefix usage as the \c schemaNS
557 /// and \c structName parameters.
558 ///
559 /// @param fieldName The name of the field. Must be a single XML name, must not be null or the
560 /// empty string. Same URI and prefix usage as the \c schemaNS and \c structName parameters.
561 ///
562 /// @param fieldValue [out] A string object in which to return the value of the field, if the
563 /// field has a value. Arrays and non-leaf levels of structs do not have values. Can be null if
564 /// the value is not wanted.
565 ///
566 /// @param options [out] A buffer in which to return the option flags describing the field. Can
567 /// be null if the flags are not wanted.
568 ///
569 /// @return True if the field exists.
570
571 bool GetStructField ( XMP_StringPtr schemaNS,
572 XMP_StringPtr structName,
573 XMP_StringPtr fieldNS,
574 XMP_StringPtr fieldName,
575 tStringObj * fieldValue,
576 XMP_OptionBits * options ) const;
577
578 // ---------------------------------------------------------------------------------------------
579 /// @brief \c GetQualifier() provides access to a qualifier attached to a property.
580 ///
581 /// @note In this version of the Toolkit, qualifiers are supported only for simple leaf properties.
582 ///
583 /// @param schemaNS The namespace URI; see \c GetProperty().
584 ///
585 /// @param propName The name of the property to which the qualifier is attached. Can be a
586 /// general path expression, must not be null or the empty string; see \c GetProperty() for
587 /// namespace prefix usage.
588 ///
589 /// @param qualNS The namespace URI for the qualifier. Same URI and prefix usage as the
590 /// \c schemaNS and \c propName parameters.
591 ///
592 /// @param qualName The name of the qualifier. Must be a single XML name, must not be null or
593 /// the empty string. Same URI and prefix usage as the \c schemaNS and \c propName parameters.
594 ///
595 /// @param qualValue [out] A string object in which to return the value of the qualifier, if the
596 /// qualifier has a value. Arrays and non-leaf levels of structs do not have values. Can be null
597 /// if the value is not wanted.
598 ///
599 /// @param options [out] A buffer in which to return the option flags describing the qualifier.
600 /// Can be null if the flags are not wanted.
601 ///
602 /// @return True if the qualifier exists.
603
604 bool GetQualifier ( XMP_StringPtr schemaNS,
605 XMP_StringPtr propName,
606 XMP_StringPtr qualNS,
607 XMP_StringPtr qualName,
608 tStringObj * qualValue,
609 XMP_OptionBits * options ) const;
610
611 /// @}
612
613 // =============================================================================================
614
615 // ---------------------------------------------------------------------------------------------
616 /// \name Creating properties and setting their values
617 /// @{
618 ///
619 /// These functions all take a property specification; the top level namespace URI (the "schema"
620 /// namespace) and the basic name of the property being referenced. See the introductory
621 /// discussion of path expression usage for more information.
622 ///
623 /// All of the functions take a UTF-8 encoded Unicode string for the property value. Arrays and
624 /// non-leaf levels of structs do not have values. The value can be passed as an
625 /// \c #XMP_StringPtr (a pointer to a null-terminated string), or as a string object
626 /// (\c tStringObj).
627
628 /// Each function takes an options flag that describes the property. You can use these functions
629 /// to create empty arrays and structs by setting appropriate option flags. When you assign a
630 /// value, all levels of a struct that are implicit in the assignment are created if necessary.
631 /// \c TXMPMeta::AppendArrayItem() implicitly creates the named array if necessary.
632 ///
633 /// The allowed option bit-flags include:
634 /// \li \c #kXMP_PropValueIsStruct - Can be used to create an empty struct.
635 /// A struct is implicitly created when the first field is set.
636 /// \li \c #kXMP_PropValueIsArray - By default, a general unordered array (bag).
637 /// \li \c #kXMP_PropArrayIsOrdered - An ordered array.
638 /// \li \c #kXMP_PropArrayIsAlternate - An alternative array.
639 /// \li \c #kXMP_PropArrayIsAltText - An alt-text array. Each array element must
640 /// be a simple property with an \c xml:lang attribute.
641
642 // ---------------------------------------------------------------------------------------------
643 /// @brief \c SetProperty() creates or sets a property value.
644 ///
645 /// This is the simplest property setter. Use it for top-level simple properties, or after using
646 /// the path composition functions in \c TXMPUtils.
647 ///
648 /// @param schemaNS The namespace URI; see \c GetProperty().
649 ///
650 /// @param propName The name of the property. Can be a general path expression, must not be null
651 /// or the empty string; see \c GetProperty() for namespace prefix usage.
652 ///
653 /// @param propValue The new value, a pointer to a null terminated UTF-8 string. Must be null
654 /// for arrays and non-leaf levels of structs that do not have values.
655 ///
656 /// @param options Option flags describing the property; a logical OR of allowed bit-flag
657 /// constants; see \c #kXMP_PropValueIsStruct and following. Must match the type of a property
658 /// that already exists.
659
660 void SetProperty ( XMP_StringPtr schemaNS,
661 XMP_StringPtr propName,
662 XMP_StringPtr propValue,
663 XMP_OptionBits options = 0 );
664
665 // ---------------------------------------------------------------------------------------------
666 /// @brief \c SetProperty() creates or sets a property value using a string object.
667 ///
668 /// Overloads the basic form of the function, allowing you to pass a string object
669 /// for the item value. It is otherwise identical; see details in the canonical form.
670
671 void SetProperty ( XMP_StringPtr schemaNS,
672 XMP_StringPtr propName,
673 const tStringObj & propValue,
674 XMP_OptionBits options = 0 );
675
676 // ---------------------------------------------------------------------------------------------
677 /// @brief \c SetArrayItem() creates or sets the value of an item within an array.
678 ///
679 /// Items are accessed by an integer index, where the first item has index 1. This function
680 /// creates the item if necessary, but the array itself must already exist Use
681 /// \c AppendArrayItem() to create arrays. A new item is automatically appended if the index is the
682 /// array size plus 1. To insert a new item before or after an existing item, use option flags.
683 ///
684 /// Use \c TXMPUtils::ComposeArrayItemPath() to create a complex path.
685 ///
686 /// @param schemaNS The namespace URI; see \c GetProperty().
687 ///
688 /// @param arrayName The name of the array. Can be a general path expression, must not be null
689 /// or the empty string; see \c GetProperty() for namespace prefix usage.
690 ///
691 /// @param itemIndex The 1-based index of the desired item. Use the macro \c #kXMP_ArrayLastItem
692 /// to specify the last existing array item.
693 ///
694 /// @param itemValue The new item value, a null-terminated UTF-8 string, if the array item has a
695 /// value.
696 ///
697 /// @param options Option flags describing the array type and insertion location for a new item;
698 /// a logical OR of allowed bit-flag constants. The type, if specified, must match the existing
699 /// array type, \c #kXMP_PropArrayIsOrdered, \c #kXMP_PropArrayIsAlternate, or
700 /// \c #kXMP_PropArrayIsAltText. Default (0 or \c #kXMP_NoOptions) matches the existing array type.
701 ///
702 /// To insert a new item before or after the specified index, set flag \c #kXMP_InsertBeforeItem
703 /// or \c #kXMP_InsertAfterItem.
704
705 void SetArrayItem ( XMP_StringPtr schemaNS,
706 XMP_StringPtr arrayName,
707 XMP_Index itemIndex,
708 XMP_StringPtr itemValue,
709 XMP_OptionBits options = 0 );
710
711 // ---------------------------------------------------------------------------------------------
712 /// @brief \c SetArrayItem() creates or sets the value of an item within an array using a string object.
713 ///
714 /// Overloads the basic form of the function, allowing you to pass a string object in which to
715 /// return the item value. It is otherwise identical; see details in the canonical form.
716
717 void SetArrayItem ( XMP_StringPtr schemaNS,
718 XMP_StringPtr arrayName,
719 XMP_Index itemIndex,
720 const tStringObj & itemValue,
721 XMP_OptionBits options = 0 );
722
723 // ---------------------------------------------------------------------------------------------
724 /// @brief \c AppendArrayItem() adds an item to an array, creating the array if necessary.
725 ///
726 /// This function simplifies construction of an array by not requiring that you pre-create an
727 /// empty array. The array that is assigned is created automatically if it does not yet exist.
728 /// If the array exists, it must have the form specified by the options. Each call appends a new
729 /// item to the array.
730 ///
731 /// Use \c TXMPUtils::ComposeArrayItemPath() to create a complex path.
732 ///
733 /// @param schemaNS The namespace URI; see \c GetProperty().
734 ///
735 /// @param arrayName The name of the array. Can be a general path expression, must not be null
736 /// or the empty string; see \c GetProperty() for namespace prefix usage.
737 ///
738 /// @param arrayOptions Option flags describing the array type to create; a logical OR of
739 /// allowed bit-flag constants, \c #kXMP_PropArrayIsOrdered, \c #kXMP_PropArrayIsAlternate, or
740 /// \c #kXMP_PropArrayIsAltText. If the array exists, must match the existing array type or be
741 /// null (0 or \c #kXMP_NoOptions).
742 ///
743 /// @param itemValue The new item value, a null-terminated UTF-8 string, if the array item has a
744 /// value.
745 ///
746 /// @param itemOptions Option flags describing the item type to create; one of the bit-flag
747 /// constants \c #kXMP_PropValueIsArray or \c #kXMP_PropValueIsStruct to create a complex array
748 /// item.
749
750 void AppendArrayItem ( XMP_StringPtr schemaNS,
751 XMP_StringPtr arrayName,
752 XMP_OptionBits arrayOptions,
753 XMP_StringPtr itemValue,
754 XMP_OptionBits itemOptions = 0 );
755
756 // ---------------------------------------------------------------------------------------------
757 /// @brief \c AppendArrayItem() adds an item to an array using a string object value, creating
758 /// the array if necessary.
759 ///
760 /// Overloads the basic form of the function, allowing you to pass a string object in which to
761 /// return the item value. It is otherwise identical; see details in the canonical form.
762
763 void AppendArrayItem ( XMP_StringPtr schemaNS,
764 XMP_StringPtr arrayName,
765 XMP_OptionBits arrayOptions,
766 const tStringObj & itemValue,
767 XMP_OptionBits itemOptions = 0 );
768
769 // ---------------------------------------------------------------------------------------------
770 /// @brief \c SetStructField() creates or sets the value of a field within a nested structure.
771 ///
772 /// Use this to set a value within an existing structure, create a new field within an existing
773 /// structure, or create an empty structure of any depth. If you set a field in a structure that
774 /// does not exist, the structure is automatically created.
775 ///
776 /// Use \c TXMPUtils::ComposeStructFieldPath() to create a complex path.
777 ///
778 /// @param schemaNS The namespace URI; see \c GetProperty().
779 ///
780 /// @param structName The name of the struct. Can be a general path expression, must not be null
781 /// or the empty string; see \c GetProperty() for namespace prefix usage.
782 ///
783 /// @param fieldNS The namespace URI for the field. Same namespace and prefix usage as
784 /// \c GetProperty().
785 ///
786 /// @param fieldName The name of the field. Must be a single XML name, must not be null or the
787 /// empty string. Same namespace and prefix usage as \c GetProperty().
788 ///
789 /// @param fieldValue The new value, a null-terminated UTF-8 string, if the field has a value.
790 /// Null to create a new, empty struct or empty field in an existing struct.
791 ///
792 /// @param options Option flags describing the property, in which the bit-flag
793 /// \c #kXMP_PropValueIsStruct must be set to create a struct.
794
795 void SetStructField ( XMP_StringPtr schemaNS,
796 XMP_StringPtr structName,
797 XMP_StringPtr fieldNS,
798 XMP_StringPtr fieldName,
799 XMP_StringPtr fieldValue,
800 XMP_OptionBits options = 0 );
801
802 // ---------------------------------------------------------------------------------------------
803 /// @brief \c SetStructField() creates or sets the value of a field within a nested structure,
804 /// using a string object.
805 ///
806 /// Overloads the basic form of the function, allowing you to pass a string object in which to
807 /// return the field value. It is otherwise identical; see details in the canonical form.
808
809 void SetStructField ( XMP_StringPtr schemaNS,
810 XMP_StringPtr structName,
811 XMP_StringPtr fieldNS,
812 XMP_StringPtr fieldName,
813 const tStringObj & fieldValue,
814 XMP_OptionBits options = 0 );
815
816 // ---------------------------------------------------------------------------------------------
817 /// @brief \c SetQualifier() creates or sets a qualifier attached to a property.
818 ///
819 /// Use this to set a value for an existing qualifier, or create a new qualifier. <<how do
820 /// options work? macro vs bit-flag? interaction w/XMP_PropHasQualifier?>> Use
821 /// \c TXMPUtils::ComposeQualifierPath() to create a complex path.
822 ///
823 /// @param schemaNS The namespace URI; see \c GetProperty().
824 ///
825 /// @param propName The name of the property to which the qualifier is attached. Can be a
826 /// general path expression, must not be null or the empty string; see \c GetProperty() for
827 /// namespace prefix usage.
828 ///
829 /// @param qualNS The namespace URI for the qualifier. Same namespace and prefix usage as
830 /// \c GetProperty().
831 ///
832 /// @param qualName The name of the qualifier. Must be a single XML name, must not be null or
833 /// the empty string. Same namespace and prefix usage as \c GetProperty().
834 ///
835 /// @param qualValue The new value, a null-terminated UTF-8 string, if the qualifier has a
836 /// value. Null to create a new, empty qualifier.
837 ///
838 /// @param options Option flags describing the <<qualified property? qualifier?>>, a logical OR
839 /// of property-type bit-flag constants. Use the macro \c #XMP_PropIsQualifier to create a
840 /// qualifier. <<??>>
841
842 void SetQualifier ( XMP_StringPtr schemaNS,
843 XMP_StringPtr propName,
844 XMP_StringPtr qualNS,
845 XMP_StringPtr qualName,
846 XMP_StringPtr qualValue,
847 XMP_OptionBits options = 0 );
848
849 // ---------------------------------------------------------------------------------------------
850 /// @brief \c SetQualifier() creates or sets a qualifier attached to a property using a string object.
851 ///
852 /// Overloads the basic form of the function, allowing you to pass a string object
853 /// for the qualifier value. It is otherwise identical; see details in the canonical form.
854
855 void SetQualifier ( XMP_StringPtr schemaNS,
856 XMP_StringPtr propName,
857 XMP_StringPtr qualNS,
858 XMP_StringPtr qualName,
859 const tStringObj & qualValue,
860 XMP_OptionBits options = 0 );
861
862 /// @}
863
864 // =============================================================================================
865
866 // ---------------------------------------------------------------------------------------------
867 /// \name Detecting and deleting properties.
868 /// @{
869 ///
870 /// The namespace URI and prefix usage for property specifiers in these functions is the same as
871 /// for \c TXMPMeta::GetProperty().
872
873 // ---------------------------------------------------------------------------------------------
874 /// @brief \c DeleteProperty() deletes an XMP subtree rooted at a given property.
875 ///
876 /// It is not an error if the property does not exist.
877 ///
878 /// @param schemaNS The namespace URI for the property; see \c GetProperty().
879 ///
880 /// @param propName The name of the property; see \c GetProperty().
881
882 void DeleteProperty ( XMP_StringPtr schemaNS,
883 XMP_StringPtr propName );
884
885 // ---------------------------------------------------------------------------------------------
886 /// @brief \c DeleteArrayItem() deletes an XMP subtree rooted at a given array item.
887 ///
888 /// It is not an error if the array item does not exist. Use
889 /// \c TXMPUtils::ComposeArrayItemPath() to create a complex path.
890 ///
891 /// @param schemaNS The namespace URI for the array; see \c GetProperty().
892 ///
893 /// @param arrayName The name of the array. Can be a general path expression, must not be null
894 /// or the empty string; see \c GetProperty() for namespace prefix usage.
895 ///
896 /// @param itemIndex The 1-based index of the desired item. Use the macro \c #kXMP_ArrayLastItem
897 /// to specify the last existing array item.
898
899 void DeleteArrayItem ( XMP_StringPtr schemaNS,
900 XMP_StringPtr arrayName,
901 XMP_Index itemIndex );
902
903 // ---------------------------------------------------------------------------------------------
904 /// @brief \c DeleteStructField() deletes an XMP subtree rooted at a given struct field.
905 ///
906 /// It is not an error if the field does not exist.
907 ///
908 /// @param schemaNS The namespace URI for the struct; see \c GetProperty().
909 ///
910 /// @param structName The name of the struct. Can be a general path expression, must not be null
911 /// or the empty string; see \c GetProperty() for namespace prefix usage.
912 ///
913 /// @param fieldNS The namespace URI for the field. Same namespace and prefix usage as
914 /// \c GetProperty().
915 ///
916 /// @param fieldName The name of the field. Must be a single XML name, must not be null or the
917 /// empty string. Same namespace and prefix usage as \c GetProperty().
918
919 void DeleteStructField ( XMP_StringPtr schemaNS,
920 XMP_StringPtr structName,
921 XMP_StringPtr fieldNS,
922 XMP_StringPtr fieldName );
923
924 // ---------------------------------------------------------------------------------------------
925 /// @brief \c DeleteQualifier() deletes an XMP subtree rooted at a given qualifier.
926 ///
927 /// It is not an error if the qualifier does not exist.
928 ///
929 /// @param schemaNS The namespace URI; see \c GetProperty().
930 ///
931 /// @param propName The name of the property to which the qualifier is attached. Can be a
932 /// general path expression, must not be null or the empty string; see \c GetProperty() for
933 /// namespace prefix usage.
934 ///
935 /// @param qualNS The namespace URI for the qualifier. Same namespace and prefix usage as
936 /// \c GetProperty().
937 ///
938 /// @param qualName The name of the qualifier. Must be a single XML name, must not be null or
939 /// the empty string. Same namespace and prefix usage as \c GetProperty().
940
941 void DeleteQualifier ( XMP_StringPtr schemaNS,
942 XMP_StringPtr propName,
943 XMP_StringPtr qualNS,
944 XMP_StringPtr qualName );
945
946 // ---------------------------------------------------------------------------------------------
947 /// @brief \c DoesPropertyExist() reports whether a property currently exists.
948 ///
949 /// @param schemaNS The namespace URI for the property; see \c GetProperty().
950 ///
951 /// @param propName The name of the property; see \c GetProperty().
952 ///
953 /// @return True if the property exists.
954
955 bool DoesPropertyExist ( XMP_StringPtr schemaNS,
956 XMP_StringPtr propName ) const;
957
958 // ---------------------------------------------------------------------------------------------
959 /// @brief \c DoesArrayItemExist() reports whether an array item currently exists.
960 ///
961 /// Use \c TXMPUtils::ComposeArrayItemPath() to create a complex path.
962 ///
963 /// @param schemaNS The namespace URI; see \c GetProperty().
964 ///
965 /// @param arrayName The name of the array. Can be a general path expression, must not be null
966 /// or the empty string; see \c GetProperty() for namespace prefix usage.
967 ///
968 /// @param itemIndex The 1-based index of the desired item. Use the macro \c #kXMP_ArrayLastItem
969 /// to specify the last existing array item.
970 ///
971 /// @return True if the array item exists.
972
973 bool DoesArrayItemExist ( XMP_StringPtr schemaNS,
974 XMP_StringPtr arrayName,
975 XMP_Index itemIndex ) const;
976
977 // ---------------------------------------------------------------------------------------------
978 /// @brief \c DoesStructFieldExist() reports whether a struct field currently exists.
979 ///
980 /// Use \c TXMPUtils::ComposeStructFieldPath() to create a complex path.
981 ///
982 /// @param schemaNS The namespace URI; see \c GetProperty().
983 ///
984 /// @param structName The name of the struct. Can be a general path expression, must not be null
985 /// or the empty string; see \c GetProperty() for namespace prefix usage.
986 ///
987 /// @param fieldNS The namespace URI for the field. Same namespace and prefix usage as
988 /// \c GetProperty().
989 ///
990 /// @param fieldName The name of the field. Must be a single XML name, must not be null or the
991 /// empty string. Same namespace and prefix usage as \c GetProperty().
992 ///
993 /// @return True if the field exists.
994
995 bool DoesStructFieldExist ( XMP_StringPtr schemaNS,
996 XMP_StringPtr structName,
997 XMP_StringPtr fieldNS,
998 XMP_StringPtr fieldName ) const;
999
1000 // ---------------------------------------------------------------------------------------------
1001 /// @brief \c DoesQualifierExist() reports whether a qualifier currently exists.
1002 ///
1003 /// @param schemaNS The namespace URI; see \c GetProperty().
1004 ///
1005 /// @param propName The name of the property to which the qualifier is attached. Can be a
1006 /// general path expression, must not be null or the empty string; see \c GetProperty() for
1007 /// namespace prefix usage.
1008 ///
1009 /// @param qualNS The namespace URI for the qualifier. Same namespace and prefix usage as
1010 /// \c GetProperty().
1011 ///
1012 /// @param qualName The name of the qualifier. Must be a single XML name, must not be null or
1013 /// the empty string. Same namespace and prefix usage as \c GetProperty().
1014 ///
1015 /// @return True if the qualifier exists.
1016
1017 bool DoesQualifierExist ( XMP_StringPtr schemaNS,
1018 XMP_StringPtr propName,
1019 XMP_StringPtr qualNS,
1020 XMP_StringPtr qualName ) const;
1021
1022 /// @}
1023
1024 // =============================================================================================
1025 // Specialized Get and Set functions
1026 // =============================================================================================
1027
1028 // ---------------------------------------------------------------------------------------------
1029 /// \name Accessing properties as binary values.
1030 /// @{
1031 ///
1032 /// These are very similar to \c TXMPMeta::GetProperty() and \c TXMPMeta::SetProperty(), except
1033 /// that the value is returned or provided in binary form instead of as a UTF-8 string.
1034 /// \c TXMPUtils provides functions for converting between binary and string values.
1035 /// Use the path composition functions in \c TXMPUtils to compose complex path expressions
1036 /// for fields or items in nested structures or arrays, or for qualifiers.
1037
1038 // ---------------------------------------------------------------------------------------------
1039 /// @brief \c GetProperty_Bool() retrieves the value of a Boolean property as a C++ bool.
1040 ///
1041 /// Reports whether a property exists, and retrieves its binary value and property type information.
1042 ///
1043 /// @param schemaNS The namespace URI; see \c GetProperty().
1044 ///
1045 /// @param propName The name of the property. Can be a general path expression, must not be null
1046 /// or the empty string; see \c GetProperty() for namespace prefix usage.
1047 ///
1048 /// @param propValue [out] A buffer in which to return the binary value. Can be null if the
1049 /// value is not wanted. Must be null for arrays and non-leaf levels of structs that do not have
1050 /// values.
1051 ///
1052 /// @param options [out] A buffer in which to return the option flags describing the property, a
1053 /// logical OR of allowed bit-flag constants; see \c #kXMP_PropValueIsStruct and following. Can
1054 /// be null if flags are not wanted.
1055 ///
1056 /// @return True if the property exists.
1057
1058 bool GetProperty_Bool ( XMP_StringPtr schemaNS,
1059 XMP_StringPtr propName,
1060 bool * propValue,
1061 XMP_OptionBits * options ) const;
1062
1063 // ---------------------------------------------------------------------------------------------
1064 /// @brief \c GetProperty_Int() retrieves the value of an integer property as a C long integer.
1065 ///
1066 /// Reports whether a property exists, and retrieves its binary value and property type information.
1067 ///
1068 /// @param schemaNS The namespace URI; see \c GetProperty().
1069 ///
1070 /// @param propName The name of the property. Can be a general path expression, must not be null
1071 /// or the empty string; see \c GetProperty() for namespace prefix usage.
1072 ///
1073 /// @param propValue [out] A buffer in which to return the binary value. Can be null if the
1074 /// value is not wanted. Must be null for arrays and non-leaf levels of structs that do not have
1075 /// values.
1076 ///
1077 /// @param options [out] A buffer in which to return the option flags describing the property, a
1078 /// logical OR of allowed bit-flag constants; see \c #kXMP_PropValueIsStruct and following. Can
1079 /// be null if flags are not wanted.
1080 ///
1081 /// @return True if the property exists.
1082
1083 bool GetProperty_Int ( XMP_StringPtr schemaNS,
1084 XMP_StringPtr propName,
1085 XMP_Int32 * propValue,
1086 XMP_OptionBits * options ) const;
1087
1088 // ---------------------------------------------------------------------------------------------
1089 /// @brief \c GetProperty_Int64() retrieves the value of an integer property as a C long long integer.
1090 ///
1091 /// Reports whether a property exists, and retrieves its binary value and property type information.
1092 ///
1093 /// @param schemaNS The namespace URI; see \c GetProperty().
1094 ///
1095 /// @param propName The name of the property. Can be a general path expression, must not be null
1096 /// or the empty string; see \c GetProperty() for namespace prefix usage.
1097 ///
1098 /// @param propValue [out] A buffer in which to return the binary value. Can be null if the
1099 /// value is not wanted. Must be null for arrays and non-leaf levels of structs that do not have
1100 /// values.
1101 ///
1102 /// @param options [out] A buffer in which to return the option flags describing the property, a
1103 /// logical OR of allowed bit-flag constants; see \c #kXMP_PropValueIsStruct and following. Can
1104 /// be null if flags are not wanted.
1105 ///
1106 /// @return True if the property exists.
1107
1108 bool GetProperty_Int64 ( XMP_StringPtr schemaNS,
1109 XMP_StringPtr propName,
1110 XMP_Int64 * propValue,
1111 XMP_OptionBits * options ) const;
1112
1113 // ---------------------------------------------------------------------------------------------
1114 /// @brief \c GetProperty_Float() retrieves the value of a floating-point property as a C double float.
1115 ///
1116 /// Reports whether a property exists, and retrieves its binary value and property type information.
1117 ///
1118 /// @param schemaNS The namespace URI; see \c GetProperty().
1119 ///
1120 /// @param propName The name of the property. Can be a general path expression, must not be null
1121 /// or the empty string; see \c GetProperty() for namespace prefix usage.
1122 ///
1123 /// @param propValue [out] A buffer in which to return the binary value. Can be null if the
1124 /// value is not wanted. Must be null for arrays and non-leaf levels of structs that do not have
1125 /// values.
1126 ///
1127 /// @param options [out] A buffer in which to return the option flags describing the property, a
1128 /// logical OR of allowed bit-flag constants; see \c #kXMP_PropValueIsStruct and following. Can
1129 /// be null if flags are not wanted.
1130 ///
1131 /// @return True if the property exists.
1132
1133 bool GetProperty_Float ( XMP_StringPtr schemaNS,
1134 XMP_StringPtr propName,
1135 double * propValue,
1136 XMP_OptionBits * options ) const;
1137
1138 // ---------------------------------------------------------------------------------------------
1139 /// @brief \c GetProperty_Date() retrieves the value of a date-time property as an \c #XMP_DateTime structure.
1140 ///
1141 /// Reports whether a property exists, and retrieves its binary value and property type information.
1142 ///
1143 /// @param schemaNS The namespace URI; see \c GetProperty().
1144 ///
1145 /// @param propName The name of the property. Can be a general path expression, must not be null
1146 /// or the empty string; see \c GetProperty() for namespace prefix usage.
1147 ///
1148 /// @param propValue [out] A buffer in which to return the binary value. Can be null if the
1149 /// value is not wanted. Must be null for arrays and non-leaf levels of structs that do not have
1150 /// values.
1151 ///
1152 /// @param options [out] A buffer in which to return the option flags describing the property, a
1153 /// logical OR of allowed bit-flag constants; see \c #kXMP_PropValueIsStruct and following. Can
1154 /// be null if flags are not wanted.
1155 ///
1156 /// @return True if the property exists.
1157
1158 bool GetProperty_Date ( XMP_StringPtr schemaNS,
1159 XMP_StringPtr propName,
1160 XMP_DateTime * propValue,
1161 XMP_OptionBits * options ) const;
1162
1163 // ---------------------------------------------------------------------------------------------
1164 /// @brief \c SetProperty_Bool() sets the value of a Boolean property using a C++ bool.
1165 ///
1166 /// Sets a property with a binary value, creating it if necessary.
1167 ///
1168 /// @param schemaNS The namespace URI; see \c GetProperty().
1169 ///
1170 /// @param propName The name of the property. Can be a general path expression, must not be null
1171 /// or the empty string; see \c GetProperty() for namespace prefix usage.
1172 ///
1173 /// @param propValue The new binary value. Can be null if creating the property. Must be null
1174 /// for arrays and non-leaf levels of structs that do not have values.
1175 ///
1176 /// @param options Option flags describing the property; a logical OR of allowed bit-flag
1177 /// constants; see \c #kXMP_PropValueIsStruct and following. Must match the type of a property
1178 /// that already exists.
1179
1180 void SetProperty_Bool ( XMP_StringPtr schemaNS,
1181 XMP_StringPtr propName,
1182 bool propValue,
1183 XMP_OptionBits options = 0 );
1184
1185 // ---------------------------------------------------------------------------------------------
1186 /// @brief \c SetProperty_Int() sets the value of an integer property using a C long integer.
1187 ///
1188 /// Sets a property with a binary value, creating it if necessary.
1189 ///
1190 /// @param schemaNS The namespace URI; see \c GetProperty().
1191 ///
1192 /// @param propName The name of the property. Can be a general path expression, must not be null
1193 /// or the empty string; see \c GetProperty() for namespace prefix usage.
1194 ///
1195 /// @param propValue The new binary value. Can be null if creating the property. Must be null
1196 /// for arrays and non-leaf levels of structs that do not have values.
1197 ///
1198 /// @param options Option flags describing the property; a logical OR of allowed bit-flag
1199 /// constants; see \c #kXMP_PropValueIsStruct and following. Must match the type of a property
1200 /// that already exists.
1201
1202 void SetProperty_Int ( XMP_StringPtr schemaNS,
1203 XMP_StringPtr propName,
1204 XMP_Int32 propValue,
1205 XMP_OptionBits options = 0 );
1206
1207 // ---------------------------------------------------------------------------------------------
1208 /// @brief \c SetProperty_Int64() sets the value of an integer property using a C long long integer.
1209 ///
1210 /// Sets a property with a binary value, creating it if necessary.
1211 ///
1212 /// @param schemaNS The namespace URI; see \c GetProperty().
1213 ///
1214 /// @param propName The name of the property. Can be a general path expression, must not be null
1215 /// or the empty string; see \c GetProperty() for namespace prefix usage.
1216 ///
1217 /// @param propValue The new binary value. Can be null if creating the property. Must be null
1218 /// for arrays and non-leaf levels of structs that do not have values.
1219 ///
1220 /// @param options Option flags describing the property; a logical OR of allowed bit-flag
1221 /// constants; see \c #kXMP_PropValueIsStruct and following. Must match the type of a property
1222 /// that already exists.
1223
1224 void SetProperty_Int64 ( XMP_StringPtr schemaNS,
1225 XMP_StringPtr propName,
1226 XMP_Int64 propValue,
1227 XMP_OptionBits options = 0 );
1228
1229 // ---------------------------------------------------------------------------------------------
1230 /// @brief \c SetProperty_Float() sets the value of a floating-point property using a C double float.
1231 ///
1232 /// Sets a property with a binary value, creating it if necessary.
1233 ///
1234 /// @param schemaNS The namespace URI; see \c GetProperty().
1235 ///
1236 /// @param propName The name of the property. Can be a general path expression, must not be null
1237 /// or the empty string; see \c GetProperty() for namespace prefix usage.
1238 ///
1239 /// @param propValue The new binary value. Can be null if creating the property. Must be null
1240 /// for arrays and non-leaf levels of structs that do not have values.
1241 ///
1242 /// @param options Option flags describing the property; a logical OR of allowed bit-flag
1243 /// constants; see \c #kXMP_PropValueIsStruct and following. Must match the type of a property
1244 /// that already exists.
1245
1246 void SetProperty_Float ( XMP_StringPtr schemaNS,
1247 XMP_StringPtr propName,
1248 double propValue,
1249 XMP_OptionBits options = 0 );
1250
1251 // ---------------------------------------------------------------------------------------------
1252 /// @brief \c SetProperty_Date() sets the value of a date/time property using an \c #XMP_DateTime structure.
1253 ///
1254 /// Sets a property with a binary value, creating it if necessary.
1255 ///
1256 /// @param schemaNS The namespace URI; see \c GetProperty().
1257 ///
1258 /// @param propName The name of the property. Can be a general path expression, must not be null
1259 /// or the empty string; see \c GetProperty() for namespace prefix usage.
1260 ///
1261 /// @param propValue The new binary value. Can be null if creating the property. Must be null
1262 /// for arrays and non-leaf levels of structs that do not have values.
1263 ///
1264 /// @param options Option flags describing the property; a logical OR of allowed bit-flag
1265 /// constants; see \c #kXMP_PropValueIsStruct and following. Must match the type of a property
1266 /// that already exists.
1267
1268 void SetProperty_Date ( XMP_StringPtr schemaNS,
1269 XMP_StringPtr propName,
1270 const XMP_DateTime & propValue,
1271 XMP_OptionBits options = 0 );
1272
1273 /// @}
1274 // =============================================================================================
1275 /// \name Accessing localized text (alt-text) properties.
1276 /// @{
1277 ///
1278 /// Localized text properties are stored in alt-text arrays. They allow multiple concurrent
1279 /// localizations of a property value, for example a document title or copyright in several
1280 /// languages.
1281 ///
1282 /// These functions provide convenient support for localized text properties, including a
1283 /// number of special and obscure aspects. The most important aspect of these functions is that
1284 /// they select an appropriate array item based on one or two RFC 3066 language tags. One of
1285 /// these languages, the "specific" language, is preferred and selected if there is an exact
1286 /// match. For many languages it is also possible to define a "generic" language that can be
1287 /// used if there is no specific language match. The generic language must be a valid RFC 3066
1288 /// primary subtag, or the empty string.
1289 ///
1290 /// For example, a specific language of "en-US" should be used in the US, and a specific
1291 /// language of "en-UK" should be used in England. It is also appropriate to use "en" as the
1292 /// generic language in each case. If a US document goes to England, the "en-US" title is
1293 /// selected by using the "en" generic language and the "en-UK" specific language.
1294 ///
1295 /// It is considered poor practice, but allowed, to pass a specific language that is just an
1296 /// RFC 3066 primary tag. For example "en" is not a good specific language, it should only be
1297 /// used as a generic language. Passing "i" or "x" as the generic language is also considered
1298 /// poor practice but allowed.
1299 ///
1300 /// Advice from the W3C about the use of RFC 3066 language tags can be found at:
1301 /// \li http://www.w3.org/International/articles/language-tags/
1302 ///
1303 /// \note RFC 3066 language tags must be treated in a case insensitive manner. The XMP toolkit
1304 /// does this by normalizing their capitalization:
1305 /// \li The primary subtag is lower case, the suggested practice of ISO 639.
1306 /// \li All 2 letter secondary subtags are upper case, the suggested practice of ISO 3166.
1307 /// \li All other subtags are lower case.
1308 ///
1309 /// The XMP specification defines an artificial language, "x-default", that is used to
1310 /// explicitly denote a default item in an alt-text array. The XMP toolkit normalizes alt-text
1311 /// arrays such that the x-default item is the first item. The \c SetLocalizedText() function
1312 /// has several special features related to the x-default item, see its description for details.
1313
1314 // ---------------------------------------------------------------------------------------------
1315 /// @brief \c GetLocalizedText() retrieves information about a selected item in an alt-text array.
1316 ///
1317 /// The array item is selected according to these rules:
1318 /// \li Look for an exact match with the specific language.
1319 /// \li If a generic language is given, look for a partial match.
1320 /// \li Look for an x-default item.
1321 /// \li Choose the first item.
1322 ///
1323 /// A partial match with the generic language is where the start of the item's language matches
1324 /// the generic string and the next character is '-'. An exact match is also recognized as a
1325 /// degenerate case.
1326 ///
1327 /// You can pass "x-default" as the specific language. In this case, selection of an
1328 /// \c x-default item is an exact match by the first rule, not a selection by the 3rd rule. The
1329 /// last 2 rules are fallbacks used when the specific and generic languages fail to produce a
1330 /// match.
1331 ///
1332 /// The return value reports whether a match was successfully made.
1333 ///
1334 /// @param schemaNS The namespace URI for the alt-text array; see \c GetProperty().
1335 ///
1336 /// @param altTextName The name of the alt-text array. Can be a general path expression, must
1337 /// not be null or the empty string; see \c GetProperty() for namespace prefix usage.
1338 ///
1339 /// @param genericLang The name of the generic language as an RFC 3066 primary subtag. Can be
1340 /// null or the empty string if no generic language is wanted.
1341 ///
1342 /// @param specificLang The name of the specific language as an RFC 3066 tag, or "x-default".
1343 /// Must not be null or the empty string.
1344 ///
1345 /// @param actualLang [out] A string object in which to return the language of the selected
1346 /// array item, if an appropriate array item is found. Can be null if the language is not wanted.
1347 ///
1348 /// @param itemValue [out] A string object in which to return the value of the array item, if an
1349 /// appropriate array item is found. Can be null if the value is not wanted.
1350 ///
1351 /// @param options A buffer in which to return the option flags that describe the array item, if
1352 /// an appropriate array item is found. Can be null if the flags are not wanted.
1353 ///
1354 /// @return True if an appropriate array item exists.
1355
1356 bool GetLocalizedText ( XMP_StringPtr schemaNS,
1357 XMP_StringPtr altTextName,
1358 XMP_StringPtr genericLang,
1359 XMP_StringPtr specificLang,
1360 tStringObj * actualLang,
1361 tStringObj * itemValue,
1362 XMP_OptionBits * options ) const;
1363
1364 // ---------------------------------------------------------------------------------------------
1365 /// @brief \c SetLocalizedText() modifies the value of a selected item in an alt-text array.
1366 ///
1367 /// Creates an appropriate array item if necessary, and handles special cases for the x-default
1368 /// item.
1369 ///
1370 /// The array item is selected according to these rules:
1371 /// \li Look for an exact match with the specific language.
1372 /// \li If a generic language is given, look for a partial match.
1373 /// \li Look for an x-default item.
1374 /// \li Choose the first item.
1375 ///
1376 /// A partial match with the generic language is where the start of the item's language matches
1377 /// the generic string and the next character is '-'. An exact match is also recognized as a
1378 /// degenerate case.
1379 ///
1380 /// You can pass "x-default" as the specific language. In this case, selection of an
1381 /// \c x-default item is an exact match by the first rule, not a selection by the 3rd rule. The
1382 /// last 2 rules are fallbacks used when the specific and generic languages fail to produce a
1383 /// match.
1384 ///
1385 /// Item values are modified according to these rules:
1386 ///
1387 /// \li If the selected item is from a match with the specific language, the value of that
1388 /// item is modified. If the existing value of that item matches the existing value of the
1389 /// x-default item, the x-default item is also modified. If the array only has 1 existing item
1390 /// (which is not x-default), an x-default item is added with the given value.
1391 ///
1392 /// \li If the selected item is from a match with the generic language and there are no other
1393 /// generic matches, the value of that item is modified. If the existing value of that item
1394 /// matches the existing value of the x-default item, the x-default item is also modified. If
1395 /// the array only has 1 existing item (which is not x-default), an x-default item is added
1396 /// with the given value.
1397 ///
1398 /// \li If the selected item is from a partial match with the generic language and there are
1399 /// other partial matches, a new item is created for the specific language. The x-default item
1400 /// is not modified.
1401 ///
1402 /// \li If the selected item is from the last 2 rules then a new item is created for the
1403 /// specific language. If the array only had an x-default item, the x-default item is also
1404 /// modified. If the array was empty, items are created for the specific language and
1405 /// x-default.
1406 ///
1407 /// @param schemaNS The namespace URI for the alt-text array; see \c GetProperty().
1408 ///
1409 /// @param altTextName The name of the alt-text array. Can be a general path expression, must
1410 /// not be null or the empty string; see \c GetProperty() for namespace prefix usage.
1411 ///
1412 /// @param genericLang The name of the generic language as an RFC 3066 primary subtag. Can be
1413 /// null or the empty string if no generic language is wanted.
1414 ///
1415 /// @param specificLang The name of the specific language as an RFC 3066 tag, or "x-default".
1416 /// Must not be null or the empty string.
1417 ///
1418 /// @param itemValue The new value for the matching array item, specified as a null-terminated
1419 /// UTF-8 string.
1420 ///
1421 /// @param options Option flags, none currently defined.
1422
1423 void SetLocalizedText ( XMP_StringPtr schemaNS,
1424 XMP_StringPtr altTextName,
1425 XMP_StringPtr genericLang,
1426 XMP_StringPtr specificLang,
1427 XMP_StringPtr itemValue,
1428 XMP_OptionBits options = 0 );
1429
1430 // ---------------------------------------------------------------------------------------------
1431 /// @brief \c SetLocalizedText() modifies the value of a selected item in an alt-text array using
1432 /// a string object.
1433 ///
1434 /// Creates an appropriate array item if necessary, and handles special cases for the x-default
1435 /// item.
1436 ///
1437 /// The array item is selected according to these rules:
1438 /// \li Look for an exact match with the specific language.
1439 /// \li If a generic language is given, look for a partial match.
1440 /// \li Look for an x-default item.
1441 /// \li Choose the first item.
1442 ///
1443 /// A partial match with the generic language is where the start of the item's language matches
1444 /// the generic string and the next character is '-'. An exact match is also recognized as a
1445 /// degenerate case.
1446 ///
1447 /// You can pass "x-default" as the specific language. In this case, selection of an \c x-default
1448 /// item is an exact match by the first rule, not a selection by the 3rd rule. The last 2 rules
1449 /// are fallbacks used when the specific and generic languages fail to produce a match.
1450 ///
1451 /// Item values are modified according to these rules:
1452 ///
1453 /// \li If the selected item is from a match with the specific language, the value of that
1454 /// item is modified. If the existing value of that item matches the existing value of the
1455 /// x-default item, the x-default item is also modified. If the array only has 1 existing item
1456 /// (which is not x-default), an x-default item is added with the given value.
1457 ///
1458 /// \li If the selected item is from a match with the generic language and there are no other
1459 /// generic matches, the value of that item is modified. If the existing value of that item
1460 /// matches the existing value of the x-default item, the x-default item is also modified. If
1461 /// the array only has 1 existing item (which is not x-default), an x-default item is added
1462 /// with the given value.
1463 ///
1464 /// \li If the selected item is from a partial match with the generic language and there are
1465 /// other partial matches, a new item is created for the specific language. The x-default item
1466 /// is not modified.
1467 ///
1468 /// \li If the selected item is from the last 2 rules then a new item is created for the
1469 /// specific language. If the array only had an x-default item, the x-default item is also
1470 /// modified. If the array was empty, items are created for the specific language and
1471 /// x-default.
1472 ///
1473 /// @param schemaNS The namespace URI for the alt-text array; see \c GetProperty().
1474 ///
1475 /// @param altTextName The name of the alt-text array. Can be a general path expression, must
1476 /// not be null or the empty string; see \c GetProperty() for namespace prefix usage.
1477 ///
1478 /// @param genericLang The name of the generic language as an RFC 3066 primary subtag. Can be
1479 /// null or the empty string if no generic language is wanted.
1480 ///
1481 /// @param specificLang The name of the specific language as an RFC 3066 tag, or "x-default".
1482 /// Must not be null or the empty string.
1483 ///
1484 /// @param itemValue The new value for the matching array item, specified as a string object.
1485 ///
1486 /// @param options Option flags, none currently defined.
1487
1488 void SetLocalizedText ( XMP_StringPtr schemaNS,
1489 XMP_StringPtr altTextName,
1490 XMP_StringPtr genericLang,
1491 XMP_StringPtr specificLang,
1492 const tStringObj & itemValue,
1493 XMP_OptionBits options = 0 );
1494
1495 // ---------------------------------------------------------------------------------------------
1496 /// @brief \c DeleteLocalizedText() deletes specific language alternatives from an alt-text array.
1497 ///
1498 /// The rules for finding the language value to delete are similar to those for \c #SetLocalizedText().
1499 ///
1500 /// @param schemaNS The namespace URI for the alt-text array; see \c #GetProperty().
1501 ///
1502 /// @param altTextName The name of the alt-text array. Can be a general path expression, must
1503 /// not be null or the empty string; see \c #GetProperty() for namespace prefix usage.
1504 ///
1505 /// @param genericLang The name of the generic language as an RFC 3066 primary subtag. Can be
1506 /// null or the empty string if no generic language is wanted.
1507 ///
1508 /// @param specificLang The name of the specific language as an RFC 3066 tag, or "x-default".
1509 /// Must not be null or the empty string.
1510 ///
1511 void
1512 DeleteLocalizedText ( XMP_StringPtr schemaNS,
1513 XMP_StringPtr altTextName,
1514 XMP_StringPtr genericLang,
1515 XMP_StringPtr specificLang );
1516
1517 /// @}
1518
1519 // =============================================================================================
1520 /// \name Creating and reading serialized RDF.
1521 /// @{
1522 ///
1523 /// The metadata contained in an XMP object must be serialized as RDF for storage in an XMP
1524 /// packet and output to a file. Similarly, metadata in the form of serialized RDF (such as
1525 /// metadata read from a file using \c TXMPFiles) must be parsed into an XMP object for
1526 /// manipulation with the XMP Toolkit.
1527 ///
1528 /// These functions support parsing serialized RDF into an XMP object, and serializing an XMP
1529 /// object into RDF. The input for parsing can be any valid Unicode encoding. ISO Latin-1 is
1530 /// also recognized, but its use is strongly discouraged. Serialization is always as UTF-8.
1531
1532 // ---------------------------------------------------------------------------------------------
1533 /// @brief \c ParseFromBuffer() parses RDF from a series of input buffers into this XMP object.
1534 ///
1535 /// Use this to convert metadata from serialized RDF form (as, for example, read from an XMP
1536 /// packet embedded in a file) into an XMP object that you can manipulate with the XMP Toolkit.
1537 /// If this XMP object is empty and the input buffer contains a complete XMP packet, this is the
1538 /// same as creating a new XMP object from that buffer with the constructor.
1539 ///
1540 /// You can use this function to combine multiple buffers into a single metadata tree. To
1541 /// terminate an input loop conveniently, pass the option \c #kXMP_ParseMoreBuffers for all
1542 /// real input, then make a final call with a zero length and \c #kXMP_NoOptions. The buffers
1543 /// can be any length. The buffer boundaries need not respect XML tokens or even Unicode
1544 /// characters.
1545 ///
1546 /// @param buffer A pointer to a buffer of input. Can be null if \c bufferSize is 0.
1547 ///
1548 /// @param bufferSize The length of the input buffer in bytes. Zero is a valid value.
1549 ///
1550 /// @param options An options flag that controls how the parse operation is performed. A logical
1551 /// OR of these bit-flag constants:
1552 /// \li \c #kXMP_ParseMoreBuffers - This is not the last buffer of input, more calls follow.
1553 /// \li \c #kXMP_RequireXMPMeta - The \c x:xmpmeta XML element is required around \c rdf:RDF.
1554 ///
1555 /// @see \c TXMPFiles::GetXMP()
1556
1557 void ParseFromBuffer ( XMP_StringPtr buffer,
1558 XMP_StringLen bufferSize,
1559 XMP_OptionBits options = 0 );
1560
1561 // ---------------------------------------------------------------------------------------------
1562 /// @brief \c SerializeToBuffer() serializes metadata in this XMP object into a string as RDF.
1563 ///
1564 /// Use this to prepare metadata for storage as an XMP packet embedded in a file. See \c TXMPFiles::PutXMP().
1565 ///
1566 /// @param rdfString [out] A string object in which to return the serialized RDF. Must not be null.
1567 ///
1568 /// @param options An options flag that controls how the serialization operation is performed.
1569 /// The specified options must be logically consistent; an exception is thrown if they are not.
1570 /// A logical OR of these bit-flag constants:
1571 /// \li \c kXMP_OmitPacketWrapper - Do not include an XML packet wrapper. This cannot be
1572 /// specified together with \c #kXMP_ReadOnlyPacket, \c #kXMP_IncludeThumbnailPad, or
1573 /// \c #kXMP_ExactPacketLength.
1574 /// \li \c kXMP_ReadOnlyPacket - Create a read-only XML packet wapper. Cannot be specified
1575 /// together with \c kXMP_OmitPacketWrapper.
1576 /// \li \c kXMP_UseCompactFormat - Use a highly compact RDF syntax and layout.
1577 /// \li \c kXMP_IncludeThumbnailPad - Include typical space for a JPEG thumbnail in the
1578 /// padding if no \c xmp:Thumbnails property is present. Cannot be specified together with
1579 /// \c kXMP_OmitPacketWrapper.
1580 /// \li \c kXMP_ExactPacketLength - The padding parameter provides the overall packet length.
1581 /// The actual amount of padding is computed. An exception is thrown if the packet exceeds
1582 /// this length with no padding. Cannot be specified together with
1583 /// \c kXMP_OmitPacketWrapper.
1584 ///
1585 /// In addition to the above options, you can include one of the following encoding options:
1586 /// \li \c #kXMP_EncodeUTF8 - Encode as UTF-8, the default.
1587 /// \li \c #kXMP_EncodeUTF16Big - Encode as big-endian UTF-16.
1588 /// \li \c #kXMP_EncodeUTF16Little - Encode as little-endian UTF-16.
1589 /// \li \c #kXMP_EncodeUTF32Big - Encode as big-endian UTF-32.
1590 /// \li \c #kXMP_EncodeUTF32Little - Encode as little-endian UTF-32.
1591 ///
1592 /// @param padding The amount of padding to be added if a writeable XML packet is created. If
1593 /// zero (the default) an appropriate amount of padding is computed.
1594 ///
1595 /// @param newline The string to be used as a line terminator. If empty, defaults to linefeed,
1596 /// U+000A, the standard XML newline.
1597 ///
1598 /// @param indent The string to be used for each level of indentation in the serialized RDF. If
1599 /// empty, defaults to two ASCII spaces, U+0020.
1600 ///
1601 /// @param baseIndent The number of levels of indentation to be used for the outermost XML
1602 /// element in the serialized RDF. This is convenient when embedding the RDF in other text.
1603
1604 void SerializeToBuffer ( tStringObj * rdfString,
1605 XMP_OptionBits options,
1606 XMP_StringLen padding,
1607 XMP_StringPtr newline,
1608 XMP_StringPtr indent = "",
1609 XMP_Index baseIndent = 0 ) const;
1610
1611 // ---------------------------------------------------------------------------------------------
1612 /// @brief \c SerializeToBuffer() serializes metadata in this XMP object into a string as RDF.
1613 ///
1614 /// This simpler form of the function uses default values for the \c newline, \c indent, and
1615 /// \c baseIndent parameters.
1616 ///
1617 /// @param rdfString [out] A string object in which to return the serialized RDF. Must not be null.
1618 ///
1619 /// @param options An options flag that controls how the serialization operation is performed.
1620 /// The specified options must be logically consistent; an exception is thrown if they are not.
1621 /// A logical OR of these bit-flag constants:
1622 /// \li \c kXMP_OmitPacketWrapper - Do not include an XML packet wrapper. This cannot be
1623 /// specified together with \c #kXMP_ReadOnlyPacket, \c #kXMP_IncludeThumbnailPad, or
1624 /// \c #kXMP_ExactPacketLength.
1625 /// \li \c kXMP_ReadOnlyPacket - Create a read-only XML packet wapper. Cannot be specified
1626 /// together with \c kXMP_OmitPacketWrapper.
1627 /// \li \c kXMP_UseCompactFormat - Use a highly compact RDF syntax and layout.
1628 /// \li \c kXMP_IncludeThumbnailPad - Include typical space for a JPEG thumbnail in the
1629 /// padding if no \c xmp:Thumbnails property is present. Cannot be specified together with
1630 /// \c kXMP_OmitPacketWrapper.
1631 /// \li \c kXMP_ExactPacketLength - The padding parameter provides the overall packet length.
1632 /// The actual amount of padding is computed. An exception is thrown if the packet exceeds
1633 /// this length with no padding. Cannot be specified together with
1634 /// \c kXMP_OmitPacketWrapper.
1635 ///
1636 /// In addition to the above options, you can include one of the following encoding options:
1637 /// \li \c #kXMP_EncodeUTF8 - Encode as UTF-8, the default.
1638 /// \li \c #kXMP_EncodeUTF16Big - Encode as big-endian UTF-16.
1639 /// \li \c #kXMP_EncodeUTF16Little - Encode as little-endian UTF-16.
1640 /// \li \c #kXMP_EncodeUTF32Big - Encode as big-endian UTF-32.
1641 /// \li \c #kXMP_EncodeUTF32Little - Encode as little-endian UTF-32.
1642 ///
1643 /// @param padding The amount of padding to be added if a writeable XML packet is created.
1644 /// If zero (the default) an appropriate amount of padding is computed.
1645
1646 void SerializeToBuffer ( tStringObj * rdfString,
1647 XMP_OptionBits options = 0,
1648 XMP_StringLen padding = 0 ) const;
1649
1650 #if AdobePrivate
1651 void
1652 SerializeToBuffer ( tStringObj * rdfString, // Obsolete form, padding is poorly placed.
1653 XMP_OptionBits options,
1654 XMP_StringPtr newline,
1655 XMP_StringPtr indent,
1656 XMP_Index baseIndent,
1657 XMP_StringLen padding ) const;
1658
1659 #if ENABLE_CPP_DOM_MODEL
1660 // ---------------------------------------------------------------------------------------------
1661 /// @brief \c GetIMetadata() returns the shared pointer of the IXMPMetadata object present inside the XMPMeta object
1662 ///in case the client has chosen to set the Use_CPP_DOM_APIs flag as true
1663 ///if Use_CPP_DOM_APIs is passed false, null is returned with an error message "Not Available"
1664 AdobeXMPCore::spIMetadata GetIMetadata();
1665 #endif
1666 #endif
1667
1668 /// @}
1669 // =============================================================================================
1670 // Miscellaneous Member Functions
1671 // ==============================
1672
1673 // ---------------------------------------------------------------------------------------------
1674 /// \name Helper functions.
1675 /// @{
1676
1677 // ---------------------------------------------------------------------------------------------
1678 /// @brief Retrieves an internal reference that can be safely passed across DLL boundaries and
1679 /// reconstructed.
1680 ///
1681 /// The \c TXMPMeta class is a normal C++ template, it is instantiated and local to each client
1682 /// executable, as are the other \c TXMP* classes. Different clients might not use the same
1683 /// string type to instantiate \c TXMPMeta.
1684 ///
1685 /// Because of this you should not pass \c SXMPMeta objects, or pointers to \c SXMPMeta objects,
1686 /// across DLL boundaries. Use this function to obtain a safe internal reference that you can
1687 /// pass, then construct a local object on the callee side. This construction does not create a
1688 /// cloned XMP tree, it is the same underlying XMP object safely wrapped in each client's
1689 /// \c SXMPMeta object.
1690 ///
1691 /// Use this function and the associated constructor like this:
1692 /// \li The callee's header contains:
1693 /// <pre>
1694 /// CalleeMethod ( XMPMetaRef xmpRef );
1695 /// </pre>
1696 ///
1697 /// \li The caller's code contains:
1698 /// <pre>
1699 /// SXMPMeta callerXMP;
1700 /// CalleeMethod ( callerXMP.GetInternalRef() );
1701 /// </pre>
1702 ///
1703 /// \li The callee's code contains:
1704 /// <pre>
1705 /// SXMPMeta calleeXMP ( xmpRef );
1706 /// </pre>
1707 ///
1708 /// @return The reference object.
1709
1710 XMPMetaRef GetInternalRef() const;
1711
1712 // ---------------------------------------------------------------------------------------------
1713 /// @brief \c GetObjectName() retrieves the client-assigned name of this XMP object.
1714 ///
1715 /// Assign this name with \c SetObjectName().
1716 ///
1717 /// @param name [out] A string object in which to return the name.
1718
1719 void GetObjectName ( tStringObj * name ) const;
1720
1721 // ---------------------------------------------------------------------------------------------
1722 /// @brief \c SetObjectName() assigns a name to this XMP object.
1723 ///
1724 /// Retrieve this client-assigned name with \c GetObjectName().
1725 ///
1726 /// @param name The name as a null-terminated UTF-8 string.
1727
1728 void SetObjectName ( XMP_StringPtr name );
1729
1730 // ---------------------------------------------------------------------------------------------
1731 /// @brief \c SetObjectName() assigns a name to this XMP object.
1732 ///
1733 /// Retrieve this client-assigned name with \c GetObjectName().
1734 ///
1735 /// @param name The name as a string object.
1736
1737 void SetObjectName ( tStringObj name );
1738
1739 // ---------------------------------------------------------------------------------------------
1740 /// @brief \c Sort() sorts the data model tree of an XMP object.
1741 ///
1742 /// Use this function to sort the data model of an XMP object into a canonical order. This can
1743 /// be convenient when comparing data models, (e.g. by text comparison of DumpObject output).
1744 ///
1745 /// At the top level the namespaces are sorted by their prefixes. Within a namespace, the top
1746 /// level properties are sorted by name. Within a struct, the fields are sorted by their
1747 /// qualified name, i.e. their XML prefix:local form. Unordered arrays of simple items are
1748 /// sorted by value. Language Alternative arrays are sorted by the xml:lang qualifiers, with
1749 /// the "x-default" item placed first.
1750
1751 void Sort();
1752
1753 // ---------------------------------------------------------------------------------------------
1754 /// @brief \c Erase() restores the object to a "just constructed" state.
1755
1756 void Erase();
1757
1758 // ---------------------------------------------------------------------------------------------
1759 /// @brief \c Clone() creates a deep copy of an XMP object.
1760 ///
1761 /// Use this function to copy an entire XMP metadata tree. Assignment and copy constructors only
1762 /// increment a reference count, they do not do a deep copy. This function returns an object,
1763 /// not a pointer. The following shows correct usage:
1764 ///
1765 /// <pre>
1766 /// SXMPMeta * clone1 = new SXMPMeta ( sourceXMP.Clone() ); // This works.
1767 /// SXMPMeta clone2 ( sourceXMP.Clone ); // This works also. (Not a pointer.)
1768 /// </pre>
1769 /// The \c clone2 example does not use an explicit pointer.
1770 /// This is good for local usage, protecting against memory leaks.
1771 ///
1772 /// This is an example of incorrect usage:
1773 /// <pre>
1774 /// SXMPMeta * clone3 = &sourceXMP.Clone(); // ! This does not work!
1775 /// </pre>
1776 /// The assignment to \c clone3 creates a temporary object, initializes it with the clone,
1777 /// assigns the address of the temporary to \c clone3, then deletes the temporary.
1778 ///
1779 /// @param options Option flags, not currently defined..
1780 ///
1781 /// @return An XMP object cloned from the original.
1782
1783 TXMPMeta Clone ( XMP_OptionBits options = 0 ) const;
1784
1785 // ---------------------------------------------------------------------------------------------
1786 /// @brief \c CountArrayItems() reports the number of items currently defined in an array.
1787 ///
1788 /// @param schemaNS The namespace URI; see \c GetProperty().
1789 ///
1790 /// @param arrayName The name of the array. Can be a general path expression, must not be null
1791 /// or the empty string; see \c GetProperty() for namespace prefix usage.
1792 ///
1793 /// @return The number of items.
1794
1795 XMP_Index CountArrayItems ( XMP_StringPtr schemaNS,
1796 XMP_StringPtr arrayName ) const;
1797
1798 // ---------------------------------------------------------------------------------------------
1799 /// @brief \c DumpObject() outputs the content of an XMP object to a callback handler for debugging.
1800 ///
1801 /// Invokes a client-defined callback for each line of output.
1802 ///
1803 /// @param outProc The client-defined procedure to handle each line of output.
1804 ///
1805 /// @param clientData A pointer to client-defined data to pass to the handler.
1806 ///
1807 /// @return A success-fail status value, returned from the handler. Zero is success, failure
1808 /// values are client-defined.
1809 ///
1810 /// @see Static function \c DumpNamespaces()
1811
1812 XMP_Status DumpObject ( XMP_TextOutputProc outProc,
1813 void * clientData ) const;
1814
1815 // ---------------------------------------------------------------------------------------------
1816 /// @brief Not implemented
1817 XMP_OptionBits GetObjectOptions() const;
1818
1819 // ---------------------------------------------------------------------------------------------
1820 /// \brief Not implemented
1821 void SetObjectOptions ( XMP_OptionBits options );
1822
1823 #if AdobePrivate
1824 // ---------------------------------------------------------------------------------------------
1825 /// \deprecated <b>Not implemented</b>
1826 /// @brief Not implemented
1827 void MarkStaleProperties ( XMP_OptionBits options = 0 ) __AVAILABILITY_INTERNAL_DEPRECATED_XMP;
1828 #endif
1829
1830 /// @}
1831
1832 // =============================================================================================
1833 // Error notifications
1834 // ===================
1835
1836 // ---------------------------------------------------------------------------------------------
1837 /// \name Error notifications
1838 /// @{
1839 ///
1840 /// From the beginning through version 5.5, XMP Tookit errors result in throwing an \c XMP_Error
1841 /// exception. For the most part exceptions were thrown early and thus API calls aborted as soon
1842 /// as an error was detected. Starting in version 5.5, support has been added for notifications
1843 /// of errors arising in calls to \c TXMPMeta functions.
1844 ///
1845 /// A client can register an error notification callback function for a \c TXMPMeta object. This
1846 /// can be done as a global default or individually to each object. The global default applies
1847 /// to all objects created after it is registered. Within the object there is no difference
1848 /// between the global default or explicitly registered callback. The callback function returns
1849 /// a \c bool value indicating if recovery should be attempted (true) or an exception thrown
1850 /// (false). If no callback is registered, a best effort at recovery and continuation will be
1851 /// made with an exception thrown if recovery is not possible.
1852 ///
1853 /// The number of notifications delivered for a given TXMPMeta object can be limited. This is
1854 /// intended to reduce chatter from multiple or cascading errors. The limit is set when the
1855 /// callback function is registered. This limits the number of notifications of the highest
1856 /// severity delivered or less. If a higher severity error occurs, the counting starts again.
1857 /// The limit and counting can be reset at any time, see \c ResetErrorCallbackLimit.
1858
1859 // --------------------------------------------------------------------------------------------
1860 /// @brief SetDefaultErrorCallback() registers a global default error notification callback.
1861 ///
1862 /// @param proc The client's callback function.
1863 ///
1864 /// @param context Client-provided context for the callback.
1865 ///
1866 /// @param limit A limit on the number of notifications to be delivered.
1867
1868 static void SetDefaultErrorCallback ( XMPMeta_ErrorCallbackProc proc, void* context = 0, XMP_Uns32 limit = 1 );
1869
1870 // --------------------------------------------------------------------------------------------
1871 /// @brief SetErrorCallback() registers an error notification callback.
1872 ///
1873 /// @param proc The client's callback function.
1874 ///
1875 /// @param context Client-provided context for the callback.
1876 ///
1877 /// @param limit A limit on the number of notifications to be delivered.
1878
1879 void SetErrorCallback ( XMPMeta_ErrorCallbackProc proc, void* context = 0, XMP_Uns32 limit = 1 );
1880
1881 // --------------------------------------------------------------------------------------------
1882 /// @brief ResetErrorCallbackLimit() resets the error notification limit and counting. It has no
1883 /// effect if an error notification callback function is not registered.
1884 ///
1885 /// @param limit A limit on the number of notifications to be delivered.
1886
1887 void ResetErrorCallbackLimit ( XMP_Uns32 limit = 1 );
1888
1889 /// @}
1890
1891 // =============================================================================================
1892
1893 XMPMetaRef xmpRef; // *** Should be private, see below.
1894
1895 private:
1896
1897 #if 0 // *** VS.Net and gcc seem to not handle the friend declarations properly.
1898 friend class TXMPIterator <class tStringObj>;
1899 friend class TXMPUtils <class tStringObj>;
1900 #endif
1901
1902 static void SetClientString ( void * clientPtr, XMP_StringPtr valuePtr, XMP_StringLen valueLen );
1903
1904 }; // class TXMPMeta
1905
1906 #endif // __TXMPMeta_hpp__