summaryrefslogtreecommitdiff
path: root/public/include/TXMPFiles.hpp
diff options
context:
space:
mode:
Diffstat (limited to 'public/include/TXMPFiles.hpp')
-rw-r--r--public/include/TXMPFiles.hpp767
1 files changed, 492 insertions, 275 deletions
diff --git a/public/include/TXMPFiles.hpp b/public/include/TXMPFiles.hpp
index 499dfb9..00c0b7d 100644
--- a/public/include/TXMPFiles.hpp
+++ b/public/include/TXMPFiles.hpp
@@ -14,393 +14,610 @@
// of the Adobe license agreement accompanying it.
// =================================================================================================
-// ================================================================================================
+// =================================================================================================
/// \file TXMPFiles.hpp
-/// \brief API for access to the "main" metadata in a file.
+/// \brief API for access to the main (document-level) 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.
+/// 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
-/// particulary appropriate for files authored by an application. I.e. those files for which the
+/// \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" metadata in a file.
+/// \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.
///
-/// \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.
+/// 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.
///
-/// Errors result in the throw of an \c XMPError exception.
+/// 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.
///
-/// 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.
+/// \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.
///
-/// 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
-// ================================================================================================
+/// Access these functions through the concrete class, \c SXMPFiles.
+// =================================================================================================
+
template <class tStringObj>
class TXMPFiles {
public:
-
- // ============================================================================================
+
+ // =============================================================================================
/// \name Initialization and termination
/// @{
- /// \c SXMPFiles must be initialized before use and may be terminated when done.
+ ///
+ /// 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 \c Initialize must be called before using \c SXMPFiles. It returns a Boolean
- /// success/failure value.
-
+ // ---------------------------------------------------------------------------------------------
+ /// @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 only one option is defined, \c kXMPFiles_NoQuickTimeInit. This option
+ /// prevents calling the QuickTime initialization on Windows, which can be slow. The MOV file
+ /// handler on Windows uses Apple's QuickTime SDK for the actual file I/O.
+ ///
+ /// 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 \c Terminate may be called when done using \c SXMPFiles. It deallocates global data
- /// structures created by \c Initialize.
+ // ---------------------------------------------------------------------------------------------
+ /// @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 OpenFile. The destructor automatically calls CloseFile if necessary.
-
- /// \brief The default constructor initializes an object that is associated with no file.
-
+ /// 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 These alternate constructors call \c OpenFile. The second form is a trivial overload
- /// that calls the first form passing \c filePath.c_str().
-
+ // ---------------------------------------------------------------------------------------------
+ /// @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_OpenCacheTNail
+ /// \li \c #kXMPFiles_OpenStrictly
+ /// \li \c #kXMPFiles_OpenUseSmartHandler
+ /// \li \c #kXMPFiles_OpenUsePacketScanning
+ /// \li \c #kXMPFiles_OpenLimitedScanning
+ /// \li \c #kXMPFiles_OpenInBackground
+ ///
+ /// @return The new \c TXMPFiles object.
+
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 The copy constructor and assignment operator increment an internal reference count,
- /// they do not perform a deep copy.
-
+ // ---------------------------------------------------------------------------------------------
+ /// @brief Copy constructor
+ ///
+ /// Increments an internal reference count but does not perform a deep copy.
+ ///
+ /// @param original The existing \c TXMPFiles object to copy.
+ ///
+ /// @return The new \c TXMPFiles object.
+
TXMPFiles ( const TXMPFiles<tStringObj> & 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<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.
-
+ // ---------------------------------------------------------------------------------------------
+ /// @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().
+ ///
+ /// @return The new object.
+
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 Static Functions
+
+ // =============================================================================================
+ /// \name File handler information
/// @{
-
- // --------------------------------------------------------------------------------------------
- /// \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.
+ /// 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.
///
- /// \param format The format whose support flags are desired.
+ ///This function is static; make the call directly from the concrete class (\c SXMPFiles).
///
- /// \param handlerFlags A set of option bits showing the support for this format:
+ /// @param format The file format whose support flags are desired.
///
- /// \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.
+ /// @param handlerFlags [out] A buffer in which to return a logical OR of option bit flags.
+ /// The following constants are defined:
///
- /// The kXMPFiles_AllowsOnlyXMP flag is only meaningful if kXMPFiles_CanReconcile is set.
+ /// \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_ReturnsTNail - File handler returns native thumbnail information.
+ /// \li \c #kXMPFiles_ReturnsRawPacket - File handler returns raw XMP packet information and string.
///
- /// 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.
+ /// 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.
///
- /// \result Returns true if the format has explicit "smart" support. Returns false if the format
- /// is handled by the default packet scanning plus heuristics.
-
+ /// @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 OpenFile, CloseFile, and related file-oriented operations
+
+ // =============================================================================================
+ /// \name File operations
/// @{
-
- // --------------------------------------------------------------------------------------------
- /// \brief Open a file for metadata access.
+ ///
+ /// These functions allow you to open, close, and query files.
+
+ // ---------------------------------------------------------------------------------------------
+ /// @brief \c CheckFileFormat() tries to determine the format of a file.
+ ///
+ /// \c CheckFileFormat tries to determine the format of a file, returning an XMP_FileFormat value.
+ /// It uses the same logic as \c OpenFile will use 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, otherwise \c kXMP_UnknownFile.
+
+ static XMP_FileFormat CheckFileFormat ( XMP_StringPtr filePath );
+
+ // ---------------------------------------------------------------------------------------------
+ /// @brief \c CheckPackageFormat() tries to determine the format of a "package" folder.
+ ///
+ /// \c CheckPackageFormat tries to determine the format of a "package" given the name of the top
+ /// level folder, returning an 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. The path is not the same as would be passed
+ /// to \c OpenFile. For example the path passed to \c CheckPackageFormat might be ".../MyMovie",
+ /// while the path passed to \c OpenFile would be ".../MyMovie/SomeClip".
+ ///
+ /// @return The package's format if a smart handler would be selected, otherwise \c kXMP_UnknownFile.
+
+ static XMP_FileFormat CheckPackageFormat ( XMP_StringPtr folderPath );
+
+ // ---------------------------------------------------------------------------------------------
+ /// @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 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
+ /// metadata reconciliation then legacy metadata is also read, unless \c #kXMPFiles_OpenOnlyXMP
+ /// is passed. If the file handler supports native thumbnails and \c #kXMPFiles_OpenCacheTNail
+ /// is passed, the native thumbnail is cached.
+ ///
+ /// 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 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.
+ /// @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_OpenCacheTNail - Cache thumbnail if possible, GetThumbnail will be called.
+ /// \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.
+ ///
+ /// @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 );
- // --------------------------------------------------------------------------------------------
- /// \brief Close an opened file.
+ // ---------------------------------------------------------------------------------------------
+ /// @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.
///
- /// \param closeFlags A set of bit flags for optional closing actions.
+ /// 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.
///
- /// The defined closeFlags bits are:
+ /// 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().
///
- /// \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 closeFlags Option flags for optional closing actions. This bit-flag constant is
+ /// defined:
///
- /// \param filePath If not null, returns the path passed to OpenFile.
+ /// \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 openFlags If not null, returns the flags passed to OpenFile.
+ /// @param filePath [out] A buffer in which to return the path passed to \c OpenFile(). Can be
+ /// null if value is not wanted.
///
- /// \param format If not null, returns the format of the file.
+ /// @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 handlerFlags If not null, returns the handler's capability flags.
+ /// @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.
///
- /// \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.
-
+ /// @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 Set the callback function used to check for a user signaled abort.
+
+ // ---------------------------------------------------------------------------------------------
+ /// @brief \c SetAbortProc() registers a 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.
+ /// 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 abortArg An argument passed to the callback function.
+ /// @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 Metadata Access Functions
+
+ // =============================================================================================
+ /// \name Accessing metadata
/// @{
-
- // --------------------------------------------------------------------------------------------
- /// \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.
-
+ /// 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 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.
-
+
+ // ---------------------------------------------------------------------------------------------
+ /// @brief \c GetThumbnail() retrieves the native thumbnail from an open file.
+ ///
+ /// Use this function to obtain native thumbnail information, if the associated file handler
+ /// supports that and the thumbnail was cached by the call to \c OpenFile(); that is, the
+ /// \c #kXMPFiles_OpenCacheTNail option flag was set. The return value reports whether a thumbnail
+ /// is present in the file.
+ ///
+ /// The returned thumbnail information can be incomplete, depending on the file format, the file
+ /// handler's capabilities, and the specific file content.
+ ///
+ /// \li The \c #XMP_ThumbnailInfo::fullWidth, \c fullHeight, and \c 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, and so on. The field values are zero if not
+ /// meaningful or not determined.
+ /// \li The \c #XMP_ThumbnailInfo::tnailImage and \c #XMP_ThumbnailInfo::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
+ /// return as a single contiguous block of thumbnail data. For example, for a TIFF uncompressed
+ /// thumbnail, the handler might not have logic to gather the various disjoint pieces of the
+ /// thumbnail from the overall TIFF stream.
+ ///
+ /// @param tnailInfo [out] Optional. A buffer in which to return information about a recognized
+ /// native thumbnail, and related information about the primary image if appropriate. Can be
+ /// null if the information is not desired.
+ ///
+ /// @return True if a recognized native thumbnail is present and the thumbnail was cached by the
+ /// call to \c OpenFile(); that is, the \c #kXMPFiles_OpenCacheTNail option flag was set. Can
+ /// return true even if the function cannot retrieve the actual thumbnail image.
+
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.
-
+
+ // ---------------------------------------------------------------------------------------------
+ /// @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 <tt>const char *</tt> 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 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
-
+
+ // ---------------------------------------------------------------------------------------------
+ /// @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:
+ ///
+ /// <pre>
+ /// 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;
+ /// }
+ /// </pre>
+ ///
+ /// @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 <tt>const char *</tt> 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 );