Chapter 2. Processing engine-to-plugin requests

When engine needs to notify plugin about certain facts, it uses ProgramRequestProc function which is implemented in plugin and given to engine at the time of plugin init inside the TPluginInfo structure. This function is defined as follows:

TProgramRequestProc = function(

  RequestType: DWORD;
  ExtraInfo: pointer;
  ExtraInfoLength: DWORD;
  ParentHandle: DWORD

): DWORD stdcall of object;

RequestType: DWORD;
one of PROGRAM_REQ_* constants defined below

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

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

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

Plugin must return PROGRAM_REQ_RESULT_OK on success, or one of the following values on failure:

PROGRAM_REQ_RESULT_NOT_SUPPORTED
The RequestType specified in function call is not supported by the current version of the plugin

PROGRAM_REQ_RESULT_FAILED
Function call failed due to unknown reason.

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

If this function is made thread-safe (i.e. no Delphi VCL is directly used in it), plugin can initialize the VCLSyncRequests structure to have all members equal to FALSE. But if processing certain requests requires reference to thread-unsafe code, plugin must specify such requests to be made in thread-safe manner, by using VCLSyncRequests.

Example

A simple example can be built into your plugin like this:

function ProgramRequestProc( 
   RequestType: DWORD;
   ExtraInfo: pointer;
   ExtraInfoLength: DWORD;
   ParentHandle: DWORD): DWORD; stdcall;

begin
  case RequestType of

    PROGRAM_REQ_TYPE_INIT_PLUGIN:      Result:=PROGRAM_REQ_RESULT_OK;

    PROGRAM_REQ_TYPE_SHUTDOWN_REQUEST: Result:=PROGRAM_REQ_RESULT_OK;

    PROGRAM_REQ_TYPE_SHUTDOWN:         Result:=PROGRAM_REQ_RESULT_OK;

    else
      Result:=PROGRAM_REQ_RESULT_NOT_SUPPORTED;

  end;
end;

This function is enough for the plugin to be loaded - but this plugin will not be able to do anything beside loading and unloading. To be of any value, plugin has to take specific care of each request sent by program. This is done by using request-specific structures, which are pointed to by ExtraInfo parameter of the ProgramRequestProc.

E.g. for PROGRAM_REQ_TYPE_INIT_PLUGIN, the ExtraInfo will point to

TInitPluginParams = packed record
  phPluginIcon: PHandle; // a pointer to a Handle variable
end;

Each engine request can either be accompanied with a specific structure, or come alone, with ExtraInfo set to NIL, when no additional info is required. All conditions along with all RequestType values and their structures are defined in plugin_header_un.pas file.

Each request is expecting plugin to do, or not do a specific thing. E.g. the PROGRAM_REQ_TYPE_INIT_PLUGIN notifies plugin about the program initialization stage, and is offering plugin a possibility to supply its icon to the engine GUI.

Chapter 3 >>