Chapter 3. Requesting engine to do something for your plugin

In Chapter 1 we have seen how the engine gives to plugin a pointer to PluginRequestProc. Plugin can call this function when it needs engine to do something. The function is defined as follows:

TPluginRequestProc = function(

  RequestType: DWORD;

  ExtraInfo: pointer;

  ExtraInfoLength: DWORD;

  ParentHandle: DWORD

): DWORD stdcall of object;

RequestType: DWORD;
one of PLUGIN_REQ_* constants defined below

ExtraInfo: pointer;
a pointer to a request-specific structure
Request-specific structures are defined
next to each PLUGIN_REQ_* constant

ExtraInfoLength: DWORD;
length of the structure pointed to by ExtraInfo parameter

ParentHandle: DWORD
a handle to a plugin window to be parent
for possible message boxes displayed when processing
this plugin request

Function returns PLUGIN_REQ_RESULT_OK on success, or one of the following values on failure:

PLUGIN_REQ_RESULT_NOT_SUPPORTED
The RequestType specified in function call is not supported by the current version of the engine

PLUGIN_REQ_RESULT_FAILED
Function call failed due to unknown reason.

PLUGIN_REQ_RESULT_INVALID_STRUCTURE
The size of request-specific structure passed in ExtraInfo parameter is not correct.

PLUGIN_REQ_RESULT_PLUGINS_LIST_CHANGED
The engine is loading or unloading plugins. All plugin operations are not allowed during this time.

This function is thread-safe, and can be called at any time.

Example

function GetLocalClientID: string;
var
  GetLocalClientIDParams: TGetLocalClientIDParams;
  ID: TIDString;

begin
  with GetLocalClientIDParams do begin
    ClientID:=@ID;
    ClientIDLength:=sizeof(TIDString);
  end;

  if PluginRequestProc(
       PLUGIN_REQ_GET_LOCAL_CLIENT_ID,
       @GetLocalClientIDParams,
       sizeof(GetLocalClientIDParams),
       0
     ) = PLUGIN_REQ_RESULT_OK then

        Result:=string(ID)

  else
        Result:='';
end;

If the requested operation requires some kind of reply from program, and this reply cannot be spelled in terms of OK / not OK, program will call plugin to notify it about the result. Program can also call plugin when it needs to notify it about program initialization, or shutdown.

In next chapters we will learn about each plugin-to-engine and engine-to-plugin request and its handling.

Chapter 4 >>