Callback Overview
This callback suite provides the plug-in with a suite of functions for manipulating mark-up metadata. It is recommended that plug-ins use this suite instead of writing mark-up data directly; the reason for this is that it transfers the burden of standards conformance to the host and thus makes your plug-in more future-proof.
Callback Interface Description
This interface is used for working with MARK metadata via an instance of an object of type pimm_MARK. The interface itself is encapsulated in an object of type pi_METAMARKUP. Both objects are defined in plugin.h.
#define PI_METAMARKUP_VERSION 0x00010003
struct pimm_MARK
{
char* data;
unsigned long size;
char* raw_data;
unsigned long raw_size;
};
struct pi_METAMARKUP
{
unsigned long version;
unsigned long host_id;
//8
int (__cdecl* create )(pimm_MARK* mark);
int (__cdecl* import )(pimm_MARK* mark,const void* data,unsigned long size);
int (__cdecl* destroy)(pimm_MARK* mark);
int (__cdecl* append )(pimm_MARK* mark,const char* fragment);
int (__cdecl* get_tag)(pimm_MARK* mark,const char* tag,char* value,unsigned long size);
int (__cdecl* set_tag)(pimm_MARK* mark,const char* tag,const char* value);
int (__cdecl* bpp_get)(pimm_MARK* mark,unsigned int* bpp);
int (__cdecl* bpp_set)(pimm_MARK* mark,unsigned int bpp);
int (__cdecl* exif_get)(pimm_MARK* mark,void** exif,unsigned long* sz_exif);
int (__cdecl* exif_set)(pimm_MARK* mark,const void* exif,unsigned long sz_exif);
int (__cdecl* exif_loadXMP)(pimm_MARK* mark,const char* xmp_str,int limit_or_zero);
//52
unsigned char reserved_x[1024-52];//do not touch
};
create() creates a new blank mark-up data buffer.
import() creates a new blank mark-up data buffer and initializes it with the contents of the raw data provided.
destroy() destroys the mark-up data buffer and frees all memory used by it. Must be called for all buffers after use.
append() adds the mark-up fragment to the mark-up data buffer. It’s useful for cases in which the mark-up data has been compiled in pieces.
get_tag() and set_tag() retrieve and modify (respectively) the value of the specified tag. If “value” is null when calling the set function, the refrenced tag will be removed from the mark-up.
bpp_get() and bpp_set() retrieve and modify (respectively) the value of the image.bpp (bits per pixel) tag.
exif_get() and exif_set() retrieve and modify (respectively) the exif.* group of tags (EXIF metadata). The exif data is passed in and out in binary format as per the EXIF standard; host is responsible for converting this data to and from the textual representation used by the MARK attachment. This saves the plug-in the burden of implementing an EXIF conversion library. When you call exif_get(), the host dereferences exif and sz_exif and checks if they point to valid exif data (header-less EXIF data is accepted by later versions). If so, the host will attempt to initialize the EXIF object with that data before inserting values from markup. The host will then return the new data and its size without attempting to free the original buffer; doing that is the caller’s responsibility. exif_loadXMP() modifies the EXIF metadata based on the data contained in the provided XMP metadata. The XMP data should be a null-terminated string containing UTF-encoded XML. If it is not possible to guarantee that the string is null-terminated, then the limit_or_zero parameter should be set to the exact length of the string, otherwise it should be set to zero.