#ifndef __TXMPFiles_hpp__ #define __TXMPFiles_hpp__ 1 #if ( ! __XMP_hpp__ ) #error "Do not directly include, use XMP.hpp" #endif // ================================================================================================= // Copyright Adobe // Copyright 2002 Adobe // All Rights Reserved // // NOTICE: Adobe permits you to use, modify, and distribute this file in accordance with the terms // of the Adobe license agreement accompanying it. // ================================================================================================= // ================================================================================================= /// \file TXMPFiles.hpp /// \brief API for access to the main (document-level) metadata in a file_. /// /// The Adobe XMP Toolkit's file handling component, XMPFiles, is a front end to a set of /// format-specific file handlers that support file I/O for XMP. The file handlers implement smart, /// efficient support for those file formats for which the means to embed XMP is defined in the XMP /// Specification. Where possible, this support allows: /// \li Injection of XMP where none currently exists /// \li Expansion of XMP without regard to existing padding /// \li Reconciliation of the XMP and other legacy forms of metadata. /// /// \c TXMPFiles is designed for use by clients interested in the metadata and not in the primary /// file content; the Adobe Bridge application is a typical example. \c TXMPFiles is not intended to /// be appropriate for files authored by an application; that is, those files for which the /// application has explicit knowledge of the file format. // ================================================================================================= // ================================================================================================= /// \class TXMPFiles TXMPFiles.hpp /// \brief API for access to the main (document-level) metadata in a file. /// /// \c TXMPFiles is a template class that provides the API for the Adobe XMP Toolkit's XMPFiles /// component. This provides convenient access to the main, or document level, XMP for a file. Use /// it to obtain metadata from a file, which you can then manipulate with the XMP Core component /// (the classes \c TXMPMeta, \c TXMPUtils, and \c TXMPIterator); and to write new or changed /// metadata back out to a file. /// /// The functions allow you to open a file, read and write the metadata, then close the file. /// While open, portions of the file might be maintained in RAM data structures. Memory /// usage can vary considerably depending onfile format and access options. /// /// A file can be opened for read-only or read-write access, with typical exclusion for both /// modes. Errors result in the throw of an \c XMPError exception. /// /// \c TXMPFiles is the template class. It must be instantiated with a string class such as /// \c std::string. Read the Toolkit Overview for information about the overall architecture of the XMP /// API, and the documentation for \c XMP.hpp for specific instantiation instructions. /// /// Access these functions through the concrete class, \c SXMPFiles. // ================================================================================================= #if XMP_StaticBuild // ! Client XMP_IO objects can only be used in static builds. #include "XMP_IO.hpp" #endif template class TXMPFiles { public: // ============================================================================================= /// \name Initialization and termination /// @{ /// /// A \c TXMPFiles object must be initialized before use and can be terminated when done. // --------------------------------------------------------------------------------------------- /// @brief \c GetVersionInfo() retrieves version information for the XMPFiles component. /// /// Can be called before \c #Initialize(). This function is static; make the call directly from /// the concrete class (\c SXMPFiles). /// /// @param versionInfo [out] A buffer in which to return the version information. static void GetVersionInfo ( XMP_VersionInfo * versionInfo ); // --------------------------------------------------------------------------------------------- /// @brief Initializes the XMPFiles library; must be called before creating an \c SXMPFiles object. /// /// The main action is to activate the available smart file handlers. Must be called before /// using any methods except \c GetVersionInfo(). /// /// This function is static; make the call directly from the concrete class (\c SXMPFiles). /// /// @return True on success. static bool Initialize(); // --------------------------------------------------------------------------------------------- /// @brief Initializes the XMPFiles library; must be called before creating an \c SXMPFiles object. /// /// This overload of TXMPFiles::Initialize() accepts option bits to customize the initialization /// actions. At this time no option is defined. /// /// The main action is to activate the available smart file handlers. Must be called before /// using any methods except \c GetVersionInfo(). /// /// This function is static; make the call directly from the concrete class (\c SXMPFiles). /// /// @param options Option flags to control the initialization actions. /// /// @return True on success. static bool Initialize ( XMP_OptionBits options ); // --------------------------------------------------------------------------------------------- /// @brief Initializes the XMPFiles library; must be called before creating an \c SXMPFiles object. /// /// This overload of TXMPFiles::Initialize() accepts plugin directory and name of the plug-ins /// as a comma separated list to load the file handler plug-ins. If plugins == NULL, then all /// plug-ins present in the plug-in directory will be loaded. /// /// The main action is to activate the available smart file handlers. Must be called before /// using any methods except \c GetVersionInfo(). /// /// This function is static; make the call directly from the concrete class (\c SXMPFiles). /// /// @param pluginFolder Pugin directorty to load the file handler plug-ins. /// @param plugins Comma sepearted list of plug-ins which should be loaded from the plug-in directory. /// If plugin == NULL, then all plug-ins availbale in the plug-in directory will be loaded. /// /// @return True on success. static bool Initialize ( const char* pluginFolder, const char* plugins = NULL ); // --------------------------------------------------------------------------------------------- /// @brief Initializes the XMPFiles library; must be called before creating an \c SXMPFiles object. /// /// This overload of TXMPFiles::Initialize( XMP_OptionBits options ) accepts plugin directory and /// name of the plug-ins as a comma separated list to load the file handler plug-ins. /// If plugins == NULL, then all plug-ins present in the plug-in directory will be loaded. /// /// The main action is to activate the available smart file handlers. Must be called before /// using any methods except \c GetVersionInfo(). /// /// This function is static; make the call directly from the concrete class (\c SXMPFiles). /// /// @param options Option flags to control the initialization actions. /// @param pluginFolder Pugin directorty to load the file handler plug-ins. /// @param plugins Comma sepearted list of plug-ins which should be loaded from the plug-in directory. /// If plugin == NULL, then all plug-ins availbale in the plug-in directory will be loaded. /// /// @return True on success. static bool Initialize ( XMP_OptionBits options, const char* pluginFolder, const char* plugins = NULL ); // --------------------------------------------------------------------------------------------- /// @brief Terminates use of the XMPFiles library. /// /// Optional. Deallocates global data structures created by intialization. Its main action is to /// deallocate heap-allocated global storage, for the benefit of client leak checkers. /// /// This function is static; make the call directly from the concrete class (\c SXMPFiles). static void Terminate(); /// @} // ============================================================================================= /// \name Constructors and destructor /// @{ /// /// The default constructor initializes an object that is associated with no file. The alternate /// constructors call \c OpenFile(). // --------------------------------------------------------------------------------------------- /// @brief Default constructor initializes an object that is associated with no file. TXMPFiles(); // --------------------------------------------------------------------------------------------- /// @brief Destructor; typical virtual destructor. /// /// The destructor does not call \c CloseFile(); pending updates are lost when the destructor is run. /// /// @see \c OpenFile(), \c CloseFile() virtual ~TXMPFiles() throw(); // --------------------------------------------------------------------------------------------- /// @brief Alternate constructor associates the new \c XMPFiles object with a specific file. /// /// Calls \c OpenFile() to open the specified file after performing a default construct. /// /// @param filePath The path for the file, specified as a nul-terminated UTF-8 string. /// /// @param format A format hint for the file, if known. /// /// @param openFlags Options for how the file is to be opened (for read or read/write, for /// example). Use a logical OR of these bit-flag constants: /// /// \li \c #kXMPFiles_OpenForRead /// \li \c #kXMPFiles_OpenForUpdate /// \li \c #kXMPFiles_OpenOnlyXMP /// \li \c #kXMPFiles_OpenStrictly /// \li \c #kXMPFiles_OpenUseSmartHandler /// \li \c #kXMPFiles_OpenUsePacketScanning /// \li \c #kXMPFiles_OpenLimitedScanning /// TXMPFiles ( XMP_StringPtr filePath, XMP_FileFormat format = kXMP_UnknownFile, XMP_OptionBits openFlags = 0 ); // --------------------------------------------------------------------------------------------- /// @brief Alternate constructor associates the new \c XMPFiles object with a specific file, /// using a string object. /// /// Overloads the basic form of the function, allowing you to pass a string object /// for the file path. It is otherwise identical; see details in the canonical form. TXMPFiles ( const tStringObj & filePath, XMP_FileFormat format = kXMP_UnknownFile, XMP_OptionBits openFlags = 0 ); // --------------------------------------------------------------------------------------------- /// @brief Copy constructor /// /// Increments an internal reference count but does not perform a deep copy. /// /// @param original The existing \c TXMPFiles object to copy. /// TXMPFiles ( const TXMPFiles & original ); // --------------------------------------------------------------------------------------------- /// @brief Assignment operator /// /// Increments an internal reference count but does not perform a deep copy. /// /// @param rhs The existing \c TXMPFiles object. void operator= ( const TXMPFiles & rhs ); // --------------------------------------------------------------------------------------------- /// @brief Reconstructs a \c TXMPFiles object from an internal reference. /// /// This constructor creates a new \c TXMPFiles object that refers to the underlying reference /// object of an existing \c TXMPFiles object. Use to safely pass \c SXMPFiles references across /// DLL boundaries. /// /// @param xmpFilesObj The underlying reference object, obtained from some other XMP object /// with \c TXMPFiles::GetInternalRef(). /// TXMPFiles ( XMPFilesRef xmpFilesObj ); // --------------------------------------------------------------------------------------------- /// @brief GetInternalRef() retrieves an internal reference that can be safely passed across DLL /// boundaries and reconstructed. /// /// Use with the reconstruction constructor to safely pass \c SXMPFiles references across DLL /// boundaries where the clients might have used different string types when instantiating /// \c TXMPFiles. /// /// @return The internal reference. /// /// @see \c TXMPMeta::GetInternalRef() for usage. XMPFilesRef GetInternalRef(); /// @} // ============================================================================================= /// \name File handler information /// @{ /// /// Call this static function from the concrete class, \c SXMPFiles, to obtain information about /// the file handlers for the XMPFiles component. // --------------------------------------------------------------------------------------------- /// @brief GetFormatInfo() reports what features are supported for a specific file format. /// /// The file handlers for different file formats vary considerably in what features they /// support. Support depends on both the general capabilities of the format and the /// implementation of the handler for that format. /// ///This function is static; make the call directly from the concrete class (\c SXMPFiles). /// /// @param format The file format whose support flags are desired. /// /// @param handlerFlags [out] A buffer in which to return a logical OR of option bit flags. /// The following constants are defined: /// /// \li \c #kXMPFiles_CanInjectXMP - Can inject first-time XMP into an existing file. /// \li \c #kXMPFiles_CanExpand - Can expand XMP or other metadata in an existing file. /// \li \c #kXMPFiles_CanRewrite - Can copy one file to another, writing new metadata (as in SaveAs) /// \li \c #kXMPFiles_CanReconcile - Supports reconciliation between XMP and other forms. /// \li \c #kXMPFiles_AllowsOnlyXMP - Allows access to just the XMP, ignoring other forms. /// This is only meaningful if \c #kXMPFiles_CanReconcile is set. /// \li \c #kXMPFiles_ReturnsRawPacket - File handler returns raw XMP packet information and string. /// /// Even if \c #kXMPFiles_ReturnsRawPacket is set, the returned packet information might have an /// offset of -1 to indicate an unknown offset. While all file handlers should be able to return /// the raw packet, some might not know the offset of the packet within the file. This is /// typical in cases where external libraries are used. These cases might not even allow return /// of the raw packet. /// /// @return True if the format has explicit "smart" support, false if the format is handled by /// the default packet scanning plus heuristics. */ static bool GetFormatInfo ( XMP_FileFormat format, XMP_OptionBits * handlerFlags = 0 ); /// @} // ============================================================================================= /// \name File operations /// @{ /// /// These functions allow you to open, close, and query files. // --------------------------------------------------------------------------------------------- /// @brief \c CheckFileFormat() tries to determine the format of a file. /// /// Tries to determine the format of a file, returning an \c #XMP_FileFormat value. Uses the /// same logic as \c OpenFile() to select a smart handler. /// /// @param filePath The path for the file, appropriate for the local operating system. Passed as /// a nul-terminated UTF-8 string. The path is the same as would be passed to \c OpenFile. /// /// @return The file's format if a smart handler would be selected by \c OpenFile(), otherwise /// \c #kXMP_UnknownFile. static XMP_FileFormat CheckFileFormat ( XMP_StringPtr filePath ); // --------------------------------------------------------------------------------------------- /// @brief \c CheckPackageFormat() tries to determine the format of a "package" folder. /// /// Tries to determine the format of a package, given the name of the top-level folder. Returns /// an \c #XMP_FileFormat value. Examples of recognized packages include the video formats P2, /// XDCAM, or Sony HDV. These packages contain collections of "clips", stored as multiple files /// in specific subfolders. /// /// @param folderPath The path for the top-level folder, appropriate for the local operating /// system. Passed as a nul-terminated UTF-8 string. This is not the same path you would pass to /// \c OpenFile(). For example, the top-level path for a package might be ".../MyMovie", while /// the path to a file you wish to open would be ".../MyMovie/SomeClip". /// /// @return The package's format if it can be determined, otherwise \c #kXMP_UnknownFile. static XMP_FileFormat CheckPackageFormat ( XMP_StringPtr folderPath ); // --------------------------------------------------------------------------------------------- /// @brief \c GetFileModDate() returns the last modification date of all files that are returned /// by \c GetAssociatedResources() /// /// Returns the most recent O/S file modification date of all associated files. In the typical case /// of a single file containing embedded XMP, returned date value is the modification date of the /// same file. For sidecar and folder based video packages, returned date value is the modification /// date of that associated file which was updated last. /// /// @param filePath A path exactly as would be passed to \c OpenFile. /// /// @param modDate A required pointer to return the last modification date. /// /// @param format A format hint as would be passed to \c OpenFile. /// /// @param options An optional set of option flags. The only defined one is \c kXMPFiles_ForceGivenHandler, /// used to shortcut the handler selection logic if the caller is certain of the format. /// /// @return Returns true if the file path is valid to select a smart handler, false for an /// invalid path or if fallback packet scanning would be selected. static bool GetFileModDate ( XMP_StringPtr filePath, XMP_DateTime * modDate, XMP_FileFormat * format = 0, XMP_OptionBits options = 0 ); // --------------------------------------------------------------------------------------------- /// @brief \c GetAssociatedResources() returns a list of files and folders associated to filePath. /// /// \c GetAssociatedResources is provided to locate all files that are associated to the given /// filePath such as sidecar-based XMP or folder-based video packages.If a smart /// handler can be selected (not fallback packet scanning) then a list of file/folder paths is /// returned for the related files that can be safely copied/imported to a different location, /// keeping intact metadata(XMP and non-XMP),content and the necessary folder structure of the /// format. The necessary folder structure here is the structure that is needed to uniquely /// identify a folder-based format.The filePath and format parameters are exactly as would be /// used for OpenFile. In the simple embedded XMP case just one path is returned. In the simple /// sidecar case one or two paths will be returned, one if there is no sidecar XMP and two if /// sidecar XMP exists. For folder-based handlers paths to all associated files is returned, /// including the files and folders necessary to identify the format.In general, all the returned /// paths are existent.In case of folder based video formats the first associated resource in the /// resourceList is the root folder. /// /// @param filePath A path exactly as would be passed to \c OpenFile. /// /// @param resourceList Address of a vector of strings to receive all associated resource paths. /// /// @param format A format hint as would be passed to \c OpenFile. /// /// @param options An optional set of option flags. The only defined one is \c kXMPFiles_ForceGivenHandler, /// used to shortcut the handler selection logic if the caller is certain of the format. /// /// @return Returns true if the file path is valid to select a smart handler, false for an /// invalid path or if fallback packet scanning would be selected. Can also return false for /// unexpected errors that prevent knowledge of the file usage. static bool GetAssociatedResources ( XMP_StringPtr filePath, std::vector* resourceList, XMP_FileFormat format = kXMP_UnknownFile, XMP_OptionBits options = 0); // --------------------------------------------------------------------------------------------- /// @brief \c IsMetadataWritable() returns true if metadata can be updated for the given media path. /// /// \c IsMetadataWritable is provided to check if metadata can be updated or written to the format.In /// the case of folder-based video formats only if all the metadata files can be written to, true is /// returned.In other words, false is returned for a partial-write state of metadata files in /// folder-based media formats. /// /// @param filePath A path exactly as would be passed to \c OpenFile. /// /// @param writable A pointer to the result flag. Is true if the metadata can be updated in the format, /// otherwise false. /// /// @param format A format hint as would be passed to \c OpenFile. /// /// @param options An optional set of option flags. The only defined one is \c kXMPFiles_ForceGivenHandler, /// used to shortcut the handler selection logic if the caller is certain of the format. /// /// @return Returns true if the file path is valid to select a smart handler, false for an /// invalid path or if fallback packet scanning would be selected. static bool IsMetadataWritable (XMP_StringPtr filePath, bool * writable, XMP_FileFormat format = kXMP_UnknownFile, XMP_OptionBits options = 0 ); // --------------------------------------------------------------------------------------------- /// @brief \c OpenFile() opens a file for metadata access. /// /// Opens a file for the requested forms of metadata access. Opening the file at a minimum /// causes the raw XMP packet to be read from the file. If the file handler supports legacy /// metadata reconciliation then legacy metadata is also read, unless \c #kXMPFiles_OpenOnlyXMP /// is passed. /// /// If the file is opened for read-only access (passing \c #kXMPFiles_OpenForRead), the disk /// file is closed immediately after reading the data from it; the \c XMPFiles object, however, /// remains in the open state. You must call \c CloseFile() when finished using it. Other /// methods, such as \c GetXMP(), can only be used between the \c OpenFile() and \c CloseFile() /// calls. The \c XMPFiles destructor does not call \c CloseFile(); if you call it without /// closing, any pending updates are lost. /// /// If the file is opened for update (passing \c #kXMPFiles_OpenForUpdate), the disk file /// remains open until \c CloseFile() is called. The disk file is only updated once, when /// \c CloseFile() is called, regardless of how many calls are made to \c PutXMP(). /// /// Typically, the XMP is not parsed and legacy reconciliation is not performed until \c GetXMP() /// is called, but this is not guaranteed. Specific file handlers might do earlier parsing of /// the XMP. Delayed parsing and early disk file close for read-only access are optimizations /// to help clients implementing file browsers, so that they can access the file briefly /// and possibly display a thumbnail, then postpone more expensive XMP processing until later. /// /// @param filePath The path for the file, appropriate for the local operating system. Passed as /// a nul-terminated UTF-8 string. /// /// @param format The format of the file. If the format is unknown (\c #kXMP_UnknownFile) the /// format is determined from the file content. The first handler to check is guessed from the /// file's extension. Passing a specific format value is generally just a hint about what file /// handler to try first (instead of the one based on the extension). If /// \c #kXMPFiles_OpenStrictly is set, then any format other than \c #kXMP_UnknownFile requires /// that the file actually be that format; otherwise an exception is thrown. /// /// @param openFlags A set of option flags that describe the desired access. By default (zero) /// the file is opened for read-only access and the format handler decides on the level of /// reconciliation that will be performed. A logical OR of these bit-flag constants: /// /// \li \c #kXMPFiles_OpenForRead - Open for read-only access. /// \li \c #kXMPFiles_OpenForUpdate - Open for reading and writing. /// \li \c #kXMPFiles_OpenOnlyXMP - Only the XMP is wanted, no reconciliation. /// \li \c #kXMPFiles_OpenStrictly - Be strict about locating XMP and reconciling with other /// forms. By default, a best effort is made to locate the correct XMP and to reconcile XMP /// with other forms (if reconciliation is done). This option forces stricter rules, resulting /// in exceptions for errors. The definition of strictness is specific to each handler, there /// might be no difference. /// \li \c #kXMPFiles_OpenUseSmartHandler - Require the use of a smart handler. /// \li \c #kXMPFiles_OpenUsePacketScanning - Force packet scanning, do not use a smart handler. /// \li \c #kXMPFiles_OptimizeFileLayout - When updating a file, spend the effort necessary /// to optimize file layout. /// /// @return True if the file is succesfully opened and attached to a file handler. False for /// anticipated problems, such as passing \c #kXMPFiles_OpenUseSmartHandler but not having an /// appropriate smart handler. Throws an exception for serious problems. bool OpenFile ( XMP_StringPtr filePath, XMP_FileFormat format = kXMP_UnknownFile, XMP_OptionBits openFlags = 0 ); // --------------------------------------------------------------------------------------------- /// @brief \c OpenFile() opens a file for metadata access, using a string object /// /// Overloads the basic form of the function, allowing you to pass a string object for the file /// path. It is otherwise identical; see details in the canonical form. bool OpenFile ( const tStringObj & filePath, XMP_FileFormat format = kXMP_UnknownFile, XMP_OptionBits openFlags = 0 ); #if XMP_StaticBuild // ! Client XMP_IO objects can only be used in static builds. // --------------------------------------------------------------------------------------------- /// @brief \c OpenFile() opens a client-provided XMP_IO object for metadata access. /// /// Alternative to the basic form of the function, allowing you to pass an XMP_IO object for /// client-managed I/O. /// bool OpenFile ( XMP_IO * clientIO, XMP_FileFormat format = kXMP_UnknownFile, XMP_OptionBits openFlags = 0 ); #endif // --------------------------------------------------------------------------------------------- /// @brief CloseFile() explicitly closes an opened file. /// /// Performs any necessary output to the file and closes it. Files that are opened for update /// are written to only when closing. /// /// If the file is opened for read-only access (passing \c #kXMPFiles_OpenForRead), the disk /// file is closed immediately after reading the data from it; the \c XMPFiles object, however, /// remains in the open state. You must call \c CloseFile() when finished using it. Other /// methods, such as \c GetXMP(), can only be used between the \c OpenFile() and \c CloseFile() /// calls. The \c XMPFiles destructor does not call \c CloseFile(); if you call it without closing, /// any pending updates are lost. /// /// If the file is opened for update (passing \c #kXMPFiles_OpenForUpdate), the disk file remains /// open until \c CloseFile() is called. The disk file is only updated once, when \c CloseFile() /// is called, regardless of how many calls are made to \c PutXMP(). When in-place update is not possible /// we might write into a temporary file and then swap for corruption/crash safety. /* Documenatation update for CTECHXMP-4170278*/ /// /// @param closeFlags Option flags for optional closing actions. This bit-flag constant is /// defined: /// /// \li \c #kXMPFiles_UpdateSafely - Write into a temporary file then swap for crash safety. void CloseFile ( XMP_OptionBits closeFlags = 0 ); // --------------------------------------------------------------------------------------------- /// @brief \c GetFileInfo() retrieves basic information about an opened file. /// /// @param filePath [out] A buffer in which to return the path passed to \c OpenFile(). Can be /// null if value is not wanted. /// /// @param openFlags [out] A buffer in which to return the option flags passed to /// \c OpenFile(). Can be null if value is not wanted. /// /// @param format [out] A buffer in which to return the file format. Can be null if value is not /// wanted. /// @param handlerFlags [out] A buffer in which to return the handler's capability flags. Can /// be null if value is not wanted. /// /// @return True if the file object is in the open state; that is, \c OpenFile() has been called /// but \c CloseFile() has not. False otherwise. Even if the file object is open, the actual /// disk file might be closed in the host file-system sense; see \c OpenFile(). bool GetFileInfo ( tStringObj * filePath = 0, XMP_OptionBits * openFlags = 0, XMP_FileFormat * format = 0, XMP_OptionBits * handlerFlags = 0 ); // --------------------------------------------------------------------------------------------- /// @brief \c SetAbortProc() registers a callback function used to check for a user-signaled abort. /// /// The specified procedure is called periodically to allow a user to cancel time-consuming /// operations. The callback function should return true to signal an abort, which results in an /// exception being thrown. /// /// @param abortProc The callback function. /// /// @param abortArg A pointer to caller-defined data to pass to the callback function. void SetAbortProc ( XMP_AbortProc abortProc, void * abortArg ); /// @} // ============================================================================================= /// \name Accessing metadata /// @{ /// /// These functions allow you to retrieve XMP metadata from open files, so that you can use the /// \c TXMPMeta API to manipulate it. The \c PutXMP() functions update the XMP packet in memory. /// Changed XMP is not actually written out to the file until the file is closed. // --------------------------------------------------------------------------------------------- /// @brief \c GetXMP() retrieves the XMP metadata from an open file. /// /// The function reports whether XMP is present in the file; you can choose to retrieve any or /// all of the parsed XMP, the raw XMP packet,or information about the raw XMP packet. The /// options provided when the file was opened determine if reconciliation is done with other /// forms of metadata. /// /// @param xmpObj [out] An XMP object in which to return the parsed XMP metadata. Can be null. /// /// @param xmpPacket [out] An string object in which to return the raw XMP packet as stored in /// the file. Can be null. The encoding of the packet is given in the \c packetInfo. Returns an /// empty string if the low level file handler does not provide the raw packet. /// /// @param packetInfo [out] An string object in which to return the location and form of the raw /// XMP in the file. \c #XMP_PacketInfo::charForm and \c #XMP_PacketInfo::writeable reflect the /// raw XMP in the file. The parsed XMP property values are always UTF-8. The writeable flag is /// taken from the packet trailer; it applies only to "format ignorant" writing. The /// \c #XMP_PacketInfo structure always reflects the state of the XMP in the file. The offset, /// length, and character form do not change as a result of calling \c PutXMP() unless the file /// is also written. Some file handlers might not return location or contents of the raw packet /// string. To determine whether one does, check the \c #kXMPFiles_ReturnsRawPacket bit returned /// by \c GetFormatInfo(). If the low-level file handler does not provide the raw packet /// location, \c #XMP_PacketInfo::offset and \c #XMP_PacketInfo::length are both 0, /// \c #XMP_PacketInfo::charForm is UTF-8, and \c #XMP_PacketInfo::writeable is false. /// /// @return True if the file has XMP, false otherwise. bool GetXMP ( SXMPMeta * xmpObj = 0, tStringObj * xmpPacket = 0, XMP_PacketInfo * packetInfo = 0 ); // --------------------------------------------------------------------------------------------- /// @brief \c PutXMP() updates the XMP metadata in this object without writing out the file. /// /// This function supplies new XMP for the file. However, the disk file is not written until the /// object is closed with \c CloseFile(). The options provided when the file was opened /// determine if reconciliation is done with other forms of metadata. /// /// @param xmpObj The new metadata as an XMP object. void PutXMP ( const SXMPMeta & xmpObj ); // --------------------------------------------------------------------------------------------- /// @brief \c PutXMP() updates the XMP metadata in this object without writing out the file, /// using a string object for input. /// /// Overloads the basic form of the function, allowing you to pass the metadata as a string object /// instead of an XMP object. It is otherwise identical; see details in the canonical form. /// /// @param xmpPacket The new metadata as a string object containing a complete XMP packet. void PutXMP ( const tStringObj & xmpPacket ); // --------------------------------------------------------------------------------------------- /// @brief \c PutXMP() updates the XMP metadata in this object without writing out the file, /// using a string object and optional length. /// /// Overloads the basic form of the function, allowing you to pass the metadata as a string object /// instead of an XMP object. It is otherwise identical; see details in the canonical form. /// /// @param xmpPacket The new metadata as a const char * string containing an XMP packet. /// /// @param xmpLength Optional. The number of bytes in the string. If not supplied, the string is /// assumed to be nul-terminated. void PutXMP ( XMP_StringPtr xmpPacket, XMP_StringLen xmpLength = kXMP_UseNullTermination ); // --------------------------------------------------------------------------------------------- /// @brief \c CanPutXMP() reports whether this file can be updated with a specific XMP packet. /// /// Use to determine if the file can probably be updated with a given set of XMP metadata. This /// depends on the size of the packet, the options with which the file was opened, and the /// capabilities of the handler for the file format. The function obtains the length of the /// serialized packet for the provided XMP, but does not keep it or modify it, and does not /// cause the file to be written when closed. This is implemented roughly as follows: /// /// 
    /// bool CanPutXMP ( XMP_StringPtr xmpPacket )
    /// {
    ///    XMP_FileFormat format;
    ///    this->GetFileInfo ( 0, &format, 0 );
    ///
    ///    XMP_OptionBits formatFlags;
    ///    GetFormatInfo ( format, &formatFlags );
    ///
    ///    if ( (formatFlags & kXMPFiles_CanInjectXMP) && (formatFlags & kXMPFiles_CanExpand) ) return true;
    ///
    ///    XMP_PacketInfo packetInfo;
    ///    bool hasXMP = this->GetXMP ( 0, 0, &packetInfo );
    ///
    ///    if ( ! hasXMP ) {
    ///       if ( formatFlags & kXMPFiles_CanInjectXMP ) return true;
    ///    } else {
    ///       if ( (formatFlags & kXMPFiles_CanExpand) ||
    ///            (packetInfo.length >= strlen(xmpPacket)) ) return true;
    ///    }
    ///    return false;
    /// }
    ///
/// /// @param xmpObj The proposed new metadata as an XMP object. bool CanPutXMP ( const SXMPMeta & xmpObj ); // --------------------------------------------------------------------------------------------- /// @brief \c CanPutXMP() reports whether this file can be updated with a specific XMP packet, /// passed in a string object. /// /// Overloads the basic form of the function, allowing you to pass the metadata as a string object /// instead of an XMP object. It is otherwise identical; see details in the canonical form. /// /// @param xmpPacket The proposed new metadata as a string object containing an XMP packet. bool CanPutXMP ( const tStringObj & xmpPacket ); // --------------------------------------------------------------------------------------------- /// @brief \c CanPutXMP() reports whether this file can be updated with a specific XMP packet, /// passed in a string object. /// /// Overloads the basic form of the function, allowing you to pass the metadata as a string object /// instead of an XMP object. It is otherwise identical; see details in the canonical form. /// /// @param xmpPacket The proposed new metadata as a const char * string containing an XMP packet. /// /// @param xmpLength Optional. The number of bytes in the string. If not supplied, the string /// is assumed to be nul-terminated. bool CanPutXMP ( XMP_StringPtr xmpPacket, XMP_StringLen xmpLength = kXMP_UseNullTermination ); /// @} // ============================================================================================= /// \name Progress notifications /// @{ /// /// These functions allow track the progress of file operations. Initially only file updates are /// tracked, these all occur within calls to SXMPFiles::CloseFile. There are no plans to track /// other operations at this time. Tracking support must be added to specific file handlers, /// there are no guarantees about which handlers will have support. To simplify the logic only /// file writes will be estimated and measured. // --------------------------------------------------------------------------------------------- /// @brief \c SetDefaultProgressCallback() sets a global default for progress tracking. This is /// used as a default for XMPFiles (library) objects created after the default is set. This does /// not affect the callback for new SXMPFiles (client) objects with an existing XMPFiles object. /// /// @param proc The client's callback function. Can be zero to disable notifications. /// /// @param context A pointer used to carry client-private context. /// /// @param interval The desired number of seconds between notifications. Ideally the first /// notification is sent after this interval, then at each following multiple of this interval. /// /// @param sendStartStop A Boolean value indicating if initial and final notifications are /// wanted in addition to those at the reporting intervals. static void SetDefaultProgressCallback ( XMP_ProgressReportProc proc, void * context = 0, float interval = 1.0, bool sendStartStop = false ); // --------------------------------------------------------------------------------------------- /// @brief \c SetProgressCallback() sets the progress notification callback for the associated /// XMPFiles (library) object. /// /// @param proc The client's callback function. Can be zero to disable notifications. /// /// @param context A pointer used to carry client-private context. /// /// @param interval The desired number of seconds between notifications. Ideally the first /// notification is sent after this interval, then at each following multiple of this interval. /// /// @param sendStartStop A Boolean value indicating if initial and final notifications are /// wanted in addition to those at the reporting intervals. void SetProgressCallback ( XMP_ProgressReportProc proc, void * context = 0, float interval = 1.0, bool sendStartStop = false ); /// @} // ============================================================================================= // Error notifications // =================== // --------------------------------------------------------------------------------------------- /// \name Error notifications /// @{ /// /// From the beginning through version 5.5, XMP Toolkit errors result in throwing an \c XMP_Error /// exception. For the most part exceptions were thrown early and thus API calls aborted as soon /// as an error was detected. Starting in version 5.5, support has been added for notifications /// of errors arising in calls to \c TXMPFiles functions. /// /// A client can register an error notification callback function for a \c TXMPFile object. This /// can be done as a global default or individually to each object. The global default applies /// to all objects created after it is registered. Within the object there is no difference /// between the global default or explicitly registered callback. The callback function returns /// a \c bool value indicating if recovery should be attempted (true) or an exception thrown /// (false). If no callback is registered, a best effort at recovery and continuation will be /// made with an exception thrown if recovery is not possible. /// /// The number of notifications delivered for a given TXMPFiles object can be limited. This is /// intended to reduce chatter from multiple or cascading errors. The limit is set when the /// callback function is registered. This limits the number of notifications of the highest /// severity delivered or less. If a higher severity error occurs, the counting starts again. /// The limit and counting can be reset at any time, see \c ResetErrorCallbackLimit. // -------------------------------------------------------------------------------------------- /// @brief SetDefaultErrorCallback() registers a global default error notification callback. /// /// @param proc The client's callback function. /// /// @param context Client-provided context for the callback. /// /// @param limit A limit on the number of notifications to be delivered. static void SetDefaultErrorCallback ( XMPFiles_ErrorCallbackProc proc, void* context = 0, XMP_Uns32 limit = 1 ); // -------------------------------------------------------------------------------------------- /// @brief SetErrorCallback() registers an error notification callback. /// /// @param proc The client's callback function. /// /// @param context Client-provided context for the callback. /// /// @param limit A limit on the number of notifications to be delivered. void SetErrorCallback ( XMPFiles_ErrorCallbackProc proc, void* context = 0, XMP_Uns32 limit = 1 ); // -------------------------------------------------------------------------------------------- /// @brief ResetErrorCallbackLimit() resets the error notification limit and counting. It has no /// effect if an error notification callback function is not registered. /// /// @param limit A limit on the number of notifications to be delivered. void ResetErrorCallbackLimit ( XMP_Uns32 limit = 1 ); /// @} // ============================================================================================= private: XMPFilesRef xmpFilesRef; // These are used as callbacks from the library code to the client when returning values that // involve heap allocations. This ensures the allocations occur within the client. static void SetClientString ( void * clientPtr, XMP_StringPtr valuePtr, XMP_StringLen valueLen ); static void SetClientStringVector ( void * clientPtr, XMP_StringPtr* arrayPtr, XMP_Uns32 stringCount ); }; // class TXMPFiles // ================================================================================================= #endif // __TXMPFiles_hpp__