Online Help for Chasys Photo: SDK - Callback Suites

Online Help for Chasys Photo: 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 0x00030001 // 22 Oct 2025

struct pi_STATESTORE

{

unsigned long version;

unsigned long host_id;

//8

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

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

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

void* temporary_unused; //do not touch

//24

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

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

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

void* permanent_unused; //do not touch

//40

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

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

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

void* encrypted_unused; //do not touch

//56

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

};

Temporary State Stores

Temporary State Stores are stores that remain valid only during the course of the current session. If the app is ended and restarted, their contents are erased. They are intended for the storage of volatile information.

temporary_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.

temporary_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.

temporary_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

Permanent State Stores are stores that remain valid even after the computer is restarted and even across version updates. They are intended for the storage of non-volatile information such as settings and configuration data.

permanent_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.

permanent_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.

permanent_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.

Secure State Stores

Encrypted State Stores are stores are similar to Permanent State Stores, except that their contents are encrypted and thus are not transferable between computer and may not survive a version update. They are intended for the storage of sensitive information such as log-in data and security keys. The type of encryption used and the choice of encryption key is determined by the host.

encrypted_read() reads data from the named Encrypted 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.

encrypted_write() writes data to the named Encrypted 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.

encrypted_size() returns the size of the named Encrypted 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 plug-in 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.

There is no minimum security level defined for Secure State Stores; therefore, the host is at liberty to implement whatever level of security that it deems appropriate. You should therefore consider the security provided here as basic security.

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