UDP standard functions

Primary UDP API, including functions compliant with Xinu's device model. More...

Functions
ushort	udpAlloc (void)
devcall	udpClose (device *devptr)
devcall	udpControl (device *devptr, int func, long arg1, long arg2)
devcall	udpInit (device *devptr)
devcall	udpOpen (device *devptr, va_list ap)
devcall	udpRead (device *devptr, void *buf, uint len)
devcall	udpWrite (device *devptr, const void *buf, uint len)

Detailed Description

Primary UDP API, including functions compliant with Xinu's device model.

Users should use udpAlloc() to allocate a UDP device, then use the generic device calls open(), read(), write(), control(), or close() on it, each of which calls the corresponding function listed here. A UDP device essentially corresponds to a "socket" as used in other operating systems. Local and remote ports and addresses are specified in the open() calle.

Function Documentation

ushort udpAlloc

(

void

)

Allocate an available UDP device.

Returns

Device number for a UDP device, or ::SYSERR if none are free.

devcall udpClose

(

device *

devptr

)

Closes a UDP device.

Caveat: There must not be any threads executing udpWrite() on the UDP device when it is closed. On the other hand, it is safe to close the UDP device while threads are executing udpRead(), and they will return ::SYSERR. However, you still must not re-open the UDP device before all udpRead() threads have returned.

Parameters

devptr

Device entry for the UDP device.

Returns

::OK if the UDP device was closed successfully; ::SYSERR otherwise. Currently this function can only fail if the UDP device was not actually open.

devcall udpControl	(	device *	devptr,
		int	func,
		long	arg1,
		long	arg2
	)

Control function for udp devices.

Parameters

devptr	udp device table entry
func	control function to execute
arg1	first argument for the control function
arg2	second argument for the control function

Returns

the result of the control function

devcall udpInit

(

device *

devptr

)

Set aside some space for a UDP device to be opened on

Parameters

devptr

UDP device table entry

Returns

OK

devcall udpOpen	(	device *	devptr,
		va_list	ap
	)

Associate a UDP socket with local and remote IP addresses and ports, and prepare it for receiving and sending data with udpRead() and udpWrite().

Parameters

devptr	Device table entry for the UDP device.
ap	Four additional arguments, specifying the following in order: The local IP address. The remote IP address. May be NULL to create an initially unbound socket. The local port. May be 0 to auto-assign a port number. The remote port. May be 0 if creating an initially unbound socket.

Returns

::OK if the UDP device was opened successfully; otherwise ::SYSERR.

devcall udpRead	(	device *	devptr,
		void *	buf,
		uint	len
	)

Read the next UDP packet from a UDP device and place its data into the provided buffer.

In the default mode, the resulting data will be the UDP payload. If instead the UDP is in passive mode, the resulting data will be the UDP pseudo-header, directly followed by the UDP header, directly followed by the UDP payload.

Parameters

devptr	Device table entry for the UDP device.
buf	Buffer into which to read the data.
len	Maximum amount of data to read (length of buf).

Returns

On success, returns the number of bytes read. This is normally the size of the UDP packet (see note about passive mode above), but as special cases it will be 0 if the UDP is in non-blocking mode and no packets are available, or it will be len if the actual amount of data that was available was greater than len. Alternatively, if the UDP device was not initially open or was closed while attempting to read a packet, ::SYSERR is returned.

devcall udpWrite	(	device *	devptr,
		const void *	buf,
		uint	len
	)

Write data to a UDP device, thereby sending it over the network in one or more UDP packets using the address/port parameters with which the UDP device is configured.

Note: depending on the lower levels of the network stack, this function likely only buffers the UDP packet(s) to be sent at some later time. Therefore, they may not have actually been transmitted on the wire when this function returns.

The UDP device MUST be open and MUST remain open throughout the execution of this function.

Parameters

devptr	Device entry for the UDP device.
buf	Buffer of data to be sent. If the UDP device is in the default mode, this is interpreted as the UDP payload to send, which will be split up among multiple UDP packets if its size exceeds ::UDP_MAX_DATALEN bytes. Alternatively, if the UDP device is in passive mode", the data is intepreted as a single UDP packet including the UDP pseudo-header, followed by the UDP header, followed by the UDP payload.
len	Number of bytes of data to send (length of buf).

Returns

If any packets were successfully sent, returns the number of bytes of data successfully sent, which may be less than len in the case of an error. If the UDP device is not in passive mode and len was 0, no packets will be sent and 0 will be returned. Otherwise, returns ::SYSERR.