Script API and plugins creation

Plugins are the expansions connected to plugins processor of Bot Ekzekutor. At writing of own plugins you can use the plugin-template "- TEST PATTERN PLUGIN -", which present in standard package of distribution kits and which represents a set of all possible event files with empty template of contents. The plugin name is a name of its folder. In the plugin folder should be file Pluginfo.lua, where in table Pluginfo contains data about this plugin: description ("info"), version ("version") and activity flag ("enable"):

Pluginfo = {
["enable"] = 1,
["version"] = 1,
["info"] = "Plugin description.",
}

At plugin start if the activity flag sets to 0 it not added in procedures table (inactive). If at start this file is not found then the plugin is considered incorrect and deactivated.

In this folder there should be folders with the name of localisations which are supported by plugin. In these folders files which are brought in the procedures table. Here the list of files which can be in the folder of localisation and their description:

Config.lua - file of configuration with the table containing variables and values by default, which at start are brought in the general configuration file of script (Config.cfg). Here the Config.lua file content:

Config = {
["variable"] = value,
}

Main.lua - file containing operations, carried out at start (loading) of script (plugin). It can be simple setting of any value to variables or performance of any actions and etc.

Vars.lua - in this file variables are created, functions and procedures which are used by plugin. It loading first at plugin start.

Killer.lua - this file contains the destructors. Destruction created in the file Vars.lua variables and functions (sets the value nil) for release the memory occupied with them. It is carried out at full plugin unloading.

Menu.lua - file is similar by structure to files of the Bot or Hub menus. In Menu table contain tables of commands used by plugin. At start the commands from this file are brought in the table of the Bot menu (BotMenu).

OnCommand.lua - file containing procedure, caused at event when the user enters a command. Here it's content:

MyFunctionTable = {
go = function(curUser, data, userclass, curCmd, sParam)
?
return
end,
}
Instead of dots necessary actions are set. Function as parametres receives the command entering user's nick (curUser), his entering text (data), user's profile number (userclass), entering command separately (curCmd) and the command parameters separatly (sParam). If function after actions processing returns nil (return without the parameters), that command processing proceeds further, transferring processing to following plugins after that. If you wish to interrupt command processing use return with value true (return true).

OnMsgAny.lua - in this file contains the function caused at any message from user. On this function basis private messages processing. Here it's content:

MyFunctionTable = {
go = function(curUser, data, userclass, To)
?
return
end,
}
Instead of dots necessary actions are set. Function as parametres receives the user's nick (curUser), his entering text (data), user's profile number (userclass), nick to which the private message is addressed (To). If the message not private, value of variable To is empty string. If function after actions processing returns nil (return without parameters), that command processing proceeds further, transferring processing to following plugins after that. If you wish to interrupt command processing use return with value true (return true).
Except the data variable You can use the variable rawdata, which contains the text transferred in function as is, without change and preliminary processing.

OnMsgChat.lua - file contains the function caused when the user writes message to the general chat. Here it's content:

MyFunctionTable = {
go = function(curUser, chatdata, userclass)
?
return nil,chatdata
end,
}
Instead of dots necessary actions are set. Function as parametres receives the user's nick (curUser), his entering text (chatdata), user's profile number (userclass). If function after actions processing returns nil and variable with chat text chatdata (return nil,chatdata), that text processing proceeds further, transferring processing to following plugins after that. If you wish to interrupt action processing use return with value true (return true).

OnMsgSearch.lua - file with the function caused at receipt of search request and the answer to search request from the user. Here it's content:

MyFunctionTable = {
go = function(curUser, data, sIP)
?
return
end,
}
Instead of dots necessary actions are set. Function as parametres receives the user's nick (curUser), entering search request text (data), user's IP-address (sIP).
If function after actions processing returns nil (return without parameters), that text processing proceeds further, transferring processing to following plugins after that. If you wish to interrupt action processing use return with value true (return true).

OnPlugError.lua - file with the function caused at occurrence an error in script (can not work on Verlihub). Here it's content:

MyFunctionTable = {
go = function(ErrorMsg)
?
end,
}
Instead of dots necessary actions are set. Function as parametres receives the error message (ErrorMsg).

OnPlugTimer.lua - file with the function which is carried out at the main timer operation (60 seconds interval). Here it's content:

MyFunctionTable = {
go = function()
?
end,
}
Instead of dots necessary actions are set.

OnSecondPlugTimer.lua - file with the function which is carried out at the second timer operation (1 seconds interval). Here it's content:

MyFunctionTable = {
go = function()
?
end,
}
Instead of dots necessary actions are set.

OnUnload.lua - file with the function caused at an unloading of plugin or script. Here it's content:

MyFunctionTable = {
go = function()
?
end,
}
Instead of dots necessary actions are set.

OnUserLogin.lua - file with the function caused at connection user to the Hub. Here it's content:

MyFunctionTable = {
go = function(curUser, userclass, sIP)
?
return
end,
}
Instead of dots necessary actions are set. Function as parametres receives the user's nick (curUser), user's profile number (userclass), user's IP-address (sIP).
If function after actions processing returns nil (return without parameters), that action processing proceeds further, transferring processing to following plugins after that. If you wish to interrupt action processing use return with value true (return true).

OnUserLogout.lua - file with the function caused at event disconnect (exit) of the user. Here it's content:

MyFunctionTable = {
go = function(curUser, sIP)
?
return
end,
}
Instead of dots necessary actions are set. Function as parametres receives the user's nick (curUser) user's IP-address (sIP).
If function after actions processing returns nil (return without parameters), that action processing proceeds further, transferring processing to following plugins after that. If you wish to interrupt action processing use return with value true (return true).

OnMsgConnectToMe.lua - file with the function caused at active connection request. Here it's content:

MyFunctionTable = {
go = function(curUser, connectUser, connectIP, connectPort)
?
return
end,
}
Instead of dots necessary actions are set. Function as parametres receives the user's nick (curUser), nick the required user (connectUser), reported current user's IP-address (connectIP) and reported current user's port (connectPort).
If function after actions processing returns nil (return without parameters), that action processing proceeds further, transferring processing to following plugins after that. If you wish to interrupt action processing use return with value true (return true).

OnMsgRevConnectToMe.lua - file with the function caused at passive connection request. Here it's content:

MyFunctionTable = {
go = function(curUser, connectUser)
?
return
end,
}
Instead of dots necessary actions are set. Function as parametres receives the user's nick (curUser) and nick the required user (connectUser).
If function after actions processing returns nil (return without parameters), that action processing proceeds further, transferring processing to following plugins after that. If you wish to interrupt action processing use return with value true (return true).

OnMsgMyINFO.lua - file with the function caused at receipt from the user the MyINFO string. Here it's content:

MyFunctionTable = {
go = function(curUser, data)
?
return
end,
}
Instead of dots necessary actions are set. Function as parametres receives the user's nick (curUser) and text (data).
If function after actions processing returns nil (return without parameters), that action processing proceeds further, transferring processing to following plugins after that. If you wish to interrupt action processing use return with value true (return true).

OnConnect.lua - file with the function caused at client connection to hub before the autorization. Here it's content:

MyFunctionTable = {
go = function(sIP)
…
return
end,
}
Instead of dots necessary actions are set. Function as parametres receives the client's IP (sIP).
If function after actions processing returns nil (return without parameters), that action processing proceeds further, transferring processing to following plugins after that. If you wish to interrupt action processing use return with value true (return true).

Text_lang.lua, where lang - language (2 characters in lower case from the table of supported languages EkzekutorLangs) - text translations of plugin for the selected language (used for multi-language features). Here it's content:

EkzekutorText = {
[1]="index 1 text",
[2]="index 2 text",
?
}
The value of each element may be not only string, but other types of objects (eg table). For get text (or element of any object) from the language file with the appropriate indexes are used multilingual functions of Bot.

Functions of plugins are carried out as sequence of their priorities, by order in which they are in the list of plugins.

Some information about script features and it's API

gl(key, user) - multilingual function. Serves for getting text (or object) with the desired key from the localization file for the language the user or default language, if the user is not contained in the table UsersLangTable and does not set the language. If instead the user's nick function get an empty string, it also means getting the default language. The key is a set of file and index. For text from file of Bot language localization is a combination "Bot_index". For text from file of Hub language localization is a combination "Hub_index". For text from file of Plugin language localization is a combination "PluginName_index". Plugins to get the key for yourself using the variable CurPlugName, which contains the name of the current plugin, and through an underscore index in the table text localization.

GetLangsList() - returns list of languages from the table EkzekutorLangs.

AddRobotBot(nm,cls,dsk,eml) - adds the Bot to the list of Hub. Parameters: nm - name, cls - class, dsk - description, eml - Email.

DelRobotBot(nm) - deletes the Bot to the list of Hub. Parameters: nm - name.

GetClassCount() - returns quantity of available classes on the Hub.

PMToUser(bot, user, from, data) - to send the private message to the specified user. Parameters: bot - nick of bot from whose name the message is sent, user - nick of user to send the message, from - nick which is highlighted in the message as sender, data - message text.

PMToAll(user, bot, data) - to send the private message to all users. Parameters: user - nick which is highlighted in the message as sender, bot - nick of bot (can be empty string) from whose name the message is sent, data - message text.

PMToOPs(user, bot, data) - to send the private message to all operators. Parameters: user - nick which is highlighted in the message as sender, bot - nick of bot from whose name the message is sent, data - message text.

PMToOPsOver(prf, user, bot, data) - to send the private message to all users with frofile not less than prf. Parameters: prf - profile to which the message (and above this profile) is sent, user - nick which is highlighted in the message as sender, bot - nick of bot from whose name the message is sent, data - message text.

PMToClass(prf, user, bot, data) - to send the private message to all users with the profile prf. Parameters: prf - profile to which the message is sent, user - nick which is highlighted in the message as sender (can be empty string), bot - nick of bot from whose name the message is sent, data - message text.

PMToMode(prf, user, bot, data) - to send the private message to all users with the connection mode prf. Parameters: prf - connection mode to which the message is sent (A, P or S, that corresponds active, passive and SOCKS types), user - nick which is highlighted in the message as sender (can be empty string), bot - nick of bot from whose name the message is sent, data - message text.

ToUser(bot, user, data) - to send the text to user. Parameters: bot - nick of bot from whose name the message is sent (can be empty string), user - nick of user to send the message, data - message text.

ToAll(user, data) - to send the text to all. Parameters: user - nick of bot from whose name the message is sent (can be empty string), data - message text.

ToOPs(user, data) - to send the text to operatorf. Parameters: user - nick which is highlighted in the message as sender (can be empty string), data - message text.

ToClass(prf, user, data) - to send the text to all users with the profile prf. Parameters: prf - profile to which the message is sent, user - nick which is highlighted in the message as sender (can be empty string), data - message text.

ToMode(prf, user, data) - to send the text to all users with connection mode prf. Parameters: prf - connection mode to which the message is sent (A, P or S, that corresponds active, passive and SOCKS types), user - nick which is highlighted in the message as sender (can be empty string), data - message text.

ToAllExeptGag(msgs) - to send the text to all except maskgagged. Parameters: msgs - table with list of nicks to which send the message in format [msgs][i]={"name","mes"}, each element of the table msgs is the table of two elements, first of which - nick, the second - message.

ToAllExeptOPs(user, msgs) - to send the text to all except operators. Parameters: user - nick which is highlighted in the message as sender (can be empty string), msgs - message text.

GetAllOnline() - returns the table with list of all users connected to the Hub in format: [user]=class.

GetAllRegs() - returns the table with list of all registered users in format: [user]=class.

GetAllIPs() - returns the table with list of all IP-addresses of connected to Hub users in format: [IP]=user.

SendMenu(str, user) - sends the menu line to the user user. To string str it is automatically added in the beginning "$UserCommand 1 3 " and "||" in the end.

SendMenuToAll(str) - similarly previous function, but the str line sent to all users.

SendMenuToOPs(str) - also similarly previous function, but the str line sent to all operators.

GetUsrClass(user) - returns class of the user user (number).

UsrClassConvert(usercl) - convertation class usercl in scale of Verlihub style, on increase. In verlihub localization, for example, function will return back entrance parametre without changes. In ptokax04 localization will return result by the formula: total_profiles_count - usercl.

isReg(user) - returns true, if user has registered on the Hub, else returns false.

isVip(user) - returns true, if user is VIP, else returns false. In verlihub localization VIP-class considers class 2, in ptokax04 localization VIP-class considers class first after operator class (if there are still classes, besides, without the rights of the Operator).

isOp(user) - returns true, if user has the rights of operator, else returns false.

isMaster(user) - returns true, if user has the rights of the Admin (the highest class), else returns false.

isClassPermissionValid(class1, class2) - function makes comparison the rights of two classes received as parametres. If class1 more exclusive by the rights, than class2, then function will return 1, if both classes are equal in the rights, function will return 0, if class1 less exclusive by the rights, than class2, will return nil.

isPermissionValid(user1, user2) - function makes comparison the rights of two users user1 and user2 received as parametres. If user1 more exclusive by the rights, than user2, then function will return 1, if both users are equal in the rights, function will return 0, if user1 less exclusive by the rights, than user2, will return nil.

GetIP(user) - will return the IP-address string of user.

GetMyInfo(user) - returns the full MyINFO line of user.

GetConMode(user) - will return the description connection mode of user. If the mode is active will return "Active", if the mode is passive will return "Passive", if the mode is Socks5 will return "Socks5", else will return "Unknown".

GetUsrShare(user) - will return an integer byte share size of user.

GetClient(user) - will return line with description the client version of user.

GetUsrConnection(user) - will return line with connection mode of user.

GetDescription(user) - will return line with description of user.

GetUsrEmail(user) - will return line with E-mail of user.

GetSpeedLimit(user) - will return line with value the speed limitation of user, else empty string.

GetSlotCount(user) - will return slots count of user or empty string.

DoBan(user, msg, bantime) - makes ban of user by time in minutes bantime with reason msg. If bantime is -1, then ban is permanent. If bantime is 0, then makes ban by default time.

DoDisconnect(user) - disconnecting of user.

GetMyPrefix(user) - returns approaching for current class of the user command prefix.

GetIPHost(host) - will returns string contains IP-address DNS-name host.

GetCurTopic() - will return the corrent Hub topic.

strLower(str) - converts string str to lower case.

strUpper(str) - converts string str to upper case.

FormatFileSize(int) - converts number int in format of conclusion the share size (string).

getDateTime(dtFormat,user) - will returns time or date string by user language or language by default. If dtFormat = 0, then returns the seconds count from the "Age". If dtFormat = 1, then returns the time in format hh:mm. If dtFormat = 2, then returns the date in format dd.mm.yyyy. If dtFormat = 3, then returns formatted string by seconds count dtFormat, past from the "Age".

SaveToFile(file,table,tablename) - function of saving in text file with name file (full path) contents of table with name tablename.

BotReload() - Bot hot restart.

isForbiddenChars(str) - check the maintenance in line str forbidden characters (the symbols are not containing in the table of allowed nick chars). Will returns true if found else returns nil.

charEncode(str) - will returns str, where all occurrences of HTML codes "&code;" are replaced with corresponding symbols.

getURLSource(url,gz,cp,prox) - will returns the code page from url. If sets parametre qz and it is 1, that will be made GZip unpacking. If sets string cp, that will be is spent the symbols decoding from the codpage cp. In parametre prox may be sets the proxy-server address.

Some useful variables and constants:

localization - current Bot's localisation.

DefaultLang - default Bot's language.

EkzekutorLangs - languages table (["lg"]="Language").

CurPlugName - current plugin name (for using in current plugin).

version - the Bot version.

myhubname - Hub name.

OpChat - Op-chat name.

PathSeparator - separator in the file path string.

CmdPrefix - commands prefix pattern.

wait_chat - table, containing the chat messages sequence for sending in format: wait_chat[n]={user, data}.

wait_pm - table, containing the PM messages sequence for sending in format: wait_pm[n]={bot, user, from, data}.

wait_touser - table, containing the messages sequence for sending to users in format wait_touser[n]={bot, user, data}. Tables wait_chat, wait_pm and wait_touser are processed at the first operation of the main script timer and are cleared.

TableName - table with the users-exceptions (["nick"]=1,).

MaskGagged - maskgagged users table.

The folder name where the script is located, is stored in variable MySettings["FName"] with the path divider at end.

<<< back | print | To main...
PhazaSoft© Ekzekutor©
Hosted by uCoz