You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
419 lines
21 KiB
C++
419 lines
21 KiB
C++
#ifndef __TXMPFiles_hpp__
|
|
#define __TXMPFiles_hpp__ 1
|
|
|
|
#if ( ! __XMP_hpp__ )
|
|
#error "Do not directly include, use XMP.hpp"
|
|
#endif
|
|
|
|
// =================================================================================================
|
|
// ADOBE SYSTEMS INCORPORATED
|
|
// Copyright 2002-2007 Adobe Systems Incorporated
|
|
// 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" metadata in a file.
|
|
///
|
|
/// \c TXMPFiles provides the API for the Adobe XMP Toolkit's File Handler component. This provides
|
|
/// convenient access to the main, or document level, XMP for a file. The File Handler supports file
|
|
/// I/O, the XMP Toolkit Core supports manipulation of the XMP properties. The File Handler is
|
|
/// intended to eventually have smart, efficient support for all file formats for which the means to
|
|
/// embed XMP is defined in the XMP Specification. Where possible this support will allow injection
|
|
/// of XMP where none currently exists, expansion of XMP without regard to existing padding, and
|
|
/// 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
|
|
/// particulary appropriate for files authored by an application. I.e. those files for which the
|
|
/// application has explicit knowledge of the file format.
|
|
// ================================================================================================
|
|
|
|
// ================================================================================================
|
|
/// \class TXMPFiles TXMPFiles.hpp
|
|
/// \brief API for access to the "main" metadata in a file.
|
|
///
|
|
/// \c TXMPFiles provides the API for the Adobe XMP Toolkit's File Handler component. This provides
|
|
/// convenient access to the main, or document level, XMP for a file. The general model is 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 on
|
|
/// file format and access options. The file may 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.
|
|
///
|
|
/// The template is instantiated with a string object class. This allows a clean implementation
|
|
/// that provides two major benefits: output string storage is fully owned by the client and access
|
|
/// is fully thread safe. The template parameter, class \c tStringObj, is described in the XMP.hpp
|
|
/// umbrella header.
|
|
///
|
|
/// To use TXMPFiles define TXMP_STRING_TYPE and XMP_INCLUDE_XMPFILES, then include the XMP.hpp
|
|
/// umbrella header:
|
|
/// \code
|
|
/// #define TXMP_STRING_TYPE std::string
|
|
/// #define XMP_INCLUDE_XMPFILES 1
|
|
/// #include "XMP.hpp"
|
|
/// \endcode
|
|
// ================================================================================================
|
|
|
|
template <class tStringObj>
|
|
class TXMPFiles {
|
|
|
|
public:
|
|
|
|
// ============================================================================================
|
|
/// \name Initialization and termination
|
|
/// @{
|
|
/// \c SXMPFiles must be initialized before use and may be terminated when done.
|
|
|
|
static void GetVersionInfo ( XMP_VersionInfo * versionInfo );
|
|
|
|
/// \brief \c Initialize must be called before using \c SXMPFiles. It returns a Boolean
|
|
/// success/failure value.
|
|
|
|
static bool Initialize();
|
|
static bool Initialize ( XMP_OptionBits options );
|
|
|
|
/// \brief \c Terminate may be called when done using \c SXMPFiles. It deallocates global data
|
|
/// structures created by \c Initialize.
|
|
|
|
static void Terminate();
|
|
|
|
/// @}
|
|
|
|
// ============================================================================================
|
|
/// \name Constructors and destructor
|
|
/// @{
|
|
/// The default constructor initializes an object that is associated with no file. The alternate
|
|
/// constructors call OpenFile. The destructor automatically calls CloseFile if necessary.
|
|
|
|
/// \brief The default constructor initializes an object that is associated with no file.
|
|
|
|
TXMPFiles();
|
|
virtual ~TXMPFiles() throw();
|
|
|
|
/// \brief These alternate constructors call \c OpenFile. The second form is a trivial overload
|
|
/// that calls the first form passing \c filePath.c_str().
|
|
|
|
TXMPFiles ( XMP_StringPtr filePath,
|
|
XMP_FileFormat format = kXMP_UnknownFile,
|
|
XMP_OptionBits openFlags = 0 );
|
|
|
|
TXMPFiles ( const tStringObj & filePath,
|
|
XMP_FileFormat format = kXMP_UnknownFile,
|
|
XMP_OptionBits openFlags = 0 );
|
|
|
|
/// \brief The copy constructor and assignment operator increment an internal reference count,
|
|
/// they do not perform a deep copy.
|
|
|
|
TXMPFiles ( const TXMPFiles<tStringObj> & original );
|
|
|
|
void operator= ( const TXMPFiles<tStringObj> & rhs );
|
|
|
|
/// \brief The "ref" constructor and \c GetInternalRef serve the same purpose as their analogs
|
|
/// in SXMPMeta, safely passing \c SXMPFiles references across DLL boundaries where the clients
|
|
/// might have used different string types when instantiating \c TXMPFiles.
|
|
|
|
TXMPFiles ( XMPFilesRef xmpFilesObj );
|
|
|
|
XMPFilesRef GetInternalRef();
|
|
|
|
/// @}
|
|
|
|
// ============================================================================================
|
|
/// \name Static Functions
|
|
/// @{
|
|
|
|
// --------------------------------------------------------------------------------------------
|
|
/// \brief Determine the supported features for a given file format.
|
|
///
|
|
/// The supported features can vary quite a bit among file formats, depending on both the
|
|
/// general capabilities of the format and the implementation of the handler for that format.
|
|
///
|
|
/// \param format The format whose support flags are desired.
|
|
///
|
|
/// \param handlerFlags A set of option bits showing the support for this format:
|
|
///
|
|
/// \li kXMPFiles_CanInjectXMP - Can inject first-time XMP into an existing file.
|
|
/// \li kXMPFiles_CanExpand - Can expand XMP or other metadata in an existing file.
|
|
/// \li kXMPFiles_CanRewrite - Can copy one file to another, writing new metadata.
|
|
/// \li kXMPFiles_CanReconcile - Supports reconciliation between XMP and other forms.
|
|
/// \li kXMPFiles_AllowsOnlyXMP - Allows access to just the XMP, ignoring other forms.
|
|
/// \li kXMPFiles_ReturnsRawPacket - File handler returns raw XMP packet information and string.
|
|
/// \li kXMPFiles_ReturnsTNail - File handler returns native thumbnail information.
|
|
///
|
|
/// The kXMPFiles_AllowsOnlyXMP flag is only meaningful if kXMPFiles_CanReconcile is set.
|
|
///
|
|
/// If 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.
|
|
///
|
|
/// \result Returns true if the format has explicit "smart" support. Returns false if the format
|
|
/// is handled by the default packet scanning plus heuristics.
|
|
|
|
static bool GetFormatInfo ( XMP_FileFormat format,
|
|
XMP_OptionBits * handlerFlags = 0 );
|
|
|
|
/// @}
|
|
|
|
// ============================================================================================
|
|
/// \name OpenFile, CloseFile, and related file-oriented operations
|
|
/// @{
|
|
|
|
// --------------------------------------------------------------------------------------------
|
|
/// \brief Open 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 will also be read, unless kXMPFiles_OpenOnlyXMP
|
|
/// is passed. If the file handler supports native thumbnails and kXMPFiles_OpenCacheTNail is
|
|
/// passed then the native thumbnail will also be cached.
|
|
///
|
|
/// If the file is opened for read-only access (passing kXMPFiles_OpenForRead), then the disk
|
|
/// file itself will be closed after reading the data from it. The XMPFiles object will not be
|
|
/// "closed" though, it is still necessary to call CloseFile when finished using it. Other
|
|
/// methods (GetXMP, etc.) can only be used between the OpenFile and CloseFile calls. The XMPFiles
|
|
/// destructor will not call CloseFile, any pending updates will be lost.
|
|
///
|
|
/// If the file is opened for update (passing kXMPFiles_OpenForUpdate), then the disk file remains
|
|
/// open until CloseFile is called. The disk file is only updated once, when Close file is called,
|
|
/// no matter how many calls are made to PutXMP.
|
|
///
|
|
/// Ideally the XMP is not parsed and legacy reconciliation is not performed until GetXMP is
|
|
/// called. This is not guaranteed though, specific file handlers might do earlier parsing of
|
|
/// the XMP. This delayed parsing and the early disk file close for read-only access are
|
|
/// optimizations to help clients implementing file browsers. They can access the file briefly
|
|
/// and possibly display a thumbnail, then postpone more expensive XMP processing until later.
|
|
///
|
|
/// \param filePath The UTF-8 path for the file, appropriate for the local OS. Overloads are
|
|
/// declared to pass the path as either a "const char *" or a string object.
|
|
///
|
|
/// \param format The format of the file. If the format is unknown pass \c kXMP_UnknownFile and
|
|
/// the format will be determined from the file content. The first handler to check will be
|
|
/// guessed from the file's extension. Passing any other format value is generally just a hint
|
|
/// about what file handler to try first (instead of the one based on the extension). If the
|
|
/// kXMPFiles_OpenStrictly is set, then any format other than kXMP_UnknownFile requires that the
|
|
/// file actually be that format, an exception is thrown if not.
|
|
///
|
|
/// \param openFlags A set of option bits describing 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. By default a best effort will be made to locate the
|
|
/// correct XMP and to reconcile XMP with other forms (if reconciliation is done). The option
|
|
/// \c kXMPFiles_OpenStrictly may be used to force more strict rules, resulting is exceptions for
|
|
/// errors. The definition of strictness is specific to each handler, there may be no difference.
|
|
///
|
|
/// The defined openFlag bits are:
|
|
///
|
|
/// \li kXMPFiles_OpenForRead - Open for read-only access.
|
|
/// \li kXMPFiles_OpenForUpdate - Open for reading and writing.
|
|
/// \li kXMPFiles_OpenOnlyXMP - Only the XMP is wanted, no reconciliation.
|
|
/// \li kXMPFiles_OpenCacheTNail - Cache thumbnail if possible, GetThumbnail will be called.
|
|
/// \li kXMPFiles_OpenStrictly - Be strict about locating XMP and reconciling with other forms.
|
|
/// \li kXMPFiles_OpenUseSmartHandler - Require the use of a smart handler.
|
|
/// \li kXMPFiles_OpenUsePacketScanning - Force packet scanning, don't use a smart handler.
|
|
///
|
|
/// \result Returns true if the file is succesfully opened and attached to a file handler.
|
|
/// Returns false for "anticipated" problems, e.g. passing 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 );
|
|
|
|
bool OpenFile ( const tStringObj & filePath,
|
|
XMP_FileFormat format = kXMP_UnknownFile,
|
|
XMP_OptionBits openFlags = 0 );
|
|
|
|
// --------------------------------------------------------------------------------------------
|
|
/// \brief Close 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.
|
|
///
|
|
/// \param closeFlags A set of bit flags for optional closing actions.
|
|
///
|
|
/// The defined closeFlags bits are:
|
|
///
|
|
/// \li kXMPFiles_UpdateSafely - Write into a temporary file then swap for crash safety.
|
|
|
|
void CloseFile ( XMP_OptionBits closeFlags = 0 );
|
|
|
|
// --------------------------------------------------------------------------------------------
|
|
/// \brief Get basic information about an opened file.
|
|
///
|
|
/// \param filePath If not null, returns the path passed to OpenFile.
|
|
///
|
|
/// \param openFlags If not null, returns the flags passed to OpenFile.
|
|
///
|
|
/// \param format If not null, returns the format of the file.
|
|
///
|
|
/// \param handlerFlags If not null, returns the handler's capability flags.
|
|
///
|
|
/// \result Returns true if a file is opened, false otherwise. This notion of "open" really means
|
|
/// that OpenFile has been called but CloseFile has not. The actual disk file might be closed in
|
|
/// the host file system sense, as explained for OpenFile.
|
|
|
|
bool GetFileInfo ( tStringObj * filePath = 0,
|
|
XMP_OptionBits * openFlags = 0,
|
|
XMP_FileFormat * format = 0,
|
|
XMP_OptionBits * handlerFlags = 0 );
|
|
|
|
// --------------------------------------------------------------------------------------------
|
|
/// \brief Set the callback function used to check for a user signaled abort.
|
|
///
|
|
/// \param abortProc The callback function used to check for a user signaled abort. It will be
|
|
/// called periodically to allow an abort of time consuming operations. The abort results in an
|
|
/// exception being thrown. The callback function should return true to signal an abort.
|
|
///
|
|
/// \param abortArg An argument passed to the callback function.
|
|
|
|
void SetAbortProc ( XMP_AbortProc abortProc,
|
|
void * abortArg );
|
|
|
|
/// @}
|
|
|
|
// ============================================================================================
|
|
/// \name Metadata Access Functions
|
|
/// @{
|
|
|
|
// --------------------------------------------------------------------------------------------
|
|
/// \brief Obtain the XMP.
|
|
///
|
|
/// \c GetXMP is used to obtain the parsed XMP, and/or the raw XMP packet, and/or information
|
|
/// about the raw XMP packet. If all parameters are null it simply tells if XMP is present or
|
|
/// not. The options provided when the file was opened determine if reconciliation is done with
|
|
/// other forms of metadata.
|
|
///
|
|
/// \param xmpObj If not null, returns the parsed XMP.
|
|
///
|
|
/// \param xmpPacket If not null, returns the raw XMP packet as stored in the file. The encoding
|
|
/// of the packet is given in the packetInfo. The string will be empty if the low level file
|
|
/// handler does not provide the raw packet.
|
|
///
|
|
/// \param packetInfo If not null, returns the location and form of the raw XMP in the file. The
|
|
/// charForm and writeable flag 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 is only relevant
|
|
/// for "format ignorant" writing.
|
|
///
|
|
/// \note The packetInfo struct always reflects the state of the XMP in the file. The offset,
|
|
/// length, and character form will not change as a result of calling \c PutXMP unless the file
|
|
/// is also written.
|
|
///
|
|
/// \note Some file handlers might not return location or contents of the raw packet string.
|
|
/// Check the \c kXMPFiles_ReturnsRawPacket bit returned by GetFormatInfo if you depend on this.
|
|
/// If the low level file handler does not provide the raw packet location then the offset and
|
|
/// length will both be 0, the charForm will be UTF-8, and the writeable flag will be false.
|
|
///
|
|
/// \result Returns true if the file has XMP, false otherwise.
|
|
|
|
bool GetXMP ( SXMPMeta * xmpObj = 0,
|
|
tStringObj * xmpPacket = 0,
|
|
XMP_PacketInfo * packetInfo = 0 );
|
|
|
|
// --------------------------------------------------------------------------------------------
|
|
/// \brief Obtain the native thumbnail.
|
|
///
|
|
/// \c GetThumbnail is used to obtain native thumbnail information, if the associated file
|
|
/// handler supports that and the thumbnail was cached by OpenFile. This requires that
|
|
/// kXMPFiles_OpenCacheTNail be passed to OpenFile. The tnailInfo output pointer can be null,
|
|
/// in which case GetThumbnail will simply tell if a recognized native thumbnail is present.
|
|
///
|
|
/// \param tnailInfo If not null, returns information about a recognized native thumbnail, and
|
|
/// some related information about the primary image if appropriate.
|
|
///
|
|
/// \note The returned thumbnail information can be incomplete. What gets returned can depend on
|
|
/// the file format, the file handler's capabilities, and the specific file content.
|
|
///
|
|
/// \li The fullHeight, fullWIdth, and fullOrientation fields are only meaningful for image files.
|
|
/// They are not meaningful for multi-page files such as PDF or InDesign, for dynamic audio or
|
|
/// video files, etc. The fields will be zero if not meaningful or not determined.
|
|
///
|
|
/// \li The tnailImage and tnailSize fields might be zero even if a "recognized" thumbnail is
|
|
/// present. Being recognized means only that the handler has determined that the file does
|
|
/// contain a native thumbnail. The thumbnail data might be of a format that the file handler
|
|
/// cannot (or does not) return a single contiguous block of thumbnail data. A possible case of
|
|
/// this is a TIFF uncompressed thumbnail, the handler might not have logic to gather the various
|
|
/// disjoint pieces of the thumbnail from the overall TIFF stream.
|
|
///
|
|
/// \result Returns true if a recognized native thumbnail is presentand the thumbnail was
|
|
/// cached by OpenFile. This requires that kXMPFiles_OpenCacheTNail be passed to OpenFile. Note
|
|
/// that GetThumbnail can return true but still not return an actual thumbnail image, see the
|
|
/// above note.
|
|
|
|
bool GetThumbnail ( XMP_ThumbnailInfo * tnailInfo );
|
|
|
|
// --------------------------------------------------------------------------------------------
|
|
/// \brief Update the XMP.
|
|
///
|
|
/// \c PutXMP supplies new XMP for the file. However, the file is not actully written until
|
|
/// closed. The options provided when the file was opened determine if reconciliation is done
|
|
/// with other forms of metadata. Overloads are provided to pass the XMP as an XMP
|
|
/// object, a string object, or a "const char *" plus length.
|
|
|
|
void PutXMP ( const SXMPMeta & xmpObj );
|
|
|
|
void PutXMP ( const tStringObj & xmpPacket );
|
|
|
|
void PutXMP ( XMP_StringPtr xmpPacket,
|
|
XMP_StringLen xmpLength = kXMP_UseNullTermination );
|
|
|
|
// --------------------------------------------------------------------------------------------
|
|
/// \brief Determine if the XMP can be updated.
|
|
///
|
|
/// \c CanPutXMP determines if the XMP can (probably) be updated. The provided XMP is only used
|
|
/// to obtain the length of the serialized packet. The new XMP is not kept, calling this will
|
|
/// not cause the file to be written when closed. Overloads are provided to pass the XMP as an
|
|
/// XMP object, a string object, or a "const char *" plus length. This is implemented roughly
|
|
/// as:
|
|
///
|
|
/// \code
|
|
/// 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;
|
|
///
|
|
/// }
|
|
/// \endcode
|
|
|
|
bool CanPutXMP ( const SXMPMeta & xmpObj );
|
|
|
|
bool CanPutXMP ( const tStringObj & xmpPacket );
|
|
|
|
bool CanPutXMP ( XMP_StringPtr xmpPacket,
|
|
XMP_StringLen xmpLength = kXMP_UseNullTermination );
|
|
|
|
/// @}
|
|
|
|
// =============================================================================================
|
|
|
|
private:
|
|
XMPFilesRef xmpFilesRef;
|
|
|
|
}; // class TXMPFiles
|
|
|
|
// =================================================================================================
|
|
|
|
#endif // __TXMPFiles_hpp__
|