The PtokaX second API (most known as API2)
First version of API2 was written in 0.3.6.0d
Last add to API2 was in 0.4.0.1

API2 can be divided into these categories:

• The Base
  • Global Functions
  • Core
  • SetMan
  • RegMan
  • BanMan
  • ProfMan
  • TmrMan
  • UDPDbg
  • ScriptMan
  • IP2Country
• Tables
  • User table
  • Registered user table
  • Ban table
  • Range ban table
  • Profile table
  • Profile permissions table
• IDs
  • Profile permissions IDs
  • Setting boolean IDs
  • Setting number IDs
  • Setting string IDs
  • User data IDs for Core.GetUserData call.

All events that happens in the hub (i.e user login / script start) is explained here
All functions using (user) or (user,data), gets the user in user table

Code written here, will be processed at script (re)start and hub start. Usually we reg bots and load files here.

Called at script stop, restart and hub stop. Here is a good place to save files

Default function called by timer on given interval
You may add a timerID with a specified interval, this function is fired at that interval.
The timer is vastly different than in the previous API yet it allows for multimers without a great deal of code
When converting script from API1, ensure the required changes in the timer code are attended to.

Called when an unregistered user completes the log-in process.
Here we can send RightClicks or messages to the user and so on.

This is called when an unregistered user logs out.
Here we usually sends log-out messages and save user data to files.

Same as UserConnected but for registered users whose profile class is not an operator.
Default qualifying profiles: Reg and VIP

Same as UserDisconnected but for registered users whose profile class is not an operator.
Default qualifying profiles: Reg and VIP

Same as RegConnected but for registered users whose profile class is an operator.
After successful log-in an operator's client should enable the “Redirect User” and “Kick” functions.
Profile permissions as well as script may offer additional operator commands, but these are required per protocol.
Default qualifying profiles: Operators and Masters

Same as RegDisconnected but for registered users whose profile class is an operator.
Default qualifying profiles: Operators and Masters

Is called when a critical [fatal] script error is encountered.
This makes it possible to send error messages to specific user and profiles.

Note that error message is always sent to Px GUI as well as the debug interface.

Incoming supports from user which indicate to the hub what extended features a client possesses.
Examples: UserCommand and UserIP2

Incoming key from user. As part of the initial negotiation between the client and hub,
the hub sends a $Lock command and the client must respond with a $Key command.
The $Lock and $Key commands will be explained in greater detail later on.

Incoming validate nick from user. All characters except $ | and space are allowed in a nickname.
If the nick is already in use or is otherwise not accepted, the hub sends, $ValidateDenide The client must send $ValidateNick again.
If the nick is accepted and is registered, the hub may then send the $GetPass command.
You may set minimum and maximum limits on user nickname in PtokaX → Settings → Rules

Incoming password from user. If the client receives the $GetPass it must reply with: $MyPass <password>

Incoming version from user.

Incoming get nick list request from user.

Incoming user myinfo. Here we receive user nick, tag, description, E-mail etc.
Format: $MyINFO $ALL nick description<tag>$ $<speed><magicbyte>$<e-mail>$<sharesize in bytes>$

Incoming get info request from user. To obtain detailed information about a specific user, the client may send, $GetINFO
The hub must respond with exact $MyINFO command previously sent to the hub by target user.
PtokaX may filter the MyINFO data, relative to it's settings. See: Settings → MyINFO Processing.
PtokaX has a more advanced hub command !getinfo which returns a greater amount of information on the target user.

All Global functions below can ignore received data if we return true in that function.
PtokaX will stop processing the data received from that user.
It will process new data at the next arrival.

This function is called every time something is written in main chat. Here we parse commands, change user messages and so on.

This will show us what user is searching for. Here we can block all searches, or specific profiles/users searches. Or block only some keywords

This function is called every time a private message is sent between users.
As the name indicates a private message or 'pm' is sent strictly from one user to
another rather than a main chat message which is sent to all connected users.
How that message displays in a particular client is relative to the client settings.
Clients typically provide the option of showing pm's in a separate window [preferred by most].

Incoming Active connection request from user.
A client may send $ConnectToMe to cause a peer to initiate a peer-to-peer connection for the purpose of transferring data.
This function is fired on receipt of this command. The hub only handles the request and forwards it on to the remote nick.
The hub has no further invlovement in the transfer.Return true in your script to block this request [stop processing data].

Incoming connection request from user. A client may send this instead of the $ConnectToMe
to cause a peer on another hub to initiate a peer-to-peer connection for the purpose of
transfering data. This is an extension for multiple [network] hubs.

Incoming Passive connection request from user.
A passive client may send $RevConnectToMe <nick> <target-nick> to request a peer to send a $ConnectToMe command back.

Search result sent from a passive mode user.

Search result sent from an active mode user.

Data sent from user when useing the inbuilt kick command in DC clients

Data sent from user when useing the inbuilt rediect command in DC clients

Incoming hublist pinger request from user

Incoming close command from user

Home

This is the core part of Px Lua API. With these calls we can get/ basic info from the hub, i.e Uptime,Path
We can get user info, online users and Reg bot's for out scripts.
And also send data from the hub as main chat and PM

Calls with a [sVar] in the () i.e ([sVar]), means that sVar is optional
The first letter in the var explains what type it is.
s means string and should be entred “string” or 'string'
n means number and should be written as is 101
b means boolean and should be written as true/false for on/off

Returns the version of PtokaX, useful when saving error logs etc. through script.

Restarts the hub

Terminates the program

Resume listening thread(s) if they were suspended

Stop listening thread(s). If nTime then stops for given time in seconds. Hub looks in this time like it's not running

Register a scripted bot name to userlist.
BotName,Description,Email are string values. bHaveKey is boolean [true/false]
[true = Bot is an operator [has key] / false Bot appears as user ]
Returns true on success, and nil on fail. Parameter Limits:

• BotName: Characters $|<>:?*”/\ and space are not allowed.
• Description: Characters $| are not allowed.
• All Strings: Maximum length limited to 64 characters.

Unregisters sBotname from userlist. Returns true on success, and nil on fail

Returns currently registered bots as table with the values: sNick, sMyINFO, bIsOP and sScriptName

Returns current user peak. Number of users in hub since last start.

Returns max user peak ever

Returns hubs current share size in bytes

Returns hub IP, if available. Else returns nil

Returns Hub-Security or Hub Bot's name

Returns path to PtokaX root folder.
Windows user should know that \ is returned as /

Returns the number of users currently online.

Returns hubs uptime in seconds

Returns all users with user base table. if bAllData is true, then all data for users is returned

Same as Core.GetOnlineNonOps but for profiles with Operator status
Default qualifying profiles: Operators and Masters

Same as Core.GetOnlineNonOps but for regged profiles
Default qualifying profiles: Regs, VIPs, Operators and Masters

Returns all users with user base table. if bAllData is true, then all data for users is returned.
Vars can be written as following (bAllData),(nProfileNumber]),(nProfileNumber,bAllData). Non of the vars is requierd.

Returns online user base table, if bAllData is true, then all data for user is returned Return nil when user not online

Returns all data about user Return nil when user is not online

Gets boolean of nVauleID, return true on success (user online), or nil on fail List of nVauleIDs is listed under User data IDs for Core.GetUserData call

Get value of nVauleID, or nil when fail (user not online) List of nVauleIDs is listed under User data IDs for Core.GetUserData call

Returns online user from IP as table as base user table or nil when no user with that IP is found, or a bad IP was gived. Use bAllData for getting full user table insted of base table

If sNick is given then disconnect user with that nick. Usefull for disconnecting a specific user If user is given then disconnect any user recived by this call.

Kicks user, with a message kicked by sKickerNick with sReason. Return nil on fail, and true on success.
Limits:

• sKickerNick: max length 64 chars and chars $ | and space is not allowed
• sReason: max length 128000

Redirects user to given address with reason. Returns true on success and nil on fail.
Limits:

• sAddress: max lenght 1024
• sReason: max length 128000

Warn user on flood, return true if success, nil on fail

All calls below has an data max length of 128000 chars
All data should end with an endpipe ( | ). If nothing else is noted, calls automatic adds | at end.

Send data to all users in main chat

Send data to specific nick

Send data as pm to OpChat, this call does not add | at end.
If OpChat is not enabled in Px GUI, then nothing is sent

Send data in main chat, to users with Operator status
Default qualifying profiles: Operators and Masters

Send data to nProfileNumber in main chat

Send data to user in main chat

All calls below has an data max length of 128000 chars
sFromNick has a max length of 64 chars
No data should end with an endpipe ( | )

Send data to all users in pm, from sFromNick

Send data in pm to sToNick from sFromNick

Send data in pm to online profiles with operator status from sFromNick
Default qualifying profiles: Operators and Masters

Send data in pm to nProfileNumber from sFromNick

Send data in pm to user, from sFromNick

Home

This is the Settings Manager part of the API. Calls here allows you to set all Px settings.
Explanation of nBoolID, nNumberID, nStringID ID's is covered under the following categories:
Setting bools IDs, Setting numbers IDs, Setting strings IDs Link this line to thoose cat when created!
All 3 is number values and should be written as SetMan.GetBool(0)
All Settings can be found in Px GUI under the Settings page

I think this should be documented to the extent of explaining variable types and referring to the PtokaX setings pages. — bastya_elvtars

Something like the line above, and the explonation of SetMan.SetBool below? – Madman

Save all settings to Settings.xml

Returns the Message Of The Day. Which is the content of cfg/Motd.txt

Sets hubs MOTD, | (endpipe) is not allowed.

Returns true if nBoolID is on, else it returns nil

Sets nBoolID on or off. bBoolean should be true if setting should be turned on, or false if setting should be off.

Returns the number of nNumberID

Sets nNumberID to given nNumber

Returns string if nStringID, or nil

Set nStringID to sString

Returns minimum share for hub in bytes

Sets the minimum share for the hub useing bytes

Sets the minimum share for the hub with nMinShare as limit and, nShareUnit as 0 = B, 1 = kB, 2 = MB, 3 = GB, 4 = TB
nMinShare has a limit of 9999

Set the rule for slot ratio

Returns a table with sNick,sDecription,sEmail,bEnable

Set OpChats data. bEnable sets on/off with true/false, all other is string values Returns true on success, and nil on fail Limts:

• All strings has a max length of 64
• In sNewOpChatName is $|<>:?*”/\ and space not allowed
• In sNewDescription and sNewEmail is $ and | not allowed

Returns a table with sNick,sDecription,sEmail,bEnable,bUsedAsHubSecAlias

Set HubBot data. bEnable and bUseAsHubSecAlias sets on/off with true/false, all other is string values Returns true on success, and nil on fail Limts:

• All strings has a max length of 64
• In sNewHubBotName is $|<>:?*”/\ and space not allowed
• In sNewDescription and sNewEmail is $ and | not allowed

Home

This part allows you to controll registerd user data.
With the calls here you get info about registerd users and Reg/Delete user.
Some calls returns regisregistered user table, explanation of that table can be found under : Registered user table

Save registerd users to xml

Returns a table with all regged as registerd user table

Returns a table with regged users that don't have Operator status Default qualifying profiles: VIP, Reg

Returns a table with regged user that have Operator status Default qualifying profiles: Master and Operator

Returns a table with given nick, or nil if nick is not regged

Returns a table with all registerd users

Adds nick as regsiterd user with given profile and password.
Returns true is success and nil if failed Limits :

• sNick can not contain, $|<>:?*”/\ and space
• sPass can not contain |
• sNick and sPass can not be longer then 64 chars

Deletes nick from regsterd users, returns true if success else nil

Change given nick's password and/or profile.
Returns true if success else nil

Clear bad password count(advanced password protection) for given nick. Return nil on fail, and true on success

Home

BanMan allows you to script everything that has do do with banning.
It controlls, Rangebans, ipbans, pern/temp bans and unbaning
Some calls returns ban table/range ban table, explanation of that can be found under Ban table and Range ban table need links

Save bans to xml

Returns all bans as ban table

Returns temporary bans as ban table

Returns permanent bans as ban table

Returns all bans as ban table for given nick or IP, or nil if ban do not exist

Returns temporary bans as ban table for given nick or IP, or nil if ban do not exist

Returns permanent bans as ban table for given nick or IP, or nil if ban do not exist

Returns all range bans as ban table

Returns temporary range bans as ban table

Returns permanent range bans as ban table

Returns all range bans with in sIPFrom and sIPTo range, or nil if ban do not exist

Returns temporary range bans with in sIPFrom and sIPTo range, or nil if ban do not exist

Returns permanent range bans with in sIPFrom and sIPTo range, or nil if ban do not exist

Unbans all bans with given nick or IP. Returns true on success and nil on failed

Unbans temporary bans with given nick or IP. Returns true on success and nil on failed

Unbans permanent bans with given nick or IP. Returns true on success and nil on failed

Unban all bans within given range of sIPFrom and sIPTo. Returns true on success and nil on failed

Unban permanent bans within given range of sIPFrom and sIPTo. Returns true on success and nil on failed

Unban temporary bans within given range of sIPFrom and sIPTo. Returns true on success and nil on failed

Remove all bans

Remove all permanent bans

Renove all temporary bans

Remove all range bans

Remove all permanent bans

Remove all temporary bans

Permantly bans users nick and ip
tUser should be user table, sReason and sBy are string values, bFullIpBan is a boolean (true/false)
Returns true on success and nil on failed

Permantly ban ip, with reason.
sIP, sReason and sBy are string values, bFullIpBan is a boolean
Returns true on success and nil on failed

Permantly ban nick, with reason.
sNick, sReason and sBy are string values, bFullIpBan is a boolean
Returns true on success and nil on failed

Temporary bans users nick and ip
tUser should be user table, sReason and sBy are string values, bFullIpBan is a boolean (true/false)
nTime is in minutes (0 = default tempban time from settings)
Returns true on success and nil on failed

Temporary ban ip, with reason.
sIP, sReason and sBy are string values, bFullIpBan is a boolean
nTime is in minutes (0 = default tempban time from settings)
Returns true on success and nil on failed

Temporary ban nick, with reason.
sNick, sReason and sBy are string values, bFullIpBan is a boolean
nTime is in minutes (0 = default tempban time from settings)
Returns true on success and nil on failed

Permantly ban ip within range of sIPFrom to sIPTo
tUser should be user table, sReason and sBy are string values, bFullIpBan is a boolean (true/false)
Returns true on success and nil on failed

Temporary ban ip within range of sIPFrom to sIPTo
sIP, sReason and sBy are string values, bFullIpBan is a boolean
nTime is in minutes (0 = default tempban time from settings)
Returns true on success and nil on failed

Home

This part of the API allows you to add/remove profiles and set/get profile permissions
Some calls returns profile table, details can be found under Profile table needs link as well
Some calls returns permission table, details can be found under Profile permissions table link!

Adds a profile to PtokaX, returns profilenumber if success, nil if profile already exist

Removes given profile from PtokaX. Returns true if success or nil if profile is in use or don't exist

Move profile with profile number down one step. Profile 0 would become Profile 1.
Returns true on success or nil on failed

Move profile with profile number up one step. Profile 1 would become Profile 0.
Returns true on success or nil on failed

Returns profile as profile table, or nil if profile don't exist

Returns table with profiles as profile table.

Returns true if permission is true, else returns nil

Returns table with profile permissions

Change profile name on given profile number to given profilename
Return true if success or nil if profile not exist.

Change profile permission on given profile
Use bBoolean with true/false to set on/off on profile permission
return true if success or nil if profile not exist.

Home

This handels the timer functions.

Adds new timer for script. nTimerInterval is in milliseconsd.
sFunctionName is a string and is optional, if it's not added, what ever the timer should do must be written in OnTimer Return nil when failed or nTimerId when success.

Remove timer with given ID from script.

Home

This part handels UDP debug. I never used it, so someone has to give more details

Register to receive data to PtokaX UDP Debug receiver.
if bAllData is false, Debuger wil only receive data from this script.
Return nil when failed or true when success.

Remove from receiving data.

Send data to udp debug. If script is registered then only to this reg, else to all.
Return nil when failed or true when success.

Home