Online Help for Chasys Photo: SDK - Callback Suites

Online Help for Chasys Photo: SDK - Callback Suites - Table of Contents

SDK - Callback Suites - Table of Contents

SDK - Callback Suites

About Callback Suites

Calback suites extend the functionality of the interface they appear in by exposing extended services provided by the host, such as graphics services, color services, storage services, etc. They ease plug-in devcelopment by allowing plug-ins to leverage functionality that has already been implemented in the host application.

The following suites are currently available for use by all plug-ins:


pi_StateStore	Provides the plug-in with a way of storing/persisting state information (such as the positions of scroll-bars) and configuration data (settings) so that it can be used the next time the plug-in is loaded.
pi_MetaMarkup	Provides the plug-in with functionality for handling mark-up metadata.
pi_BasicQuery	Provides the plug-in with a way to query the host for other interfaces.
pi_BasicImage	Provides the plug-in with basic image allocation and management functionality, including allocation, deallocation, GDI interoperability, and blitting/blending.
pi_BasicColor	Provides the plug-in with basic color conversion and manipulation functionality, including color space conversions.
pi_BasicUtils	Provides the plug-in with basic utilities such as language translation and internet access.
pi_BasicVideo	Provides the plug-in with basic video manipulation and frame-grab functionality. Usually only available via pi_BasicQuery. Interface definition is provided in the header.
pi_BasicCrypt	Provides the plug-in with basic cryptographic services; currently not implemented.
pi_Forwarding	Allows related plug-ins to forward request between each other; use by 3^rd party plug-ins is strongly discouraged. Usually only available via pi_BasicQuery. Interface definition is provided in the header.

Typically, a plug-in will start its execution sequence by checking that all the callback suites it needs are available and are of an acceptable version:

pi_BASICVIDEO *pi_BasicVideo;

// Check that we have all the callback suites we need and handle optional suites

if(!host)

{

return PLUGIN_ERR_BAD_PARAM;

}

if(!(host->pi_BasicImage))

{

return PLUGIN_ERR_BAD_HOST;

}
if(!(PLUGIN_TEST_PI_VERSION(host->pi_BasicImage->version,PI_BASICIMAGE_VERSION)))

{

return PLUGIN_ERR_BAD_HOST;

}

if(!(host->pi_BasicColor))

{

return PLUGIN_ERR_BAD_HOST;

}
if(!(PLUGIN_TEST_PI_VERSION(host->pi_BasicColor->version,PI_BASICCOLOR_VERSION)))

{

return PLUGIN_ERR_BAD_HOST;

}

if(pi_StateStore)

{

if(PLUGIN_TEST_PI_VERSION(pi_StateStore->version,PI_STATESTORE_VERSION))

{

...

}

...

The general rule with versioning of callback suites is that the major version must match but the minor version of the host must be either equal to or greater than the version the plug-in was compiled against.

Before using a callback suite, check that it is implemented by confirming that the pointer is not NULL and that the version is acceptable by using the PLUGIN_TEST_PI_VERSION macro as illustrated above.

Not all callback suites are implemented by all hosts. In the even that your plug-in requires a callback suite that is not implemented and a workaround does not exist, your plug-in should fail with the error PLUGIN_ERR_BAD_HOST.

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