🚀 go-pugleaf

		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.