This is just to give a first glance at sockets, if you want more in-depth information, check out some of the new scripts at the various mIRC sites.

How to get it to work?

1. Receiving

First of all, you need to tell mIRC to start listening at a certain port.

You do this with the

command /socklisten

/socklisten [port]

eg. /socklisten moo 1234

This would tell mIRC to start listening at port 1234, and call this socket moo.

Next thing you need to do is have an event that listens at that port to see if anyone connects to it.

ON 1:SOCKLISTEN:name:commands

eg. ON 1:SOCKLISTEN:moo {

sockaccept cow

echo 4 -s I accepted a connection at port 1234

}

** If you want to accept a connection at the port you are listening on, you must, MUST, must accept it in the commands part of the ON 1:SOCKLISTEN using the /sockaccept command. If you don't the connection is not established.

2. Sending

To initiate a socket connection, you need to use the command /sockopen

/sockopen

eg. /sockopen arnie boerenkool.food.globalxs.nl 1234

This would try to open a connection to the ip address

boerenkool.food.globalxs.nl at port 1234, and it would be given the name arnie.

Of course you also want to track if this connection is successfull, and exactly when it is established. For this you use the ON 1:SOCKOPEN event.

ON 1:SOCKOPEN:name:commands

eg. ON 1:SOCKOPEN:arnie {

echo 4 -s Yeah, I now have a connection established

}

The sockopen event is triggered when a /sockopen command is successful and a connection has been made.

3. Closing a socket

You can close a socket connection with the command /sockclose.

/sockclose

eg. /sockclose arnie

If you specify a wildcard name, all connections that match the wildcard are closed.

The event that goes with it is ON 1:SOCKCLOSE, which however is ONLY triggered when the connection is closed by the remote connection, and it is NOT triggered when you yourself close the connection.

ON 1:SOCKCLOSE:name:commands

eg. ON 1:SOCKCLOSE:arnie {

echo 4 -s The connection called æarnieÆ has been closed by the remote connection

}

4. Reading and writing

Now that you have a connection, you also want to be able to receive and send information over it.

4.1 Receiving -- /sockread

/sockread [numbytes] <%var|&binvar>

eg. /sockread %text

eg. /sockread 200 &binary_variable

The /sockread command reads bytes from the receive buffer into the specified variable.

If you specify a %var variable, a line of text ending with a

Carriage Return/LineFeed is read into %var. The CRLF are stripped off (this could mean that a %var consists out of $null only, if there was only a CRLF sent.)

If you specify a &binvar then [numbytes] of info is read into the binary variable.

If no [numbytes] is specified it defaults to 4096 bytes.

** Important note ! A single /sockread command might not be enough to process all the lines in the buffer. Instead of waiting for the ON SOCKREAD event to get triggered again, it is faster to use a loop and use $sockbr to test if there was something read, and if so to process it :

ON 1:SOCKREAD:arnie {

:begin

sockread %dummy_variable

if ($sockbr == 0) { return }

echo 4 -s I read %dummy_variable from the socket

connection

goto begin

}

If your script doesn't read the whole buffer, the on sockread event is re-triggered if:

a) you were reading into a &binvar.

b) you were reading into a %var and there is still a CRLF

terminated line in the buffer waiting to be read.

4.2 Writing -- /sockwrite

/sockwrite [-tn]

eg. /sockwrite arnie This is some text I want to send.

eg. /sockwrite arnie %text_variable

The /sockwrite command queues info to be sent on the specified connection.

mIRC will then try to send that info as quickly as it can. Once it has finished sending the info, it triggers the on sockwrite event so you can send more info if you need to. Wildcards are allowed in socket-

names to send info to all sockets that match the wildcard. If you use the /sockwrite command and there is still info in the buffer waiting to be sent, the new info is just added to the back of the queue. You can find out how much info is currently queued by using $sock().sq

(send queue).

If you specify the -t switch, it forces mIRC to send anything beginning with a & as normal text instead of interpreting it as a binary variable. The -n switch appends a CRLF to the line being sent if it's not a &binvar and if it doesn't already have a CRLF.

This is IMPORTANT, because mIRC doesnÆt send unless thereÆs an CRLF at the end.

The ON 1:SOCKWRITE event is triggered when mIRC has finished sending all the info you previously queued for sending.

ON 1:SOCKWRITE:name:commands

eg. ON 1:SOCKWRITE:arnie {

echo 4 -s All queued messages have been sent.

}

5. Miscellaneous (from the versions.txt)

The $sock identifier :

* $sock(name,N).name,.port,.ip,.status,.sent,.rcvd,.sq,.rq,.ls,.lr,.mark

.name is the name you give to a connection to identify it.

.sent and .rcvd return the number of bytes sent and rcvd

over that connection so far.

.sq and .rq return the number of bytes queued in the send

and receive buffers respectively (see below for more info).

.ls and .lr return the number of seconds since the connection

last sent and last received info.

.mark is a user storage area max. 512 bytes (see /sockmark)

Note: you can use a wildcard name to quickly reference only matching entries. The N parameter is optional, if it isn't specified it is assumed to be 1.

* $sockname

$sockname is the name given to a connection to identify

it. In events it is filled with the name of the connection an event

occured on

* $sockerr

$sockerr is set to a value after each socket command/event

and *must* be checked after each socket command and before

processing an event to see if an error occurred.

* $sockbr

$sockbr is set to the number of bytes read by a /sockread

command. It is used to test whether any information was in fact

read from the buffer. You can use it in an if statement:

if ($sockbr > 0) { commands }

* $portfree(N)

returns $true if the specified port number is not in use, otherwise

returns $false.

* /sockrename

The /sockrename command assigns a new name to an existing

connection.

* /sockmark [text]

The /sockmark command is used to associate some kind of info

with a certain sock name for future reference. For example, the

time when the connection was established. You can access this

information again with the $sock().mark property. If you do not

specify any text the mark is cleared.

Note: you can use a wildcard name to set the same information at once for all connections that match the wildcard.