- void Initialize(HWND
applicationHandle, int pluginId, ActionCallback callback)
typedef _stdcall void (* ActionCallback)(int pluginId, int actionId);
This function initializes the plugin and WILL be the first to
be called after the DLL is loaded into the main program. You
SHOULD use the given handle to keep track of the main application
handle. The main application passes you a plugin Id which you MUST keep
track of in order to give it when you use callback functions.
When this function is called, the callback parameter points to a
function the plugin MUST call when its active state has changed as the
result of an internal decision. It MUST NOT be called as the result
of a call to SetActionActive(). The pluginId parameter MUST be the
pluginId passed to the DLL when this function was called. The actionId
parameter MUST be the Id of the action which state has changed.
Introduced in version 0.1
- WORD GetSpecVersion()
This function returns a WORD (2 bytes) containing the number
of the version of these specifications used when the plugin
was developed. The high order byte contains the major number and the
low order byte contains the minor number. Hence for version 0.2, this
function MUST return 2 (0*256+2)
Introduced in version 0.1
- void GetTitle(char * title)
This function returns the title of the plugin. The string
MUST NOT be longer than 255 characters including the
terminating NULL character.
Introduced in version 0.1
- void GetDescription(char *
description)
This function returns a description of the plugin. The
string MUST NOT be longer than 65535 charactes including the
terminating NULL character. This SHOULD be the place where you put your
acknoledgments to the people who helped you.
Introduced in version 0.1
- void GetVersion(char * version)
This function returns a string containing the version of
the plugin. The string MUST NOT be longer than 255 charactes
including the terminating NULL character.
Introduced in version 0.1
- void GetAuthorName(char * name)
This function returns the name of the author of the
plugin. The string MUST NOT be longer than 255 charactes including
the terminating NULL character. This string MAY contain the author's
email if GetAuthorEmail() is not defined.
Introduced in version 0.1
- unsigned int GetTypes()
This function returns the number of different action
types this plugin contains. This SHOULD be greater than
0 (why would a plugin return 0 anyway ?) and will usually be 1.
Introduced in version 0.1
- int GetTypeId(int typeNumber)
This function returns the type ID for the given type indicated
by a sequence number.
This function will be called sequentially after a call to GetTypes()
to discover all the type IDs a plugin proposes. The sequence will go
from 0 to GetTypes()-1. However, if typeNumber is greater than
GetTypes()-1, this function MUST return -1 to indicate an error.
Your plugin can return any value it wants as an ID but all the IDs
MUST be unique within the plugin. You MAY choose to return the sequence
number as it is clearly the easiest solution.
Introduced in version 0.1
- void GetTypeTitle(int typeId, char
* title)
This function MUST fill the given string with the title of
the given type. The string MUST NOT be longer than 255
characters, including the trailing null character.
Introduced in version 0.1
- void GetTypeDescription(int
typeId, char * description)
This function MUST fill the given string with the
description of the given type the plugin proposes. The string
MUST NOT be longer than 65535 characters, including the trailing
null character.
Introduced in version 0.1
- int CreateAction(int typeId)
This function creates an action of the given type and
returns its Id. The returned Id MUST be unique within the
plugin and will be used by other functions to refer to that
particular action.
Introduced in version 0.1
- void DestroyAction(int actionId)
This function tells the plugin to destroy the given action . This is
when you MUST wake up and delete any thread you might have created when
the action was itself created. Indeed, deleting the thread upon
unloading of the DLL is unsafe and MUST NOT be done. The main program
will ensure that the calls to DestroyAction are done before unloading
the DLL, thus avoiding any problem.
Introduced in version 0.1
- bool LoadActionFromXML(int
actionId, char * node)
This function loads the properties of the indicated action
from the given XML node represented as a null terminated string. Only
the action properties specific to the plugin are required to be loaded.
For instance, the name SHOULD NOT not be loaded, unless the plugin
needs it for its internal processing. However, keep in mind that any
change to the non specific properties will not be passed along to the
action. The return value MUST indicate if the loading was successful.
Introduced in version 0.1 -
Modified in version 0.2
- void SaveActionToXML(int
actionId, char * node)
This function saves the properties of the indicated action
into the given XML node. ONLY the properties that are specific
to the plugin MUST be saved. All the other ones that the plugin
might have loaded when LoadActionFromXML() was called will be
discarded. It is recommended to store properties as attributes to the
given node, unless they require a specific structure. The
returned null terminated string must not be longer than 524288 bytes
(512k) including the trailing null character. It MUST be well formed
XML but MUST NOT include any character codeset definition (<?xml
version="1.0" encoding="iso-8859-1"?> for instance)
Introduced in version 0.1 -
Modified in version 0.2
- bool WillActionFinish(int
actionId)
This function MUST return false if the action is not meant
to stop by itself after it has performed its mission. Else, it MUST
return true.
For instance, a TCP port redirection action never finishes and
returns false, whereas an application launching action is
finished when the action is launched and thus returns true (when
the action goes back to an inactive state by itself, it MUST call the
callback function passed to Initialize()).
Introduced in version 0.1
- void SetActionActive(int
actionId, bool active)
This function sets the active state of the given action.
If active is true, it MUST start the action mission. If active
is false, it MUST stop what the action is doing.
If the action is already active, calling this function again with
active set to true MUST NOT do anything.
If the action is already inactive, calling this function again
with active set to false MUST NOT do anything.
In both cases, the callback passed to Initialize() MUST NOT be called.
Introduced in version 0.1
- bool GetActionActive(int
actionId)
This function MUST return true if the given action is
active, false otherwise
Introduced in version 0.1
- HWND
DisplayActionProperties(int actionId, HWND parent, RECT * area)
This function MUST display in the given parent window a
set of controls that will give the opportunity to the user to
change the values for the given action.
This function MUST return the handle to the control containing all
the controls required to edit the values.
Before display, the plugin MUST update the content of the
controls with the latest values.
The controls MUST be displayed within the given area of the
parent window. Upon return, the values of area must have been
updated to indicate the minimum area requires for the controls to be
displayed correctly. You SHOULD set top and left to 0, right to the
minimum width and bottom to the minimum height. The size of the
area MAY change but will never be smaller than the returned value. The
control which handle was returned will receive resizing messages
stating the new size of the parent. In Delphi 6, you MAY use a
TFame descendant to contain your editing controls (see the
examples).
The controls that are displayed are meant to change the
properties specific to the action, not the generic ones like the
name. You MUST NOT provide controls to change generic properties as
all changes will be discarded.
If parent is set to NULL, then the plugin MUST consider that
the controls have no parents, are not shown and that the
previous parent is no longer valid.
Introduced in version 0.1
- void GetIcon(HDC dc)
This function MUST draw in the given device context (refer
to Win32 API documentation for the definition of a
device context) a picture that will be used as an icon to
display the plugin in the 'Plugins' dialog. The picture MUST be
rendered on a white background and MUST be 16x16 pixels.
If this function is not implemented, a standard icon
representing the idea of a plugin will be used.
Introduced in version 0.1
- void GetTypeIcon(int typeId, HDC dc)
This function MUST draw in the given device context (refer
to Win32 API documentation for the definition of a
device context) a picture that will be used as an icon to
display the type identified by typeId in the 'Add an action'
dialog. The picture MUST be rendered on a white background and
MUST be 16x16 pixels.
If this function is not implemented, the icon returned by
GetIcon() will be used. If GetIcon() is not defined, a standard
icon representing the idea of a plugin will be used.
Introduced in version 0.1
- void GetActionIcon(int actionId,
HDC dc)
This function MUST draw in the given device context (refer
to Win32 API documentation for the definition of a device context)
a picture that will be used as an icon to display the
indicated action in the action list. The picture MUST be
rendered on a white background and MUST be 16x16 pixels.
If this function is not implemented, the icon returned by
GetTypeIcon() will be used. If GetTypeIcon() is not defined,
the icon returned by GetIcon() will be used. If GetIcon() is not
defined, a standard icon representing the idea of a plugin
will be used
Introduced in version 0.1
- void GetAuthorEmail(char * email)
This functions returns the email of the author of the
plugin. The string MUST NOT be longer than 255 characters including
the terminating NULL character.
If this function is not defined, the author's email will show up
as 'not specified' and will not link to anything.
Introduced in version 0.1
- void
GetDefaultActionName(int typeId, char * name)
This functions returns the default name for actions of the given
type. The string MUST NOT be longer than 255 characters including
the terminating NULL character.
If this function is not defined, the default action name for the
given type will be its title.
Introduced in version 0.1
- void GetActionHint(int actionId,
char * hint)
This functions returns a hint to be added to the hint displayed when
the user leaves the mouse long enough on the icon in the notification
area. The hint will be added on a line of its own and SHOULD NOT be
longer than 30 characters and MUST NOT be longer than 128 characters
including the trailing null character.
If this function is not defined, no line will be added to the hint
for this action.
Introduced in version 0.1
- void UseLanguage(char * code)
This functions tells the plugin that the current language has changed
in the application. If the plugin supports multiple languages, it
SHOULD
use the one indicated. The code is an ISO code as used by GNU gettext.
If the given language is not supported or the plugin doesn't support
multiple languages, it SHOULD default to English (en).
If this function is not defined, the plugin will not be informed of
language changes and SHOULD use English (en).
Introduced in version 0.1
