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

On Thu, Jan 7, 2010 at 11:02 AM, Chun Tian (binghe) binghe.lisp@gmail.comwrote:

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)

It isn't clear to me how unconnected UDP sockets are to be used, since the host and port are unspecified. I would expect that most users would always want to use connected sockets.

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).

What does the return value of socket-send mean?

[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+.

The constant +max-datagram-packet-size+ is not exported from the usocket package, and seems to be unbound when I try to access it.

When I try to call socket-receive with both buffer and length nil, it complains that they can't both be nil. I was under the impression that if I left both as nil then it would create a buffer of size +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.

Thanks for working on this. I'm eagerly awaiting full compatibility win32 implementations.