Online Help for Chasys Draw IES: SDK - Callback Suites

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

SDK - Callback Suites - pi_StateStore

SDK - Callback Suites - pi_StateStore

Callback Overview

This callback suite 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. The are two kinds of State Stores, temporary and permanent. Temporary stores are stored in memory per session per host and are destroyed when the host ceases execution. Permanent stores are globally visible and are stored on disk, and therefore remain valid until either the store or the backing file is deleted. It is recommended that temporary stores be used for user interface settings like the positions of scroll-bars, and permanent stores be used for configuration data.

Callback Interface Description

The interface itself is encapsulated in an object of type pi_STATESTORE. This object is defined in plugin.h.

#define PI_STATESTORE_VERSION 0x00020002

struct pi_STATESTORE

{

unsigned long version;

unsigned long host_id;

int (__cdecl* temp_read )(const wchar_t* name,void* data,int size);

int (__cdecl* temp_write)(const wchar_t* name,void* data,int size);

int (__cdecl* temp_size )(const wchar_t* name);

int (__cdecl* perm_read )(const wchar_t* name,void* data,int size);

int (__cdecl* perm_write)(const wchar_t* name,void* data,int size);

int (__cdecl* perm_size )(const wchar_t* name);

//32

unsigned char reserved_x[1024-32];//do not touch

};

Temporary State Stores

temp_read() reads data from the named Temporary State Store. Store names are required to be globally unique and less than 32 characters in length; it is recommended that you use the plug-in filename. If the function succeeds, it returns the amount of data read in bytes, otherwise it returns zero.

temp_write() writes data to the named Temporary State Store. If the store does not exist, it is created. If the function succeeds, it returns the amount of data written in bytes, otherwise it returns zero. If size is zero, the store is deleted. For a code example, see the source-code for the NSContrast plug-in.

temp_size() returns the size of the named Temporary State Store. If the store does not exist, it returns zero. The size of the store is set when it is created or updated. Currently, the store size is limited to a maximum of 64 KiB.

Permanent State Stores

perm_read() reads data from the named Permanent State Store. Store names are required to be globally unique and less than 32 characters in length; it is recommended that you use the plug-in filename. If the function succeeds, it returns the amount of data read in bytes, otherwise it returns zero.

perm_write() writes data to the named Permanent State Store. If the store does not exist, it is created. If the function succeeds, it returns the amount of data written in bytes, otherwise it returns zero. If size is zero, the store is deleted. For a code example, see the source-code for the PNG file plug-in.

perm_size() returns the size of the named Permanent State Store. If the store does not exist, it returns zero. The size of the store is set when it is created or updated. Currently, the store size is limited to a maximum of 256 KiB.

The plugin is expected to use default settings if this callback is not available.

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

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