SDK - Callback Suites - pi_BasicQuery
Callback Overview
This callback suite provides the plug-in with a means for querying the host for other callback suites and data as and when it requires them. All of the currently implemented suites are exposed by the various interfaces, so you may not need to use this interface.
Callback Interface Description
This interface is used for querying interfaces and data from the host. The interface itself is encapsulated in an object of type pi_BASICQUERY. This object is defined in plugin.h.
#define PI_BASICQUERY_VERSION 0x00010005 // 28 Aug 2023
struct pi_BASICQUERY
{
unsigned long version;
unsigned long host_id;
//8
void* (__cdecl* get_PI )(pi_BASICQUERY* self,const wchar_t* name);
HMODULE (__cdecl* get_lib)(pi_BASICQUERY* self,const wchar_t* name);
//16
int (__cdecl* get_flag)(pi_BASICQUERY* self,const wchar_t* name);
int (__cdecl* set_flag)(pi_BASICQUERY* self,const wchar_t* name,bool value);
//24
int (__cdecl* get_long)(pi_BASICQUERY* self,const wchar_t* name,long* value);
int (__cdecl* set_long)(pi_BASICQUERY* self,const wchar_t* name,long value);
//32
int (__cdecl* get_str )(pi_BASICQUERY* self,const wchar_t* name,wchar_t* str,int len);
int (__cdecl* set_str )(pi_BASICQUERY* self,const wchar_t* name,const wchar_t* str);
//40
int (__cdecl* get_data)(pi_BASICQUERY* self,const wchar_t* name,void* data,int size);
int (__cdecl* set_data)(pi_BASICQUERY* self,const wchar_t* name,const void* data,int size);
//48
unsigned char reserved_x[1024-48];//do not touch
};
get_PI() returns the requested interface. The name parameter is a string containing the name of any recognized PI interface, including the default interfaces. The return value is a pointer to the interface, or zero if the query failed.
get_lib() returns the requested module. The name parameter is a string containing the name of the DLL file of the module to be loaded. The return value is a module handle, or zero if the query failed. It is the caller’s reponsibility to free the handle using FreeLibrary().
get_flag() returns the requested flag. The name parameter is a string containing the name of the host flag being queried. The return value is either 0 or 1 if the query succeeded, or a negative number if it failed.
set_flag() modifies the specified flag. The return value will be greater than zero if the set operation succeeds. If the host rejects the new value due to data errors or permissions, the return value is a negative number. If the variable being set is unknown or unavailable, or if the function fails for any other reason, the return value is zero.
The following variables are currently supported:
| Variable | Details |
| “cpu.has_MMX” PI_BQ_FLAG_CPU_MMX |
Indicates if the CPU supports MMX. Read-only. |
| “cpu.has_SSE1” PI_BQ_FLAG_CPU_SSE1 |
Indicates if the CPU supports SSE. Read-only. |
| “cpu.has_SSE2” PI_BQ_FLAG_CPU_SSE2 |
Indicates if the CPU supports SSE2. Read-only. |
| “cpu.has_SSE3” PI_BQ_FLAG_CPU_SSE3 |
Indicates if the CPU supports SSE3. Read-only. |
| “cpu.has_sSSE3” PI_BQ_FLAG_CPU_sSSE3 |
Indicates if the CPU supports sSSE3. Read-only. |
| “cpu.has_SSE41” PI_BQ_FLAG_CPU_SSE41 |
Indicates if the CPU supports SSE4.1. Read-only. |
| “cpu.has_SSE42” PI_BQ_FLAG_CPU_SSE42 |
Indicates if the CPU supports SSE4.2. Read-only. |
| “cpu.has_AVX1” PI_BQ_FLAG_CPU_AVX1 |
Indicates if the CPU supports AVX1. Read-only. |
| “cpu.has_AVX2” PI_BQ_FLAG_CPU_AVX2 |
Indicates if the CPU supports AVX2. Read-only. |
| “cpu.has_POPCNT” PI_BQ_FLAG_CPU_POPCNT |
Indicates if the CPU supports POPCNT. Read-only. |
get_long() returns the requested integer variable. The name parameter is a string containing the name of the host variable being queried. The value parameter is a pointer to a long integer that will receive the requested value. The return value is greater than 0 if the query succeeds. If the variable being set is known or unavailable, or if the function fails for any other reason, the return value is zero.
set_long() modifies the specified integer variable. The return value will be greater than zero if the set operation succeeds. If the host rejects the new value due to data errors or permissions, the return value is a negative number. If the variable being set is unknown or unavailable, or if the function fails for any other reason, the return value is zero.
The following variables are currently supported:
| Variable | Details |
| “cpu.num_cores” PI_BQ_LONG_CPU_CORES |
Number of CPU cores as a long integer. Read-only. |
| “cpu.num_threads” PI_BQ_LONG_CPU_THREADS |
Number of CPU threads (logical CPUs) as a long integer. Read-only. |
| “host.progress.value” PI_BQ_LONG_PROGRESS |
Progress bar percentage in hundredths of a percent, i.e 0..10000. Write-only, deprecated. |
get_str() returns the requested string variable. The name parameter is a string containing the name of the host string variable being queried. The str parameter is a pointer to a string buffer that will receive the requested value, and len is the maximum length of that buffer in characters. The return value is the number of characters copied into str (including the terminating null) if the query succeeds. If the query fails because the buffer is too small, the return value is a negative number whose absolute value is the minimum expected buffer size. If the variable being set is known or unavailable, or if the function fails for any other reason, the return value is zero.
set_str() modifies the specified string variable. The str parameter is a pointer to a string that contains the new value. The return value will be greater than zero if the set operation succeeds. If the host rejects the new value due to data errors or permissions, the return value is a negative number. If the variable being set is known or unavailable, or if the function fails for any other reason, the return value is zero.
The following variables are currently supported:
| Variable | Details |
| “host.name” PI_BQ_STR_HOST_NAME |
Name of the host as a null-terminated unicode string. Read-only. e.g. “Chasys Photo” |
| “host.version” PI_BQ_STR_HOST_VERSION |
Version of the host as a null-terminated unicode string. Read-only. e.g. “5.32.01” |
| “host.temp_dir” PI_BQ_STR_HOST_TEMP_DIR |
The volatile TEMP path in use by the host as a null-terminated unicode string; read-only.
If the host supports automatic purging of TEMP, this will be a process-specific folder (not thread-specific or plug-in specific) that the host may choose to clean up when the calling process shuts down.
Do not rely on the automated cleanup; you must clear the files you put here. e.g. “C:\Windows\TEMP\_ies_pid_0012_tmp” |
| “host.temp_root” PI_BQ_STR_HOST_TEMP_ROOT |
The non-volatile TEMP path in use by the host as a null-terminated unicode string; read-only.
Depending on the user’s configuration, this can either be the TEMP folder of the Operating System or a user-defined “scratch-disc” location.
This folder is not automatically cleaned. e.g. “C:\Windows\TEMP” |
| “host.docs_dir” PI_BQ_STR_HOST_DOCS_DIR |
The sub-folder for the host under the system’s “Documents” folder as a null-terminated unicode string; read-only.
This is the folder that serves as the parent folder for the sub-folders used to store assets such as brushes,
textures, palettes, gradients and sample images. e.g. “C:\Users\Public\Documents\Chasys Photo” |
| “progress.string” PI_BQ_STR_PROGRESS |
Progress bar text (shown in the progress bar or window title) as a null-terminated unicode string. Write-only, deprecated. e.g. “Writing JPEG file, please wait...” |
| “config.author_name” PI_BQ_STR_AUTHOR_NAME |
The configured default author name if one is defined, or the currently logged-in user if not, as a null-terminated unicode string. Read-only. e.g. “John Paul Chacha” |
| “icm.cmyk_file” PI_BQ_STR_ICM_CMYK_FILE |
The path to the ICM color profile file that is currently designated as the default CMYK color profile file, as a null-terminated unicode string. Read-only. e.g. “C:\Users\Public\Documents\Chasys Photo\Color Profiles\Default CMYK.icm” |
| “workspace.file” PI_BQ_STR_WORKSPACE_FILE |
The path to the file associated which the image curently loaded into the workspace for Chasys Photo Editor, as a null-terminated unicode string. Read-only. e.g. “E:\My Photos\Holiday Photos\DCS_0234_edit.cd5” |
get_data() returns the requested raw data variable. The name parameter is a string containing the name of the host variable being queried. The data parameter is a pointer to a variable that will receive the requested value; it is assumed that the format of the data is known by both parties. The size parameter is the data buffer size in bytes. The return value is the number of bytes copied into data if the query succeeds. If the query fails because the buffer is too small, the return value is a negative number whose absolute value is the minimum expected buffer size. If the variable being set is known or unavailable, or if the function fails for any other reason, the return value is zero.
set_data() modifies the specified raw data variable. The data parameter is a pointer to a variable that contains the new value; it is assumed that the format of the data is known by both parties. The size parameter is the size of the data in bytes. The return value will be greater than zero if the set operation succeeds. If the host rejects the new value due to data errors or permissions, the return value is a negative number. If the variable being set is known or unavailable, or if the function fails for any other reason, the return value is zero.
The following variables are currently supported:
| Variable | Details |