Creating Puac Plug-ins

Puac version 3.2
Last modified: March 10, 2004

Since version 3.2, it is possible to create your own plug-ins for Puac. You can make plug-ins that import and export alarmgroups or that perform an alarm action.

Files to get started:


Contents


How to create a plug-in

Things you should know before reading further
Each plug-in library can contain multiple plug-ins, with multiple plug-ins possibly of the same type. To get a plug-in library working, there are several things you need to take care of.

To ensure that plug-ins will be compatible with future (and in the future, with previous) versions of Puac, the program relies heavily on XML to pass data between the program and the plug-ins. In fact, there is only one interface you should implement and it only contains one method. This one method has one string as a parameter and returns a string as result. As you might have guessed, these strings are in XML format. Which actions are to be taken by which plug-ins and the parameters on which the plug-in acts are all included in the parameter XML string.

Below, a specification of the format of these xml strings is given. This list will change with future versions. Given the properties of xml however, this should not always be problematic (at least the version conflicts will not be as severe as having one large type library changing with each version). Everything that I don't specify in this file is unspecified. If something unspecified works in one version of Puac, it might not work in another. If you need to be sure about something, please contact me. I'll be happy to specify it.

Short overview
-Create a class PlugIn that implements IPlugIn
-Provide PlugIn information through the PlugInInfo 'plug-in'
-Create your plug-in(s)
-Deploy the plug-in

Create a class PlugIn that implements IPlugIn
This is a real class in that it will have to be a creatable object. The name of the class that implements IPlugIn MUST be "PlugIn". All the other classes are non-existing classes with non-existing methods that will have to be simulated. The IPlugIn interface can be found in the Puac Plug-in type library.

Provide PlugIn information through the PlugInInfo 'plug-in'
You must implement IPlugInInfo (more information). This object will supply Puac with information on the names of the plug-ins in your library. The name of this class must always be PlugInInfo.

Create your plug-in(s)
Each plug-in should:

Deploy the plug-in
Take the following steps to get Puac to recognize your plug-in:


IPlugIn

This is a real object in that it will have to be a creatable object. Almost all the other objects listed below are non-existing objects with non-existing methods that will have to be simulated. The name of the class MUST be "PlugIn".

MethodCall

<xml>
  <plugin>
  <method>
  <params>

<result>

plugin - The name of the plug-in that is called. The value PlugInInfo should always be supported (it is called to get the names of the plug-ins).

method - The name of the method that is called in the specified plug-in. The values this parameter can have are depending on the kind of plug-in.

params - The parameters that are passed to the method.


PuacControl

This is a control that is needed for some plug-ins if you want to display something in the user interface (for example the settings of an action). The only requirement of the control is that it implements IPlugIn. The meaning of the method call of the PuacControl is slightly different from that for the PlugIn:

MethodCall

<xml>
  <plugin>
  <method>
  <params>

<result>

plugin - The name of the plug-in for which the control is used in the current method call. (Although it is possible to specify a different control for each plug-in, you might want to use the same control for several plug-ins.)

method - The name of the method that is called in the control. The values this parameter can have are depending on the kind of plug-in the control was created for.

params - The parameters that are passed to the method.


PlugInInfo

Not really a plug-in. It provides information about the available plug-ins in the library. This plug-in should always be present.

GetPlugIns

<params>

<result>
  <plugins>
    <plugin>*
      <type>
      <name>

Gets the names and types of the plug-ins in the library.

plugins - A list of plugin nodes.

plugin - A plugin node.

type - The type of the plug-in. The value of type can be one of the following strings:

  • ImportPlugIn
  • FileImportPlugIn
  • ExportPlugIn
  • FileExportPlugIn
  • SynchronizationPlugIn
  • ActionPlugIn
  • GeneralPurposePlugIn

name - The name of the plug-in. This name will be used to call methods of the plug-in.


Providing general information

The following methods should be implemented for all plug-ins, because they enable the user to get help, set settings, and view information about the plug-in in the Puac plug-in window.

GetName

<params>
  <language>

<result>
  <name>

Gets the name of the plug-in.

name - the name of the plug-in. This name will be shown in the plug-in window or when an error occurs when calling a method of the plug-in.

ShowAbout

<params>
  <language>

<result>

Should display an about window for the plug-in.

ShowHelp

<params>
  <language>

<result>

Should display a help window for the plug-in.

ShowSettings

<params>
  <language>

<result>

Should show a settings window for the plug-in.

Example: In the case of an action plug-in: for a message window that pops up for a few seconds, you may want to let the user specify how long the window should be displayed. These settings could then be used for all instances of the action, instead of specifying the time for each separate instance of the action.

You must take care of saving the settings yourself. You could do this in the registry for example. You can also save the settings as a file in the plug-ins directory. The names of these files should start with the name of the dll, followed by an underscore, after which you can make up something of your own. For example: PuacOutlook_settings.ini for a dll called PuacOutlook.dll.


ImportPlugIn

This plug-in is used to import alarmgroups from some unspecified source. This plug-in can be executed by the user by choosing it from the alarmgroups -> import menu.

GetImpMenuCaption

<params>
  <language>

<result>
  <menucaption>

Returns the menu caption that will be shown in the import menu.

menucaption - The menu caption that will be shown in the import menu.

GetAlarmgroups

<params>
  <language>

<result>
  <alarmgroups>
    <algr>*

Returns zero or more alarmgroups that have been imported. This method is called when the user chooses the plug-in from the import menu.

alarmgroups - A list of alarmgroup nodes.

algr - A node that represents the alarm group. See the alarm group specification for the format of these nodes.


FileImportPlugIn

This plug-in is used to import files. It will have to provide the supported file formats to Puac, which then shows the format in the open-file dialog if the user wants to import a file.

GetImpFileFormats

<params>
  <language>

<result>
  <filters>
  <extensions>


GetAlarmgroupFromFile

<params>
  <language>
  <path>

<result>
    <algr>


ExportPlugIn

This plug-in is used to export alarmgroups to some unspecified source. This plug-in can be executed by the user by choosing it from the alarmgroups -> export menu.

GetExpMenuCaption

<params>
  <language>

<result>
  <menucaption>

SetAlarmgroups

<params>
  <language>
  <alarmgroups>
    <algr>*

<result>
  <success>|<error>


FileExportPlugIn

This plug-in is used to export alarm groups to files. It will have to provide the supported file formats to Puac, which then shows the format in the save-file dialog if the user wants to export a file.

GetExpFileFormats

<params>
  <language>

<result>
  <filters>
  <extensions>

SaveAlarmgroupToFile

<params>
  <language>
  <path>
  <algr>

<result>
  <success>|<error>


SynchronizationPlugIn

A synchronization plug-in is a plug-in that automatically keeps an alarm group up to date with a source outside of Puac.

If you want an alarm group to be read only, you should specify a read only tag in the alarm group when sending it to Puac (see agx specification). If you want an alarm group to be write only, just return the alarm group you get passed by Puac without changing it.

Synchronize

<params>
  <language>
  <syst>
  <algr>

<result>
  <algr>

Is called when an alarm group needs to be synchronized. The original alarm group is passed as a parameter. The updated alarm group should be returned.

syst - These are the synchronization settings that have been set by the user in the alarm group properties window.

algr - This parameter contains the xml of the alarm group that should be synchronized (see agx specification). If you didn't specify an alarm group to be read-only, the user might have changed properties and you should save them or at least make sure the changes aren't lost when you return the updated alarm group.

algr - This is the updated alarm group.

GetSynchInfo

<params>
  <language>

<result>
  <description>
  <shortdescription>

This method will have to return information about the synchronization plug-in.

description - A description of the synchronization plug-in. It will be shown in the list with synchronizers in the alarm properties window.

shortdescription - A short description of the synchronization plug-in. It will be shown in the list of alarm groups in the main window.

GetSynchSettingsControlName

<params>
  <language>

<result>
  <name>

Returns the name of the control that will be used to show the settings in the alarm group properties window (see below).

name - The name of the control. Returns an empty string if there is no control to display settings.

The synchronization settings control

This is the control you should provide if you want to show some settings for the synchronization plug-in. It should implement the methods below. This control should have a size of 336*72 pixels.

SetSettings

<params>
  <language>
  <sett>

<result>

Shows the specified settings in the control.

sett - The settings of the synchronizaction plug-in for a specific alarm group. If the sett node is empty, the control should display the default settings.

GetSettings

<params>
  <language>

<result>
  <sett>

Returns the settings currently displayed in the control.

sett - The settings. These settings will be used when they are displayed again (SetSettings) and when the alarm group is synchronized.


ActionPlugIn

Execute

<params>
  <language>
  <sett>
  <alrm>

<result>
  <success>|<error>

Is called when the action should be executed.

sett - These are the parameters that have been set by the user in the alarm properties window in the action settings control.

alrm - This parameter contains the xml of the alarm that executes the action. You can of course ignore this, but you may want to use it to for example show the name of the alarm somewhere.

success - This is an empty node that should be returned in the case that the action succeeds. If this node is not present, Puac will show an error message or execute some other replacing action. (Note that we really do need a separate node to indicate success: an error could occur while returning the error string.)

error - This is an optional error message. This error will only be shown when the success node is not present.

GetStatus

<params>
  <language>

<result>
  <active>

Returns the status of the plug-in.

active - A boolean value indicating if the plug-in is currently executing. 0 = False, any other number = True. A reference is kept to the plug-in until this method returns false (to prevent the plug-in from terminating early).

GetActionInfo

<params>
  <language>

<result>
  <shortdescription>
  <category>
  <description>

This method will have to return information about the action.

shortdescription - A short description of the action. It will be shown as the name of the action in the action selection window, as description in the list of actions in the alarm properties window and as description of the action in the main window.

category - The category of the action. This will be shown as the category of the action in the action selection window. Although you are free to make up your own categories, I recommend you conform to the categories that already exist, because it will be easier for the user to search for actions in a specific category.

description - The description of the action. This will be shown as the description of the action in the action selection window. If you are 'extending' an already existing action, you should specify what makes this action different from the already existing one. For example: 'Shows a message window that will disappear after 3 seconds'.

GetSettingsControlName

<params>
  <language>

<result>
  <name>

Returns the name of the control that will be used to show the settings in the alarm properties window (see below).

name - The name of the control. Returns an empty string if there is no control to display settings.

The action settings control

This is the control you should provide if you want to show the settings of an action. It should implement the methods below. For this control, a spacious area of 600*72 pixels is reserved in the alarm properties window.

SetSettings

<params>
  <language>
  <sett>

<result>

Shows the specified settings in the control.

sett - The settings of the action. These are the same settings as in the sett node of an action in an alarm. If the sett node is empty, the control should display the default settings.

GetSettings

<params>
  <language>

<result>
  <sett>

Returns the settings currently displayed in the control.

sett - The settings of the action. These are the same settings as in the sett node of an action in an alarm. You can choose the format of the sett node yourself. It will be used in the SetSettings method and when the action is executed.


GeneralPurposePlugIn

This is a plug-in that just runs at the same time as Puac, for example a clock.

GetGPPMenuCaption

<params>
  <language>

<result>
  <menucaption>

Returns the menu caption that will be shown in the general purpose plug-ins menu.

menucaption - The menu caption that will be shown in the active plug-ins menu.

Run

<params>
  <language>

<result>
  <success>|<error>

Runs the plug-in.

Quit

<params>
  <language>

<result>
  <success>|<error>

Quits the plug-in.

GetStatus

<params>
  <language>

<result>
  <active>

Returns the status of the plug-in.

active - A boolean value indicating if the plug-in is currently running. 0 = False, any other number = True. This method is called every time the user opens the 'active plug-ins' menu and when the settings are saved. This is because you might want the user to quit the plug-in from the plug-in itself and Puac can currently not be notified when this happens.


www.puac.net
www.kokpeter.dds.nl/Puac3/index.html