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