|
sampleplugin |
library SamplePlugin;
{This is a sample zMUD Plugin. Use this as a template for other plugins}
{zMUDAPI VERSION 2}
{Note that SysUtils is optional and is only used by the call to IntToStr in the
ParseMUDLine sample procedure}
uses SysUtils, zMUDAPI; {includes all the functions we can call}
{$I zmud.inc} {include zMUD command IDs if you need to reference them}
type
PCharArray = Array[1..99] of PChar; {array used to pass parameter lists}
procedure RegisterPlugin( Name, Company, Regcode, Description, Version, HelpFile: PChar; var LoadDef: Boolean); stdcall;
{REQUIRED}
{this routine is called to install your plugin. You must return the
Name of the plugin, the name of your Company (or author name), and the
Registration code that you are issued when you purchase the zMUD
Developer's Kit. Without all of this information, the plugin will not
install. Also note that only the registered version of zMUD (v5.30 and
greater) will install your plugin. The Description of the plugin is
optional information shown in the About box for the plugin. The Version number
is shown in the About box for the plugin}
{Plugins autoload the first time they are used. To disable this and force
the user to manually load the plugin from the zMUD Plugins menu, set
LoadDef to false. After the first time, plugin loading is determined by
whether the plugin was last loaded or unloaded by the user in the Plugins menu}
{HelpFile is the name of the *.HLP file for the plugin. If left blank, the name of the
DLL file with HLP instead of DLL is used}
begin
{Note that this routine can also check whatever you wish to see if the user
has purchased the plugin from you as well, so you are free to sell your
plugins if you wish, or you can just distribute them freely. There are
no license requirements other than being a registered zMUD user and registered
user of the Developer's Kit}
{This information is displayed within the About box for the plugin within zMUD}
StrCopy( Name, PChar('Name of Plugin')); {this is the name of the plugin}
StrCopy( Company, PChar('Registration Name')); {replace this with your actual registration name}
StrCopy( Regcode, PChar('XXXXXXXXXXXX')); {replace XXXXXXXXXXXX with your actual reg code}
{Note that you probably do not want to pass the Regcode in clear text like this in case
someone snoops your DLL. Perform some sort of encoding so that the proper value is returned
without it appearing as clear text}
StrCopy( Description, PChar('Description of plugin')); {limited to 2046 characters}
StrCopy( Version, PChar('1.0'));
StrCopy( HelpFile, PChar('')); {use DLL file name as HLP file name}
LoadDef := false; {do this to prevent autoloading the plugin the first time}
InitAPI(0); {THIS LINE IS REQUIRED} {initializes the zMUDAPI.DLL}
end;
function PluginAPIVersion: Integer; stdcall;
{REQUIRED}
{Return the version of the zMUDAPI that is being used for this plugin. Your plugin will
only be loaded by versions of zMUD that support this API version}
{If this routine is omitted, your Plugin is assumed to be version 1}
begin
Result := 2;
end;
procedure InitPlugin; stdcall;
{OPTIONAL}
{This routine is called after the plugin is successfully registered. Do whatever
initialization code you need here}
begin
end;
procedure ClosePlugin; stdcall;
{OPTIONAL}
{This routine is called before zMUD exits. Do whatever cleanup code is needed here}
begin
end;
{$I Sample.INC} {reference any .INC file created by CMDEDIT.EXE}
procedure AddCommands( Filename: PChar; var ComVersion: Integer); stdcall;
{OPTIONAL}
{allows you to add commands to zMUD. Create a command file using the
supplied CMDEDIT program. Include the resulting filename.INC file above
to include your command symbols, and distribute the filename.DAT command
file with your plugin.DLL file (you do not distribute the .INC file, it
is just for the Delphi compiler)}
begin
StrCopy( Filename, PChar('SAMPLE.DAT')); {name of .DAT file created by CMDEDIT}
ComVersion := PluginVers; {points to the current version stored in the .INC file}
end;
procedure PluginCommand( H: THandle; ComID, NumParam: Integer; ComStr: PChar; P, AllP: PCharArray); stdcall;
{OPTIONAL}
{Execute one of your plugin commands. ComID contains the ID number of the command
to execute. ComStr contains the entire parameter list in case you need to parse it
yourself. NumParam is the number of parameters passed in the P array. AllP contains
the parameters %-1, %-2, %-3, etc which are the full command parameter list starting
at the specified argument number}
{H is the handle of the MUD window making the call}
begin
end;
function PluginFunction( H: THandle; ComID, NumParam: Integer; ComStr: PChar; P: PCharArray; var L: Integer): PChar; stdcall;
{OPTIONAL}
{Execute a plugin function and return the result. ComID contains the ID number of the
function. ComStr contains the entire parameter list in case you need to parse it
yourself. NumParam is the number of parameters passed in the P array}
{Set L to the length of the result that you return}
{DisposeStr will be called to allow you to dispose of the result you return}
{H is the handle of the MUD window making the call}
begin
Result := nil;
end;
procedure AddMenu( MenuIndex: Integer; Caption, HelpStr: PChar; var ComID: Integer; M: HMENU); stdcall;
{OPTIONAL}
{used to add menu items to the Tools menu for your Plugin. All your menu items are
on the submenu for your plugin in the zMUD Tools menu. This routine is called multiple
times, with MenuIndex starting at one and then incrementing. Each time, you should
return the Caption of a menu item and the corresponding command ID you want to execute
when the user selects the menu item. If you are done adding menu items, return a blank
Caption name}
{M is the Handle to the MenuItem being created}
{You can also return ComID of -1 with blank Caption to prevent any menu from being added
for this plugin.}
begin
StrCopy( Caption, PChar(''));
end;
procedure MenuCommand( H: THandle; ComID: Integer); stdcall;
{OPTIONAL}
{executes a menu command previously defined with the AddMenu call.
Note that menu command IDs are seperate than Command and Function IDs}
{H is the handle of the MUD window making the call, or zero if no mud window is open}
begin
end;
const
idPluginFunction = 1;
idUserInput = 2;
idSaveSettings = 3;
idParseMUDLine = 4;
idMUDInput = 5;
procedure DisposeStr( H: THandle; id: Word; P: PChar; L: Integer); stdcall;
{SEMI-OPTIONAL}
{Called whenever you send a PChar result back to PluginFunction, UserInput, SaveSettings,
ParseMUDLine, or MUDInput. id indicated the procedure that allocated the memory}
{The PChar that you returned to these functions is given in P so that you can dispose
of the memory used by the string as needed. L is the size of the data to be disposed.}
{H is the handle of the MUD window making the call}
begin
end;
function UserInput( H: THandle; P: PChar; var L: Integer; var SendToMUD: Boolean): PChar; stdcall;
{OPTIONAL}
{called when the user sends output to the MUD. The line to be sent to the MUD is
passed in P. L is the length of the line. Set SendToMUD to false to prevent the command
from being sent. To modify the command, return a PChar with the new command and set L
to the length of the new command. zMUD will call DisposeStr to allow you to dispose the
PChar if you need to}
{H is the handle of the MUD window making the call}
begin
SendToMUD := true;
Result := nil;
end;
function ParseMUDLine( H: THandle; P: PChar; var L: Integer; IsPrompt: Boolean; var DoGag: Integer; var DoUpdate: Boolean); stdcall;
{OPTIONAL}
{Called when a line of text is received from the MUD. You get this line BEFORE triggers
have been processed. You can return different text as the result of this function (and
set L to its length) and the triggers will process your modified text.
However, if you want the updated text also changed on the screen,
you need to set the DoUpdate flag to true. To delete the line from the screen and
prevent the zMUD triggers from seeing it, set the DoGag parameter to 1. If you want
to prevent the line from being gagged by anyone else, including zMUD, set the DoGag
paremeter to -1. The IsPrompt variable indicates whether this is a full line (false)
or whether it is a partial line without a newline that might be a MUD prompt (true).
Note that it might not actually be a MUD prompt, but could just be the end of a network
data buffer. L is the length of the line}
{If you return new text to be processed, DisposeStr will be called to dispose of the string
when it it no longer needed by zMUD}
{H is the handle of the MUD window making the call}
begin
Result := nil;
end;
procedure CaptureOutput( H: THandle; AsciiText, RawText: PChar); stdcall;
{OPTIONAL}
{This routine is called whenever a line of text has been displayed on the screen. It is
called AFTER triggers have been processed and reflects the actual output on the screen
(which may have been modified with #SUB or #CW triggers). The text cannot be changed here
(use ParseMUDLine to change it). This routine is used to snoop the actual text displayed
on the user's screen}
{The AsciiText variable contains only the ascii text of the line, with any control codes
stripped out. The RawText includes any ANSI color codes used in the line. Not that zMUD
regenerates the ANSI color codes so this text may not exactly match the raw input received
from the MUD (use MUDInput for that)}
{H is the handle of the MUD window making the call}
begin
end;
function MUDInput( H: THandle; P: PChar; var L: Integer): PChar; stdcall;
{OPTIONAL}
{VERY LOW LEVEL! This routine is called whenever a buffer of data is received from
the MUD server. You can change the text by returning a new text buffer and setting L
to its length. zMUD will discard the original text and use your returned text as if
it was received from the MUD instead. DisposeStr will be called to allow you to dispose
of your string buffer if necessary}
{H is the handle of the MUD window making the call}
begin
end;
procedure UpdatePlugin( H: THandle); stdcall;
{OPTIONAL}
{this procedure is called whenever a change is made to a zMUD variable in case
the plugin needs to be updated or recomputed when this occurs}
{H is the handle of the MUD window making the call}
begin
end;
procedure LoadSettings( P: PChar; L: Integer); stdcall;
{OPTIONAL}
{settings for the plugin have been loaded from the user's .MUD settings file
and placed into the P buffer. L is the length of data in the buffer}
begin
end;
function SaveSettings( var L: Integer): PChar; stdcall;
{OPTIONAL}
{in order to store settings for the plugin into the user's .MUD settings file,
place the data into a PChar buffer and return it. L is the length of data stored
in the buffer}
{DisposeStr is called to dispose of the result}
begin
Result := nil;
end;
const
zMUDSTAT_ACTIVATE = 1; {zMUD application is now the active app on the system}
zMUDSTAT_DEACTIVATE = 2; {zMUD application no longer the active app}
procedure zMUDStatus( Stat: Integer); stdcall;
{OPTIONAL}
{called when the zMUD application status changes values. Possible values are shown above}
begin
end;
procedure OpenThread( H: THandle; Name, Host: PChar; Port: Word); stdcall;
{OPTIONAL}
{Called when a MUD character using this plugin is first opened in zMUD. Name is the name
of the MUD character and H is the handle of the MUD character window, Host is the MUD
Hostname, and Port is the port number being connected to}
begin
end;
procedure CloseThread( H: THandle); stdcall;
{OPTIONAL}
{Called when a MUD character window is closed. H is the handle of the window}
begin
end;
procedure OnConnect( H: THandle); stdcall;
{OPTIONAL}
{Called when the MUD socket connection of a character window is connected to the MUD.
You can use SendStr at this point to send data to the MUD}
begin
end;
procedure OnDisconnect( H: THandle); stdcall;
{OPTIONAL}
{Called when the socket to the MUD window is closed by the MUD server}
begin
end;
{EXPORTS LINE IS REQUIRED}
{be sure and only list the routines that you have actually implemented}
exports
RegisterPlugin, InitPlugin, ClosePlugin, AddCommands, PluginCommand, PluginFunction,
AddMenu, MenuCommand, UserInput, ParseMUDLine, MUDInput, UpdatePlugin,
LoadSettings, SaveSettings, PluginAPIVersion, CaptureOutput, zMUDStatus,
OpenThread, CloseThread, OnConnect, OnDisConnect;
begin
end.
|
|