13. TCP connections

Eggdrop allows you to make two types of TCP ("telnet") connections: outgoing and incoming. For an outgoing connection, you specify the remote host and port to connect to. For an incoming connection, you specify a port to listen on.

All of the connections are *event driven*. This means that the bot will trigger your procs when something happens on the connection, and your proc is expected to return as soon as possible. Waiting in a proc for more input is a no-no.

To initiate an outgoing connection, use:

set idx [connect <hostname> <port>]

$idx now contains a new DCC entry for the outgoing connection.

All connections use non-blocking (commonly called "asynchronous", which is a misnomer) I/O. Without going into a big song and dance about asynchronous I/O, what this means to you is:

assume the connection succeeded immediately

if the connection failed, an EOF will arrive for that idx

The only time a 'connect' will return an error is if you give it a hostname that can't be resolved (this is considered a "DNS error"). Otherwise, it will appear to have succeeded. If the connection failed, you will immediately get an EOF.

Right after doing a 'connect' call, you should set up a 'control' for the new idx (see the section above). From then on, the connection will act just like a normal DCC connection that has been put under the control of a script. If you ever return "1" from the control proc (indicating that you want control to return to Eggdrop), the bot will just close the connection and dispose of it. Other commands that work on normal DCC connections, like 'killdcc' and 'putdcc', will work on this idx, too. The 'killdcc' command will fail with "invalid idx" if you attempt to use it on a closed socket.

To create a listen port, use:

listen <port> script <proc>

Procs should be declared as:

procname <newidx>

For example:

listen 6687 script listen:grab

proc listen:grab {newidx} {
control $newidx listen:control
}

When a new connection arrives in port 6687, Eggdrop will create a new idx for the connection. That idx is sent to 'listen:grab'. The proc immediately puts this idx under control. Once 'listen:grab' has been called, the idx behaves exactly like an outgoing connection would.

The best way to learn how to use these commands is to find a script that uses them and follow it carefully. However, hopefully this has given you a good start.

14. Match characters

Many of the bindings allow match characters in the arguments. Here are the four special characters:

?
matches any single character

*
matches 0 or more characters of any type

%
matches 0 or more non-space characters (can be used to match a single word)

~
matches 1 or more space characters (can be used for whitespace between words)