UDP Library

The User Datagram Protocol enables users to quickly develop machine to machine communications either through a classic Method-Event style or a stream based style. This allows for both quick one off messaging, or full fledged back and forth communication, though no state or quality assurance is enforced by the standard.

The standard requires that a packet start with a 2 Byte Connection ID and a 2 Byte Length, Though the library will strip both of these off at read time.

The Connection ID is useful for keeping packets with a similar purpose together, or otherwise ensure that a UDP stream remains in the same socket. Connection IDs do not need to be unique, provided that the destination-id combination is. For example, multiple clients may use connection ID 2, but a single client may not use 2 multiple times. In reality if this form of collision does occur, the 2 "connections" will be treated as one.

The Length is used by the receiver to determine where one packet ends and the other begins in the buffer, if using events rather than buffered sockets, this is usually discarded. Note that this is the length of the data, and does not include the headers themselves or any other information sent from lower layers.

UDP API

The Library offers the following functions:

udp.send(destination, data, [id]) Sends a UDP packet containing data to the destination, if provided, will use the provided connection id instead of a randomly generated one.

udp.openSocket(destination[, id]) Returns a socket object that will read and write with the given destination, if provided, will open the socket with ID, rather then generating a random one. Will ensure the connection is unique and not bound already. Returns false and an error message on error.

Events will also be generated upon successful UDP Packets being received, the event is as follows: "udp_packet", sender, Connection ID[, Data] Data is optional as it will not be included in the event if it was buffered in a socket. If it is included then all control information would have been striped off

UDP Socket

A socket object provides the following fields:

socket.dest which contains the address used for sending socket.id which contains the Connection ID used for sending and buffering received messages socket.readBuffer the raw buffer of received packets, will contain multiple packets and control bytes so should not be used directly socket.bufferOverrun is a flag which is set when the readBuffer discarded a packet that would have otherwise resulted in the buffers size exceeding the maximum of 65535 bytes

A socket object also contains the following instance methods:

socket:read() returns the data of the oldest queued packet from the buffer, as a string. Takes care to strip the control data off. This method will block the caller if the buffer is empty until more data is available socket:write(data) formats a packet containing this socket's connection ID, the length of the carried data, and the data itself, then sends it to the destination socket:close() closes the socket, really just un-allocate's memory and internally flags the connection as un buffered