SDK – Layer Attachments – 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.