UDP - User Datagram Protocol Class

The Udp enables IP datagrams to be transferred. Transferring data using datagrams (UDP) is like posting a letter -- the envelope holds the address, and the letter holds the data. There is no direct connection between the letter sender and recipient. A connection-oriented protocol, such as TCP/IP, is more like a telephone call -- a connection stage (ringing, picking-up the phone etc.) is required before user communication can occur.

Datagrams are considered unreliable since the system does not inform you if a datagram fails to be delivered. Also, there is generally quite a small size-limit on the amount of data a datagram may hold. Datagrams have their place, however, since they are very light-weight and they can be broadcast (rather than connection-based protocols which are point-to-point).

An example of the use of datagrams is in a system which periodically sends out a datagram to say 'I am still alive'. A monitoring agent could monitor a collection of such systems, and raise an alert when too many datagrams from a system have not appeared.

Udp Creation

The create function can be used to create a Udp object eg.

    (create Udp "mybox.mydomain.com" 1111)

This creates an Udp which is bound to the local address of mybox.mydomain.com, port 1111. Rather than hard-coding the domain name, we could use the hostName function as follows:

The simplest way to find the domain for the local machine is as follows:

    (create Udp (hostName "localhost") 1111)

Once created, this object is tailored using its properties and methods.

Udp Properties

A Udp object supports the following properties:

property name	property type	description
`host`	String	name or IP address of the local host bound to this object
`port`	Integer	the UDP port which is bound to this object
`bufferLength`	Integer	the length of the buffer used to receive datagrams
`socketType`	String	the type of socket -- either `udp` or `icmp`
`log`	Log	a log to record send and received datagrams

Udp Methods

The Udp object supports the following methods:

method name	description
`send`	send a datagram containing the supplied data to the supplied recipient
`receive`	attempt to receive a datagram within the supplied time
`hostName`	determine the host name for the supplied IP address
`encodePing`	encode a PING datagram -- i.e. an ICMP ECHO request
`decodePing`	decode a PING datagram -- i.e. an ICMP ECHO-REPLY response
`close`	close the UDP socket

`send`

Send a datagram containing the supplied data to the supplied recipient. Note that the system does not inform you if the datagram cannot be delivered. The recipient is identified by the supplied hostname and port.

Note that if the recipient hostname is broadcast, the datagram is broadcast to all machines on the network to the specified port. For this to be successful, the hostname bound to this Udp object must identify it as a member of a domain. For example, if the local machine has domain name mybox.mydomain.com then we can broadcast to mydomain.com by creating our Udp object as follows:

    (create Udp "mybox.mydomain.com" 1111)

However, if we were lazy and did the following:

    (create Udp "localhost" 1111)

then the broadcast would not work.

Arguments:

hostName	`String`
port	`String`
data	`Binary`

Return type: the empty List ()

`receive`

Attempt to receive a datagram within the supplied time (in milliseconds). If successful, a list of three items is returned:

the Binary data
a String holding the sender's IP address
an Integer holding the sender's port

A comms timeout error is raised if no datagram is received in time.

Arguments:

timeout Integer

Return type: List

`hostName`

Look up the supplied IP address.

Arguments:

name String

Return type: String -- an error is raised if the hostname could not be resolved.

`encodePing`

Encode a PING datagram -- i.e. an ICMP ECHO request. The socketType must be icmp for this operation to succeed.

Arguments:

id	`Integer`
sequenceNo	`Integer`

Return type: Binary

`decodePing`

Decode a PING datagram -- i.e. an ICMP ECHO-REPLY response.

Arguments:

datagram Binary

Return type: List containing the following Integer values in order:

identity -- as supplied in the orginal PING
sequenceNo -- as supplied in the original PING
milliTime -- time when the original PING was sent

`close`

Close the UDP socket.

Arguments: none

Return type: the empty List is returned.

Contents

Index

Current topic: communications

Related topics: communications classes, objects