BCDC++ Lua API

Registered API functions: DC class

The following functions are the members of DC class. You can call them with DC(): prefix. For example: DC():PrintDebug()

DC():SendHubMessage()

Description

This function sends a message to the hub. The message should match the specifitations of NMDC or ADC protocol otherwise the hub can't process it.

Usage

DC():SendHubMessage(<hub_id>, <message>)

<hub_id>
HubID is the identifier of the hub
<message>
The message-to-send. It should end with a newline in case of an ADC hub, or a pipe in case of an NMDC hub.

Examples

on NMDC hub

DC():SendHubMessage( hub:getId(), "<" .. hub:getOwnNick() .. "> Hi, I'm happy to meet you!|" )

on ADC hub

DC():SendHubMessage( this:getId(), "BMSG " .. hub:getOwnSid() .. " Hi,\sI'm\shappy\sto\smeet\syou\n" )

DC():PrintDebug()

Description

The functions write a message to System Log (Debug window in the past).

Usage

DC():PrintDebug(<string>)

<string>
The message to the log

Examples

DC():PrintDebug("*** Script succesfully loaded")

DC():GetClientIp()

Description

Returns with the Client IP. It can be used in a p2p connection, since the requied parameter is the Client Pointer

Usage

DC():GetClientIp(<client_pointer>)

<client_pointer>
Client Pointer is a userdata variable containing the connection

Examples

dcpp:setListener( "clientIn", "c2ci", function( userp, line ) DC():PrintDebug("Incoming connection IP: " .. DC():GetClientIp(userp) ) return nil end )

DC():GetHubIpPort()

Description

This function returns with the IP and port of the specified hub in format x.x.x.x[:port] where port is absent if the NMDC hub runs on port 411.

Usage

DC():GetHubIpPort(<hub_id>)

<hub_id>
HubID is the identifier of the hub

Examples

if DC():GetHubIpPort( hub:getId() ) == "1.2.3.4:1416" then DC():PrintDebug("I'm cool") end

DC():GetHubUrl()

Description

This function returns with the address of the selected hub.

Usage

DC():GetHubUrl(<hub_id>)

<hub_id>
HubID is the identifier of the hub

Examples

if DC():GetHubUrl( hub:getId() ) == "elite.4242.hu:4242" then DC():PrintDebug("something happened") end

This article needs some work to define the behavior this command

DC():InjectHubMessage()

Description

It inserts an NMDC message to the specified hubwindow. The client will see it as a command originated from the hub. You can use it to add chat lines to the client window (or help), add UserCommand and more.

Usage

DC():InjectHubMessage( <hub_id>, <message> )

<hub_id>
HubID is the identifier of the hub
<message>
The message can be anything your client can process. This includes NMDC commands starting with $ but without the pipe. If the message starts with other than $ mark, it will show up on the chat (this is an intended behavior of DC++, used for /help, status messages, etc). Dollar and pipe marks can be escaped inside the message (&#36; for dollar, &#124; for pipe) to avoid misusing.

Examples

DC():InjectHubMessage( hub:getId(), "*** This is help")

DC():InjectHubMessage( hub:getId(), "<Phantom> Hi, noone can see this. Are you scared?" )

DC():InjectHubMessage( hub:getId(), "$To: " .. hub:getOwnNick() .. " From: [OP]Jety $<" .. hub:getOwnNick() .."> This message is injected into a private chat window with [OP]Jety, although he can't see it since it's not sent to the hub.")

DC():HubWindowAttention()

Description

The function makes the hubwindow flash. It's useful to notify the user if any important thing happens on the hub.

Usage

DC():HubWindowAttention(<hub_id>)

<hub_id>
HubID is the identifier of the hubwindow

Examples

DC():HubWindowAttention( hub:getId() )

DC():RunTimer()

Description

BCDC++ includes a timer which calls dcpp.OnTimer in every second. RunTimer() can enable or disable this timer (disabled by default).

Usage

DC():RunTimer(<enabled>)

<enabled>
0 disables the timer, all different values enables it

It gives a "RunTimer: missing integer (0=off,!0=on)" error when the parameter is missing.

Examples

DC():RunTimer(1) -- enable timer

DC():GetSetting()

Description

GetSetting returns with the current values of BCDC++ config. The return value can be a number of a string, depending on the content of the variable.

Usage

DC():GetSetting(<config_variable>)

<config_variable>
The name of the configuration value defined in SettingsManager (see: SettingsManager class, SettingsManager.cpp) or DCPlusPlus.xml

If <config_variable> doesn't exist, it drops a "GetSetting: setting not found" error message.

Examples

  • local slots = DC():GetSetting("Slots") -- Returns with the number of upload slots
  • local message = DC():GetSetting("DefaultAwayMessage") -- Returns with the Default Away Message

DC()GetAppPath

Description

Returns with the name of the BCDC executable's directory. Generally it's not used for locating the .exe but useful for getting location of scripts or text files.

Usage

DC():GetAppPath()

Examples

local filename = DC():GetAppPath() .. "scripts\slotrules.txt" -- DC():GetAppPath() == "C:\Utilites\BCDC++\"

DC():FromUtf8()

Description

This function converts text from UTF8 to the Active CodePage. Its return value is the converted text.

Usage

DC():FromUtf8( <text> )

<text>
Text in UTF8

DC():ToUtf8()

Description

This function converts text to UTF8 from the Active CodePage. Its return value is the UTF8 text.

Usage

DC():ToUtf8( <text> )

<text>
Text encoded with the Active CodePage

API-called Lua functions

The following functions are called by BCDC++ when a specified event happens. These functions shall be defined in startup.lua.

dcpp table

nmdch and adch table

dcpp.OnTimer()

BCDC calls dcpp.OnTimer() on every seconds. The function is defined in startup.lua and executes all timer listener one by one. Can be enabled or disabled with the RunTimer function; disabled by default.

dcpp.OnCommandEnter()

Description

When you enter anything to main chat, BCDC++ calls dcpp.OnCommandEnter() before sending it to the hub. You can use it to process new client-side commands and/or filter or modify the outgoing message. Defined in startup.lua and calls the ownChatOut listeners. If any of the listeners return non-nil, BCDC discards the message.

Parameters

dcpp.OnCommandEnter( <hub_id>, <text> )

<hub_id>
HubID is the identifier of the hub
<text>
The text entered by the user

Return values

If return non-nil, BCDC discards the message.

dcpp.FormatChatText

Description

BCDC++ has RichEdit mainchat. BCDC++ lets the RichText to be formatted by the dcpp.FormatChatText function, so it is called before any message is written to the chat window. Defined in formatting.lua

Parameters

dcpp.FormatChatText( <hub_id>, <text> )

<hub_id>
HubID is the identifier of the hub
<text>
The original rich text

Return values

The function shall return the formatted text. Then, BCDC will send that to the chat.

Notes

  • Unsure about the coding, if I'm right, <text> is in UTF-8

dcpp.UserDataIn(), dcpp.UserDataOut()

Description

These functions are called when an NMDC client-to-client message is sent or arrives.

Parameters

  • dcpp.UserDataIn( <clt_pointer>, <msg> )
  • dcpp.UserDataOut( <clt_pointer>, <msg> )
<clt_pointer>
Client Pointer, a userdata variable containing the connection.
<msg>
The sent or received message

Return values

Returning non-nil kills the connection

Notes

  • At this moment, UserDataIn/Out is called only in NMDC connections
  • Only messages starting with $ trigger the call. Other raw data are ignored


nmdch.OnHubAdded(), adch.OnHubAdded()

Description

When you connect to a hub, BCDC++ calls one of the functions: nmdch.OnHubAdded() for NMDC hubs, adch.OnHubAdded() for ADC hubs. They are defined in startup.lua and call the appropriate addHub function.

Parameters

nmdch.OnHubAdded( <hub_id> )

adch.OnHubAdded( <hub_id> )

<hub_id>
HubID is the identifier of the new hub. In the future when you call a Registered API function, you have to use this identifier to select the hub.

Return values

None

nmdch.OnHubRemoved(), adch.OnHubRemoved()

Description

When you disconnect from a hub, BCDC calls the nmdch.OnHubRemoved() function for NMDC hub or adch.OnHubRemoved() for ADC hub. They are defined in startup.lua and call the removeHub function.

Parameters

nmdch.OnHubRemoved( <hub_id> )

adch.OnHubRemoved( <hub_id> )

<hub_id>
HubID is the unique identifier of the hub

Return values

None

nmdch.DataArrival(), adch.DataArrival()

Description

When any data arrives from the NMDC hub, BCDC++ calls this function. It's defined in startup.lua.

First it calls the raw listeners. If any of the listeners returns with a non-nil value, the command will be discarded and no further processing happens. Otherwise it tries to process the message. If a known NMDC command is found ($MyINFO, $Search, <..>) it calls the appropriate function. See startup.lua for details.

Parameters

nmdch.DataArrival( <hub_id>, <message> )

adch.DataArrival( <hub_id>, <message> )

<hub_id>
HubID identifies the hub individually
<message>
The command which comes from the hub

Return values

Non-nil discards the message.

Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox