Debian Codegraph @

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

raw
1 #ifndef __TXMPUtils_hpp__
2 #define __TXMPUtils_hpp__ 1
3
4 #if ( ! __XMP_hpp__ )
5 #error "Do not directly include, use XMP.hpp"
6 #endif
7
8 // =================================================================================================
9 // Copyright Adobe
10 // Copyright 2002 Adobe
11 // All Rights Reserved
12 //
13 // NOTICE: Adobe permits you to use, modify, and distribute this file in accordance with the terms
14 // of the Adobe license agreement accompanying it. If you have received this file from a source other
15 // than Adobe, then your use, modification, or distribution of it requires the prior written permission
16 // of Adobe.
17 // =================================================================================================
18
19 #if AdobePrivate
20 // =================================================================================================
21 // Change history
22 // ==============
23 //
24 // Writers:
25 // AWL Alan Lillich
26 //
27 // mm-dd-yy who Description of changes, most recent on top
28 //
29 // 03-16-15 AJ 5.6-c047 Completing Rework of Get/SetBulkMarkers()
30 // 12-03-15 AJ 5.6-c045 Reworking glue code for Get/SetBulkMarkers()
31 // 03-02-15 AJ 5.6-c039 Marker Extensibility - Backward compatibility for extensions in GetBulkMarkers() and SetBulkMarkers()
32 // 07-21-09 AWL 5.0-c047 Add XMPUtils::ApplyTemplate.
33 // 05-21-09 AWL 5.0-c032 Revamp glue again to pass SetClientString with each function.
34 //
35 // 10-13-08 AWL 4.4-c009 Add support for zone-less times. Get rid of old XMPUtils forms of DocOps.
36 //
37 // 04-29-08 AWL 4.2.2-c052 [1768777,1768782] Add private performance enhancements for temporal metadata.
38 //
39 // 08-02-07 AWL 4.2 Incorporate major revamp to doxygen comments.
40 //
41 // 01-02-07 AWL 4.2-c004 [1449038] Add option to XMPUtils::AppendProperties to delete things with
42 // empty values. Used in FileInfo templates to delete sensitive info.
43 //
44 // 05-16-06 AWL 4.0-c006 Add SXMPUtils::PackageForJPEG and SXMPUtils::MergeFromJPEG.
45 // 04-17-06 AWL Add documentation for AppendProperties.
46 // 03-24-06 AWL 4.0 Adapt for move to ham-perforce, integrate XMPFiles, bump version to 4.
47 //
48 // 02-21-06 AWL 3.3-015 Expose some of the "File Info" utils. The Adobe Labs build of XMPFiles needs
49 // SXMPUtils::RemoveProperties and SXMPUtils::AppendProperties.
50 // 07-15-05 AWL 3.3-001 [1214033] Bump version to 3.3, the SDK is out. Put back missing multi-file utils.
51 //
52 // 05-16-05 AWL 3.2-100 Complete the deBIBification, integrate the internal and SDK source.
53 // 04-19-05 AWL Improve Doxygen comments for SDK.
54 // 04-11-05 AWL 3.2-016 Add AdobePrivate conditionals where appropriate.
55 // 01-28-05 AWL 3.2-001 Remove BIB.
56 //
57 // 11-08-04 AWL 3.1.1-095 [0663706] Allow null or empty MIME string in SetMIMEMapping - deletes mapping.
58 // 11-04-04 AWL 3.1.1-090 [1014853] Add XMPUtils::RemoveMultiValueInfo.
59 //
60 // 08-18-04 AWL 3.1-075 Add HasContainedDoc.
61 //
62 // 06-08-04 AWL Add CanUpdateMainPacket and overloads for GetMainPacket and UpdateMainPacket.
63 // 03-29-04 AWL Add Q&D versions of GetMainPacket and UpdateMainPacket.
64 // 02-17-04 AWL Add multi-file utilities. Rename CreateXyzDocument to InitializeXyzDocument.
65 // 02-09-04 AWL Start adding the new Document Operation utilities.
66 // 01-30-04 AWL Add overloads for set-like functions to take a tStringObj value.
67 // 01-17-04 AWL Move into new Perforce depot, cosmetic cleanup.
68 // 03-03-03 AWL Add Doxygen comments.
69 // 10-29-02 AWL Started first draft.
70 //
71 // =================================================================================================
72 #endif // AdobePrivate
73
74 // =================================================================================================
75 /// \file TXMPUtils.hpp
76 /// \brief API for access to the XMP Toolkit utility services.
77 ///
78 /// \c TXMPUtils is the template class providing utility services for the XMP Toolkit. It must be
79 /// instantiated with a string class such as \c std::string. See the instructions in XMP.hpp, and
80 /// the Overview for a discussion of the overall architecture of the XMP API.
81 // =================================================================================================
82
83 // =================================================================================================
84 /// \class TXMPUtils TXMPUtils.hpp
85 /// @brief API for access to the XMP Toolkit utility services.
86 ///
87 /// \c TXMPUtils is a template class which must be instantiated with a string class such as
88 /// \c std::string. See the instructions in XMP.hpp, and the Overview for a discussion of the overall
89 /// architecture of the XMP API.
90 ///
91 /// This class defines helper functions that support the basic metadata manipulation provided by
92 /// \c TXMPMeta. All of the functions are static; that is, you call them directly from the concrete
93 /// class (\c SXMPUtils), which is never itself instantiated.
94 ///
95 /// General categories of utilities include:
96 ///
97 /// \li Composing complex path expressions, which you can then pass to the property access
98 /// functions in \c TXMPMeta
99 /// \li Converting between binary and string forms of property values
100 /// \li Manipulating date/time values
101 /// \li Encoding and decoding base-64 strings
102 /// \li JPEG file handling
103 /// \li Editing aids for creating a user interface for the XMP Toolkit
104 // =================================================================================================
105
106 template <class tStringObj> class TXMPUtils {
107
108 public:
109
110 // =============================================================================================
111 // No constructors or destructor declared or needed
112 // ================================================
113
114 // ============================================================================================
115 /// \name Path composition
116 /// @{
117 ///
118 /// These functions provide support for composing path expressions to deeply nested properties.
119 /// The functions in \c TXMPMeta such as \c TXMPMeta::GetProperty(),
120 /// \c TXMPMeta::GetArrayItem(), and \c TXMPMeta::GetStructField() provide easy access to top level
121 /// simple properties, items in top level arrays, and fields of top level structs. They are
122 /// not as convenient for more complex things, such as fields several levels deep in a complex
123 /// struct, or fields within an array of structs, or items of an array that is a field of a
124 /// struct. You can use these utility functions to compose these paths, which you can then pass
125 /// to the property access functions. You can also compose paths to top-level array items or
126 /// struct fields so that you can use the binary accessors such as
127 /// \c TXMPMeta::GetProperty_Int().
128 ///
129 /// You can use these functions is to compose a complete path expression, or all but the last
130 /// component. For example, suppose you have a property that is an array of integers within a
131 /// struct. You can access one of the array items like this:
132 ///
133 /// <pre>
134 /// SXMPUtils::ComposeStructFieldPath ( schemaNS, "Struct", fieldNS, "Array", &path );
135 /// SXMPUtils::ComposeArrayItemPath ( schemaNS, path, index, &path );
136 /// exists = xmpObj.GetProperty_Int ( schemaNS, path, &value, &options );
137 /// </pre>
138 ///
139 /// You could also use this code if you want the string form of the integer:
140 ///
141 /// <pre>
142 /// SXMPUtils::ComposeStructFieldPath ( schemaNS, "Struct", fieldNS, "Array", &path );
143 /// xmpObj.GetArrayItem ( schemaNS, path, index, &value, &options );
144 /// </pre>
145 ///
146 /// \note It might look confusing that the \c schemaNS is passed in all of the calls above. This
147 /// is because the XMP Toolkit keeps the top-level "schema" namespace separate from the rest of
148 /// the path expression.
149
150 // ---------------------------------------------------------------------------------------------
151 /// @brief \c ComposeArrayItemPath() composes the path expression for an item in an array.
152 ///
153 /// The returned string is in the form <tt>ns:arrayName[i]</tt>, where "ns" is the prefix for
154 /// the specified namespace, and "i" is the decimal representation of specified item index.
155 /// If the last item was specified, the path is <tt>ns:arrayName[last()]</tt>.
156 ///
157 /// @param schemaNS The namespace URI for the array; see \c GetProperty().
158 ///
159 /// @param arrayName The name of the array. Can be a general path expression, must not be null
160 /// or the empty string; see \c GetProperty() for namespace prefix usage.
161 ///
162 /// @param itemIndex The 1-based index of the desired item. Use the macro
163 /// \c #kXMP_ArrayLastItem to specify the last existing array item.
164 ///
165 /// @param fullPath [out] A string in which to return the composed path.
166
167 static void ComposeArrayItemPath ( XMP_StringPtr schemaNS,
168 XMP_StringPtr arrayName,
169 XMP_Index itemIndex,
170 tStringObj * fullPath );
171
172 // ---------------------------------------------------------------------------------------------
173 /// @brief \c ComposeStructFieldPath() composes the path expression for a field in a struct.
174 ///
175 /// The returned string is in the form <tt>ns:structName/fNS:fieldName</tt>, where "ns" is the
176 /// prefix for the schema namespace, and "fNS" is the prefix for field namespace.
177 ///
178 /// @param schemaNS The namespace URI for the struct; see \c GetProperty().
179 ///
180 /// @param structName The name of the struct. Can be a general path expression, must not be null
181 /// or the empty string; see \c GetProperty() for namespace prefix usage.
182 ///
183 /// @param fieldNS The namespace URI for the field. Same URI and prefix usage as the
184 /// \c schemaNS and \c structName parameters.
185 ///
186 /// @param fieldName The name of the field. Must be a single XML name, must not be null or the
187 /// empty string. Same URI and prefix usage as the \c schemaNS and \c structName parameters.
188 ///
189 /// @param fullPath [out] A string in which to return the composed path.
190
191 static void ComposeStructFieldPath ( XMP_StringPtr schemaNS,
192 XMP_StringPtr structName,
193 XMP_StringPtr fieldNS,
194 XMP_StringPtr fieldName,
195 tStringObj * fullPath );
196
197 // ---------------------------------------------------------------------------------------------
198 /// @brief \c ComposeQualifierPath() composes the path expression for a qualifier.
199 ///
200 /// The returned string is in the form <tt>ns:propName/?qNS:qualName</tt>, where "ns" is the
201 /// prefix for the schema namespace, and "qNS" is the prefix for the qualifier namespace.
202 ///
203 /// @param schemaNS The namespace URI; see \c GetProperty().
204 ///
205 /// @param propName The name of the property to which the qualifier is attached. Can be a
206 /// general path expression, must not be null or the empty string; see \c GetProperty() for
207 /// namespace prefix usage.
208 ///
209 /// @param qualNS The namespace URI for the qualifier. Same URI and prefix usage as the
210 /// \c schemaNS and \c propName parameters.
211 ///
212 /// @param qualName The name of the qualifier. Must be a single XML name, must not be null or the
213 /// empty string. Same URI and prefix usage as the \c schemaNS and \c propName parameters.
214 ///
215 /// @param fullPath [out] A string in which to return the composed path.
216
217 static void ComposeQualifierPath ( XMP_StringPtr schemaNS,
218 XMP_StringPtr propName,
219 XMP_StringPtr qualNS,
220 XMP_StringPtr qualName,
221 tStringObj * fullPath );
222
223 // ---------------------------------------------------------------------------------------------
224 /// @brief \c ComposeLangSelector() composes the path expression to select an alternate item by language.
225 ///
226 /// Path syntax allows two forms of "content addressing" to select an item in an array of
227 /// alternatives. The form used in this function lets you select an item in an alt-text array
228 /// based on the value of its \c xml:lang qualifier. The other form of content addressing is
229 /// shown in \c ComposeFieldSelector().
230 ///
231 /// The returned string is in the form <tt>ns:arrayName[\@xml:lang='langName']</tt>, where
232 /// "ns" is the prefix for the schema namespace
233 ///
234 /// This function provides a path expression that is explicitly and only for a specific
235 /// language. In most cases, \c TXMPMeta::SetLocalizedText() and \c TXMPMeta::GetLocalizedText()
236 /// are preferred, because they provide extra logic to choose the appropriate language and
237 /// maintain consistency with the 'x-default' value.
238 ///
239 /// @param schemaNS The namespace URI for the array; see \c GetProperty().
240 ///
241 /// @param arrayName The name of the array. Can be a general path expression, must not be null
242 /// or the empty string; see \c GetProperty() for namespace prefix usage.
243 ///
244 /// @param langName The RFC 3066 code for the desired language, as a null-terminated UTF-8 string.
245 ///
246 /// @param fullPath [out] A string in which to return the composed path.
247
248 static void ComposeLangSelector ( XMP_StringPtr schemaNS,
249 XMP_StringPtr arrayName,
250 XMP_StringPtr langName,
251 tStringObj * fullPath );
252
253 // ---------------------------------------------------------------------------------------------
254 /// @brief \c ComposeLangSelector() composes a path expression to select an alternate item by language.
255 ///
256 /// Path syntax allows two forms of "content addressing" to select an item in an array of
257 /// alternatives. The form used in this function lets you select an item in an alt-text array
258 /// based on the value of its \c xml:lang qualifier. The other form of content addressing is
259 /// shown in \c ComposeFieldSelector().
260 ///
261 /// The returned string is in the form <tt>ns:arrayName[\@xml:lang='langName']</tt>, where
262 /// "ns" is the prefix for the schema namespace
263 ///
264 /// This function provides a path expression that is explicitly and only for a specific
265 /// language. In most cases, \c TXMPMeta::SetLocalizedText() and \c TXMPMeta::GetLocalizedText()
266 /// are preferred, because they provide extra logic to choose the appropriate language and
267 /// maintain consistency with the 'x-default' value.
268 ///
269 /// @param schemaNS The namespace URI for the array; see \c GetProperty().
270 ///
271 /// @param arrayName The name of the array. Can be a general path expression, must not be null
272 /// or the empty string; see \c GetProperty() for namespace prefix usage.
273 ///
274 /// @param langName The RFC 3066 code for the desired language, as a string object.
275 ///
276 /// @param fullPath [out] A string in which to return the composed path.
277
278 static void ComposeLangSelector ( XMP_StringPtr schemaNS,
279 XMP_StringPtr arrayName,
280 const tStringObj & langName,
281 tStringObj * fullPath );
282
283 // ---------------------------------------------------------------------------------------------
284 /// @brief \c ComposeFieldSelector() composes a path expression to select an alternate item by a field's value.
285 ///
286 /// Path syntax allows two forms of "content addressing" to select an item in an array of
287 /// alternatives. The form used in this function lets you select an item in an array of structs
288 /// based on the value of one of the fields in the structs. The other form of content addressing
289 /// is shown in \c ComposeLangSelector().
290 ///
291 /// For example, consider a simple struct that has two fields, the name of a city and the URI of
292 /// an FTP site in that city. Use this to create an array of download alternatives. You can show
293 /// the user a popup built from the values of the city fields, then get the corresponding URI as
294 /// follows:
295 /// <pre>
296 /// ComposeFieldSelector ( schemaNS, "Downloads", fieldNS, "City", chosenCity, &path );
297 /// exists = GetStructField ( schemaNS, path, fieldNS, "URI", &uri );
298 /// </pre>
299 ///
300 /// The returned string is in the form <tt>ns:arrayName[fNS:fieldName='fieldValue']</tt>, where
301 /// "ns" is the prefix for the schema namespace and "fNS" is the prefix for the field namespace.
302 ///
303 /// @param schemaNS The namespace URI for the array; see \c GetProperty().
304 ///
305 /// @param arrayName The name of the array. Can be a general path expression, must not be null
306 /// or the empty string; see \c GetProperty() for namespace prefix usage.
307 ///
308 /// @param fieldNS The namespace URI for the field used as the selector. Same URI and prefix
309 /// usage as the \c schemaNS and \c arrayName parameters.
310 ///
311 /// @param fieldName The name of the field used as the selector. Must be a single XML name, must
312 /// not be null or the empty string. It must be the name of a field that is itself simple.
313 ///
314 /// @param fieldValue The desired value of the field, specified as a null-terminated UTF-8 string.
315 ///
316 /// @param fullPath [out] A string in which to return the composed path.
317
318 static void ComposeFieldSelector ( XMP_StringPtr schemaNS,
319 XMP_StringPtr arrayName,
320 XMP_StringPtr fieldNS,
321 XMP_StringPtr fieldName,
322 XMP_StringPtr fieldValue,
323 tStringObj * fullPath );
324
325 // ---------------------------------------------------------------------------------------------
326 /// @brief \c ComposeFieldSelector() composes a path expression to select an alternate item by a field's value.
327 ///
328 /// Path syntax allows two forms of "content addressing" to select an item in an array of
329 /// alternatives. The form used in this function lets you select an item in an array of structs
330 /// based on the value of one of the fields in the structs. The other form of content addressing
331 /// is shown in \c ComposeLangSelector().
332 ///
333 /// For example, consider a simple struct that has two fields, the name of a city and the URI of
334 /// an FTP site in that city. Use this to create an array of download alternatives. You can show
335 /// the user a popup built from the values of the city fields, then get the corresponding URI as
336 /// follows:
337 /// <pre>
338 /// ComposeFieldSelector ( schemaNS, "Downloads", fieldNS, "City", chosenCity, &path );
339 /// exists = GetStructField ( schemaNS, path, fieldNS, "URI", &uri );
340 /// </pre>
341 ///
342 /// The returned string is in the form <tt>ns:arrayName[fNS:fieldName='fieldValue']</tt>, where
343 /// "ns" is the prefix for the schema namespace and "fNS" is the prefix for the field namespace.
344 ///
345 /// @param schemaNS The namespace URI for the array; see \c GetProperty().
346 ///
347 /// @param arrayName The name of the array. Can be a general path expression, must not be null
348 /// or the empty string; see \c GetProperty() for namespace prefix usage.
349 ///
350 /// @param fieldNS The namespace URI for the field used as the selector. Same URI and prefix
351 /// usage as the \c schemaNS and \c arrayName parameters.
352 ///
353 /// @param fieldName The name of the field used as the selector. Must be a single XML name, must
354 /// not be null or the empty string. It must be the name of a field that is itself simple.
355 ///
356 /// @param fieldValue The desired value of the field, specified as a string object.
357 ///
358 /// @param fullPath [out] A string in which to return the composed path.
359
360 static void ComposeFieldSelector ( XMP_StringPtr schemaNS,
361 XMP_StringPtr arrayName,
362 XMP_StringPtr fieldNS,
363 XMP_StringPtr fieldName,
364 const tStringObj & fieldValue,
365 tStringObj * fullPath );
366
367 /// @}
368
369 // =============================================================================================
370 /// \name Conversion between binary types and strings
371 /// @{
372 ///
373 /// The main accessors in \c TXMPMeta set and retrieve property values as strings. additional
374 /// functions, such as \c TXMPMeta::SetPropertyInt(), set and retrieve property values as
375 /// explicit binary data types. Use these functions to convert between binary and string
376 /// values.
377 ///
378 /// Strings can be specified as null-terminated UTF-8 (\c #XMP_StringPtr), or as string
379 /// objects (\c tStringObj) of the type declared when instantiating the XMP classes; see
380 /// \c XMP.hpp. Alternate forms of each conversion function allow either type of string.
381
382 // ---------------------------------------------------------------------------------------------
383 /// @brief \c ConvertFromBool() converts a Boolean value to a string.
384 ///
385 /// The string values of Booleans are returned by the macros \c #kXMP_TrueStr and
386 /// \c #kXMP_FalseStr in \c XMP_Const.h.
387 ///
388 /// @param binValue The Boolean value to be converted.
389 ///
390 /// @param strValue [out] A buffer in which to return the string representation of the value.
391
392 static void ConvertFromBool ( bool binValue,
393 tStringObj * strValue );
394
395 // ---------------------------------------------------------------------------------------------
396 /// @brief \c ConvertFromInt() converts a 32-bit integer value to a string.
397 ///
398 /// @param binValue The integer value to be converted.
399 ///
400 /// @param format Optional. A C \c sprintf format for the conversion. Default is "%d".
401 ///
402 /// @param strValue [out] A buffer in which to return the string representation of the value.
403
404 static void ConvertFromInt ( long binValue,
405 XMP_StringPtr format,
406 tStringObj * strValue );
407 // ---------------------------------------------------------------------------------------------
408 /// @brief \c ConvertFromInt64() converts a 64-bit integer value to a string.
409 ///
410 /// @param binValue The integer value to be converted.
411 ///
412 /// @param format Optional. A C \c sprintf format for the conversion. Default is "%d".
413 ///
414 /// @param strValue [out] A buffer in which to return the string representation of the value.
415
416 static void ConvertFromInt64 ( long long binValue,
417 XMP_StringPtr format,
418 tStringObj * strValue );
419
420 // ---------------------------------------------------------------------------------------------
421 /// @brief \c ConvertFromFloat() converts a floating-point value to a string.
422 ///
423 /// @param binValue The floating-point value to be converted.
424 ///
425 /// @param format Optional. A C \c sprintf format for the conversion. Default is "%d".
426 ///
427 /// @param strValue [out] A buffer in which to return the string representation of the value.
428
429 static void ConvertFromFloat ( double binValue,
430 XMP_StringPtr format,
431 tStringObj * strValue );
432
433 // ---------------------------------------------------------------------------------------------
434 /// @brief \c ConvertFromDate() converts a date/time value to a string.
435 ///
436 /// Formats a date according to the ISO 8601 profile in http://www.w3.org/TR/NOTE-datetime:
437 /// <pre>
438 /// YYYY
439 /// YYYY-MM
440 /// YYYY-MM-DD
441 /// YYYY-MM-DDThh:mmTZD
442 /// YYYY-MM-DDThh:mm:ssTZD
443 /// YYYY-MM-DDThh:mm:ss.sTZD
444 /// </pre>
445 ///
446 /// \c YYYY = four-digit year, formatted as "%.4d" <br>
447 /// \c MM = two-digit month (01=January) <br>
448 /// \c DD = two-digit day of month (01 through 31) <br>
449 /// \c hh = two digits of hour (00 through 23) <br>
450 /// \c mm = two digits of minute (00 through 59) <br>
451 /// \c ss = two digits of second (00 through 59) <br>
452 /// \c s = one or more digits representing a decimal fraction of a second <br>
453 /// \c TZD = time zone designator (Z or +hh:mm or -hh:mm)
454 ///
455 /// Time-only input is allowed where the year, month, and day are all zero. This is output as
456 /// "0000-00-00...".
457 ///
458 /// @note ISO 8601 does not allow years less than 1000 or greater than 9999. This API allows
459 /// any year, even negative ones. The W3C profile also requires a time zone designator if a time
460 /// is present, this API treats the time zone designator as optional. The XMP_DateTime type has
461 /// an explicit notion of zone-less time.
462 ///
463 /// @param binValue The date/time value to be converted.
464 ///
465 /// @param strValue [out] A buffer in which to return the ISO 8601 string representation of the date/time.
466
467 static void ConvertFromDate ( const XMP_DateTime & binValue,
468 tStringObj * strValue );
469
470 // ---------------------------------------------------------------------------------------------
471 /// @brief \c ConvertToBool() converts a string to a Boolean value.
472 ///
473 /// The preferred strings are those returned by the macros \c #kXMP_TrueStr and \c #kXMP_FalseStr.
474 /// If these do not match, the function does a case insensitive comparison, then simply 't' or 'f',
475 /// and finally non-zero and zero integer representations.
476 ///
477 /// @param strValue The string representation of the value, specified as a null-terminated UTF-8 string.
478 ///
479 /// @return The appropriate C++ bool value for the string.
480
481 static bool ConvertToBool ( XMP_StringPtr strValue );
482
483 // ---------------------------------------------------------------------------------------------
484 /// @brief \c ConvertToBool() converts a string to a Boolean value.
485 ///
486 /// Overloads the basic form of the function, allowing you to pass a string object,
487 /// rather than a <tt>const * char</tt>. It is otherwise identical; see details in the canonical form.
488 ///
489 /// @param strValue The string representation of the value, specified as a string object.
490 ///
491 /// @return The appropriate C++ bool value for the string.
492
493 static bool ConvertToBool ( const tStringObj & strValue );
494
495 // ---------------------------------------------------------------------------------------------
496 /// @brief \c ConvertToInt() converts a string to a 32-bit integer value.
497 ///
498 /// @param strValue The string representation of the value, specified as a null-terminated UTF-8 string.
499 ///
500 /// @return The 32-bit integer value.
501
502 static long ConvertToInt ( XMP_StringPtr strValue );
503
504 // ---------------------------------------------------------------------------------------------
505 /// @brief \c ConvertToInt() converts a string to a 32-bit integer value.
506 ///
507 /// Overloads the basic form of the function, allowing you to pass a string object,
508 /// rather than a <tt>const * char</tt>. It is otherwise identical.
509 ///
510 /// @param strValue The string representation of the value, specified as a string object.
511 ///
512 /// @return The 32-bit integer value.
513
514 static long ConvertToInt ( const tStringObj & strValue );
515
516 // ---------------------------------------------------------------------------------------------
517 /// @brief \c ConvertToInt64() converts a string to a 64-bit integer value.
518 ///
519 /// @param strValue The string representation of the value, specified as a null-terminated UTF-8 string.
520 ///
521 /// @return The 64-bit integer value.
522
523 static long long ConvertToInt64 ( XMP_StringPtr strValue );
524
525 // ---------------------------------------------------------------------------------------------
526 /// @brief \c ConvertToInt64() converts a string to a 64-bit integer value.
527 ///
528 /// Overloads the basic form of the function, allowing you to pass a string object,
529 /// rather than a <tt>const * char</tt>. It is otherwise identical.
530 ///
531 /// @param strValue The string representation of the value, specified as a string object.
532 ///
533 /// @return The 64-bit integer value.
534
535 static long long ConvertToInt64 ( const tStringObj & strValue );
536
537 // ---------------------------------------------------------------------------------------------
538 /// @brief \c ConvertToFloat() converts a string to a floating-point value.
539 ///
540 /// @param strValue The string representation of the value, specified as a null-terminated UTF-8 string.
541 ///
542 /// @return The floating-point value.
543
544 static double ConvertToFloat ( XMP_StringPtr strValue );
545
546 // ---------------------------------------------------------------------------------------------
547 /// @brief \c ConvertToFloat() converts a string to a floating-point value.
548 ///
549 /// Overloads the basic form of the function, allowing you to pass a string object,
550 /// rather than a <tt>const * char</tt>. It is otherwise identical.
551 ///
552 /// @param strValue The string representation of the value, specified as a string object.
553 ///
554 /// @return The floating-point value.
555
556 static double ConvertToFloat ( const tStringObj & strValue );
557
558 // ---------------------------------------------------------------------------------------------
559 /// @brief \c ConvertToDate() converts a string to a date/time value.
560 ///
561 /// Parses a date according to the ISO 8601 profile in http://www.w3.org/TR/NOTE-datetime:
562 /// <pre>
563 /// YYYY
564 /// YYYY-MM
565 /// YYYY-MM-DD
566 /// YYYY-MM-DDThh:mmTZD
567 /// YYYY-MM-DDThh:mm:ssTZD
568 /// YYYY-MM-DDThh:mm:ss.sTZD
569 /// </pre>
570 ///
571 /// \c YYYY = four-digit year, formatted as "%.4d" <br>
572 /// \c MM = two-digit month (01=January) <br>
573 /// \c DD = two-digit day of month (01 through 31) <br>
574 /// \c hh = two digits of hour (00 through 23) <br>
575 /// \c mm = two digits of minute (00 through 59) <br>
576 /// \c ss = two digits of second (00 through 59) <br>
577 /// \c s = one or more digits representing a decimal fraction of a second <br>
578 /// \c TZD = time zone designator (Z or +hh:mm or -hh:mm)
579 ///
580 /// A missing date portion or missing TZD are tolerated. A missing date value can begin with
581 /// "Thh:" or "hh:"; the year, month, and day are all set to zero in the \c #XMP_DateTime value.
582 /// A missing TZD is assumed to be UTC.
583 ///
584 /// @note ISO 8601 does not allow years less than 1000 or greater than 9999. This API allows
585 /// any year, even negative ones. The W3C profile also requires a time zone designator if a time
586 /// is present, this API treats the time zone designator as optional. The XMP_DateTime type has
587 /// an explicit notion of zone-less time.
588 ///
589 /// @param strValue The ISO 8601 string representation of the date/time, specified as a
590 /// null-terminated UTF-8 string.
591 ///
592 /// @param binValue [out] A buffer in which to return the binary date/time value.
593
594 static void ConvertToDate ( XMP_StringPtr strValue,
595 XMP_DateTime * binValue );
596
597 // ---------------------------------------------------------------------------------------------
598 /// @brief \c ConvertToDate() converts a string to a date/time value.
599 ///
600 /// Overloads the basic form of the function, allowing you to pass a string object,
601 /// rather than a <tt>const * char</tt>. It is otherwise identical.
602 /// See details for the canonical form.
603 ///
604 ///
605 /// @param strValue The ISO 8601 string representation of the date/time, specified as a string
606 /// object.
607 ///
608 /// @param binValue [out] A buffer in which to return the binary date/time value.
609
610 static void ConvertToDate ( const tStringObj & strValue,
611 XMP_DateTime * binValue );
612
613 /// @}
614
615 // =============================================================================================
616 /// \name Date-time manipulation
617 /// @{
618 ///
619 /// In addition to the type-conversion functions that convert between strings and binary
620 /// date-time values, these functions create, manipulate, and compare date-time values.
621
622 // ---------------------------------------------------------------------------------------------
623 /// @brief \c CurrentDateTime() obtains the current date and time.
624 ///
625 /// Creates and returns a binary \c #XMP_DateTime value. The returned time is UTC, properly
626 /// adjusted for the local time zone. The resolution of the time is not guaranteed to be finer
627 /// than seconds.
628 ///
629 /// @param time [out] A buffer in which to return the date/time value.
630
631 static void CurrentDateTime ( XMP_DateTime * time );
632
633 // ---------------------------------------------------------------------------------------------
634 /// @brief \c SetTimeZone() sets the time zone in a date/time value to the local time zone.
635 ///
636 /// Any existing time zone value is replaced. The other date/time fields are not adjusted in any way.
637 ///
638 /// @param time A pointer to the date-time value, which is modified in place.
639
640 static void SetTimeZone ( XMP_DateTime * time );
641
642 // ---------------------------------------------------------------------------------------------
643 /// @brief \c ConvertToUTCTime() ensures that a time is UTC.
644 ///
645 /// If the time zone is not UTC, the time is adjusted and the time zone set to be UTC. The value
646 /// is not modified if the time zone is already UTC or if the value has no time zone.
647 ///
648 /// @param time A pointer to the date-time value, which is modified in place.
649
650 static void ConvertToUTCTime ( XMP_DateTime * time );
651
652 // ---------------------------------------------------------------------------------------------
653 /// @brief \c ConvertToLocalTime() ensures that a time is local.
654 ///
655 /// If the time zone is not the local zone, the time is adjusted and the time zone set to be local.
656 /// The value is not modified if the time zone is already the local zone or if the value has no
657 /// time zone.
658 ///
659 /// @param time A pointer to the date-time value, which is modified in place.
660
661 static void ConvertToLocalTime ( XMP_DateTime * time );
662
663 // ---------------------------------------------------------------------------------------------
664 /// @brief \c CompareDateTime() compares the order of two date/time values.
665 ///
666 /// Both values are treated as in the same time zone if either has no time zone.
667 ///
668 /// @param left The left-side date/time value.
669 ///
670 /// @param right The right-side date/time value.
671 ///
672 /// @return An integer indicating the order:
673 /// \li -1 if left is earlier than right
674 /// \li 0 if left matches right
675 /// \li +1 if left is later than right
676
677 static int CompareDateTime ( const XMP_DateTime & left,
678 const XMP_DateTime & right );
679
680 /// @}
681
682 // =============================================================================================
683 /// \name Base64 encoding and decoding
684 /// @{
685 ///
686 /// These functions convert between raw data values and Base64-encoded strings.
687
688 // ---------------------------------------------------------------------------------------------
689 /// @brief \c EncodeToBase64() converts a raw data value to a Base64-encoded string.
690 ///
691 /// @param rawStr An \c #XMP_StringPtr (char *) string containing the raw data to be converted.
692 ///
693 /// @param rawLen The number of characters of raw data to be converted.
694 ///
695 /// @param encodedStr [out] A string object in which to return the encoded string.
696
697 static void EncodeToBase64 ( XMP_StringPtr rawStr,
698 XMP_StringLen rawLen,
699 tStringObj * encodedStr );
700
701 // ---------------------------------------------------------------------------------------------
702 /// @brief \c EncodeToBase64() converts a raw data value passed in a string object to a Base64-encoded string.
703 ///
704 /// Overloads the basic form of the function, allowing you to pass a string object as input.
705 /// It is otherwise identical.
706 ///
707 /// @param rawStr A string object containing the raw data to be converted.
708 ///
709 /// @param encodedStr [out] A string object in which to return the encoded string.
710
711 static void EncodeToBase64 ( const tStringObj & rawStr,
712 tStringObj * encodedStr );
713
714 // ---------------------------------------------------------------------------------------------
715 /// @brief \c DecodeFromBase64() Decodes a Base64-encoded string to raw data.
716 ///
717 /// @param encodedStr An \c #XMP_StringPtr (char *) string containing the encoded data to be converted.
718 ///
719 /// @param encodedLen The number of characters of raw data to be converted.
720 ///
721 /// @param rawStr [out] A string object in which to return the decoded data.
722
723 static void DecodeFromBase64 ( XMP_StringPtr encodedStr,
724 XMP_StringLen encodedLen,
725 tStringObj * rawStr );
726
727 // ---------------------------------------------------------------------------------------------
728 /// @brief \c DecodeFromBase64() Decodes a Base64-encoded string, passed as a string object, to raw data.
729 ///
730 /// Overloads the basic form of the function, allowing you to pass a string object as input.
731 /// It is otherwise identical.
732 ///
733 /// @param encodedStr An string object containing the encoded data to be converted.
734 ///
735 /// @param rawStr [out] A string object in which to return the decoded data.
736
737 static void DecodeFromBase64 ( const tStringObj & encodedStr,
738 tStringObj * rawStr );
739
740 /// @}
741
742 // =============================================================================================
743 // =============================================================================================
744 /// \name JPEG file handling
745 /// @{
746 ///
747 /// These functions support the partitioning of XMP in JPEG files into standard and extended
748 /// portions in order to work around the 64KB size limit of JPEG marker segments.
749 ///
750 /// @note (Doc note) Add detail about how to write out and read back extended data
751
752 // ---------------------------------------------------------------------------------------------
753 /// @brief \c PackageForJPEG() creates XMP serializations appropriate for a JPEG file.
754 ///
755 /// The standard XMP in a JPEG file is limited to 64K bytes. This function serializes the XMP
756 /// metadata in an XMP object into a string of RDF (see \c TXMPMeta::SerializeToBuffer()). If
757 /// the data does not fit into the 64K byte limit, it creates a second packet string with the
758 /// extended data.
759 ///
760 /// @param xmpObj The XMP object containing the metadata.
761 ///
762 /// @param standardXMP [out] A string object in which to return the full standard XMP packet.
763 ///
764 /// @param extendedXMP [out] A string object in which to return the serialized extended XMP,
765 /// empty if not needed.
766 ///
767 /// @param extendedDigest [out] A string object in which to return an MD5 digest of the serialized
768 /// extended XMP, empty if not needed.
769 ///
770 /// @see \c MergeFromJPEG()
771
772 static void PackageForJPEG ( const TXMPMeta<tStringObj> & xmpObj,
773 tStringObj * standardXMP,
774 tStringObj * extendedXMP,
775 tStringObj * extendedDigest );
776
777 // ---------------------------------------------------------------------------------------------
778 /// @brief \c MergeFromJPEG() merges standard and extended XMP retrieved from a JPEG file.
779 ///
780 /// When an extended partition stores properties that do not fit into the JPEG file limitation
781 /// of 64K bytes, this function integrates those properties back into the same XMP object with
782 /// those from the standard XMP packet.
783 ///
784 /// @param fullXMP [in, out] An XMP object which the caller has initialized from the standard
785 /// XMP packet in a JPEG file. The extended XMP is added to this object.
786 ///
787 /// @param extendedXMP An XMP object which the caller has initialized from the extended XMP
788 /// packet in a JPEG file.
789 ///
790 /// @see \c PackageForJPEG()
791
792 static void MergeFromJPEG ( TXMPMeta<tStringObj> * fullXMP,
793 const TXMPMeta<tStringObj> & extendedXMP );
794
795 /// @}
796
797 // =============================================================================================
798 /// \name Editing utilities
799 /// @{
800 ///
801 /// These functions are useful in implementing a user interface for editing XMP. They
802 /// convert sets of property values to and from displayable and manipulable strings, and perform
803 /// operations on sets of metadata, such as those available from the File Info dialog box.
804
805 // ---------------------------------------------------------------------------------------------
806 /// @brief \c CatenateArrayItems() creates a single edit string from a set of array item values.
807 ///
808 /// Collects the values of all items in an array into a single string, using a specified
809 /// separation string. Each item in the specified array must be a simple string value.
810 ///
811 /// @param xmpObj The XMP object containing the array to be catenated.
812 ///
813 /// @param schemaNS The schema namespace URI for the array. Must not be null or the empty string.
814 ///
815 /// @param arrayName The name of the array. May be a general path expression, must not be null
816 /// or the empty string.
817 ///
818 /// @param separator The string with which to separate the items in the catenated string.
819 /// Defaults to "; ", ASCII semicolon and space (U+003B, U+0020).
820 ///
821 /// @param quotes The character or characters to use as quotes around array items that contain a
822 /// separator. Defaults to the double-quote character ("), ASCII quote (U+0022).
823 ///
824 /// @param options Option flags to control the catenation. <<what options?>>
825 ///
826 /// @param catedStr [out] A string object in which to return the catenated array items.
827 ///
828 /// @see \c SeparateArrayItems()
829
830 static void CatenateArrayItems ( const TXMPMeta<tStringObj> & xmpObj,
831 XMP_StringPtr schemaNS,
832 XMP_StringPtr arrayName,
833 XMP_StringPtr separator,
834 XMP_StringPtr quotes,
835 XMP_OptionBits options,
836 tStringObj * catedStr );
837
838 // ---------------------------------------------------------------------------------------------
839 /// @brief \c SeparateArrayItems() updates an array from a concatenated edit string of values.
840 ///
841 /// This reverses the action of \c CatenateArrayItems(), separating out individual array items
842 /// from the edit string and updating the array with the new values. Each item in the array must
843 /// be a simple string value.
844 ///
845 /// @param xmpObj The XMP object containing the array to be updated.
846 ///
847 /// @param schemaNS The schema namespace URI for the array. Must not be null or the empty string.
848 ///
849 /// @param arrayName The name of the array. May be a general path expression, must not be null
850 /// or the empty string.
851 ///
852 /// @param options Option flags to control the separation. <<what options?>>
853 ///
854 /// @param catedStr The concatenated array items, as created by \c CatenateArrayItems(),
855 /// specified as a null-terminated UTF-8 string.
856
857 static void SeparateArrayItems ( TXMPMeta<tStringObj> * xmpObj,
858 XMP_StringPtr schemaNS,
859 XMP_StringPtr arrayName,
860 XMP_OptionBits options,
861 XMP_StringPtr catedStr );
862
863 // ---------------------------------------------------------------------------------------------
864 /// @brief \c SeparateArrayItems() updates an array from a concatenated edit string of values.
865 ///
866 /// Overloads the basic form of the function, allowing you to pass a string object in which
867 /// to return the concatenated string. It is otherwise identical; see details for the canonical form.
868 ///
869
870 static void SeparateArrayItems ( TXMPMeta<tStringObj> * xmpObj,
871 XMP_StringPtr schemaNS,
872 XMP_StringPtr arrayName,
873 XMP_OptionBits options,
874 const tStringObj & catedStr );
875
876 /// @brief \c ApplyTemplate() modifies a working XMP object according to a template object.
877 ///
878 /// The XMP template can be used to add, replace or delete properties from the working XMP object.
879 /// This function replaces the previous \c AppendProperties() function, which is no longer available.
880 /// The actions that you specify determine how the template is applied. Each action can be applied
881 /// individually or combined; if you do not specify any actions, the properties and values in the working
882 /// XMP object do not change.
883 ///
884 /// These actions are available:
885 /// \li Clear (\c #kXMPTemplate_ClearUnnamedProperties): Deletes top-level properties.
886 /// Any top-level property that is present in the template (even with empty value)
887 /// is retained. All other top-level properties in the working object are deleted.
888 ///
889 /// \li Add (\c #kXMPTemplate_AddNewProperties): Adds new properties to the working object if the
890 /// template properties have values. See additional detail below.
891 ///
892 /// \li Replace (\c #kXMPTemplate_ReplaceExistingProperties): Replaces the values of existing top-level
893 /// properties in the working XMP if the value forms match those in the template. Properties
894 /// with empty values in the template are ignored. If combined with Clear or Add actions,
895 /// those take precedence; values are cleared or added, rather than replaced.
896 ///
897 /// \li Replace/Delete empty (\c #kXMPTemplate_ReplaceWithDeleteEmpty): Replaces values in the same way
898 /// as the simple Replace action, and also deletes properties if the value in the template is empty.
899 /// If combined with Clear or Add actions, those take precedence; values are cleared or added,
900 /// rather than replaced.
901 ///
902 /// \li Include internal (\c #kXMPTemplate_IncludeInternalProperties): Performs specified action
903 /// on internal properties as well as external properties. By default, internal properties
904 /// are ignored for all actions.
905 ///
906 /// The Add behavior depends on the type of property:
907 /// <ul>
908 /// <li> If a top-level property is not in the working XMP, and has a value in the template,
909 /// the property and value are added. Empty properties are not added. </li>
910 /// <li> If a property is in both the working XMP and template, the value forms must match, otherwise
911 /// the template is ignored for that property.</li>
912 /// <li> If a struct is present in both the working XMP and template, the individual fields of the
913 /// template struct are added as appropriate; that is, the logic is recursively applied to the fields.
914 /// Struct values are equivalent if they have the same fields with equivalent values. </li>
915 /// <li> If an array is present in both the working XMP and template, items from the template are
916 /// added if the value forms match. Array values match if they have sets of equivalent items,
917 /// regardless of order.</li>
918 /// <li> Alt-text arrays use the \c xml:lang qualifier as a key, adding languages that are missing. </li>
919 /// </ul>
920 /// Array item checking is n-squared; this can be time-intensive if the Replace option is
921 /// not specified. Each source item is checked to see if it already exists in the destination,
922 /// without regard to order or duplicates. Simple items are compared by value and \c xml:lang
923 /// qualifier; other qualifiers are ignored. Structs are recursively compared by field names,
924 /// without regard to field order. Arrays are compared by recursively comparing all items.
925
926 /// @param workingXMP The destination XMP object.
927 ///
928 /// @param templateXMP The template to apply to the destination XMP object.
929 ///
930 /// @param actions Option flags to control the copying. If none are specified, the properties and values
931 /// in the working XMP do not change. A logical OR of these bit-flag constants:
932 /// \li \c #kXMPTemplate_ClearUnnamedProperties -- Delete anything that is not in the template
933 /// \li \c #kXMPTemplate_AddNewProperties -- Add properties; see detailed description.
934 /// \li \c #kXMPTemplate_ReplaceExistingProperties -- Replace the values of existing properties.
935 /// \li \c #kXMPTemplate_ReplaceWithDeleteEmpty -- Replace the values of existing properties
936 /// and delete properties if the new value is empty.
937 /// \li \c #kXMPTemplate_IncludeInternalProperties -- Operate on internal properties as well as
938 /// external properties.
939 ///
940
941 static void ApplyTemplate ( TXMPMeta<tStringObj> * workingXMP,
942 const TXMPMeta<tStringObj> & templateXMP,
943 XMP_OptionBits actions );
944
945 // ---------------------------------------------------------------------------------------------
946 /// @brief \c RemoveProperties() removes multiple properties from an XMP object.
947 ///
948 /// The operation depends on how the namespace and property are specified:
949 ///
950 /// \li Non-empty \c schemaNS and \c propName - The named property is removed if it is an
951 /// external property, or if the \c #kXMPUtil_DoAllProperties option flag is set. It does not
952 /// matter whether the named property is an actual property or an alias.
953 ///
954 /// \li Non-empty \c schemaNS and empty \c propName - All external properties in the named
955 /// schema are removed. Internal properties are also removed if the
956 /// \c #kXMPUtil_DoAllProperties option flag is set. In addition, aliases from the named schema
957 /// are removed if the \c #kXMPUtil_IncludeAliases option flag is set.
958 ///
959 /// \li Empty \c schemaNS and empty \c propName - All external properties in all schemas are
960 /// removed. Internal properties are also removed if the \c #kXMPUtil_DoAllProperties option
961 /// flag is set. Aliases are handled implicitly, because the associated actuals are removed or
962 /// not.
963 ///
964 /// \li It is an error to pass an empty \c schemaNS and non-empty \c propName.
965 ///
966 /// @param xmpObj The XMP object containing the properties to be removed.
967 ///
968 /// @param schemaNS Optional schema namespace URI for the properties to be removed.
969 ///
970 /// @param propName Optional path expression for the property to be removed.
971 ///
972 /// @param options Option flags to control the deletion operation. A logical OR of these
973 /// bit-flag constants:
974 /// \li \c #kXMPUtil_DoAllProperties - Delete internal properties in addition to external properties.
975 /// \li \c #kXMPUtil_IncludeAliases - Include aliases if the schema is explicitly specified.
976
977 static void RemoveProperties ( TXMPMeta<tStringObj> * xmpObj,
978 XMP_StringPtr schemaNS = 0,
979 XMP_StringPtr propName = 0,
980 XMP_OptionBits options = 0 );
981
982 #if AdobePrivate
983 // ---------------------------------------------------------------------------------------------
984 /// @brief \c AppendProperties() adds or moves properties from one XMP object to another.
985 ///
986 /// The default operation is to append only external properties that do not already exist in the
987 /// destination. Option flags allow you to add internal properties, and to merge values of
988 /// properties that exist in both the source and destination.
989 ///
990 /// \li \c #kXMPUtil_DoAllProperties: Operate on all top-level properties, external and
991 /// internal. You can use this flag together with \c #kXMPUtil_ReplaceOldValues to replace the
992 /// values of existing top-level properties.
993 ///
994 /// \li \c #kXMPUtil_ReplaceOldValues: Propogate all top-level properties from the source to
995 /// the destination, replacing any existing values. The values of properties in the
996 /// destination that are not in the source are not modified.<br>
997 /// The keep-or-replace-old notion also applies within structs and arrays. Top-level
998 /// properties are added to the destination if they do not already exist. If they do exist but
999 /// differ in form (simple/struct/array) then the destination is not modified. If the forms
1000 /// match, simple properties are left unchanged, while structs and arrays are merged.<br>
1001 /// Do not use this option when the processing is more complicated. <<than what??>>
1002 ///
1003 /// \li \c #kXMPUtil_DeleteEmptyValues: An empty value in the source XMP causes the
1004 /// corresponding destination property to be deleted. By default, empty values are treated in
1005 /// the same way as non-empty values. An empty value is a simple empty string, an array with
1006 /// no items,or a struct with no fields. Qualifiers are ignored.
1007 ///
1008 /// The detailed behavior is defined by the following pseudo-code:
1009 ///
1010 /// <pre>
1011 /// AppendProperties ( sourceXMP, destXMP, options ):
1012 /// doAll = options & kXMPUtil_DoAllProperties
1013 /// replaceOld = options & kXMPUtil_ReplaceOldValues
1014 /// deleteEmpty = options & kXMPUtil_DeleteEmptyValues
1015 /// for all source schema (top level namespaces):
1016 /// for all top level properties in sourceSchema:
1017 /// if doAll or prop is external:
1018 /// AppendSubtree ( sourceNode, destSchema, replaceOld, deleteEmpty )
1019 ///
1020 /// AppendSubtree ( sourceNode, destParent, replaceOld, deleteEmpty ):
1021 /// if deleteEmpty and source value is empty:
1022 /// delete the corresponding child from destParent
1023 /// else if sourceNode not in destParent (by name):
1024 /// copy sourceNode's subtree to destParent
1025 /// else if replaceOld:
1026 /// delete subtree from destParent
1027 /// copy sourceNode's subtree to destParent
1028 /// else: // (Already exists in dest and not replacing, merge structs and arrays)
1029 /// if sourceNode and destNode forms differ:
1030 /// return, leave the destNode alone
1031 /// else if form is a struct:
1032 /// for each field in sourceNode:
1033 /// AppendSubtree ( sourceNode.field, destNode, replaceOld )
1034 /// else if form is an alt-text array:
1035 /// copy new items by xml:lang value into the destination
1036 /// else if form is an array:
1037 /// copy new items by value into the destination, ignoring order and duplicates
1038 /// </pre>
1039 ///
1040 /// Array item checking is n-squared; this can be time-intensive if the replace-old options is
1041 /// not specified. Each source item is checked to see if it already exists in the destination,
1042 /// without regard to order or duplicates. Simple items are compared by value and \c xml:lang
1043 /// qualifier; other qualifiers are ignored. Structs are recursively compared by field names,
1044 /// without regard to field order. Arrays are compared by recursively comparing all items.
1045 ///
1046 /// @param source The source XMP object.
1047 ///
1048 /// @param dest The destination XMP object.
1049 ///
1050 /// @param options Option flags to control the copying. A logical OR of these bit-flag constants:
1051 /// \li \c kXMPUtil_DoAllProperties - Operate on internal properties in addition to external properties.
1052 /// \li \c kXMPUtil_ReplaceOldValues - Replace the values of existing properties.
1053 /// \li \c kXMPUtil_DeleteEmptyValues - Delete properties if the new value is empty.
1054
1055 static void AppendProperties ( const TXMPMeta<tStringObj> & source,
1056 TXMPMeta<tStringObj> * dest,
1057 XMP_OptionBits options = 0 );
1058 #endif
1059
1060 // ---------------------------------------------------------------------------------------------
1061 /// @brief \c DuplicateSubtree() replicates a subtree from one XMP object into another.
1062 ///
1063 /// The destination can be a different namespace and root location in the same object, or the
1064 /// same or a different location in another XMP object.
1065 ///
1066 /// @param source The source XMP object.
1067 ///
1068 /// @param dest The destination XMP object.
1069 ///
1070 /// @param sourceNS The schema namespace URI for the source subtree.
1071 ///
1072 /// @param sourceRoot The root location for the source subtree. Can be a general path expression,
1073 /// must not be null or the empty string.
1074 ///
1075 /// @param destNS The schema namespace URI for the destination. Defaults to the source namespace.
1076 ///
1077 /// @param destRoot The root location for the destination. Can be a general path expression.
1078 /// Defaults to the source location.
1079 ///
1080 /// @param options Option flags to control the operation. <<options?>>
1081
1082 static void DuplicateSubtree ( const TXMPMeta<tStringObj> & source,
1083 TXMPMeta<tStringObj> * dest,
1084 XMP_StringPtr sourceNS,
1085 XMP_StringPtr sourceRoot,
1086 XMP_StringPtr destNS = 0,
1087 XMP_StringPtr destRoot = 0,
1088 XMP_OptionBits options = 0 );
1089
1090 #if AdobePrivate
1091
1092 // ---------------------------------------------------------------------------------------------
1093 /// @brief \c CollectMultiFileXMP() collects the XMP from multiple files into one XMP object.
1094 ///
1095 /// This function supports the multi-file operation of the File Info dialog. Its action is
1096 /// reversed by \c DistributeMultiFileXMP().
1097 ///
1098 /// @param inputXMP An XMP object initialized from one of the files being updated.
1099 ///
1100 /// @param multiXMP [in, out] The aggregate XMP object used in the multi-file dialog. <<??>>
1101 ///
1102 /// @param options Option flags to control the operation. None are currently defined.
1103
1104 static void CollectMultiFileXMP ( const TXMPMeta<tStringObj> & inputXMP,
1105 TXMPMeta<tStringObj> * multiXMP,
1106 XMP_OptionBits options = 0 );
1107
1108 // ---------------------------------------------------------------------------------------------
1109 /// @brief DistributeMultiFileXMP() distributes the updated multi-file XMP back into the files.
1110 ///
1111 /// This function reverses the action of \c CollectMultiFileXMP().
1112 ///
1113 /// @param multiXMP The aggregate XMP object used in the multi-file dialog. <<??>>
1114 ///
1115 /// @param outputXMP [in, out] The XMP object for one of the files being updated.
1116 ///
1117 /// @param options Option flags to control the operation. None are currently defined.
1118
1119 static void DistributeMultiFileXMP ( const TXMPMeta<tStringObj> & multiXMP,
1120 TXMPMeta<tStringObj> * outputXMP,
1121 XMP_OptionBits options = 0 );
1122
1123 // ---------------------------------------------------------------------------------------------
1124 /// @brief IsPropertyMultiValued() reports whether a property was present with differing values
1125 /// in XMP from multiple files collected with \c CollectMultiFileXMP()
1126 ///
1127 /// The function accepts an arbitrary path expression and checks if the top level property is
1128 /// mentioned in the xmpx:DifferingValues array.
1129 ///
1130 /// @param multiXMP The aggregate XMP object used in the multi-file dialog.
1131 ///
1132 /// @param propNS The namespace URI for the XMP property underlying a UI widget.
1133 ///
1134 /// @param propName The path for the XMP property underlying a UI widget.
1135 ///
1136 /// @return True if the named property has multiple values in the original files.
1137
1138 static bool IsPropertyMultiValued ( const TXMPMeta<tStringObj> & multiXMP,
1139 XMP_StringPtr propNS,
1140 XMP_StringPtr propName );
1141
1142 // ---------------------------------------------------------------------------------------------
1143 /// @brief GetDateRange() retrieves the oldest and newest dates in XMP from multiple files
1144 /// collected with \c CollectMultiFileXMP().
1145 ///
1146 /// The return value reports whether the date property is present and has a range.
1147 ///
1148 /// @param multiXMP The aggregate XMP object used in the multi-file dialog.
1149 ///
1150 /// @param propNS The namespace URI for the XMP property underlying a date UI widget.
1151 ///
1152 /// @param propName The path for the XMP property underlying a date UI widget.
1153 ///
1154 /// @param oldest [out] A buffer in which to return the oldest date from the original files
1155 ///
1156 /// @param newest [out] A buffer in which to return the newest date from the original files.
1157 ///
1158 /// @return True if the named property is present with a date range.
1159
1160 static bool GetDateRange ( const TXMPMeta<tStringObj> & multiXMP,
1161 XMP_StringPtr propNS,
1162 XMP_StringPtr propName,
1163 XMP_DateTime * oldest,
1164 XMP_DateTime * newest );
1165
1166 // ---------------------------------------------------------------------------------------------
1167 /// @brief GetMergedListPath() retrieves the path for a merged array, if present in XMP from
1168 /// multiple files collected with \c CollectMultiFileXMP().
1169 ///
1170 /// @param multiXMP The aggregate XMP object used in the multi-file dialog.
1171 ///
1172 /// @param propNS The namespace URI for the XMP property underlying a list UI widget.
1173 ///
1174 /// @param propName The path for the XMP property underlying a list UI widget.
1175 ///
1176 /// @param mergedPath [out] A string object in which to return the path within the \c xmpx:
1177 /// schema for the merged array.
1178 ///
1179 /// @return True if the named property is present as a multi-valued array.
1180
1181 static bool GetMergedListPath ( const TXMPMeta<tStringObj> & multiXMP,
1182 XMP_StringPtr propNS,
1183 XMP_StringPtr propName,
1184 tStringObj * mergedPath );
1185
1186 // ---------------------------------------------------------------------------------------------
1187 /// @brief RemoveMultiValueInfo() removes all knowledge of a multiple-valued property.
1188 ///
1189 /// Call this function when the user edits a property that had multiple values.
1190 ///
1191 /// @param multiXMP The aggregate XMP object used in the multi-file dialog.
1192 ///
1193 /// @param propNS The namespace URI for the XMP property to be removed. Must not be null or the
1194 /// empty string. Must be a registered namespace URI.
1195 ///
1196 /// @param propName The path for the XMP property to be removed. Can be null or the empty string
1197 /// to remove all properties for the given namespace.
1198
1199 static void RemoveMultiValueInfo ( TXMPMeta<tStringObj> * multiXMP,
1200 XMP_StringPtr propNS,
1201 XMP_StringPtr propName );
1202
1203 #endif // AdobePrivate
1204
1205 /// @}
1206
1207 #if AdobePrivate
1208
1209 // =============================================================================================
1210
1211 // Trial special case code to improve the performance of DMO's Temporal Metadata library.
1212
1213 static bool GetBulkMarkers ( const TXMPMeta<tStringObj> & xmp,
1214 XMP_StringPtr ns, XMP_StringPtr path,
1215 std::vector<XMPDMO_MarkerInfo> * markers );
1216
1217 static void SetBulkMarkers ( TXMPMeta<tStringObj> * xmp,
1218 XMP_StringPtr ns, XMP_StringPtr path,
1219 const std::vector<XMPDMO_MarkerInfo> & markers );
1220
1221
1222 #endif // AdobePrivate
1223
1224 // =============================================================================================
1225
1226 private:
1227
1228 static void SetClientString ( void * clientPtr, XMP_StringPtr valuePtr, XMP_StringLen valueLen );
1229
1230 }; // class TXMPUtils
1231
1232 // =================================================================================================
1233
1234 #endif // __TXMPUtils_hpp__