| 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__ |