[usocket-devel] "experimental-udp" branch merged into usocket trunk

[Chun Tian (binghe)]

Hi, usocket users

I want to mention, the "experimental-udp" branch has been merged into usocket trunk.

Changed API:

[SOCKET-CONNECT]

SOCKET-CONNECT now has a new keyword argument PROTOCOL with default :STREAM as tcp, but if you set it to :DATAGRAM, this means you're creating a UDP socket.

Be different with TCP socket, a UDP socket can be connected or unconnected. The method to create a unconnected UDP socket is to leave the first two argument of SOCKET-CONNECT as NIL:

	(SOCKET-CONNECT NIL NIL :PROTOCOL :DATAGRAM)

Creating a server UDP socket which "listen" on local address is also supported, the method is to set additional keyword arguments: LOCAL-HOST and LOCAL-PORT:

	(SOCKET-CONNECT NIL NIL :PROTOCOL :DATAGRAM :LOCAL-HOST nil :LOCAL-PORT 10000)

Notice: the "nil" as LOCAL-HOST means that you listen on wildcard address "0.0.0.0", same effect as *wildcard-host*.

[SOCKET-SEND]

Syntax: SOCKET-SEND usocket buffer length &key host port

SOCKET-SEND is used for sending packets through a UDP usocket, the "buffer" arguments usually need to be a vector of (unsigned-byte 8).

[SOCKET-RECEIVE]

Syntax: SOCKET-RECEIVE usocket buffer length &key

SOCKET-RECEIVE is used for receiving packets from a UDP usocket, the "buffer" argument will be filled into received data, but if you give NIL, this function will create a new buffer object for holding received data, the default buffer length will be 65536 which defined as a constant +max-datagram-packet-size+.

Notice: if you use this function to receive data from a unconnected socket, you may need to know where the data from. Actually, SOCKET-RECEIVE will return multiple values, the exact number is 4:

	1. buffer (the same object as the "buffer" argument if it's not NIL when calling SOCKET-RECEIVE)
	2. size (how many bytes received)
	3. host (which address this data from)
	4. port (which IP port this data from)

[SOCKET-SERVER]

Syntax: SOCKET-SERVER host port function &optional arguments &key (timeout 1) (max-buffer-size +max-datagram-packet-size+)

SOCKET-SERVER can create a simple single-threaded UDP server. This function is a indefinite loop, so you should create it in a new created thread using your platform's thread API.

The arguments "function" and "arguments" controls your UDP server's function, declaration of this function:

	function (data &optional arguments)

This function will work like a filter, received data in, and return data send out. For example, a UDP Echo server can be defined in following code:

	(defun echo-function (data)
	  data)

And following code created this server on local port 10000:

	(socket-server nil 10000 #'echo-function)

What if your filter function need to know where the data from? Get this information from two special variables: *REMOTE-HOST* and *REMOTE-PORT*.

The argument "timeout" can control the loop frequency, usually no need to modify. Read "server.lisp" for details.


The last important thing USOCKET user need to know: UDP support haven't been done on all CL platforms.

Current finished supported CL platforms:

* CMUCL
* SBCL and ECL (not on win32)
* Allegro CL
* LispWorks (not on win32)
* SCL
* Clozure CL

Unfinished CL platforms:

* CLISP
* Armedbear Common Lisp (ABCL)
* Macintosh Common Lisp (MCL/RMCL)

And the USOCKET-UDP [1] project will be just closed. The function SOCKET-SYNC in that project will not be merged into USOCKET trunk because of less useful in most cases.

Bug reports, optimization suggestions, patches on unfinished platforms are all welcome. Thank you for using USOCKET project.

Regards,

Chun Tian (binghe)

[1] http://common-lisp.net/projects/cl-net-snmp/usocket.html

-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/pkcs7-signature
Size: 2603 bytes
Desc: not available
URL: <https://mailman.common-lisp.net/pipermail/usocket-devel/attachments/20100108/87bafa99/attachment.bin>