Creating a new plugin.
This section is for advanced users only. You should know at least one programming language to create a plugin. The following explanation is based upon Delphi examples.
If you want SR to successfully import the functions from your DLL library, you should comply with the following requirements:
1) The function always receives the full name of the host program (sr.exe) via pchar (pointer to a null-terminated string). Delphi programmers should always use 'stdcall':
procedure myproc(host:pchar); stdcall;
2) Your function can receive any data from SR (vars, xvars, conditions, etc) after connecting to sr.exe:
function sr_getdata(key:pchar):pchar; stdcall; external
Never call the function twice in a row: it uses one and the same buffer to prevent lost pointers. You should always save data to local (dll) variables before calling the function again:
Error: if sr_getdata('*XVR LIST COUNT') = sr_getdata('*XVR
LIST NUMBER') then...
One function for compartibility checkings - returns the version of SR:
function sr_getver:integer; stdcall;
The version is encoded so that it can be compared with < or
> operations. For example, 20300 means v2.03. For beta releases,
decrease 1 from the last number and add the beta number to the last
two digits. For instance, 20205 means v2.03 beta 5.
There are functions that can be used for result preview purposes:
// Get the number of files in the SR file list (integer is
32-bite signed integer type):
// Get the name of the file number 'num' (0 means the first
file, sr_getfilecount-1 means the last file):
// Get the number of all accessible variables (var, con, xvr,
// Get the name of var number 'num' (0 - first accessible var,
sr_getvarcount-1 - last accessible var):
3) Your function can return as many data strings as you need. Each peace of data is referred to with the help of a unique key:
procedure sr_setdata(data:pchar); stdcall; external
The 'data' data is transmitted in the following format: "key=value" where key is a unique name of the data and value is the data.
4) To get parameters values you must use the mykeys:=sr_getdata('*KEY') at the very beginning of the function, where "mykeys" is a string to store the keys.
The following function extracts the value of "keyname" from the "keys" string:
function sr_getkey(keyname,keys:pchar):pchar; stdcall;
Note: in version 2.00 you could write "myvalue:=sr_getdata('*KEY BARKANIMAL');" to do the same thing. This way is still available for backward compartibility, but use it with caution. It causes problems when you use another *XXV call from your plugin, for example, if you use "coolval:=sr_getdata('*XXV SECOND FUNCTION');". In this case the keys will be overwritten by the last function and it will cause errors in your first function. This won't happen if you use new above described rules.
5) If you write a plugin for distribution, it's preferable to create a sr_help interface to help the users understand how to use the plugin. sr_help interface contains a little help part that describes the names of functions and result keys and an auto-filling part that automatically fills out the appropriate fields in SR with the default parameters.
Your helping function is very similar to the main function but it should be called 'sr_help'. Don't forget to export it, otherwise it will not be visible for SR! The function may return the following default results (all are optional):
sr_help - the text of the help message.
procedure sr_help(host:pchar); stdcall;
hlp:='sr_help=ANIMALS DEMO PLUGIN for SR
6) One dll can contain as many functions as you need. You may make them all accessible (use export).
The examples with sources are to be found in 'external' subfolder of the program.
Suggestion: if you happen to create an interesting external program that can be useful to other users of SR, contact Acritum Software support team. Your work will become accessible for downloads from www.acritum.com. Please note that your pack should contain full sources (we cannot distribute compiled plugins that may contain harmful code).