Debian Codegraph @

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

raw
1 #ifndef __TXMPFiles_hpp__
2 #define __TXMPFiles_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 // ADC Amandeep Chawla
27 // IJS Inder Jeet Singh
28 // AB Amit Bhatti
29 //
30 // mm-dd-yy who Description of changes, most recent on top
31 //
32 // 10-21-14 AB 5.6.f120 [3836549] Making kXMPFiles_OptimizeFileLayout flag public for XMP SDK.
33 // 01-31-14 IJS 5.6-f091 Reverting Changes Done in 5.6-f089
34 // 01-20-14 ADC 5.6-f089 [3696245] Generic Handler: Generic handler returns kXMP_Unknown type for handler->format.
35 // 01-16-14 IJS 5.6-f088 Generic Handling Feature - Adding support for kXMPFiles_OpenUseGenericHandler OpenFile() flag.
36 // 01-30-13 IJS 5.6-f029 Removed LocateMetadataFiles API from XMPFiles
37 // 01-11-13 IJS 5.6-f020 Reworked GetFileModDate, GetAssociatedResources and IsMetadataWritable APIs.
38 // 01-07-13 IJS 5.6-f018 Changed name of API IsWritable to IsMetadataWritable.
39 // Added root Path folder as associated Resource for folder based Formats.
40 // 12-21-12 IJS 5.6-f008 Added GetAssociatedResources and IsWritable APIs
41 //
42 // 09-28-12 AWL 5.5-f039 Add LocateMetadataFiles.
43 // 09-28-12 ADC 5.5-f038 Implement public API and glue layer for XMPFiles error notifications.
44 // 06-20-12 AWL 5.5-f018 Add outer layers for XMPFiles progress notifications, no handlers use it yet.
45 //
46 // 10-27-11 AWL 5.4-f030 [3007461] Improve performance of GetFileModDate.
47 // 09-23-11 AWL 5.4-f012 Add GetFileModDate.
48 //
49 // 08-17-10 AWL 5.3-f001 Integrate I/O revamp to main.
50 //
51 // 05-19-09 AWL 5.0-f039 First part of threading improvements, revamp the client glue.
52 // 05-12-09 AWL 5.0-f037 Finish deprecated function removal.
53 //
54 // 02-11-08 AWL 4.2-f071 Enable SXMPFiles::CheckFileFormat, the leaks were not real.
55 // 01-28-08 AWL 4.2-f062 Add public CheckFileFormat and CheckPackageFormat functions.
56 // 08-02-07 AWL 4.2 Incorporate major revamp to doxygen comments.
57 //
58 // 01-11-07 AWL 4.2-f007 [1454747] Change QuickTime init/term calls to handle main and background thread issues.
59 //
60 // 05-19-06 AWL 4.0-f006 Change XMPFiles::OpenFile to return bool, don't throw if smart handler not
61 // found when kXMPFiles_OpenUseSmartHandler is passed.
62 // 04-07-06 AWL 4.0-f002 Add XMPFiles::GetThumbnail. Change XMPFiles::OpenFile to close the disk file
63 // early for read-only access. Change XMPFileHandler::ExtractXMP to CacheFileData.
64 // 03-24-06 AWL 4.0 Adapt for move to ham-perforce, integrate XMPFiles, bump version to 4.
65 //
66 // 07-21-05 AWL 1.3-001 Remove BIB, same as XMP. Create Xcode project. Bump version to 1.3.
67 //
68 // 09-23-04 AWL 1.0-007 Use the XMP toolkit's build number and timestamp. Add current position
69 // result to LFA_Seek. Add SetAbortProc and abort checking.
70 // 08-23-04 AWL Add GetVersion.
71 // 08-20-04 AWL Add handlerFlags output to GetFileInfo.
72 // 08-13-04 AWL Checkpoint, almost full implementation, compiles.
73 // 06-07-04 AWL First draft based on talk with Jerry Scoggins.
74 //
75 // =================================================================================================
76 #endif // AdobePrivate
77
78 // =================================================================================================
79 /// \file TXMPFiles.hpp
80 /// \brief API for access to the main (document-level) metadata in a file_.
81 ///
82 /// The Adobe XMP Toolkit's file handling component, XMPFiles, is a front end to a set of
83 /// format-specific file handlers that support file I/O for XMP. The file handlers implement smart,
84 /// efficient support for those file formats for which the means to embed XMP is defined in the XMP
85 /// Specification. Where possible, this support allows:
86 /// \li Injection of XMP where none currently exists
87 /// \li Expansion of XMP without regard to existing padding
88 /// \li Reconciliation of the XMP and other legacy forms of metadata.
89 ///
90 /// \c TXMPFiles is designed for use by clients interested in the metadata and not in the primary
91 /// file content; the Adobe Bridge application is a typical example. \c TXMPFiles is not intended to
92 /// be appropriate for files authored by an application; that is, those files for which the
93 /// application has explicit knowledge of the file format.
94 // =================================================================================================
95
96
97 // =================================================================================================
98 /// \class TXMPFiles TXMPFiles.hpp
99 /// \brief API for access to the main (document-level) metadata in a file.
100 ///
101 /// \c TXMPFiles is a template class that provides the API for the Adobe XMP Toolkit's XMPFiles
102 /// component. This provides convenient access to the main, or document level, XMP for a file. Use
103 /// it to obtain metadata from a file, which you can then manipulate with the XMP Core component
104 /// (the classes \c TXMPMeta, \c TXMPUtils, and \c TXMPIterator); and to write new or changed
105 /// metadata back out to a file.
106 ///
107 /// The functions allow you to open a file, read and write the metadata, then close the file.
108 /// While open, portions of the file might be maintained in RAM data structures. Memory
109 /// usage can vary considerably depending onfile format and access options.
110 ///
111 /// A file can be opened for read-only or read-write access, with typical exclusion for both
112 /// modes. Errors result in the throw of an \c XMPError exception.
113 ///
114 /// \c TXMPFiles is the template class. It must be instantiated with a string class such as
115 /// \c std::string. Read the Toolkit Overview for information about the overall architecture of the XMP
116 /// API, and the documentation for \c XMP.hpp for specific instantiation instructions.
117 ///
118 /// Access these functions through the concrete class, \c SXMPFiles.
119 // =================================================================================================
120
121
122 #if XMP_StaticBuild // ! Client XMP_IO objects can only be used in static builds.
123 #include "XMP_IO.hpp"
124 #endif
125
126
127 template <class tStringObj>
128 class TXMPFiles {
129
130 public:
131
132 // =============================================================================================
133 /// \name Initialization and termination
134 /// @{
135 ///
136 /// A \c TXMPFiles object must be initialized before use and can be terminated when done.
137
138 // ---------------------------------------------------------------------------------------------
139 /// @brief \c GetVersionInfo() retrieves version information for the XMPFiles component.
140 ///
141 /// Can be called before \c #Initialize(). This function is static; make the call directly from
142 /// the concrete class (\c SXMPFiles).
143 ///
144 /// @param versionInfo [out] A buffer in which to return the version information.
145
146 static void GetVersionInfo ( XMP_VersionInfo * versionInfo );
147
148 // ---------------------------------------------------------------------------------------------
149 /// @brief Initializes the XMPFiles library; must be called before creating an \c SXMPFiles object.
150 ///
151 /// The main action is to activate the available smart file handlers. Must be called before
152 /// using any methods except \c GetVersionInfo().
153 ///
154 /// This function is static; make the call directly from the concrete class (\c SXMPFiles).
155 ///
156 /// @return True on success.
157
158 static bool Initialize();
159
160 // ---------------------------------------------------------------------------------------------
161 /// @brief Initializes the XMPFiles library; must be called before creating an \c SXMPFiles object.
162 ///
163 /// This overload of TXMPFiles::Initialize() accepts option bits to customize the initialization
164 /// actions. At this time no option is defined.
165 ///
166 /// The main action is to activate the available smart file handlers. Must be called before
167 /// using any methods except \c GetVersionInfo().
168 ///
169 /// This function is static; make the call directly from the concrete class (\c SXMPFiles).
170 ///
171 /// @param options Option flags to control the initialization actions.
172 ///
173 /// @return True on success.
174
175 static bool Initialize ( XMP_OptionBits options );
176
177 // ---------------------------------------------------------------------------------------------
178 /// @brief Initializes the XMPFiles library; must be called before creating an \c SXMPFiles object.
179 ///
180 /// This overload of TXMPFiles::Initialize() accepts plugin directory and name of the plug-ins
181 /// as a comma separated list to load the file handler plug-ins. If plugins == NULL, then all
182 /// plug-ins present in the plug-in directory will be loaded.
183 ///
184 /// The main action is to activate the available smart file handlers. Must be called before
185 /// using any methods except \c GetVersionInfo().
186 ///
187 /// This function is static; make the call directly from the concrete class (\c SXMPFiles).
188 ///
189 /// @param pluginFolder Pugin directorty to load the file handler plug-ins.
190 /// @param plugins Comma sepearted list of plug-ins which should be loaded from the plug-in directory.
191 /// If plugin == NULL, then all plug-ins availbale in the plug-in directory will be loaded.
192 ///
193 /// @return True on success.
194
195 static bool Initialize ( const char* pluginFolder, const char* plugins = NULL );
196
197 // ---------------------------------------------------------------------------------------------
198 /// @brief Initializes the XMPFiles library; must be called before creating an \c SXMPFiles object.
199 ///
200 /// This overload of TXMPFiles::Initialize( XMP_OptionBits options ) accepts plugin directory and
201 /// name of the plug-ins as a comma separated list to load the file handler plug-ins.
202 /// If plugins == NULL, then all plug-ins present in the plug-in directory will be loaded.
203 ///
204 /// The main action is to activate the available smart file handlers. Must be called before
205 /// using any methods except \c GetVersionInfo().
206 ///
207 /// This function is static; make the call directly from the concrete class (\c SXMPFiles).
208 ///
209 /// @param options Option flags to control the initialization actions.
210 /// @param pluginFolder Pugin directorty to load the file handler plug-ins.
211 /// @param plugins Comma sepearted list of plug-ins which should be loaded from the plug-in directory.
212 /// If plugin == NULL, then all plug-ins availbale in the plug-in directory will be loaded.
213 ///
214 /// @return True on success.
215
216 static bool Initialize ( XMP_OptionBits options, const char* pluginFolder, const char* plugins = NULL );
217
218 // ---------------------------------------------------------------------------------------------
219 /// @brief Terminates use of the XMPFiles library.
220 ///
221 /// Optional. Deallocates global data structures created by intialization. Its main action is to
222 /// deallocate heap-allocated global storage, for the benefit of client leak checkers.
223 ///
224 /// This function is static; make the call directly from the concrete class (\c SXMPFiles).
225
226 static void Terminate();
227
228 /// @}
229
230 // =============================================================================================
231 /// \name Constructors and destructor
232 /// @{
233 ///
234 /// The default constructor initializes an object that is associated with no file. The alternate
235 /// constructors call \c OpenFile().
236
237 // ---------------------------------------------------------------------------------------------
238 /// @brief Default constructor initializes an object that is associated with no file.
239
240 TXMPFiles();
241
242 // ---------------------------------------------------------------------------------------------
243 /// @brief Destructor; typical virtual destructor.
244 ///
245 /// The destructor does not call \c CloseFile(); pending updates are lost when the destructor is run.
246 ///
247 /// @see \c OpenFile(), \c CloseFile()
248
249 virtual ~TXMPFiles() throw();
250
251 // ---------------------------------------------------------------------------------------------
252 /// @brief Alternate constructor associates the new \c XMPFiles object with a specific file.
253 ///
254 /// Calls \c OpenFile() to open the specified file after performing a default construct.
255 ///
256 /// @param filePath The path for the file, specified as a nul-terminated UTF-8 string.
257 ///
258 /// @param format A format hint for the file, if known.
259 ///
260 /// @param openFlags Options for how the file is to be opened (for read or read/write, for
261 /// example). Use a logical OR of these bit-flag constants:
262 ///
263 /// \li \c #kXMPFiles_OpenForRead
264 /// \li \c #kXMPFiles_OpenForUpdate
265 /// \li \c #kXMPFiles_OpenOnlyXMP
266 /// \li \c #kXMPFiles_OpenStrictly
267 /// \li \c #kXMPFiles_OpenUseSmartHandler
268 /// \li \c #kXMPFiles_OpenUsePacketScanning
269 /// \li \c #kXMPFiles_OpenLimitedScanning
270 ///
271
272 TXMPFiles ( XMP_StringPtr filePath,
273 XMP_FileFormat format = kXMP_UnknownFile,
274 XMP_OptionBits openFlags = 0 );
275
276 // ---------------------------------------------------------------------------------------------
277 /// @brief Alternate constructor associates the new \c XMPFiles object with a specific file,
278 /// using a string object.
279 ///
280 /// Overloads the basic form of the function, allowing you to pass a string object
281 /// for the file path. It is otherwise identical; see details in the canonical form.
282
283 TXMPFiles ( const tStringObj & filePath,
284 XMP_FileFormat format = kXMP_UnknownFile,
285 XMP_OptionBits openFlags = 0 );
286
287 // ---------------------------------------------------------------------------------------------
288 /// @brief Copy constructor
289 ///
290 /// Increments an internal reference count but does not perform a deep copy.
291 ///
292 /// @param original The existing \c TXMPFiles object to copy.
293 ///
294
295 TXMPFiles ( const TXMPFiles<tStringObj> & original );
296
297 // ---------------------------------------------------------------------------------------------
298 /// @brief Assignment operator
299 ///
300 /// Increments an internal reference count but does not perform a deep copy.
301 ///
302 /// @param rhs The existing \c TXMPFiles object.
303
304 void operator= ( const TXMPFiles<tStringObj> & rhs );
305
306 // ---------------------------------------------------------------------------------------------
307 /// @brief Reconstructs a \c TXMPFiles object from an internal reference.
308 ///
309 /// This constructor creates a new \c TXMPFiles object that refers to the underlying reference
310 /// object of an existing \c TXMPFiles object. Use to safely pass \c SXMPFiles references across
311 /// DLL boundaries.
312 ///
313 /// @param xmpFilesObj The underlying reference object, obtained from some other XMP object
314 /// with \c TXMPFiles::GetInternalRef().
315 ///
316
317
318 TXMPFiles ( XMPFilesRef xmpFilesObj );
319
320 // ---------------------------------------------------------------------------------------------
321 /// @brief GetInternalRef() retrieves an internal reference that can be safely passed across DLL
322 /// boundaries and reconstructed.
323 ///
324 /// Use with the reconstruction constructor to safely pass \c SXMPFiles references across DLL
325 /// boundaries where the clients might have used different string types when instantiating
326 /// \c TXMPFiles.
327 ///
328 /// @return The internal reference.
329 ///
330 /// @see \c TXMPMeta::GetInternalRef() for usage.
331
332 XMPFilesRef GetInternalRef();
333
334 /// @}
335
336 // =============================================================================================
337 /// \name File handler information
338 /// @{
339 ///
340 /// Call this static function from the concrete class, \c SXMPFiles, to obtain information about
341 /// the file handlers for the XMPFiles component.
342
343 // ---------------------------------------------------------------------------------------------
344 /// @brief GetFormatInfo() reports what features are supported for a specific file format.
345 ///
346 /// The file handlers for different file formats vary considerably in what features they
347 /// support. Support depends on both the general capabilities of the format and the
348 /// implementation of the handler for that format.
349 ///
350 ///This function is static; make the call directly from the concrete class (\c SXMPFiles).
351 ///
352 /// @param format The file format whose support flags are desired.
353 ///
354 /// @param handlerFlags [out] A buffer in which to return a logical OR of option bit flags.
355 /// The following constants are defined:
356 ///
357 /// \li \c #kXMPFiles_CanInjectXMP - Can inject first-time XMP into an existing file.
358 /// \li \c #kXMPFiles_CanExpand - Can expand XMP or other metadata in an existing file.
359 /// \li \c #kXMPFiles_CanRewrite - Can copy one file to another, writing new metadata (as in SaveAs)
360 /// \li \c #kXMPFiles_CanReconcile - Supports reconciliation between XMP and other forms.
361 /// \li \c #kXMPFiles_AllowsOnlyXMP - Allows access to just the XMP, ignoring other forms.
362 /// This is only meaningful if \c #kXMPFiles_CanReconcile is set.
363 /// \li \c #kXMPFiles_ReturnsRawPacket - File handler returns raw XMP packet information and string.
364 ///
365 /// Even if \c #kXMPFiles_ReturnsRawPacket is set, the returned packet information might have an
366 /// offset of -1 to indicate an unknown offset. While all file handlers should be able to return
367 /// the raw packet, some might not know the offset of the packet within the file. This is
368 /// typical in cases where external libraries are used. These cases might not even allow return
369 /// of the raw packet.
370 ///
371 /// @return True if the format has explicit "smart" support, false if the format is handled by
372 /// the default packet scanning plus heuristics. */
373
374
375 #if AdobePrivate
376 // *** kXMPFiles_CanRewrite is really a SaveAs-like operation - change the name?
377 #endif
378
379 static bool GetFormatInfo ( XMP_FileFormat format,
380 XMP_OptionBits * handlerFlags = 0 );
381
382 /// @}
383
384 // =============================================================================================
385 /// \name File operations
386 /// @{
387 ///
388 /// These functions allow you to open, close, and query files.
389
390 // ---------------------------------------------------------------------------------------------
391 /// @brief \c CheckFileFormat() tries to determine the format of a file.
392 ///
393 /// Tries to determine the format of a file, returning an \c #XMP_FileFormat value. Uses the
394 /// same logic as \c OpenFile() to select a smart handler.
395 ///
396 /// @param filePath The path for the file, appropriate for the local operating system. Passed as
397 /// a nul-terminated UTF-8 string. The path is the same as would be passed to \c OpenFile.
398 ///
399 /// @return The file's format if a smart handler would be selected by \c OpenFile(), otherwise
400 /// \c #kXMP_UnknownFile.
401
402 static XMP_FileFormat CheckFileFormat ( XMP_StringPtr filePath );
403
404 // ---------------------------------------------------------------------------------------------
405 /// @brief \c CheckPackageFormat() tries to determine the format of a "package" folder.
406 ///
407 /// Tries to determine the format of a package, given the name of the top-level folder. Returns
408 /// an \c #XMP_FileFormat value. Examples of recognized packages include the video formats P2,
409 /// XDCAM, or Sony HDV. These packages contain collections of "clips", stored as multiple files
410 /// in specific subfolders.
411 ///
412 /// @param folderPath The path for the top-level folder, appropriate for the local operating
413 /// system. Passed as a nul-terminated UTF-8 string. This is not the same path you would pass to
414 /// \c OpenFile(). For example, the top-level path for a package might be ".../MyMovie", while
415 /// the path to a file you wish to open would be ".../MyMovie/SomeClip".
416 ///
417 /// @return The package's format if it can be determined, otherwise \c #kXMP_UnknownFile.
418
419 static XMP_FileFormat CheckPackageFormat ( XMP_StringPtr folderPath );
420
421 // ---------------------------------------------------------------------------------------------
422 /// @brief \c GetFileModDate() returns the last modification date of all files that are returned
423 /// by \c GetAssociatedResources()
424 ///
425 /// Returns the most recent O/S file modification date of all associated files. In the typical case
426 /// of a single file containing embedded XMP, returned date value is the modification date of the
427 /// same file. For sidecar and folder based video packages, returned date value is the modification
428 /// date of that associated file which was updated last.
429 ///
430 /// @param filePath A path exactly as would be passed to \c OpenFile.
431 ///
432 /// @param modDate A required pointer to return the last modification date.
433 ///
434 /// @param format A format hint as would be passed to \c OpenFile.
435 ///
436 /// @param options An optional set of option flags. The only defined one is \c kXMPFiles_ForceGivenHandler,
437 /// used to shortcut the handler selection logic if the caller is certain of the format.
438 ///
439 /// @return Returns true if the file path is valid to select a smart handler, false for an
440 /// invalid path or if fallback packet scanning would be selected.
441
442 static bool GetFileModDate ( XMP_StringPtr filePath,
443 XMP_DateTime * modDate,
444 XMP_FileFormat * format = 0,
445 XMP_OptionBits options = 0 );
446
447
448 // ---------------------------------------------------------------------------------------------
449 /// @brief \c GetAssociatedResources() returns a list of files and folders associated to filePath.
450 ///
451 /// \c GetAssociatedResources is provided to locate all files that are associated to the given
452 /// filePath such as sidecar-based XMP or folder-based video packages.If a smart
453 /// handler can be selected (not fallback packet scanning) then a list of file/folder paths is
454 /// returned for the related files that can be safely copied/imported to a different location,
455 /// keeping intact metadata(XMP and non-XMP),content and the necessary folder structure of the
456 /// format. The necessary folder structure here is the structure that is needed to uniquely
457 /// identify a folder-based format.The filePath and format parameters are exactly as would be
458 /// used for OpenFile. In the simple embedded XMP case just one path is returned. In the simple
459 /// sidecar case one or two paths will be returned, one if there is no sidecar XMP and two if
460 /// sidecar XMP exists. For folder-based handlers paths to all associated files is returned,
461 /// including the files and folders necessary to identify the format.In general, all the returned
462 /// paths are existent.In case of folder based video formats the first associated resource in the
463 /// resourceList is the root folder.
464 ///
465 /// @param filePath A path exactly as would be passed to \c OpenFile.
466 ///
467 /// @param resourceList Address of a vector of strings to receive all associated resource paths.
468 ///
469 /// @param format A format hint as would be passed to \c OpenFile.
470 ///
471 /// @param options An optional set of option flags. The only defined one is \c kXMPFiles_ForceGivenHandler,
472 /// used to shortcut the handler selection logic if the caller is certain of the format.
473 ///
474 /// @return Returns true if the file path is valid to select a smart handler, false for an
475 /// invalid path or if fallback packet scanning would be selected. Can also return false for
476 /// unexpected errors that prevent knowledge of the file usage.
477
478 static bool GetAssociatedResources ( XMP_StringPtr filePath,
479 std::vector<tStringObj>* resourceList,
480 XMP_FileFormat format = kXMP_UnknownFile,
481 XMP_OptionBits options = 0);
482
483 // ---------------------------------------------------------------------------------------------
484 /// @brief \c IsMetadataWritable() returns true if metadata can be updated for the given media path.
485 ///
486 /// \c IsMetadataWritable is provided to check if metadata can be updated or written to the format.In
487 /// the case of folder-based video formats only if all the metadata files can be written to, true is
488 /// returned.In other words, false is returned for a partial-write state of metadata files in
489 /// folder-based media formats.
490 ///
491 /// @param filePath A path exactly as would be passed to \c OpenFile.
492 ///
493 /// @param writable A pointer to the result flag. Is true if the metadata can be updated in the format,
494 /// otherwise false.
495 ///
496 /// @param format A format hint as would be passed to \c OpenFile.
497 ///
498 /// @param options An optional set of option flags. The only defined one is \c kXMPFiles_ForceGivenHandler,
499 /// used to shortcut the handler selection logic if the caller is certain of the format.
500 ///
501 /// @return Returns true if the file path is valid to select a smart handler, false for an
502 /// invalid path or if fallback packet scanning would be selected.
503
504 static bool IsMetadataWritable (XMP_StringPtr filePath,
505 bool * writable,
506 XMP_FileFormat format = kXMP_UnknownFile,
507 XMP_OptionBits options = 0 );
508
509 // ---------------------------------------------------------------------------------------------
510 /// @brief \c OpenFile() opens a file for metadata access.
511 ///
512 /// Opens a file for the requested forms of metadata access. Opening the file at a minimum
513 /// causes the raw XMP packet to be read from the file. If the file handler supports legacy
514 /// metadata reconciliation then legacy metadata is also read, unless \c #kXMPFiles_OpenOnlyXMP
515 /// is passed.
516 ///
517 /// If the file is opened for read-only access (passing \c #kXMPFiles_OpenForRead), the disk
518 /// file is closed immediately after reading the data from it; the \c XMPFiles object, however,
519 /// remains in the open state. You must call \c CloseFile() when finished using it. Other
520 /// methods, such as \c GetXMP(), can only be used between the \c OpenFile() and \c CloseFile()
521 /// calls. The \c XMPFiles destructor does not call \c CloseFile(); if you call it without
522 /// closing, any pending updates are lost.
523 ///
524 /// If the file is opened for update (passing \c #kXMPFiles_OpenForUpdate), the disk file
525 /// remains open until \c CloseFile() is called. The disk file is only updated once, when
526 /// \c CloseFile() is called, regardless of how many calls are made to \c PutXMP().
527 ///
528 /// Typically, the XMP is not parsed and legacy reconciliation is not performed until \c GetXMP()
529 /// is called, but this is not guaranteed. Specific file handlers might do earlier parsing of
530 /// the XMP. Delayed parsing and early disk file close for read-only access are optimizations
531 /// to help clients implementing file browsers, so that they can access the file briefly
532 /// and possibly display a thumbnail, then postpone more expensive XMP processing until later.
533 ///
534 /// @param filePath The path for the file, appropriate for the local operating system. Passed as
535 /// a nul-terminated UTF-8 string.
536 ///
537 /// @param format The format of the file. If the format is unknown (\c #kXMP_UnknownFile) the
538 /// format is determined from the file content. The first handler to check is guessed from the
539 /// file's extension. Passing a specific format value is generally just a hint about what file
540 /// handler to try first (instead of the one based on the extension). If
541 /// \c #kXMPFiles_OpenStrictly is set, then any format other than \c #kXMP_UnknownFile requires
542 /// that the file actually be that format; otherwise an exception is thrown.
543 ///
544 /// @param openFlags A set of option flags that describe the desired access. By default (zero)
545 /// the file is opened for read-only access and the format handler decides on the level of
546 /// reconciliation that will be performed. A logical OR of these bit-flag constants:
547 ///
548 /// \li \c #kXMPFiles_OpenForRead - Open for read-only access.
549 /// \li \c #kXMPFiles_OpenForUpdate - Open for reading and writing.
550 /// \li \c #kXMPFiles_OpenOnlyXMP - Only the XMP is wanted, no reconciliation.
551 /// \li \c #kXMPFiles_OpenStrictly - Be strict about locating XMP and reconciling with other
552 /// forms. By default, a best effort is made to locate the correct XMP and to reconcile XMP
553 /// with other forms (if reconciliation is done). This option forces stricter rules, resulting
554 /// in exceptions for errors. The definition of strictness is specific to each handler, there
555 /// might be no difference.
556 /// \li \c #kXMPFiles_OpenUseSmartHandler - Require the use of a smart handler.
557 /// \li \c #kXMPFiles_OpenUsePacketScanning - Force packet scanning, do not use a smart handler.
558 /// \li \c #kXMPFiles_OptimizeFileLayout - When updating a file, spend the effort necessary
559 /// to optimize file layout.
560 #if AdobePrivate
561 /// \li \c #kXMPFiles_OpenUseGenericHandler - Open the file using Generic Handler if there
562 /// is no Smart handler for the file format.
563 #endif
564 ///
565 /// @return True if the file is succesfully opened and attached to a file handler. False for
566 /// anticipated problems, such as passing \c #kXMPFiles_OpenUseSmartHandler but not having an
567 /// appropriate smart handler. Throws an exception for serious problems.
568
569 #if AdobePrivate
570 // *** Need to think more about interaction of reconcile & strict, default behavior.
571 // *** Use specific format as hint by default and add kXMPFiles_KnownFormat option?
572 // *** Document exceptions for various typical errors.
573 #endif
574
575 bool OpenFile ( XMP_StringPtr filePath,
576 XMP_FileFormat format = kXMP_UnknownFile,
577 XMP_OptionBits openFlags = 0 );
578
579 // ---------------------------------------------------------------------------------------------
580 /// @brief \c OpenFile() opens a file for metadata access, using a string object
581 ///
582 /// Overloads the basic form of the function, allowing you to pass a string object for the file
583 /// path. It is otherwise identical; see details in the canonical form.
584
585 bool OpenFile ( const tStringObj & filePath,
586 XMP_FileFormat format = kXMP_UnknownFile,
587 XMP_OptionBits openFlags = 0 );
588
589 #if XMP_StaticBuild // ! Client XMP_IO objects can only be used in static builds.
590 // ---------------------------------------------------------------------------------------------
591 /// @brief \c OpenFile() opens a client-provided XMP_IO object for metadata access.
592 ///
593 /// Alternative to the basic form of the function, allowing you to pass an XMP_IO object for
594 /// client-managed I/O.
595 ///
596
597 bool OpenFile ( XMP_IO * clientIO,
598 XMP_FileFormat format = kXMP_UnknownFile,
599 XMP_OptionBits openFlags = 0 );
600 #endif
601
602 // ---------------------------------------------------------------------------------------------
603 /// @brief CloseFile() explicitly closes an opened file.
604 ///
605 /// Performs any necessary output to the file and closes it. Files that are opened for update
606 /// are written to only when closing.
607 ///
608 /// If the file is opened for read-only access (passing \c #kXMPFiles_OpenForRead), the disk
609 /// file is closed immediately after reading the data from it; the \c XMPFiles object, however,
610 /// remains in the open state. You must call \c CloseFile() when finished using it. Other
611 /// methods, such as \c GetXMP(), can only be used between the \c OpenFile() and \c CloseFile()
612 /// calls. The \c XMPFiles destructor does not call \c CloseFile(); if you call it without closing,
613 /// any pending updates are lost.
614 ///
615 /// If the file is opened for update (passing \c #kXMPFiles_OpenForUpdate), the disk file remains
616 /// open until \c CloseFile() is called. The disk file is only updated once, when \c CloseFile()
617 /// is called, regardless of how many calls are made to \c PutXMP(). When in-place update is not possible
618 /// we might write into a temporary file and then swap for corruption/crash safety.
619 ///
620 /// @param closeFlags Option flags for optional closing actions. This bit-flag constant is
621 /// defined:
622 ///
623 /// \li \c #kXMPFiles_UpdateSafely - Write into a temporary file then swap for crash safety.
624
625 void CloseFile ( XMP_OptionBits closeFlags = 0 );
626
627 // ---------------------------------------------------------------------------------------------
628 /// @brief \c GetFileInfo() retrieves basic information about an opened file.
629 ///
630 /// @param filePath [out] A buffer in which to return the path passed to \c OpenFile(). Can be
631 /// null if value is not wanted.
632 ///
633 /// @param openFlags [out] A buffer in which to return the option flags passed to
634 /// \c OpenFile(). Can be null if value is not wanted.
635 ///
636 /// @param format [out] A buffer in which to return the file format. Can be null if value is not
637 /// wanted.
638 /// @param handlerFlags [out] A buffer in which to return the handler's capability flags. Can
639 /// be null if value is not wanted.
640 ///
641 /// @return True if the file object is in the open state; that is, \c OpenFile() has been called
642 /// but \c CloseFile() has not. False otherwise. Even if the file object is open, the actual
643 /// disk file might be closed in the host file-system sense; see \c OpenFile().
644
645 bool GetFileInfo ( tStringObj * filePath = 0,
646 XMP_OptionBits * openFlags = 0,
647 XMP_FileFormat * format = 0,
648 XMP_OptionBits * handlerFlags = 0 );
649
650 // ---------------------------------------------------------------------------------------------
651 /// @brief \c SetAbortProc() registers a callback function used to check for a user-signaled abort.
652 ///
653 /// The specified procedure is called periodically to allow a user to cancel time-consuming
654 /// operations. The callback function should return true to signal an abort, which results in an
655 /// exception being thrown.
656 ///
657 /// @param abortProc The callback function.
658 ///
659 /// @param abortArg A pointer to caller-defined data to pass to the callback function.
660
661 void SetAbortProc ( XMP_AbortProc abortProc,
662 void * abortArg );
663
664 /// @}
665
666 // =============================================================================================
667 /// \name Accessing metadata
668 /// @{
669 ///
670 /// These functions allow you to retrieve XMP metadata from open files, so that you can use the
671 /// \c TXMPMeta API to manipulate it. The \c PutXMP() functions update the XMP packet in memory.
672 /// Changed XMP is not actually written out to the file until the file is closed.
673
674 // ---------------------------------------------------------------------------------------------
675 /// @brief \c GetXMP() retrieves the XMP metadata from an open file.
676 ///
677 /// The function reports whether XMP is present in the file; you can choose to retrieve any or
678 /// all of the parsed XMP, the raw XMP packet,or information about the raw XMP packet. The
679 /// options provided when the file was opened determine if reconciliation is done with other
680 /// forms of metadata.
681 ///
682 /// @param xmpObj [out] An XMP object in which to return the parsed XMP metadata. Can be null.
683 ///
684 /// @param xmpPacket [out] An string object in which to return the raw XMP packet as stored in
685 /// the file. Can be null. The encoding of the packet is given in the \c packetInfo. Returns an
686 /// empty string if the low level file handler does not provide the raw packet.
687 ///
688 /// @param packetInfo [out] An string object in which to return the location and form of the raw
689 /// XMP in the file. \c #XMP_PacketInfo::charForm and \c #XMP_PacketInfo::writeable reflect the
690 /// raw XMP in the file. The parsed XMP property values are always UTF-8. The writeable flag is
691 /// taken from the packet trailer; it applies only to "format ignorant" writing. The
692 /// \c #XMP_PacketInfo structure always reflects the state of the XMP in the file. The offset,
693 /// length, and character form do not change as a result of calling \c PutXMP() unless the file
694 /// is also written. Some file handlers might not return location or contents of the raw packet
695 /// string. To determine whether one does, check the \c #kXMPFiles_ReturnsRawPacket bit returned
696 /// by \c GetFormatInfo(). If the low-level file handler does not provide the raw packet
697 /// location, \c #XMP_PacketInfo::offset and \c #XMP_PacketInfo::length are both 0,
698 /// \c #XMP_PacketInfo::charForm is UTF-8, and \c #XMP_PacketInfo::writeable is false.
699 ///
700 /// @return True if the file has XMP, false otherwise.
701
702 bool GetXMP ( SXMPMeta * xmpObj = 0,
703 tStringObj * xmpPacket = 0,
704 XMP_PacketInfo * packetInfo = 0 );
705
706 // ---------------------------------------------------------------------------------------------
707 /// @brief \c PutXMP() updates the XMP metadata in this object without writing out the file.
708 ///
709 /// This function supplies new XMP for the file. However, the disk file is not written until the
710 /// object is closed with \c CloseFile(). The options provided when the file was opened
711 /// determine if reconciliation is done with other forms of metadata.
712 ///
713 /// @param xmpObj The new metadata as an XMP object.
714
715 void PutXMP ( const SXMPMeta & xmpObj );
716
717 // ---------------------------------------------------------------------------------------------
718 /// @brief \c PutXMP() updates the XMP metadata in this object without writing out the file,
719 /// using a string object for input.
720 ///
721 /// Overloads the basic form of the function, allowing you to pass the metadata as a string object
722 /// instead of an XMP object. It is otherwise identical; see details in the canonical form.
723 ///
724 /// @param xmpPacket The new metadata as a string object containing a complete XMP packet.
725
726 void PutXMP ( const tStringObj & xmpPacket );
727
728 // ---------------------------------------------------------------------------------------------
729 /// @brief \c PutXMP() updates the XMP metadata in this object without writing out the file,
730 /// using a string object and optional length.
731 ///
732 /// Overloads the basic form of the function, allowing you to pass the metadata as a string object
733 /// instead of an XMP object. It is otherwise identical; see details in the canonical form.
734 ///
735 /// @param xmpPacket The new metadata as a <tt>const char *</tt> string containing an XMP packet.
736 ///
737 /// @param xmpLength Optional. The number of bytes in the string. If not supplied, the string is
738 /// assumed to be nul-terminated.
739
740 void PutXMP ( XMP_StringPtr xmpPacket,
741 XMP_StringLen xmpLength = kXMP_UseNullTermination );
742
743 // ---------------------------------------------------------------------------------------------
744 /// @brief \c CanPutXMP() reports whether this file can be updated with a specific XMP packet.
745 ///
746 /// Use to determine if the file can probably be updated with a given set of XMP metadata. This
747 /// depends on the size of the packet, the options with which the file was opened, and the
748 /// capabilities of the handler for the file format. The function obtains the length of the
749 /// serialized packet for the provided XMP, but does not keep it or modify it, and does not
750 /// cause the file to be written when closed. This is implemented roughly as follows:
751 ///
752 /// <pre>
753 /// bool CanPutXMP ( XMP_StringPtr xmpPacket )
754 /// {
755 /// XMP_FileFormat format;
756 /// this->GetFileInfo ( 0, &format, 0 );
757 ///
758 /// XMP_OptionBits formatFlags;
759 /// GetFormatInfo ( format, &formatFlags );
760 ///
761 /// if ( (formatFlags & kXMPFiles_CanInjectXMP) && (formatFlags & kXMPFiles_CanExpand) ) return true;
762 ///
763 /// XMP_PacketInfo packetInfo;
764 /// bool hasXMP = this->GetXMP ( 0, 0, &packetInfo );
765 ///
766 /// if ( ! hasXMP ) {
767 /// if ( formatFlags & kXMPFiles_CanInjectXMP ) return true;
768 /// } else {
769 /// if ( (formatFlags & kXMPFiles_CanExpand) ||
770 /// (packetInfo.length >= strlen(xmpPacket)) ) return true;
771 /// }
772 /// return false;
773 /// }
774 /// </pre>
775 ///
776 /// @param xmpObj The proposed new metadata as an XMP object.
777
778 bool CanPutXMP ( const SXMPMeta & xmpObj );
779
780 // ---------------------------------------------------------------------------------------------
781 /// @brief \c CanPutXMP() reports whether this file can be updated with a specific XMP packet,
782 /// passed in a string object.
783 ///
784 /// Overloads the basic form of the function, allowing you to pass the metadata as a string object
785 /// instead of an XMP object. It is otherwise identical; see details in the canonical form.
786 ///
787 /// @param xmpPacket The proposed new metadata as a string object containing an XMP packet.
788
789 bool CanPutXMP ( const tStringObj & xmpPacket );
790
791 // ---------------------------------------------------------------------------------------------
792 /// @brief \c CanPutXMP() reports whether this file can be updated with a specific XMP packet,
793 /// passed in a string object.
794 ///
795 /// Overloads the basic form of the function, allowing you to pass the metadata as a string object
796 /// instead of an XMP object. It is otherwise identical; see details in the canonical form.
797 ///
798 /// @param xmpPacket The proposed new metadata as a <tt>const char *</tt> string containing an XMP packet.
799 ///
800 /// @param xmpLength Optional. The number of bytes in the string. If not supplied, the string
801 /// is assumed to be nul-terminated.
802
803 bool CanPutXMP ( XMP_StringPtr xmpPacket,
804 XMP_StringLen xmpLength = kXMP_UseNullTermination );
805
806 #if AdobePrivate
807 // ---------------------------------------------------------------------------------------------
808 /// @brief \c GetAlbumArts() retrieves the Album Artworks from the file
809 ///
810 /// This must be called after OpenFile() and before CloseFile() else exception will be thrown.
811 /// Album art or Cover art information may exist in a file. This can be used to get album art
812 /// information from a file using TXMPAlbumArt. This is format specific information and currently
813 /// the support has been provided for MP3 files only. If album art information exists in a file having
814 /// Album Art support then true will be returned.
815 ///
816 /// @param albumArtVector The pointer to a vector of TXMPAlbumArt, which will be filled by XMP. All the
817 /// required memory will be allocated at the client side and will be freed using destructer.
818 /// This vector will be first cleared before processing.
819 ///
820 /// @return True if the file has Album Art information, false otherwise.
821
822 bool GetAlbumArts( std::vector<SXMPAlbumArt> * albumArtVector );
823
824 // ---------------------------------------------------------------------------------------------
825 /// @brief \c PutAlbumArts() updates the Album Artworks in a file
826 ///
827 /// This must be called after OpenFile() and before CloseFile() else exception will be thrown.
828 /// This can be used to update the album art information in a file using TXMPAlbumArt. This is
829 /// format specific information and currently the support has been provided for MP3 files only.
830 /// If the format supports album art processing then provided album artworks will be updated in
831 /// the file. The actual changes in the file will not be reflected till the user calls CloseFile().
832 ///
833 /// @param albumArtVector The pointer to a vector of TXMPAlbumArt which will be inserted and updated in
834 /// the file.
835 ///
836 /// @return True if the album art information has been updated in the file, false otherwise.
837
838 bool PutAlbumArts( const std::vector<SXMPAlbumArt> & albumArtVector );
839 #endif
840 /// @}
841
842 // =============================================================================================
843 /// \name Progress notifications
844 /// @{
845 ///
846 /// These functions allow track the progress of file operations. Initially only file updates are
847 /// tracked, these all occur within calls to SXMPFiles::CloseFile. There are no plans to track
848 /// other operations at this time. Tracking support must be added to specific file handlers,
849 /// there are no guarantees about which handlers will have support. To simplify the logic only
850 /// file writes will be estimated and measured.
851
852 // ---------------------------------------------------------------------------------------------
853 /// @brief \c SetDefaultProgressCallback() sets a global default for progress tracking. This is
854 /// used as a default for XMPFiles (library) objects created after the default is set. This does
855 /// not affect the callback for new SXMPFiles (client) objects with an existing XMPFiles object.
856 ///
857 /// @param proc The client's callback function. Can be zero to disable notifications.
858 ///
859 /// @param context A pointer used to carry client-private context.
860 ///
861 /// @param interval The desired number of seconds between notifications. Ideally the first
862 /// notification is sent after this interval, then at each following multiple of this interval.
863 ///
864 /// @param sendStartStop A Boolean value indicating if initial and final notifications are
865 /// wanted in addition to those at the reporting intervals.
866
867 static void SetDefaultProgressCallback ( XMP_ProgressReportProc proc, void * context = 0,
868 float interval = 1.0, bool sendStartStop = false );
869
870 // ---------------------------------------------------------------------------------------------
871 /// @brief \c SetProgressCallback() sets the progress notification callback for the associated
872 /// XMPFiles (library) object.
873 ///
874 /// @param proc The client's callback function. Can be zero to disable notifications.
875 ///
876 /// @param context A pointer used to carry client-private context.
877 ///
878 /// @param interval The desired number of seconds between notifications. Ideally the first
879 /// notification is sent after this interval, then at each following multiple of this interval.
880 ///
881 /// @param sendStartStop A Boolean value indicating if initial and final notifications are
882 /// wanted in addition to those at the reporting intervals.
883
884 void SetProgressCallback ( XMP_ProgressReportProc proc, void * context = 0,
885 float interval = 1.0, bool sendStartStop = false );
886
887 /// @}
888
889 // =============================================================================================
890 // Error notifications
891 // ===================
892
893 // ---------------------------------------------------------------------------------------------
894 /// \name Error notifications
895 /// @{
896 ///
897 /// From the beginning through version 5.5, XMP Toolkit errors result in throwing an \c XMP_Error
898 /// exception. For the most part exceptions were thrown early and thus API calls aborted as soon
899 /// as an error was detected. Starting in version 5.5, support has been added for notifications
900 /// of errors arising in calls to \c TXMPFiles functions.
901 ///
902 /// A client can register an error notification callback function for a \c TXMPFile object. This
903 /// can be done as a global default or individually to each object. The global default applies
904 /// to all objects created after it is registered. Within the object there is no difference
905 /// between the global default or explicitly registered callback. The callback function returns
906 /// a \c bool value indicating if recovery should be attempted (true) or an exception thrown
907 /// (false). If no callback is registered, a best effort at recovery and continuation will be
908 /// made with an exception thrown if recovery is not possible.
909 ///
910 /// The number of notifications delivered for a given TXMPFiles object can be limited. This is
911 /// intended to reduce chatter from multiple or cascading errors. The limit is set when the
912 /// callback function is registered. This limits the number of notifications of the highest
913 /// severity delivered or less. If a higher severity error occurs, the counting starts again.
914 /// The limit and counting can be reset at any time, see \c ResetErrorCallbackLimit.
915
916 // --------------------------------------------------------------------------------------------
917 /// @brief SetDefaultErrorCallback() registers a global default error notification callback.
918 ///
919 /// @param proc The client's callback function.
920 ///
921 /// @param context Client-provided context for the callback.
922 ///
923 /// @param limit A limit on the number of notifications to be delivered.
924
925 static void SetDefaultErrorCallback ( XMPFiles_ErrorCallbackProc proc, void* context = 0, XMP_Uns32 limit = 1 );
926
927 // --------------------------------------------------------------------------------------------
928 /// @brief SetErrorCallback() registers an error notification callback.
929 ///
930 /// @param proc The client's callback function.
931 ///
932 /// @param context Client-provided context for the callback.
933 ///
934 /// @param limit A limit on the number of notifications to be delivered.
935
936 void SetErrorCallback ( XMPFiles_ErrorCallbackProc proc, void* context = 0, XMP_Uns32 limit = 1 );
937
938 // --------------------------------------------------------------------------------------------
939 /// @brief ResetErrorCallbackLimit() resets the error notification limit and counting. It has no
940 /// effect if an error notification callback function is not registered.
941 ///
942 /// @param limit A limit on the number of notifications to be delivered.
943
944 void ResetErrorCallbackLimit ( XMP_Uns32 limit = 1 );
945
946 /// @}
947
948 // =============================================================================================
949
950 private:
951
952 XMPFilesRef xmpFilesRef;
953
954 // These are used as callbacks from the library code to the client when returning values that
955 // involve heap allocations. This ensures the allocations occur within the client.
956 static void SetClientString ( void * clientPtr, XMP_StringPtr valuePtr, XMP_StringLen valueLen );
957 static void SetClientStringVector ( void * clientPtr, XMP_StringPtr* arrayPtr, XMP_Uns32 stringCount );
958 #if AdobePrivate
959 static void GetArtInfo1 ( void * clientPtr, XMP_Uns32 indexVector, XMP_Uns32 * imageLength,
960 XMP_StringPtr * description, XMP_StringLen * descLen, XMP_Uns8 * usageType,
961 XMP_Uns8 * formatType, XMP_Uns8 * encodingType, XMP_BinaryData * imageData );
962 static void PushArtInfo1 ( void * clientPtr, XMP_Uns32 imageLength, XMP_StringPtr description,
963 XMP_StringLen descLen, XMP_Uns8 usageType, XMP_Uns8 formatType,
964 XMP_Uns8 encodingType, XMP_BinaryData imageData );
965 #endif
966 }; // class TXMPFiles
967
968 // =================================================================================================
969
970 #endif // __TXMPFiles_hpp__