honey@CITI.UMICH.EDU.UUCP (03/13/87)
UDP Driver Interface Specification
Introduction
The UDP driver layer, part of the CITI MacIP driver, implements the
User Datagram Protocol [RFC 768]. This document describes the program
interface to the UDP layer. Driver requests are made by preparing a
driver parameter block and a protocol parameter block, and issuing a
driver control call. The driver parameter block is described in
[CITI MacIP].
Data Structures
The reader should be familiar with the common C derived types, such as
those described in <sys/types.h>, <sys/time.h>, MPW C, and Inside
Macintosh. All UDP datagrams are described by the UDP header
[RFC 768], described below in MPW C:
typedef struct udp_header {
u_short src_port; /* Source port */
u_short dst_port; /* Destination port */
u_short len; /* Datagram length */
u_short chksum; /* Checksum */
} udp_header_t, *udp_header_p;
For each UDP stream, a UDP client allocates a UDP protocol parameter
block, described as follows:
typedef struct udp_param {
struct timeval *io_timeout; /* I/O timeout */
caddr_t io_datagram; /* Pointer to datagram */
u_short io_datalen; /* Length of datagram */
caddr_t io_stream; /* Private UDP data */
long io_dhost; /* Destination IP address */
u_short io_dport; /* Destination UDP port */
u_short io_lport; /* Local port */
u_long io_lhost; /* Local IP address */
udp_header_p io_udph; /* Raw UDP header */
Boolean io_makesum; /* UDP checksum flag */
} udp_param_t, *udp_param_p;
UDP Functions
The following functions provide a program interface to the UDP driver
layer. Each function has a single argument of type udp_param_p and
returns failure (-1) or success (non-negative). Upon failure, the
net_errno field of the driver parameter block indicates the cause of
the failure.
Right and left arrows indicate values passed to and from the driver
functions, respectively.
int udp_open(udp_pb)
<- io_stream
-> io_lport
csCode UDP_OPEN_S
udp_open creates a UDP stream. If io_lport is non-zero, the local port
is set in io_stream, otherwise, a subsequent call to udp_setport must
set the local port. Once the local port is set, the stream can be used
to send and receive datagrams.
int udp_close(udp_pb)
-> io_stream
csCode UDP_CLOSE_S
udp_close closes a UDP stream. Outstanding datagram buffers are
deallocated and pending events are flushed.
int udp_setport(udp_pb)
<- io_stream
<-> io_lport
csCode UDP_SETPORT_S
udp_setport sets the port for a UDP stream. The UDP driver retains the
binding of a stream to a port, so that incoming datagrams can be
delivered to the proper stream and outbound datagrams show the correct
address. If io_lport is 0, the driver will assign an unused port.
int udp_alloc(udp_pb)
<- io_datagram
-> io_datalen
<-> io_stream
csCode UDP_ALLOC_S
udp_alloc allocates a UDP buffer, returning a pointer to a datagram
buffer in the protocol parameter block.
int udp_free(udp_pb)
-> io_datagram
-> io_stream
csCode UDP_FREE_S
udp_free frees a UDP datagram buffer. io_datagram must point to a
datagram buffer allocated by udp_alloc or udp_get.
int udp_put(udp_pb)
-> io_datagram
-> io_datalen
-> io_stream
-> io_dhost
-> io_dport
-> io_lhost
-> io_makesum
csCode UDP_PUT_S
udp_put sends a datagram on the stream specified by io_stream.
io_datagram must be a datagram buffer allocated by udp_alloc.
io_datagram may be freed (with udp_free) immediately upon return from
udp_put. If io_makesum is set, a UDP checksum will be computed and
included in the UDP header of the outgoing packet, otherwise the
checksum will be set to zero.
Before calling udp_put, the client must bind io_lport, either in
udp_open or udp_setport. The destination host and port, passed in
io_dhost and io_dport, respectively, must be non-zero. If io_lhost is
0, the driver will fill in the local IP address, otherwise io_lhost
must be a valid local IP address.
int udp_get(udp_pb)
-> io_timeout
<- io_datagram
<- io_datalen
<-> io_stream
<- io_dhost
<- io_dport
<- io_lhost
csCode UDP_GET_S
udp_get requests a datagram from a UDP stream. If io_timeout is NULL,
udp_get blocks until a packet arrives. If io_timeout is not NULL and a
datagram is not available within the timeout period, udp_get returns
-1. io_datagram is allocated by the driver; it is the caller's
responsibility to free datagram buffers. Before calling udp_get, the
client must bind io_lport, either in udp_open or udp_setport.