...

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

SDK - Callback Suites - pi_BasicQuery


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                         0x00010004

 

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.
   

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 Draw IES”

“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 Draw IES”
“host.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...”

   

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
   

 

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

 

 

Copyright © John Paul Chacha, 2001-2024

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