Public Types | Static Public Member Functions | Friends | List of all members
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...
 
using XmpLockFct = void(*)(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=nullptr, void *pLockData=nullptr)
 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

using Exiv2::XmpParser::XmpLockFct = void (*)(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
pLockDataPointer to the pLockData passed to initialize()
lockUnlockIndicates 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()

static 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
xmpDataContainer for the decoded XMP properties
xmpPacketThe 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.

◆ encode()

static 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
xmpPacketReference to a string to hold the encoded XMP packet.
xmpDataXMP properties to encode.
formatFlagsFlags that control the format of the XMP packet, see enum XmpFormatFlags.
paddingPadding 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.

◆ initialize()

static bool Exiv2::XmpParser::initialize ( XmpParser::XmpLockFct  xmpLockFct = nullptr,
void *  pLockData = nullptr 
)
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=nullptr, void *pLockData=nullptr)
Initialize the XMP Toolkit.
Returns
True if the initialization was successful, else false.
Examples
addmoddel.cpp, exifcomment.cpp, exifdata.cpp, exifprint.cpp, exifvalue.cpp, geotag.cpp, iptceasy.cpp, iptcprint.cpp, metacopy.cpp, mrwthumb.cpp, xmpparse.cpp, xmpprint.cpp, and xmpsample.cpp.

◆ terminate()

static 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, geotag.cpp, iptceasy.cpp, iptcprint.cpp, metacopy.cpp, mrwthumb.cpp, xmpparse.cpp, xmpprint.cpp, and xmpsample.cpp.
The documentation for this class was generated from the following file: