Online Help for Chasys Draw IES: SDK - Callback Suites - pi_MetaMarkup

SDK - Callback Suites - pi_MetaMarkup

SDK - Callback Suites - pi_MetaMarkup

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;


      int (__cdecl*   create )(pimm_MARK* mark);

      int (__cdecl*   import )(pimm_MARK* mark,const void* data,unsigned int 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 int 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 int* sz_exif);

      int (__cdecl*   exif_set)(pimm_MARK* mark,const void* exif,unsigned int sz_exif);

      int (__cdecl*   exif_loadXMP)(pimm_MARK* mark,const char* xmp_str,int limit_or_zero);


      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.

The internal implementation of pi_MetaMarkup is neither defined nor fixed, and is purely host dependent. Do not attempt to access the reserved portion of the object.



Copyright © John Paul Chacha, 2001-2024

The information herein is subject to change without any notice. The author makes no guarantees as to the completeness of this documentation.