Register forum user name Search FAQ

MUSHclient scripting

Description of MUSHclient world function: world.CallPlugin


Name CallPlugin
Type Method
Summary Calls a routine in a plugin
Prototype long CallPlugin(BSTR PluginID, BSTR Routine, BSTR Argument);
Description

Calls a nominated routine in a nominated plugin, supplying a string argument.

The intention here is to allow plugins to interact with each other, to a certain extent.

For instance, you might write a plugin that logs text to a log file (or miniwindow), and want to share it between other plugins. Hence you might log a message like this:

world.CallPlugin "80cc18937a2aca27079567f0", "LogIt", "Data to be logged"

The above example would locate plugin with the ID 80cc18937a2aca27079567f0 (if installed) and then call the routine "LogIt" in that plugin, with the argument "Data to be logged". In this example, the LogIt routine would look like this:

function LogIt (sText)
WriteLog (sText)
end -- function LogIt


You should exercise caution when using this technique. It will be annoying for plugin users if plugins become overly dependent on each other, particularly if they cannot find the one that is required.

Also, be careful you do not set up circular dependencies (eg. A needs B, and B needs A).

You can use "PluginSupports" to see if a particular routine is implemented in a plugin. For example:

if PluginSupports ("80cc18937a2aca27079567f0", "LogIt") ~= error_code.eOK then
Note "Required 'LogIt' routine is not available"
end -- if


If you want to send a message to all installed plugins you might consider using BroadcastPlugin instead.

New in version 4.55: Lua scripts can call Lua plugins using CallPlugin, but pass multiple arguments (not just a single string). Also they can receive returned data. See below for more details.


Note: Available in version 3.23 onwards.


VBscript example
world.CallPlugin "80cc18937a2aca27079567f0", "LogIt", "Data to be logged"
Jscript example
world.CallPlugin ("80cc18937a2aca27079567f0", "LogIt", "Data to be logged");
PerlScript example
$world->CallPlugin ("80cc18937a2aca27079567f0", "LogIt", "Data to be logged");
Python example
world.CallPlugin ("80cc18937a2aca27079567f0", "LogIt", "Data to be logged")
Lua example
CallPlugin ("80cc18937a2aca27079567f0", "LogIt", "Data to be logged")
Lua notes
Functions can be nested inside tables. So for example you could call function "foo.bar".


New in version 4.55 onwards:

You can pass multiple arguments which must be one of: nil, boolean, number or string.

The called function can return zero or more values which must also be one of the above types.

For example:

rc, a, b, c, d = CallPlugin ("80cc18937a2aca27079567f0", "show_message", "red", "green", "message", 42)

On an error the second value returned ('a' in the example) will be a string indicating the reason for the error.

On an execution error (eErrorCallingPluginRoutine) there will also be a third return value ('b' in the example) which is the error message generated at runtime.

See: 

http://www.gammon.com.au/forum/?id=10453
Returns eNoSuchPlugin: Plugin not installed
ePluginDisabled: Plugin is disabled
eNoSuchRoutine: Specified routine cannot be found in that plugin
eErrorCallingPluginRoutine: Error when calling function (runtime error) OR - the function returned an unsupported data type (Lua only)
eBadParameter: An argument was an invalid type (Lua only)
eOK: Called OK
Introduced in version 3.23

See also ...

Function Description
BroadcastPlugin Broadcasts a message to all installed plugins
GetPluginID Returns the 24-character ID of the current plugin
GetPluginInfo Gets details about a specified plugin
GetPluginList Gets a list of installed plugins.
IsPluginInstalled Checks to see if a particular plugin is installed
LoadPlugin Loads a plugin from disk
PluginSupports Checks if a plugin supports a particular routine

Search for script function

Enter a word or phrase in the box below to narrow the list down to those that match.

The function name, prototype, summary, and description are searched.

Search for:   

Leave blank to show all functions.


Return codes

Many functions return a "code" which indicates the success or otherwise of the function.

You can view a list of the return codes


Function prototypes

The "prototype" part of each function description lists exactly how the function is called (what arguments, if any, to pass to it).

You can view a list of the data types used in function prototypes


View all functions

[Back]

Information and images on this site are licensed under the Creative Commons Attribution 3.0 Australia License unless stated otherwise.