saf@CITI.UMICH.EDU (10/06/87)
UDP DRIVER INTERFACE SPECIFICATION (Final Draft, 10/6/87)
ABOUT THE UDP DRIVER
--------------------
The UDP driver layer, one of the CITI MacIP drivers, implements the User Datagram
Protocol [RFC 768]. This document describes the interface to UDP.
UDP 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.
Clients are given the option of writing data from a character array or from a Write Data
Structure (WDS). The WDS is a "gather write" structure. It specifies a list and ordering of
buffers to write in a single operation.
Within the WDS, wds_index is an index into an array of buffer descriptors, pointing to the
first buffer to write. UDP clients must pass wds_index as 3 or more, and allocate the
corresponding buffer descriptors. The first three buffer descriptors will be used by lower
level protocols for protocol headers. Terminate the buffer descriptor array with a descriptor
specifying length zero.
typedef struct bd { /* Buffer descriptor */
unsigned short bl; /* Buffer length */
Ptr bp; /* Buffer pointer */
} bd_t, *bd_p;
typedef struct wds { /* Write data structure */
unsigned long wds_index; /* Current descriptor index */
bd_t wds_buffer[]; /* List of descriptors */
} wds_t, *wds_p;
The following is a sample WDS. wds_index is 3, so the first buffer descriptor is
wds_buffer[3]. Descriptors wds_buffer[0], wds_buffer[1], and wds_buffer[2]
will be used for lower layer protocol headers. DATA LEN and DATA PTR are the length
of and a pointer to the client's buffer. This example shows the minimal WDS for UDP
clients.
+-----------------------+
| 3 | wds_index (long)
+-----------------------+
| | buffer length #0 (word)
+-----------------------+
| | buffer pointer #0 (pointer)
+-----------------------+
| | buffer length #1 (word)
+-----------------------+
| | buffer pointer #1 (pointer)
+-----------------------+
| | buffer length #2 (word)
+-----------------------+
| | buffer pointer #2 (pointer)
+-----------------------+
| DATA LEN | buffer length #3 (word)
+-----------------------+
| DATA PTR | buffer pointer #3 (pointer)
+-----------------------+
| 0 | buffer length #4 (word)
+-----------------------+
| UNUSED | buffer pointer #4 (pointer)
+-----------------------+
.
.
.
Version information on the UDP driver is returned in the following
structure:
typedef struct udp_version {
unsigned char version[32]; /* Version number */
unsigned char specdesc[32]; /* Specification description */
unsigned char site[32]; /* Originating site */
} udp_version_t, *udp_version_p;
If UDP is configured to collect statistics, that information is returned in the following
structure (NOTE: this structure is not finalized!):
typedef struct udp_stats { /* Not yet defined */
} udp_stats_t, *udp_stats_p;
UDP FUNCTIONS
-------------
The following functions provide a program interface to the UDP driver layer. Each
function returns success (0) or an error code. Error code identifiers are defined in
net_errno.h. The return type for all functions is long.
UDP may notify clients of asynchronous events by executing a client-supplied notification
routine. Execution of the notification routine is called delivery of notification. Clients are
notified of an event if and only if they have specifically requested notification of that event.
Clients request and cancel notification of events by setting a mask and passing it to
udp_request and udp_cancel, respectively.
Some functions accept io_timeout as a parameter. For these routines, if io_timeout is
NULL, the function blocks forever, or until the call can be completed. If io_timeout is
not NULL, the function blocks until the timeout value expires or the call can be completed.
Implementation-dependent restrictions may apply as to when a client can block. If it is
illegal for a call to block, the error E_CANTBLOCK is returned.
Some functions accept (and in certain cases return) io_flags as a parameter. io_flags is
a long-word bitmask of control flags. A list of all flags is given in "UDPJCONSTANTS."
Right and left arrows indicate values passed to and from the driver functions, respectively.
udp_create (io_stream, io_lport)
<- Ptr *io_stream UDP stream descriptor
-> unsigned short io_lport Local UDP port
udp_create 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.
Errors returned are:
E_NOMEM
E_PORTINUSE
udp_delete (io_stream)
-> Ptr io_stream UDP stream descriptor
udp_delete deletes a UDP stream. Outstanding datagram buffers are deallocated and
pending events are flushed.
Errors returned are:
E_BADSTREAM
udp_setport (io_stream, io_lport)
-> Ptr io_stream UDP stream descriptor
-> unsigned short *io_lport Local UDP port
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 zero, the driver will assign
an unused port.
Errors returned are:
E_BADSTREAM
E_PORTINUSE
udp_request (io_stream, io_nclass, io_notify, io_userdata, io_flags)
-> Ptr io_stream UDP stream descriptor
-> unsigned long io_nclass Set of events to notify on
-> ProcPtr io_notify Notification routine
-> unsigned long io_userdata Passed to notification routine
-> unsigned long io_flags Control flags
udp_request sets up notification for a stream. io_notify is a pointer to the client's
notification routine. io_userdata is passed to the client's notification routine.
io_nclass is the bitwise or of the notification identifiers to notify on. So that clients may
request to add to current notifications, io_nclass is bitwise ored to the existing bits.
Values for io_nclass are defined in the section "UDPJNOTIFICATION." When a UDP
stream is created, the default value for io_nclass is UDP_NT_NONE (i.e., no notification).
Special behavior can be specified with io_flags. The following flags are defined:
UDP_FLAG_NEWNOTIFY io_notify should replace the previous io_notify. Clients
may disable notification by passing NULL for io_notify
and setting this flag. Notification may be re-enabled later by
setting IP_FLAG_NEWNOTIFY and io_notify .
UDP_FLAG_NEWUDATA io_userdata should replace the previous io_userdata.
Errors returned are:
E_BADSTREAM
E_BADNOTIFICATION
E_BADFLAG
udp_cancel (io_stream, io_nclass)
-> Ptr io_stream UDP stream descriptor
-> unsigned long io_nclass Events not to notify on
udp_cancel subtracts from the set of events for which the client accepts notification.
io_nclass is the bitwise or of the notification identifiers to subtract, specified in
"UDPJNOTIFICATION."
Errors returned are:
E_BADSTREAM
E_BADNOTIFICATION
udp_alloc (io_stream, io_buffer, io_buflen)
-> Ptr io_stream UDP stream descriptor
<- Ptr *io_buffer Pointer to a datagram buffer
-> unsigned long io_buflen Requested buffer length
udp_alloc allocates a UDP buffer, returning io_buffer, a pointer to a datagram buffer .
Errors returned are:
E_BADSTREAM
E_NOMEM
udp_free (io_stream, io_buffer)
-> Ptr io_stream UDP stream descriptor
-> Ptr io_buffer Pointer to a datagram buffer
udp_free frees a UDP datagram buffer. io_buffer must point to a datagram buffer
allocated by udp_alloc or udp_get.
Errors returned are:
E_BADSTREAM
E_BADPTR
udp_put (io_stream, io_buffer, io_buflen, io_fhost, io_fport, io_flags)
-> Ptr io_stream UDP stream descriptor
-> Ptr io_buffer Output buffer
-> unsigned long io_buflen Buffer length (bytes)
-> unsigned long io_fhost Destination host
-> unsigned short io_fport UDP port on io_fhost
-> unsigned long io_flags Control flags
udp_put sends a datagram on the stream specified by io_stream. io_buffer is a
datagram buffer. If the flag UDP_FLAG_USEWDS is not set (see below), clients must allocate
io_buffer by calling udp_alloc and free them by calling udp_free.
Before calling udp_put, the client must bind io_lport, either in udp_create or
udp_setport. The destination host and port, passed in io_fhost and io_fport,
respectively, must be non-zero.
Special behavior can be specified with io_flags. The following flags are defined:
UDP_FLAG_MAKESUM If set, a UDP checksum will be computed and included in
the UDP header of the outgoing datagram, otherwise the
checksum will be set to zero.
UDP_FLAG_USEWDS If set, io_buffer is a pointer into a client-allocated WDS
(i.e., type wds_p). The client must allocate the structure,
leaving room for lower layer protocol headers, as specified
in the section "UDPJDATAJSTRUCTURES."
Note that if UDP_FLAG_USEWDS is set, datagram buffers need
not be allocated and freed with udp_alloc and udp_free.
Also, io_buflen is ignored.
Errors returned are:
E_BADSTREAM
E_BADWDS
E_BADFLAG
E_NOMEM
E_DTGTOOBIG
E_CANTRESOLVEADDR
E_HWWRITEERR
udp_get (io_stream, io_buffer, io_buflen, io_fhost, io_lhost io_fport,
io_lhost, io_timeout, io_flags)
-> Ptr io_stream UDP stream descriptor
<- Ptr *io_buffer Input buffer
<> unsigned long io_buflen Input buffer length (bytes)
<- unsigned long *io_fhost Foreign host
<- unsigned short *io_fport UDP port on io_fhost
<- unsigned long *io_lhost Local host
<- unsigned short *io_lport UDP port on io_lhost
-> struct timeval *io_timeout Timeout value
<> unsigned long *io_flags Control flags
udp_get requests a buffer from a UDP stream. Note that io_buffer is allocated by the
driver, but should be freed by the client (see udp_free).
If io_timeout is NULL, udp_get blocks until a datagram arrives. If io_timeout is not
NULL and a datagram is not available within the timeout period, udp_get returns an error.
Before calling udp_get, the client must bind io_lport, either in udp_create or
udp_setport.
For the parameters io_fhost, io_fport, io_lhost, io_lport, and io_flags, the client
may pass NULL if it does not need the returned values.
No values are currently defined for io_flags.
Errors returned are:
E_BADSTREAM
E_TIMEDOUT
E_CANTBLOCK
udp_control (io_stream, io_buffer, io_buflen, io_control)
-> Ptr io_stream UDP stream descriptor
<> Ptr io_buffer Data used by control call
<> unsigned long *io_buflen Size of io_buffer (bytes)
-> unsigned long io_control Specifies control operation
udp_control performs various operations for a UDP stream. io_control selects an
operation and is the only mandatory parameter. Parameters that are not required by
individual control operations may be passed as NULL.
General errors returned by udp_control are:
E_BADSTREAM
E_BADCONTROL
Currently defined control operations are:
UDP_CTL_VERSION
-> io_stream UDP stream descriptor
<> io_buffer Pointer to udp_version_t structure
-> io_control Control operation
Returns version information. Clients pass a pointer to a structure of type
udp_version_t, as defined in the section "UDPJDATAJSTRUCTURES."
No specific errors are returned for this control.
UDP_CTL_STATS
-> io_stream UDP stream descriptor
<> io_buffer Pointer to udp_stats_t structure
-> io_control Control operation
No specific errors are returned for this control.
UDP_CTL_PERM_STREAM
-> io_stream UDP stream descriptor
-> io_control Control operation
This stream should never be deallocated by the system.
No specific errors are returned for this control.
udp_task ()
Clients should call udp_task periodically to allow UDP time for asynchronous
processing (e.g., to process incoming datagrams).
Errors returned are:
E_CANTBLOCK
UDP NOTIFICATION
----------------
Clients may request and cancel notification of asynchronous events by calling
udp_request and udp_cancel, respectively. As asynchronous events occur, the
notification routine io_notify is called with the following parameters:
(*io_notify)(io_stream, io_buffer, io_buflen, io_fhost, io_fport,
io_lhost, io_lport, io_nclass, io_ndata, io_userdata)
-> Ptr io_stream
-> Ptr io_buffer
-> unsigned long io_buflen
-> unsigned long io_fhost
-> unsigned short io_fport
-> unsigned long io_lhost
-> unsigned short io_lport
-> unsigned long io_nclass
-> unsigned long io_ndata
-> unsigned long io_userdata
io_nclass is the type of event that caused this notification. io_userdata was passed to
udp_request by the client. io_ndata contains additional specification for the event.
The following describes the valid notification classes (io_nclass):
UDP_NT_DATA: Data Arrival Notification
-> io_stream
-> io_fhost
-> io_fport
-> io_lhost
-> io_lport
-> io_nclass
-> io_userdata
Data arrival notification is delivered when a datagram arrives on io_stream, from
io_fport on io_fhost.
UDP_NT_ERROR Error Notification
-> io_stream
-> io_buffer
-> io_buflen
-> io_fhost
-> io_fport
-> io_lhost
-> io_lport
-> io_nclass
-> io_ndata
-> io_userdata
The client is notified when an asynchronous error occurs, (e.g., destination unreachable
messages). io_ndata identifies the error. For all errors, an ICMP destination unreachable
datagram is returned in io_buffer. io_buflen is the length of that datagram. For more
information on ICMP, refer to [RFCJ792].
Errors delivered are:
E_NETUN
E_HOSTUN
E_PROTOUN
E_PORTUN
UDP ERROR CODES
---------------
Following is a description of all possible error codes returned by UDP:
E_NOMEM
Not enough memory to perform operation.
E_PORTINUSE
Port number is already in use by another client.
E_BADSTREAM
Stream descriptor was not found in this driver's list of streams.
E_BADNOTIFICATION
Invalid notification class.
E_BADFLAG
Invalid control flag bit is set in io_flags.
E_BADCONTROL
Invalid control identifier.
E_BADPTR
Invalid pointer; could not verify that pointer points to valid data.
E_BADWDS
Invalid WDS structure or pointer.
E_DTGTOOBIG
Datagram is too long to be handled by this driver.
E_CANTRESOLVEADDR
Unable to determine the next destination IP address that leads to the
requested destination IP address.
E_HWWRITEERR
Hardware failed in writing datagram to network.
E_CANTBLOCK
Current context does not allow a blocking call.
E_TIMEDOUT
Could not perform operation within requested timeout period.saf@CITI.UMICH.EDU (10/23/87)
IP DRIVER INTERFACE SPECIFICATION
Final Draft
MacIP project
University of Michigan, CITI
2901 Hubbard
Ann Arbor, MI 48103
macip@citi.umich.edu
ABOUT THE IP DRIVER
The IP driver layer, one of the CITI MacIP drivers, implements the Internet
Protocol [RFC 791]. This document describes the interface to IP.
IP 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.
Clients are given the option of writing data from a character array or from a
Write Data Structure (WDS). The WDS is a "gather write" structure. It
specifies a list and ordering of buffers to write in a single operation.
Within the WDS, wds_index is an index into an array of buffer descriptors,
pointing to the first buffer to write. IP clients must pass wds_index as 2 or
more, and allocate the corresponding buffer descriptors. The first two buffer
descriptors will be used by lower level protocols for protocol headers.
Terminate the buffer descriptor array with a descriptor specifying length zero.
typedef struct bd { /* Buffer descriptor */
unsigned short bl; /* Buffer length */
Ptr bp; /* Buffer pointer */
} bd_t, *bd_p;
typedef struct wds { /* Write data structure */
unsigned long wds_index; /* Descriptor index */
bd_t wds_buffer[]; /* List of descriptors */
} wds_t, *wds_p;
The following is a sample WDS. wds_index is 2, so the first buffer
descriptor is wds_buffer[2]. Descriptors wds_buffer[0] and
wds_buffer[1] will be used for lower layer protocol headers. DATA LEN
and DATA PTR are the length of and a pointer to the client's buffer. This
example shows the minimal WDS for IP clients.
+-----------------------+
| 2 | wds_index (long)
+-----------------------+
| | buffer length #0 (word)
+-----------------------+
| | buffer pointer #0 (pointer)
+-----------------------+
| | buffer length #1 (word)
+-----------------------+
| | buffer pointer #1 (pointer)
+-----------------------+
| DATA LEN | buffer length #2 (word)
+-----------------------+
| DATA PTR | buffer pointer #2 (pointer)
+-----------------------+
| 0 | buffer length #3 (word)
+-----------------------+
| UNUSED | buffer pointer #3 (pointer)
+-----------------------+
.
.
.
All IP datagrams are described by an IP header [RFC 791], described below :
typedef struct ip_header {
unsigned char ip_ver:4;
unsigned char ip_ihl:4;
unsigned char ip_tsrv;
unsigned short ip_len;
unsigned short ip_id;
unsigned short ip_flgs:3;
unsigned short ip_foff:13;
unsigned char ip_time;
unsigned char ip_prot;
unsigned short ip_chksum;
unsigned long ip_src;
unsigned long ip_dst
unsigned long ip_options;
} ip_header_t, *ip_header_p;
IP can return a list of all active local IP addresses. The list is a zero-
terminated array of the following structure:
typedef struct ip_addr {
unsigned long addr; /* IP address */
unsigned long mask; /* Net mask for addr */
} ip_addr_t, *ip_addr_p;
Information on maximum segment size is handled with the following structure:
typedef struct ip_mss {
unsigned long addr; /* IP address */
unsigned long ob_maxpaksz; /* Max outbound IP
packet, assuming no
IP options */
unsigned long ib_maxpaksz; /* Max inbound packet */
unsigned long maxfragsz; /* Maximum fragment size
on network, assuming
no IP options */
} ip_mss_t, *ip_mss_p;
Version information on the IP driver is returned in the following structure:
typedef struct ip_version {
unsigned char version[32]; /* Version number */
unsigned char specdesc[32]; /* Spec description */
unsigned char site[32]; /* Originating site */
} ip_version_t, *ip_version_p;
If IP is configured to collect statistics, that information is returned in the
following structure (NOTE: this structure is not finalized!):
typedef struct ip_stats {
short st_drop; /* # dropped */
short st_xsum; /* # with bad cksum */
short st_len; /* # with bad lengths */
short st_dest; /* # bad io_fhost*/
short st_ttl; /* # 0 time to live */
short st_prot; /* # protocol unavailable */
short st_ver; /* Bad ip version number */
short st_snd; /* # of ip datagrams sent */
short st_rcv; /* # of datagrams received */
short st_frag; /* # of fragments received */
short st_multi; /* # times >1 packet in Q */
short st_retry; /* # of retransmissions */
short st_retry_fail;/* Number of retry failures */
} ip_stats_t, *ip_stats_p;
IP FUNCTIONS
The following functions provide a program interface to the IP driver layer.
Each function returns success (0) or an error code. Error code identifiers are
defined in net_errno.h. The return type for all functions is long.
IP may notify clients of asynchronous events by executing a client-supplied
notification routine. Execution of the notification routine is called delivery of
notification. Clients are notified of an event if and only if they have
specifically requested notification of that event. Clients request and cancel
notification of events by setting a mask and passing it to ip_request and
ip_cancel, respectively.
Some functions accept io_timeout as a parameter. For these routines, if
io_timeout is NULL, the function blocks forever, or until the call can be
completed. If io_timeout is not NULL, the function blocks until the timeout
value expires or the call can be completed. Implementation-dependent
restrictions may apply as to when a client can block. If it is illegal for a call to
block, the error E_CANTBLOCK is returned.
Some functions accept (and in certain cases return) io_flags as a parameter.
io_flags is a long-word bitmask of control flags. A list of all flags is given
in "IP CONSTANTS."
Right and left arrows indicate values passed to and from the driver functions,
respectively.
ip_create (io_stream, io_prot)
<- Ptr *io_stream IP stream descriptor
-> unsigned short io_prot Internet protocol number
ip_create creates an IP stream. On success, ip_create prepares
io_stream, which carries the private, protocol-specific description of the
stream. io_prot is a protocol number as defined in [RFC 997].
Errors returned are:
E_NOMEM
E_PROTOINUSE
ip_delete (io_stream)
-> Ptr io_stream IP stream descriptor
ip_delete destroys an IP stream. Outstanding datagram buffers are freed and
pending events are flushed.
Errors returned are:
E_BADSTREAM
ip_request (io_stream, io_nclass, io_notify, io_userdata,
io_flags)
-> Ptr io_stream IP stream descriptor
-> unsigned long io_nclass Set of events to notify on
-> ProcPtr io_notify Notification routine
-> unsigned long io_userdata Passed to notification routine
-> unsigned long io_flags Control flags
ip_request sets up notification for a stream. io_notify is a pointer to the
client's notification routine. io_userdata is passed to the client's notification
routine.
io_nclass is the bitwise or of the notification identifiers to notify on. So that
clients may request to add to current notifications, io_nclass is bitwise-ored
to the existing bits. Values for io_nclass are defined in the section
"IP NOTIFICATION." When an IP stream is created, the default value for
io_nclass is IP_NT_NONE (i.e., no notification).
Special behavior can be specified with io_flags. The following flags are
defined:
IP_FLAG_NEWNOTIFY io_notify should replace the previous
io_notify. Clients may disable notification by
passing NULL for io_notify and setting this
flag. Notification may be re-enabled later by
setting IP_FLAG_NEWNOTIFY and io_notify .
IP_FLAG_NEWUDATA io_userdata should replace the previous
io_userdata.
Errors returned are:
E_BADSTREAM
E_BADNOTIFICATION
E_BADFLAG
ip_cancel (io_stream, io_nclass)
-> Ptr io_stream IP stream descriptor
-> unsigned long io_nclass Events not to notify on
ip_cancel subtracts from the set of events for which the client accepts
notification. io_nclass is the bitwise or of the notification identifiers to
subtract, specified under "IP NOTIFICATION."
Errors returned are:
E_BADSTREAM
E_BADNOTIFICATION
ip_alloc (io_stream, io_buffer, io_buflen)
-> Ptr io_stream IP stream descriptor
<- Ptr *io_buffer Pointer to a datagram buffer
-> unsigned long io_buflen Requested buffer length
ip_alloc allocates an IP datagram buffer of length io_buflen.
Errors returned are:
E_BADSTREAM
E_NOMEM
ip_free (io_stream, io_buffer)
-> Ptr io_stream IP stream descriptor
-> Ptr io_buffer Pointer to a datagram buffer
ip_free releases an IP datagram buffer. io_buffer must point to a datagram
buffer allocated by ip_alloc or ip_get.
Errors returned are:
E_BADSTREAM
E_BADPTR
ip_put (io_stream, io_buffer, io_buflen, io_fhost, io_lhost,
io_options, io_optlen, io_flags)
-> Ptr io_stream IP stream descriptor
-> Ptr io_buffer Output buffer
-> unsigned long io_buflen Buffer length (bytes)
-> unsigned long io_fhost Destination host
-> unsigned long io_lhost Local host
-> Ptr io_options IP options
-> unsigned long io_optlen Length of options (bytes)
-> unsigned long io_flags Control flags
ip_put sends data to the address specified by io_fhost. io_buffer and
io_buflen specify the data to send. If the flag IP_FLAG_USEWDS is not set
(see below), clients must allocate io_buffer by calling ip_alloc and free
them by calling ip_free.
If io_lhost is zero IP will route the packet and use the IP address of the
selected interface as the source address. If io_lhost is a valid IP address
(one of the interfaces) IP will use io_lhost as the source address for the
packet. Routing will still be done as above.
io_options is a pointer to an array of ip_options, as specified in
[RFC 791]. io_optlen specifies the length of the options, in bytes
(maximum 44). To specify no options, pass io_options as NULL.
Special behavior can be specified with io_flags. The following flags are
defined:
IP_FLAG_USEWDS If set, io_buffer is a pointer into a client-
allocated WDS (i.e., type wds_p). The client
must allocate the structure, leaving room for
lower layer protocol headers, as specified in the
section "IP DATA STRUCTURES."
Note that if IP_FLAG_USEWDS is set, datagram
buffers need not be allocated and freed with
ip_alloc and ip_free. Also, io_buflen is
ignored.
Errors returned are:
E_BADSTREAM
E_BADWDS
E_BADFLAG
E_BADIPADDR
E_NOMEM
E_DTGTOOBIG
E_CANTRESOLVEADDR
E_HWWRITEERR
ip_get (io_stream, io_buffer, io_buflen, io_fhost, io_lhost,
io_iph, io_options, io_timeout, io_flags)
-> Ptr io_stream IP stream descriptor
<- Pt r *io_buffer Datagram from foreign host
<> unsigned long *io_buflen Length of datagram
<- unsigned long *io_fhost Foreign host
<- unsigned long *io_lhost Local host
<- ip_header_p *io_iph Pointer to raw IP header
<- Ptr io_options IP options
-> struct timeval *io_timeout Timeout value
<> unsigned long *io_flags Flags
ip_get requests a buffer from an IP stream. Note that io_buffer is allocated
by the driver, but should be freed by the client (see ip_free).
If io_timeout is NULL, ip_get blocks until a datagram arrives. If
io_timeout is not NULL and a datagram is not available within the timeout
period, ip_get returns an error.
If io_iph is not NULL, a pointer is returned to the IP header for the datagram.
However, after io_buffer is deallocated (with ip_free), *io_iph is no
longer guaranteed to be valid. io_options must either be a NULL pointer or
be preallocated by the client. If NULL, no options are returned.
For the parameters io_fhost, io_lhost, and io_flags, the client may pass
NULL if it does not need the returned values.
No values are currently defined for io_flags.
Errors returned are:
E_BADSTREAM
E_TIMEDOUT
E_CANTBLOCK
ip_control (io_stream, io_buffer, io_buflen,io_control)
-> Ptr io_stream IP stream descriptor
<> Ptr io_buffer Data used by control call
<> unsigned long *io_buflen Size of io_buffer (bytes)
-> unsigned long io_control Specifies control operation
ip_control performs various operations for IP. io_control selects an
operation and is the only mandatory parameter. Parameters that are not
required by individual control operations may be passed as NULL.
General errors returned by ip_control are:
E_BADSTREAM
E_BADCONTROL
Currently defined control operations are:
IP_CTL_VERSION
<> io_buffer Pointer to ip_version_t structure
-> io_control Control operation
Returns version information. Clients pass a pointer to a
preallocated structure of type ip_version_t, as defined in the
section "IP DATA STRUCTURES."
No specific errors are returned for this control.
IP_CTL_STATS
<> io_buffer Pointer to ip_stats_t structure
-> io_control Control operation
Returns statistics for IP. Clients pass a pointer to a preallocated
structure of type ip_stats_t, as defined in the section
"IP DATA STRUCTURES." This is a preliminary version of the
final structure, and is subject to change in the near future.
No specific errors are returned for this control.
IP_CTL_GETADDR
<> io_buffer Ptr to array of ip_addr_t structures
-> *io_buflen Size of array (bytes)
-> io_control Control operation
Returns a zero-terminated list of local IP addresses (net numbers
and net masks). Clients pass a pointer to a preallocated array of
elements of type ip_addr_t, as defined in the section
"IP DATA STRUCTURES."
No specific errors are returned for this control.
IP_CTL_LHOST
<> io_buffer Points to IP address
-> io_control Control operation
Returns, through io_buffer, the local IP address that leads to the
foreign IP address specified at input.
Specific errors returned by this control are:
E_BADIPADDR
IP_CTL_MSS
<> io_buffer Pointer to ip_mss_t structure
-> io_control Control operation
Returns the maximum segment size for an IP address. Clients pass
a pointer to a preallocated structure of type ip_mss_t, as defined in
the section "IP DATA STRUCTURES." Clients should specify
an IP address in the addr field of the ip_mss_t structure. If it is
local, IP will return maximum segment size information for the
network interface on that local address. If it is foreign, IP first
determines the appropriate local IP address.
Specific errors returned by this control are:
E_BADIPADDR
ip_task ()
Clients should call ip_task periodically to allow IP time for asynchronous
processing (e.g., to process incoming datagrams).
Errors returned are:
E_CANTBLOCK
IP NOTIFICATION
Clients may request and cancel notification of asynchronous events by calling
ip_request and ip_cancel, respectively. As asynchronous events occur,
the notification routine io_notify is called with the following parameters:
(*io_notify) (io_stream, io_buffer, io_buflen, io_fhost,
io_lhost, io_prot, io_nclass, io_ndata,
io_userdata)
-> Ptr io_stream
-> Ptr io_buffer
-> unsigned long io_buflen
-> unsigned long io_fhost
-> unsigned long io_lhost
-> unsigned long io_nclass
-> unsigned long io_ndata
-> unsigned long io_userdata
io_nclass is the type of event that caused this notification. io_userdata
was passed to ip_request by the client. io_ndata contains additional
specification for the event.
The following describes the valid notification classes (io_nclass):
IP_NT_DATA: Data Arrival Notification
-> io_stream
-> io_fhost
-> io_lhost
-> io_nclass
-> io_userdata
Data arrival notification is delivered when a datagram arrives from io_fhost
on io_stream.
IP_NT_DELIVERY: Data Delivery Notification
-> io_stream
-> io_buffer
-> io_buflen
-> io_fhost
-> io_lhost
-> io_nclass
-> io_userdata
The client is notified of delivery of data from io_fhost on io_stream.
io_buffer points to a datagram of length io_buflen. This enables the client
to immediately capture the data without calling ip_get. The client is still
responsible for calling ip_free when it no longer requires the delivered
datagram.
IP_NT_ERROR: Error Notification
-> io_stream
-> io_buffer
-> io_buflen
-> io_fhost
-> io_lhost
-> io_nclass
-> io_ndata
-> io_userdata
The client is notified when an asynchronous error occurs, (e.g., destination
unreachable messages). io_ndata identifies the error. For all errors, an
ICMP destination unreachable datagram is returned in io_buffer.
io_buflen is the length of that datagram. For more information on ICMP,
refer to [RFC 792].
Errors delivered are:
E_NETUN
E_HOSTUN
E_PROTOUN
E_PORTUN
IP ERROR CODES
Following is a description of all possible error codes returned by IP:
E_NOMEM
Not enough memory to perform operation.
E_PROTOINUSE
Protocol number is already in use by another client.
E_BADSTREAM
Stream descriptor was not found in this driver's list of streams.
E_BADNOTIFICATION
Invalid notification class.
E_BADFLAG
Invalid control flag bit is set in io_flags.
E_BADCONTROL
Invalid control identifier.
E_BADPTR
Invalid pointer; could not verify that pointer points to valid data.
E_BADWDS
Invalid WDS structure or pointer.
E_BADIPADDR
Either destination IP address is invalid, or source IP address is
not on one of the interfaces.
E_DTGTOOBIG
Datagram is too long to be handled by this driver.
E_CANTRESOLVEADDR
Unable to determine the next destination IP address that leads to
the requested destination IP address.
E_HWWRITEERR
Hardware failed in writing datagram to network.
E_CANTBLOCK
Current context does not allow a blocking call.