The PtokaX API can be divided into the following categories, according to what we are dealing with:

• frmHub object
• user object
• Other objects
• Events
• Global functions

As you probably know, these are all add-ons to the current LUA functions (LUA is an 'extensible extension language').

If you know how objects look like in LUA, you can skip this.

Honestly, objects in LUA are tables (since this is the only data structuring mechanism in it).

Let's just see an example, how an object looks like:

Test=
{
  Value1=5,
  Value2=6,
  ShowValues=function()
    print(Test.Value1,Test.Value2,(Test.Value1*Test.Value2))
  end,
}

Now you call Test.ShowValues() in the end, and it will output (using the standalone LUA interpreter):

5	6	30

You can make this better:

Test=
{
  Value1=5,
  Value2=6,
  ShowValues=function(self)
    print(self.Value1,self.Value2,(self.Value1*self.Value2))
  end,
}

The way you have to call the function is: Test.ShowValues(Test), and you will get the same output (using the standalone LUA interpreter). However, if structurized this way, it is easier to call it the way Test:ShowValues(), because the self parameter lets the function know that we are referring to the table it resides in. Note that if you are using the values from the object, the parentheses must be omitted and you have to use the dot, not the colon: a=Test.Value1. Let's just change the above code a bit:

 Test=
{
  Value1=5,
  Value2=6,
  ShowValues=function(self)
    return self.Value1,self.Value2,(self.Value1*self.Value2)
  end,
}

The function does no longer print, but returns those 3 values. You can then use it the following way (using the standalone LUA interpreter):

a,b,c=Test:ShowValues()
print(a.."*"..b.."="..c)

which will output:

5*6=30

I hope you understand objects now, at least a bit, because I think this is needed for better understanding of what we are doing.

All events (that happen in the hub) call a function. These functions are the following:

Every statement inside this function is processed on script startup. Usually we register bots, and load files. Changes will aply after restarting the scripts (like in every change).

Called before the scripting part stops,usually good for saving things, etc.

This is called on every timer event, more on this at Timers.

This is called when a user's login process starts.*

This is called when a user's logout process starts.*

This is called when an operator's login process starts.

This is called when an operator's logout process starts.

Called on script errors. ErrorMsg is a string describing the error.

Incoming $Supports from user.

Incoming chat message from user. Discardable.

Incoming $Key from user.

Incoming $ValidateNick from user. Note that this is deprecated and ignored in QuickList.

Incoming $MyPass from user.

Incoming $Version from user.

Incoming $GetNickList request from user.

Incoming user $MyINFO string.

Incoming $GetINFO request from user. Note that this is deprecated and ignored in QuickList and NoHello/NoGetINFO protocols.

Incoming $Search from user. Discardable.

Incoming private message from user. Discardable.

Incoming active connection request from user. Discardable.

Incoming multi connection request from user. Discardable.

Incoming passive connection request from user. Discardable.

Incoming search reply from user. Discardable.

This includes results to be relayed to passive users and results sent directly to the hub on the UDP listening port. If this SR was sent directly to the hub then the user nick is forced to be “slotcheck”.

(HaArD - as per chat with PPK 2005-Aug-31)

As I have already covered somewhere else, this is a total waste of resources. CDMs can put at least 50% less load on the hub with ADL compared to serverside checking methods. — bastya_elvtars

Incoming $Kick command from user. Discardable.

Incoming redirect command from user. Discardable.

Incoming $UserIP from user. Discardable.

Incoming unknown command from user. Discardable.

Incoming $BotINFO from user. Discardable.

The (first) question is: 'How the hell should I use these?' The answer is: 'You just declare functions of the desired names, as usual.' Let's just see an example: this sends a welcome message to the connecting user.

function NewUserConnected(user)
  user:SendData("Welcome-Bot","Welcome! Have a good time!")
end

In these functions, user is an object ( you can learn more about this in the chapter 'Objects' in LUA). As you might probably know, these argument names are not mandatory, you can call them anything. Another example:

function MyINFOArrival(user,data)
  data=string.sub(data,1,string.len(data)-1) -- remove end pipe
  data=string.lower(data) -- make lowercase
  if string.find(data,"netlimiter") then -- if this string is found then
    user:SendData("AntiNetLimiter","Do not use NetLimiter!") -- send a message
    user:Disconnect() -- and disconnect
  end
end

In functions like this, data is always a string. The end-pipe should always be removed, as it confuses LUA. Now we have one more example left, about discarding:

function ChatArrival(user,data)
  data=string.sub(data,1,string.len(data)-1) -- remove end pipe
  if string.find(data,"https?://") or string.find(data,"www%.") then -- if this string is found then
    user:SendData("AntiAdvBot","Do not post URLs!") -- send a message
    user:Disconnect() -- and disconnect
    return 1 -- block the chat message
  end
end

If you return a 1 in a chunk, you block any further execution, if you return it in a discardable function, the hub won't process the data any further (in this example, message won't be seen in main). (Avoid to use this chunk in a 'production' environment, it's far from perfect! :D) Well, now you know all you need about events, let's go one step beyond.

The following global functions are available in PtokaX:

Sends a mainchat message to all users, in the name of Nick (it'soptional). Examples:

SendToAll("Joe","Hello") --> <Joe> Hello
 
SendToAll("Hello") --> Hello

Both work, but if no nick specified, you can send a raw command.

Sends a private message to all users, in the name of FromNick.

Sends Data to Nick, Data is always raw.

Sends a private message to ToNick from FromNick.

Same as SendToAll, but sends to operators only.

Same as SendPmToAll, but sends to operators only.

Disconnects Nick from the hub, if connected.

If Nick is online, returns the userobject belonging to it, otherwise returns nil. This seems misty, so let's see an example. This example introduces the !disc comand, which can only be used by ops, and disconnects users, reason must be specified.

function ChatArrival(user,data)
  data=string.sub(data,1,string.len(data)-1) -- remove end pipe
  local _,_,cmd=string.find(data,"%b<>%s+(%S+)") -- find the first non-space string
  if cmd=="!disc" and user.bOperator then -- only ops can disconnect
    local _,_,nick,reason=string.find(data,"%b<>%s+%S+%s+(%S+)%s+(.+)") -- the second non-space and anything afterwards are captured
    if nick then
      local usr=GetItemByName(nick) -- get the object
      if usr then -- if online
       usr:SendPM("DisconnBot","You are now disconnected because: "..reason)
       usr:Disconnect()
      end
    else
      user:SendData("DisconnBot",nick.." is offline.")
    end
    return 1 -- to block command visibility in main
  end
end

(Maybe DisconnectByName would be better? :P)

If Nick is banned, returns the IP belonging to it.

If IP is banned, returns the nick belonging to it.

Unbans the permbanned what, it can be a nick or an IP.

Unbans the tempbanned IP.

Clears the tempban list.

Clears the permban list.

Registers Nick with Pass as password, and ProfileNumber as profile. See Profiles section. It also changes the pass/profile if the nick is already registered.

Deletes registered user Nick. Returns -1 if failed.

Bans IP permanently..

Bans Nick permanently.

Bans IP temporarily, time is from PtokaX default TempBan time.

Bans IP temporarily for TimeInMinutes.

Gets the IP belonging to Nick if tempbanned.

Gets the nick belonging to IP if tempbanned.

Return remaining temp ban time in minutes for IP if tempbanned.

Returns hubsoft's name and version like this:

name, ver = getHubVersion ()
SendToAll("Info","Hub is running"..name.." "..ver) --> <Info> Hub is running PtokaX 0.3.3.1

Some parts of this section are from the original PtokaX documentation, written by Ptaczek.

Profiles were first implemented in 0.3.2.5 AshCan version of PtokaX. There have been slight changes since then. Now profiles are stored in Profiles.xml inside the cfg folder. The default file looks like ¹⁾:

<?xml version="1.0" encoding="windows-1252" standalone="yes" ?>
<Profiles>
    <Profile>
        <Name>Master</Name>
        <Permissions>1000000001111111111111111111111100000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000</Permissions>
    </Profile>
    <Profile>
        <Name>Operator</Name>
        <Permissions>1000000001111111111001100011111100000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000</Permissions>
    </Profile>
    <Profile>
        <Name>VIP</Name>
        <Permissions>0000000000000001111000000000000100000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000</Permissions>
    </Profile>
    <Profile>
        <Name>Reg</Name>
        <Permissions>0000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000</Permissions>
    </Profile>
</Profiles>

Permissions are 256-digit binary numbers. This sequence of numbers is called the profile data pattern (PDP). Each digit corresponds to one right or permission from the profile manager. In fact the pattern is a binary representation of a 256-bit number. The left-most digit is the Most Significant Bit (MSB), the right-most digit is the Least Significant Bit (LSB). Profile bits cannot be changed from LUA, only the following profile-related functions are available:

AddProfile(name, profile_data)

This function adds a new custom profile. Value profile_data is a number computed as a sum of values of individual bits. Value of a bit is a n-th power of 2. With LUA, this is easy:

function PDPToDec(PDP)
  local n,val=-1,0
  for digit in string.gfind(PDP,"(%d)") do
    n=n+1
    val=val+(n*tonumber(digit))
  end
  return val
end

Returns: -1 if the profile already exists or new profile index on success.

34 - send all users ip on login
33 - allowed for opchat
32 - allowed to enter hub if ip banned31 - Enter full hub
30 - !drop
29 - kick
28 - !ban, !unban
27 - redirect
26 - !gag, !ungag
25 - !op
24 - !restarthub
23 - !restartscripts
22 - !getbanlist
21 - !getinfo
20 - !cleartempban
19 - clear perm ban 
18 - no share limit 
17 - no slot check 
16 - no slot/hub ratio check 
15 - no max hubs check 
14 - no chat limits 
13 - add reg user 
12 - del reg user 
11 - get temp banlist 
10 - no tag check 
9 - refresh txt 
8 - temp ban, temp unban 
7 - change topic 
6 - mass msg 
5 - no deflood main chat 
4 - no deflood pm 
3 - no deflood search 
2 - no deflood myinfo 
1 - no deflood getnicklist 
0 - have key/ is op

This is not all.

Removes the profile with ProfileName. Returns: 0 if the profile doesn't exist or it's a default profile index (0-3) or no parameter given. -1 if the profile is in use. 1 on success.

Returns an array with profile names, the array is the following when using the default profiles:

{"Master","Operator","VIP","Reg"}

Returns the appropriate profile number or -1 on failure.

Returns the appropriate profile name or nil on failure.

Returns an array with nicks of given profile name or nil on failure.

Return profile number if Nick is registered, else nil.

If idx is a valid profile index, it returns an object containing the following fields:

bIsOP
bNoDefloodGetNickList
bNoDefloodNMyINFO
bNoDefloodSearch
bNoDefloodPM
bNoDefloodMainChat
bMassMsg
bTopic
bTempBan
bRefreshTxt
bNoTagCheck
bGetTempBanList
bDelRegUser
bAddRegUser
bNoChatLimits
bNoMaxHubCheck
bNoSlotHubRatio
bNoSlotCheck
bNoShareLimit
bClrPermBan
bClrTempBan
bGetInfo
bGetBanList
bRestartScripts
bRestartHub
bTempOP
bGag
bRedirect
bBan
bKick
bDrop
bEnterFullHub
bEnterIfIPBan
bAllowedOPChat
bSendAllUserIP

They are all correspondant to the bits described here.

Every script has a unique timer. You have to set the timer interval, and start the timer, usually in Main(). The interval is in milliseconds. When interval passes, it calls OnTimer(). You can stop the timer at any time. Let's just see an example (as examples attract):

g=10
 
function Main() -- called on script satrtup
  SendToAll(g.." seconds till explosion, take cover! :-)")
  SetTimer(1000) -- OnTimer() is called every second.
  StartTimer() -- we should not forget to start it.
end
 
function OnTimer()
  g=g-1 -- g decreases by 1
  if g==0 then -- when g is 0
    SendToAll("Countdown finished. KABOOM! :-D")
    StopTimer() -- we stop the timer
  else
    SendToAll(g.." seconds till explosion, take cover! :-)")
  end
end

(This is what people call pure idiotism.) GetTimerInterval() returns the number we fed to SetTimer. GetTimer() returns the timer state, returns 1 if enabled and nil if disabled.

There will be a thread library with multiple timer facilities, according to bluebear.

Every user object contains variables and methods, variables are to be described here. If you are interested in the structure of an object in LUA, see the chapter Objects. You get the user object inside a PtokaX event. You can call it user, User, curUser or anything you like. Values inside the objexct are referred to by using a dot (.), like: user.iProfile or user.bHasTag.

Variable names start with a letter referring to their type:

• i - index = number
• b - boolean, i. e. true or false/nil
• s - string.

The nickname of the user.

The client of the user (if supported).

Version of user's client. ((String!!!)

Connection mode of user, A,P, S or 5. 5: is only provided by older clients,in new ones it's only A/P/S as i've read somewhere on the www

Well, this is a right way, because DC++ can only connect through SOCKS5 and not SOCKS4 proxies so it's way futile to inform others about the SOCKS version.

— bastya_elvtars

IP address.

Full MyINFO string (with end-pipe).

Value is true if user is ready to accept user commands from the hub (thesre is UserCommand in the $Supports.)

Value is true if user is operator

Value is true if user is registered.

Value is true if user has a (recognizable) tag.

Value is true if user is in Active mode.

User's share size in bytes.

Profile number of user (see Profiles).

Return the version number from $Version NMDC command.

If user has a pre-0.240 DC++ tag (H:x,S:y, most likely using Valknut/DCGUI), then this value is equal to the number after H: in the tag.

User's slot count (after S:).

The BCDC-style B: bandwidth limit value (if present).

The L: limit value (DCGUI probably) if present.

User's whole tag.

User's whole description.

The whole connection type of user, lacking the 'magic character' from the end.

User's e-mail address.

The x from the new-style hubcount tag (H:x/y/z)

The y from the above.

The z from the above.

If user has successfully finished the login and appears in the userlist, this value is true.

Notice the difference: the methods are separated with a colon (:) from the object name, and need arguments enclosed by parentheses. Example:

user:SendData("bastya_elvtars","This is the way...")
user:Disconnect()

Now let's see the methods in detail.

Sends data in the name of FromNick. FromNick is optiional, and if unspecified, you can send raw data to the user.

Ex.:

user:SendData("bastya_elvtars","This is the way...")
user:SendData("$UserCommand 1 3 Show the help$<%[mynick]> !help&#124;")

(The second one sends a rightclick command to the user, which calls !help.)

Sends a PM in the name of FromNick.

Disconnects the user.

Kicks the user, in the name of KickerNick, which is optional.

Bans the user permanently. It only bans the IP.

Really only the IP?

Well, if I use like this:

user:NickBan(); user:Ban()

it still bans the nickname only. This will be fixed in the next PtokaX version, according to PPK.

Bans the user's nick, safest to use alongside with Ban()

Tempbans the user for the time set in PtokaX GUI.

Timebans the user for TimeInMinutes.

Redirect the user to Address, with Reason (optional).

The frmHub object contains methods only (and frankly, I don't know why, because frmHub.iMinShare would be nicer to me than frmHub:GetMinShare()', but who knows?)

There are loads of methods inside the frmHub object. This is a part which is most likely subject to changes, so I (or the future contributors) will tend to be up-to-date all the time. But let's go, I can feel your hunger for my explanations!

Registers a bot (makes it appear in the userlist.) This is the 'old' method. Rules are:

• The following chatacters are not allowed in the nick:
  • $
  • |
  • <
  • >
  • :
  • ?
  • *
  • ”
  • /
  • \
  • space
• Maximum nick length is 64 chars.

The hub does not create MyINFO here, this method is only needed for compatibility with some c * lients (NMDC v2). The bot's MyINFO has to be sent by script on NewUserConnected and Main().

Rules are as above, plus:

• $ and | are not allowed in Description and Email
• Max. length is 64 chars per string.
• IsOP is number:
  • 1 - bot has key
  • 0 - bot does not have key.

Using this method, a MyINFO string will be created for bot. If you want MyINFO without key/description/email use this for example:

frmHub:RegBot("botname", 0, "", "")

Unregisters a bot (removes from userlist.) Note that if you remove the RegBot from Main(), the bot will disappear after script restart.

Returns the hub's user count, same as the value of Users: in gui.

Returns the hub's name

Sets the hub's name to NewName.

Returns the hub's description.

Returns the hub's description to NewDescription.

Returns the hub's address.

Returns the hub's IP (resolves the address.)

Returns the TCP port the hub listens on.

Returns the UDP port the hub listens on.

Returns the current hub topic.

Sets the hub topic to NewTopic.

Returns the list of reg servers, exactly as in the GUI.

Sets reg server(s) to NewAddress, you can enter many reg servers separated by semicolons (;).

Enables (opt=0) or disables (opt=1) autoregistering to hublist servers. GetMaxUsers()

Returns the maximum number of simultaneous users allowed to be logged in.

Sets the maximum number of logged-in users to MaxUsers, which can be a number between 0 and 5000.

Returns the maximum number of simultaneous logins (handshakes) allowed.

:!:NOT influenced by XP SP2, but gonna be rewritten soon.

Sets the maximum number of simultaneous logins (handshakes) allowed (0-500).

Returns the minimum share (if set) in Bytes.

Sets the minimum share. ShareUnit can be:

• 0 - B
• 1 - kB
• 2 - MB
• 3 - GB
• 4 - TB

Returns the minimum number slots required (if set).

Sets the minimum number slots required to MinSlots.

Returns the maximum number slots required (if set).

Sets the maximum number slots required to MaxSlots.

Well, this is kinda misty for me. Probably this is about the following: there is a fraction number (x/y) where x controls how many new slots you have to open on entering y new hubs. This may return y.

This may return x. (See above.)

This sets the minimum hub/slot ratio, below this value one can not enter.

Returns the maximum hubs users can be logged in to.

Sets the maximum hubs users can be logged in to.

Returns the sum of all users' share sizes (in Bytes.)

This returns an array with all user objects of profile ProfileNumber as values. If ProfileNumber is not specified, it will return all users as objects.

Returns the builtin opchat bot's name.

Returns the builtin opchat bot's description.

Returns the builtin opchat bot's e-mail.

Sets the builtin opchat bot's name to NewOpChatName, rules can be seen at RegBot.

Sets the builtin opchat bot's properties, rules can be seen at RegBot.

Returns builtin hub bot's name.

Returns the builtin hub bot's description.

Returns the builtin hub bot's e-amil.

Sets the builtin hub bot's name, rules can be seen at RegBot.

Sets the builtin hub bot's properties, rules can be seen at RegBot.

Restarts the hub.

Returns the builtin opchat bot's enabled/disabled status: 1 if enabled, 0 if disabled.

Enables (val=1)/disables(val=0) the builtin opchat bot.

Returns the builtin hub bot's enabled/disabled status: 1 if enabled, 0 if disabled.

Enables (val=1) / disables (val=0) the builtin hub bot.

Returns the absolute path that ptokax.exe resides in. It returns with forward slashes (/), not backslashes (\), since LUA uses forward slashes. It returns the trailing slash (C:/PtokaX/) as well.

Gets the default redirect address.

Sets the default redirect address to NewAddress.

Returns the enable/disable status for the redirection of all newly connecting users.

Changes the enable/disable status for the redirection of all newly connecting users.

You have to call frmHub:SetRedirectFull(0) for this to take effect.

Returns the enable/disable status for the redirection of newly connecting users when hub is full.

Changes the enable/disable status for the redirection of newly connecting users when hub is full.

Returns whether the hub securiy bot's name is the same as the hub bot's name.

Sets whether the hub securiy bot's name is the same as the hub bot's name.

Gets the hub-security alias' name.

Returns password belonging to Nick, if registered.

Returns hub's uptime in seconds.

Returns 1 if Nick is registered, else nil.

Returns the peak usercount since the last application start.

Returns the all-time peak usercount.

Returns an array containing all logged and registered (profile index > -1) user objects.

Set new hub commands prefixes, max. 5 prefixes are allowed. Example:

frmHub:SetPrefixes("!+-?§")

Returns an array containing hub commands' prefixes.

Returns an array containing all registered users as RegisteredUser objects.

Returns an array containing all registered users as TempBan objects.

Returns an array containing all registered users as PermBan objects.

Returns an array containing all logged user objects with operator status.

Returns an array containing all logged user objects without operator status.

Returns an array containing all registered users with operator status as RegisteredUser objects.

Returns an array containing all registered users without operator status as RegisteredUser objects.

Restarts all (enabled) scripts.

The following redirect methods are basically the same, and their names are pretty self-explanatory. I will not write the same sentence 200 times, I just group them by reason.

Every redirect reason has 4 methods associated to it, which do the following:

return the redirect address return the redirect enable/disable status (1 – enabled, 0 – disabled.) set the redirect address set the enable/disable status (1 – enabled, 0 – disabled.)

There are some exceptions, namely the redirect for bad/missing tag. It has the following 2 different methods:

Returns the 'penalty' for bad/missing tag. 'Penalties' are:

• 1 – accept
• 2 – reject
• 3 – redirect

If you want to parse tags by script, you may want to set this to 1.

Sets the 'penalty' for bad/missing tag. 'Penalties' are:

• 1 – accept
• 2 – reject
• 3 – redirect

GetShareRedirAddr()
SetShareRedirAddr(NewAddress)
GetShareRedirect()
SetShareRedirect(0/1)

GetSlotsRedirAddr()
SetSlotsRedirAddr(NewAddress)
GetSlotsRedirect()
SetSlotsRedirect(0/1)

GetRatioRedirAddr()
SetRatioRedirAddr(NewAddress)
GetRatioRedirect()
SetRatioRedirect(0/1)

GetMaxHubsRedirAddr()
SetMaxHubsRedirAddr(NewAddress)
GetMaxHubsRedirect()
SetMaxHubsRedirect(0/1)

GetNoTagRedirAddr()
SetNoTagRedirAddr(NewAddress)

GetNickRuleRedirAddr()
SetNickRuleRedirAddr(NewAddress)
GetNickRuleRedirect()
SetNickRuleRedirect(0/1)

GetTempBanRedirect()
SetTempBanRedirect(0/1)
GetTempBanRedirAddr()
SetTempBanRedirAddr(NewAddress)

GetBanRedirect()
SetBanRedirect(0/1)
GetBanRedirAddr()
SetBanRedirAddr(NewAddress)

GetRegOnlyRedirect()
SetRegOnlyRedirect(0/1)
GetRegOnlyRedirAddr()
SetRegOnlyRedirAddr(NewAddress)

OK, it's finished now. I really hate this part of the API, this could be done in a much more simple way.

They have two fields:

• sNick
• sIp

The sIP field is ”-nickban-” if the object is nickbanned. The sNick field is ”<Unknown>” if the object is banned only by IP.

They have three fields:

• sNick
• sIP
• iTime

The field iTime is the time left in minutes.

They have three fields:

• sNick
• sPassword
• iProfile

These are all self-explanatory, I guess.

Deflood and ProfilePermission objects are absent.