Exiv2::XmpParser Class Reference

Stateless parser class for XMP packets. Images use this class to parse and serialize XMP packets. The parser uses the XMP toolkit to do the job. More...

`#include <xmp_exiv2.hpp>`

## Public Types

enum | XmpFormatFlags { omitPacketWrapper = 0x0010UL , readOnlyPacket = 0x0020UL , useCompactFormat = 0x0040UL , includeThumbnailPad = 0x0100UL , exactPacketLength = 0x0200UL , writeAliasComments = 0x0400UL , omitAllFormatting = 0x0800UL }
| Options to control the format of the serialized XMP packet. More...
typedef void(* | XmpLockFct) (void *pLockData, bool lockUnlock)
| Lock/unlock function type. More...

## Static Public Member Functions

static int | decode (XmpData &xmpData, const std::string &xmpPacket)
| Decode XMP metadata from an XMP packet xmpPacket into xmpData. The format of the XMP packet must follow the XMP specification. This method clears any previous contents of xmpData. More...
static int | encode (std::string &xmpPacket, const XmpData &xmpData, uint16_t formatFlags=useCompactFormat, uint32_t padding=0)
| Encode (serialize) XMP metadata from xmpData into a string xmpPacket. The XMP packet returned in the string follows the XMP specification. This method only modifies xmpPacket if the operations succeeds (return code 0). More...
static bool | initialize (XmpParser::XmpLockFct xmpLockFct=0, void *pLockData=0)
| Initialize the XMP Toolkit. More...
static void | terminate ()
| Terminate the XMP Toolkit and unregister custom namespaces. More...

## Friends

class | XmpProperties

## Detailed Description

Stateless parser class for XMP packets. Images use this class to parse and serialize XMP packets. The parser uses the XMP toolkit to do the job.

## Member Typedef Documentation

## XmpLockFct

typedef void(* Exiv2::XmpParser::XmpLockFct) (void *pLockData, bool lockUnlock)

Lock/unlock function type.

A function of this type can be passed to initialize() to make subsequent registration of XMP namespaces thread-safe. See the initialize() function for more information.

Parameters

  pLockData | Pointer to the pLockData passed to initialize()
  lockUnlock | Indicates whether to lock (true) or unlock (false)

## Member Enumeration Documentation

## XmpFormatFlags

enum Exiv2::XmpParser::XmpFormatFlags

Options to control the format of the serialized XMP packet.

Enumerator
omitPacketWrapper | Omit the XML packet wrapper.
readOnlyPacket | Default is a writeable packet.
useCompactFormat | Use a compact form of RDF.
includeThumbnailPad | Include a padding allowance for a thumbnail image.
exactPacketLength | The padding parameter is the overall packet length.
writeAliasComments | Show aliases as XML comments.
omitAllFormatting | Omit all formatting whitespace.

## Member Function Documentation

## decode()

int Exiv2::XmpParser::decode | ( | XmpData & | xmpData,
|  | const std::string & | xmpPacket
| ) |  |

static

Decode XMP metadata from an XMP packet xmpPacket into xmpData. The format of the XMP packet must follow the XMP specification. This method clears any previous contents of xmpData.

Parameters

  xmpData | Container for the decoded XMP properties
  xmpPacket | The raw XMP packet to decode

Returns
  0 if successful;
  1 if XMP support has not been compiled-in;
  2 if the XMP toolkit failed to initialize;
  3 if the XMP toolkit failed and raised an XMP_Error

Examples
  xmpparse.cpp.

References Exiv2::XmpData::clear(), and EXV_WARNING.

Referenced by Exiv2::Internal::TiffDecoder::decodeXmp(), Exiv2::EpsImage::readMetadata(), Exiv2::Jp2Image::readMetadata(), Exiv2::JpegBase::readMetadata(), Exiv2::XmpSidecar::readMetadata(), and Exiv2::Image::setXmpPacket().

## encode()

int Exiv2::XmpParser::encode | ( | std::string & | xmpPacket,
|  | const XmpData & | xmpData,
|  | uint16_t | formatFlags = `useCompactFormat`,
|  | uint32_t | padding = `0`
| ) |  |

static

Encode (serialize) XMP metadata from xmpData into a string xmpPacket. The XMP packet returned in the string follows the XMP specification. This method only modifies xmpPacket if the operations succeeds (return code 0).

Parameters

  xmpPacket | Reference to a string to hold the encoded XMP packet.
  xmpData | XMP properties to encode.
  formatFlags | Flags that control the format of the XMP packet, see enum XmpFormatFlags.
  padding | Padding length.

Returns
  0 if successful;
  1 if XMP support has not been compiled-in;
  2 if the XMP toolkit failed to initialize;
  3 if the XMP toolkit failed and raised an XMP_Error

Examples
  xmpsample.cpp.

References Exiv2::XmpData::empty(), and EXV_WARNING.

Referenced by Exiv2::EpsImage::writeMetadata(), Exiv2::XmpSidecar::writeMetadata(), and Exiv2::Image::xmpPacket().

## initialize()

bool Exiv2::XmpParser::initialize | ( | XmpParser::XmpLockFct | xmpLockFct = `0`,
|  | void * | pLockData = `0`
| ) |  |

static

Initialize the XMP Toolkit.

Calling this method is usually not needed, as encode() and decode() will initialize the XMP Toolkit if necessary.

The function takes optional pointers to a callback function xmpLockFct and related data pLockData that the parser uses when XMP namespaces are subsequently registered.

The initialize() function itself still is not thread-safe and needs to be called in a thread-safe manner (e.g., on program startup), but if used with suitable additional locking parameters, any subsequent registration of namespaces will be thread-safe.

Example usage on Windows using a critical section:

void main()
{
struct XmpLock
{
CRITICAL_SECTION cs;
XmpLock() { InitializeCriticalSection(&cs); }
~XmpLock() { DeleteCriticalSection(&cs); }
static void LockUnlock(void* pData, bool fLock)
{
XmpLock* pThis = reinterpret_cast<XmpLock*>(pData);
if (pThis)
{
(fLock) ? EnterCriticalSection(&pThis->cs)
: LeaveCriticalSection(&pThis->cs);
}
}
} xmpLock;
// Pass the locking mechanism to the XMP parser on initialization.
// Note however that this call itself is still not thread-safe.
Exiv2::XmpParser::initialize(XmpLock::LockUnlock, &xmpLock);
// Program continues here, subsequent registrations of XMP
// namespaces are serialized using xmpLock.
}
Exiv2::XmpParser::initialize
static bool initialize(XmpParser::XmpLockFct xmpLockFct=0, void *pLockData=0)
Initialize the XMP Toolkit.
Definition: xmp.cpp:641

Returns
  True if the initialization was successful, else false.

Examples
  addmoddel.cpp, exifcomment.cpp, exifdata.cpp, exifprint.cpp, exifvalue.cpp, exiv2json.cpp, geotag.cpp, iptceasy.cpp, iptcprint.cpp, metacopy.cpp, mrwthumb.cpp, xmpparse.cpp, xmpprint.cpp, and xmpsample.cpp.

## terminate()

void Exiv2::XmpParser::terminate | ( |  | ) |

static

Terminate the XMP Toolkit and unregister custom namespaces.

Call this method when the XmpParser is no longer needed to allow the XMP Toolkit to cleanly shutdown.

Examples
  addmoddel.cpp, exifcomment.cpp, exifdata.cpp, exifprint.cpp, exifvalue.cpp, exiv2json.cpp, geotag.cpp, iptceasy.cpp, iptcprint.cpp, metacopy.cpp, mrwthumb.cpp, xmpparse.cpp, xmpprint.cpp, and xmpsample.cpp.

References Exiv2::XmpProperties::unregisterNs().

The documentation for this class was generated from the following files:

- xmp_exiv2.hpp
- xmp.cpp