exiv2._xmp

XMP metadatum, container and iterators.

Classes

XmpData	A container for XMP data.
XmpData_iterator	Python wrapper for an XmpData iterator.
XmpData_iterator_base	Python wrapper for an XmpData iterator that points to the 'end' value and can not be dereferenced.
XmpParser	Stateless parser class for XMP packets.
Xmpdatum	Information related to an XMP property.

class XmpData

Bases: SwigPyObject

A container for XMP data. This is a top-level class of the Exiv2 library.

Provide high-level access to the XMP data of an image: - read XMP information from an XML block - access metadata through keys and standard C++ iterators - add, modify and delete metadata - serialize XMP data to an XML block

add()

Overload 1:

Add an Xmpdatum from the supplied key and value pair. This method copies (clones) the value.

Return type:

int

Returns:

0 if successful.

Overload 2:

Add a copy of the Xmpdatum to the XMP metadata.

Return type:

int

Returns:

0 if successful.

begin()

Begin of the metadata

clear()

Delete all Xmpdatum instances resulting in an empty container.

count()

Get the number of metadata entries

empty()

Return true if there is no XMP metadata

end()

End of the metadata

erase()

eraseFamily()

Delete the Xmpdatum at iterator position pos and update pos erases all following keys from the same family See: https://github.com/Exiv2/exiv2/issues/521

findKey()

Find the first Xmpdatum with the given key, return an iterator to it.

setPacket()

setPacket

sortByKey()

Sort metadata by key

usePacket()

Overload 1:

are we to use the packet?

Overload 2:

set usePacket_

xmpPacket()

class XmpData_iterator

Bases: XmpData_iterator_base

Python wrapper for an XmpData iterator. It has most of the methods of Xmpdatum allowing easy access to the data it points to.

copy()

Not implemented. Calling this method will raise an exception.

count()

See Xmpdatum.count().

familyName()

See Xmpdatum.familyName().

getValue()

See Xmpdatum.getValue().

groupName()

Return the (preferred) schema namespace prefix.

key()

Return the key of the Xmpdatum. The key is of the form ‘Xmp.prefix.property’. Note however that the key is not necessarily unique, i.e., an XmpData object may contain multiple metadata with the same key.

print()

Write the interpreted value to a string.

Implemented in terms of write(), see there.

setValue()

See Xmpdatum.setValue().

size()

See Xmpdatum.size().

tag()

Properties don’t have a tag number. Return 0.

tagDesc()

See Xmpdatum.tagDesc().

tagLabel()

See Xmpdatum.tagLabel().

tagName()

Return the property name.

toFloat()

See Xmpdatum.toFloat().

toInt64()

See Xmpdatum.toInt64().

toRational()

See Xmpdatum.toRational().

toString()

See Xmpdatum.toString().

toUint32()

Return the n-th component of the value converted to uint32_t.

typeId()

See Xmpdatum.typeId().

typeName()

See Xmpdatum.typeName().

typeSize()

The Exif typeSize doesn’t make sense here. Return 0.

value()

See Xmpdatum.value().

write()

See Xmpdatum.write().

class XmpData_iterator_base

Bases: SwigPyObject

Python wrapper for an XmpData iterator that points to the ‘end’ value and can not be dereferenced.

class XmpParser

Bases: SwigPyObject

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.

exactPacketLength = 512

includeThumbnailPad = 256

static initialize()

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.

}

Return type:

bool

Returns:

True if the initialization was successful, else false.

omitAllFormatting = 2048

omitPacketWrapper = 16

readOnlyPacket = 32

static terminate()

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.

useCompactFormat = 64

writeAliasComments = 1024

class Xmpdatum

Bases: Metadatum

Information related to an XMP property. An XMP metadatum consists of an XmpKey and a Value and provides methods to manipulate these.

copy()

Not implemented. Calling this method will raise an exception.

count()

Return the number of components in the value

familyName()

Return the name of the metadata family (which is also the first part of the key)

getValue()

Return an auto-pointer to a copy (clone) of the value. The caller owns this copy and the auto-poiner ensures that it will be deleted.

This method is provided for users who need full control over the value. A caller may, e.g., downcast the pointer to the appropriate subclass of Value to make use of the interface of the subclass to set or modify its contents.

Return type:

Value

Returns:

An auto-pointer containing a pointer to a copy (clone) of the value, 0 if the value is not set.

groupName()

Return the (preferred) schema namespace prefix.

key()

Return the key of the Xmpdatum. The key is of the form ‘Xmp.prefix.property’. Note however that the key is not necessarily unique, i.e., an XmpData object may contain multiple metadata with the same key.

setValue()

Overload 1:

Set the value. This method copies (clones) the value pointed to by pValue.

Overload 2:

Set the value to the string buf. Uses Value::read(const std::string& buf). If the metadatum does not have a value yet, then one is created. See subclasses for more details. Return 0 if the value was read successfully.

size()

Return the size of the value in bytes

tag()

Properties don’t have a tag number. Return 0.

tagDesc()

Return a description for the tag

tagLabel()

Return a label for the tag

tagName()

Return the property name.

toFloat()

Return the n-th component of the value converted to float. The return value is -1 if the value is not set and the behaviour of the method is undefined if there is no n-th component.

toInt64()

Return the n-th component of the value converted to int64_t. The return value is -1 if the value is not set and the behaviour of the method is undefined if there is no n-th component.

toRational()

Return the n-th component of the value converted to Rational. The return value is -1/1 if the value is not set and the behaviour of the method is undefined if there is no n-th component.

toString()

Overload 1:

Return the value as a string.

Overload 2:

Return the n-th component of the value converted to a string. The behaviour of the method is undefined if there is no n-th component.

typeId()

Return the type id of the value

typeName()

Return the name of the type

typeSize()

The Exif typeSize doesn’t make sense here. Return 0.

value()

Return a constant reference to the value.

This method is provided mostly for convenient and versatile output of the value which can (to some extent) be formatted through standard stream manipulators. Do not attempt to write to the value through this reference. An Error is thrown if the value is not set; as an alternative to catching it, one can use count() to check if there is any data before calling this method.

Return type:

Value

Returns:

A constant reference to the value.

Raises:

Exiv2Error if the value is not set.

write()

Write the interpreted value to an output stream, return the stream.

The method takes an optional pointer to a metadata container. Pretty-print functions may use that to refer to other metadata as it is sometimes not sufficient to know only the value of the metadatum that should be interpreted. Thus, it is advisable to always call this method with a pointer to the metadata container if possible.

This functionality is currently only implemented for Exif tags. The pointer is ignored when used to write IPTC datasets or XMP properties.

Without the optional metadata pointer, you do not usually have to use this function; it is used for the implementation of the output operator for Metadatum , operator<<(std::ostream &os, const Metadatum &md).

See also print(), which prints the interpreted value to a string.