TXMPFiles< tStringObj > Class Template Reference

API for access to the "main" metadata in a file. More...

#include <TXMPFiles.hpp>

List of all members.

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.

 TXMPFiles ()
 The default constructor initializes an object that is associated with no file.
virtual ~TXMPFiles () throw ()
 TXMPFiles (XMP_StringPtr filePath, XMP_FileFormat format=kXMP_UnknownFile, XMP_OptionBits openFlags=0)
 These alternate constructors call OpenFile. The second form is a trivial overload that calls the first form passing filePath.c_str().
 TXMPFiles (const tStringObj &filePath, XMP_FileFormat format=kXMP_UnknownFile, XMP_OptionBits openFlags=0)
 TXMPFiles (const TXMPFiles< tStringObj > &original)
 The copy constructor and assignment operator increment an internal reference count, they do not perform a deep copy.
void operator= (const TXMPFiles< tStringObj > &rhs)
 TXMPFiles (XMPFilesRef xmpFilesObj)
 The "ref" constructor and GetInternalRef serve the same purpose as their analogs in SXMPMeta, safely passing SXMPFiles references across DLL boundaries where the clients might have used different string types when instantiating TXMPFiles.
XMPFilesRef GetInternalRef ()

Public Member Functions

OpenFile, CloseFile, and related file-oriented operations
bool OpenFile (XMP_StringPtr filePath, XMP_FileFormat format=kXMP_UnknownFile, XMP_OptionBits openFlags=0)
 Open a file for metadata access.
void CloseFile (XMP_OptionBits closeFlags=0)
 Close an opened file.
bool GetFileInfo (tStringObj *filePath=0, XMP_OptionBits *openFlags=0, XMP_FileFormat *format=0, XMP_OptionBits *handlerFlags=0)
 Get basic information about an opened file.
void SetAbortProc (XMP_AbortProc abortProc, void *abortArg)
 Set the callback function used to check for a user signaled abort.
Metadata Access Functions
bool GetXMP (SXMPMeta *xmpObj=0, tStringObj *xmpPacket=0, XMP_PacketInfo *packetInfo=0)
 Obtain the XMP.
bool GetThumbnail (XMP_ThumbnailInfo *tnailInfo)
 Obtain the native thumbnail.
void PutXMP (const SXMPMeta &xmpObj)
 Update the XMP.
bool CanPutXMP (const SXMPMeta &xmpObj)
 Determine if the XMP can be updated.

Static Public Member Functions

Initialization and termination
SXMPFiles must be initialized before use and may be terminated when done.

static void GetVersionInfo (XMP_VersionInfo *versionInfo)
static bool Initialize ()
 Initialize must be called before using SXMPFiles. It returns a Boolean success/failure value.
static bool Initialize (XMP_OptionBits options)
static void Terminate ()
 Terminate may be called when done using SXMPFiles. It deallocates global data structures created by Initialize.
Static Functions
static bool GetFormatInfo (XMP_FileFormat format, XMP_OptionBits *handlerFlags=0)
 Determine the supported features for a given file format.


Detailed Description

template<class tStringObj>
class TXMPFiles< tStringObj >

API for access to the "main" metadata in a file.

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

  #define TXMP_STRING_TYPE std::string
  #define XMP_INCLUDE_XMPFILES 1
  #include "XMP.hpp"


Member Function Documentation

template<class tStringObj>
static bool TXMPFiles< tStringObj >::GetFormatInfo ( XMP_FileFormat  format,
XMP_OptionBits handlerFlags = 0 
) [static]

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.

Parameters:
format The format whose support flags are desired.
handlerFlags A set of option bits showing the support for this format:
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.

Returns:
Returns true if the format has explicit "smart" support. Returns false if the format is handled by the default packet scanning plus heuristics.

template<class tStringObj>
bool TXMPFiles< tStringObj >::OpenFile ( XMP_StringPtr  filePath,
XMP_FileFormat  format = kXMP_UnknownFile,
XMP_OptionBits  openFlags = 0 
)

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.

Parameters:
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.
format The format of the file. If the format is unknown pass 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.
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 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:

Returns:
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.

template<class tStringObj>
void TXMPFiles< tStringObj >::CloseFile ( XMP_OptionBits  closeFlags = 0  ) 

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.

Parameters:
closeFlags A set of bit flags for optional closing actions.
The defined closeFlags bits are:

template<class tStringObj>
bool TXMPFiles< tStringObj >::GetFileInfo ( tStringObj *  filePath = 0,
XMP_OptionBits openFlags = 0,
XMP_FileFormat *  format = 0,
XMP_OptionBits handlerFlags = 0 
)

Get basic information about an opened file.

Parameters:
filePath If not null, returns the path passed to OpenFile.
openFlags If not null, returns the flags passed to OpenFile.
format If not null, returns the format of the file.
handlerFlags If not null, returns the handler's capability flags.
Returns:
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.

template<class tStringObj>
void TXMPFiles< tStringObj >::SetAbortProc ( XMP_AbortProc  abortProc,
void *  abortArg 
)

Set the callback function used to check for a user signaled abort.

Parameters:
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.
abortArg An argument passed to the callback function.

template<class tStringObj>
bool TXMPFiles< tStringObj >::GetXMP ( SXMPMeta *  xmpObj = 0,
tStringObj *  xmpPacket = 0,
XMP_PacketInfo *  packetInfo = 0 
)

Obtain the XMP.

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.

Parameters:
xmpObj If not null, returns the parsed XMP.
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.
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 PutXMP unless the file is also written.

Some file handlers might not return location or contents of the raw packet string. Check the 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.

Returns:
Returns true if the file has XMP, false otherwise.

template<class tStringObj>
bool TXMPFiles< tStringObj >::GetThumbnail ( XMP_ThumbnailInfo *  tnailInfo  ) 

Obtain the native thumbnail.

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.

Parameters:
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.
Returns:
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.

template<class tStringObj>
void TXMPFiles< tStringObj >::PutXMP ( const SXMPMeta &  xmpObj  ) 

Update the XMP.

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.

template<class tStringObj>
bool TXMPFiles< tStringObj >::CanPutXMP ( const SXMPMeta &  xmpObj  ) 

Determine if the XMP can be updated.

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:

  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;
 
  }


The documentation for this class was generated from the following file:
Generated on Thu May 3 14:54:58 2007 for Adobe XMP Toolkit by  doxygen 1.5.1