net/udp.h File Reference

UDP Module for Modtronix TCP/IP Stack. More...

#include "net\ip.h"
#include "net\mac.h"

Data Structures

struct _UDP_HEADER

struct _UDP_SOCKET_INFO

Defines

#define INVALID_UDP_PORT   (0ul)

#define INVALID_UDP_SOCKET   (0xfful)

#define SIZEOF_MAC_HEADER   (14ul)

#define UDPGetMaxDataLength()   (MAC_TX_BUFFER_SIZE - SIZEOF_MAC_HEADER - sizeof(IP_HEADER) - sizeof(UDP_HEADER))

#define UDPSetRxBuffer(a)   IPSetRxBuffer(a+sizeof(UDP_HEADER))

#define UDPSetTxBuffer(buffer, offset)   (UDPSocketInfo[activeUDPSocket].TxOffset = offset, IPSetTxBuffer(buffer, offset+sizeof(UDP_HEADER)))

Typedefs

typedef struct _UDP_HEADER UDP_HEADER

typedef WORD UDP_PORT

typedef BYTE UDP_SOCKET

typedef struct _UDP_SOCKET_INFO UDP_SOCKET_INFO

Functions

void UDPClose (UDP_SOCKET s)

void UDPDiscard (void)

void UDPFlush (void)

BOOL UDPGet (BYTE *v)

WORD UDPGetArray (BYTE *buffer, WORD count)

NODE_INFO * UDPGetNodeInfo (void)

void UDPInit (void)

BOOL UDPIsGetReady (UDP_SOCKET s)

WORD UDPIsGetReady_ (UDP_SOCKET s)

BOOL UDPIsPutReady (UDP_SOCKET s)

UDP_SOCKET UDPOpen (UDP_PORT localPort, NODE_INFO *remoteNode, UDP_PORT remotePort)

BOOL UDPProcess (NODE_INFO *remoteNode, IP_ADDR *localIP, WORD len)

BOOL UDPPut (BYTE v)

WORD UDPPutArray (BYTE *buffer, WORD count)

Variables

UDP_SOCKET activeUDPSocket

UDP_SOCKET_INFO UDPSocketInfo [MAX_UDP_SOCKETS]

Detailed Description

UDP Module for Modtronix TCP/IP Stack.

Author:: Modtronix Engineering

Dependencies:: stacktsk.h, mac.h

Compiler:: MPLAB C18 v2.10 or higher
HITECH PICC-18 V8.35PL3 or higher

Description

This module contains the UDP code.
For a detailed description, see the UDP section of this document - in [Modules] [TCP/IP Stack] [TCP/IP Base Protocols].

The following defines are used to configure this module, and should be placed in the projdefs.h (or similar) file. For details, see Project Configuration. To configure the module, the required defines should be uncommended, and the rest commented out.

 //*********************************************************************
 //-------------------- UDP Configuration --------------------
 //*********************************************************************

 //When defined, the code will be compiled for optimal speed. If not defined, code is defined for smallest size.
 #define UDP_SPEED_OPTIMIZE

Define Documentation

#define INVALID_UDP_PORT (0ul)

Examples:: ex_udp.c, ex_udp_echo.c, ex_udp_echo2.c, and ex_udp_init.c.

#define INVALID_UDP_SOCKET (0xfful)

Examples:: ex_udp.c, ex_udp_client.c, ex_udp_client2.c, ex_udp_echo.c, ex_udp_echo2.c, and ex_udp_init.c.

#define SIZEOF_MAC_HEADER (14ul)

Returns the maximum size the UDP data is allowed to be. This value should never be execeed when writting data to the UDP transmit buffer before calling UDPFlush(). For slip: = MAC_TX_BUFFER_SIZE - sizeof(IP_HEADER) - sizeof(UDP_HEADER) = MAC_TX_BUFFER_SIZE - 20 - 8 = MAC_TX_BUFFER_SIZE - 28 For RTL MAC = MAC_TX_BUFFER_SIZE - SIZEOF_MAC_HEADER - sizeof(IP_HEADER) - sizeof(UDP_HEADER) = MAC_TX_BUFFER_SIZE - 14 - 20 - 8 = MAC_TX_BUFFER_SIZE - 42

#define UDPGetMaxDataLength ( ) (MAC_TX_BUFFER_SIZE - SIZEOF_MAC_HEADER - sizeof(IP_HEADER) - sizeof(UDP_HEADER))

#define UDPSetRxBuffer ( a ) IPSetRxBuffer(a+sizeof(UDP_HEADER))

Sets the receive buffer access point to given offset in UDP Data. For example, if UDP data is a HTTP message, an offset of 0 will set access to first byte of HTTP message (UDP data). Layers that use UDP services (HTTP) should call this macro to set the access pointer for the current buffer.

Parameters:

a

Offset, An offset with respect to UDP Data

#define UDPSetTxBuffer	(	buffer,
		offset		)	(UDPSocketInfo[activeUDPSocket].TxOffset = offset, IPSetTxBuffer(buffer, offset+sizeof(UDP_HEADER)))

This function makes the given transmit buffer active, and sets it's access pointer to be:

At the given offset after the UDP header
In the given TX Buffer
So, if we pass 0 in as the offset, we will set the pointer to the first byte of after the UDP header. All future read and writes to the TX Buffer will be to the set location.

Parameters:

	buffer	Buffer identifier
	offset	Offset

Typedef Documentation

typedef struct _UDP_HEADER UDP_HEADER

UDP Packet header

typedef WORD UDP_PORT

Handle to a UDP port

typedef BYTE UDP_SOCKET

Handle to a UDP socket

Examples:: ex_udp.c, ex_udp_client.c, ex_udp_client2.c, ex_udp_echo.c, ex_udp_echo2.c, and ex_udp_init.c.

typedef struct _UDP_SOCKET_INFO UDP_SOCKET_INFO

UDP Socket - is 22 bytes long

Function Documentation

void UDPClose ( UDP_SOCKET s )

Given socket is marked as available for future new communcations.

This function does not affect previous active UDP socket designation.

Pre-Condition:: UDPOpen() is already called

Parameters:

s

Socket that is to be closed.

void UDPDiscard ( void )

This function discards an active UDP socket content.

Pre-Condition:: UDPInit() is already called AND UDPIsGetReady() == TRUE with desired UDP socket.

Examples:: ex_udp.c, ex_udp_echo.c, and ex_udp_echo2.c.

void UDPFlush ( void )

This function transmit all data from an active UDP socket.

Pre-Condition:: UDPPut() is already called and desired UDP socket is set as an active socket by calling UDPIsPutReady().

Returns:: All and any data associated with active UDP socket buffer is marked as ready for transmission.

Examples:: ex_udp_client.c, ex_udp_client2.c, ex_udp_echo.c, and ex_udp_echo2.c.

BOOL UDPGet ( BYTE * v )

Get a byte of data.

Note: This function fetches data from the currently active UDP socket. The active UDP socket is set by the UDPIsGetReady() call.

Pre-Condition:: UDPInit() is already called AND UDPIsGetReady(s) == TRUE

Parameters:

[out] v Buffer to receive UDP data byte

Returns:: TRUE if a data byte was read
FALSE if no data byte was read or available

Examples:: ex_udp.c, and ex_udp_echo.c.

WORD UDPGetArray	(	BYTE *	buffer,
		WORD	count
	)

Read the requested number of bytes from the active UDP socket into the given buffer.

Note: This function fetches data from an active UDP socket as set by UDPIsGetReady() call.

Pre-Condition:: UDPInit() is already called AND UDPIsGetReady(s) == TRUE

Parameters:

`[in]`	buffer	Buffer to hold received data.
	count	Buffer length

Returns:: Number of bytes loaded into buffer.

Examples:: ex_udp_echo2.c.

NODE_INFO* UDPGetNodeInfo ( void )

Get's the MAC and IP address of the currently active UDP socket. This data is assigned the MAC and IP address of the remote node after a UDP message has been received. So, the MAC and IP address returned by this function will only be valid if a UDP message has already been received on this socket! The active socket is set by the UDPIsGetReady() call.

Pre-Condition:: UDPInit() is already called AND UDPIsGetReady(s) == TRUE

Returns:: Pointer to a NODE_INFO structure containing the remote node's MAC and IP address

Examples:: ex_udp_echo2.c.

void UDPInit ( void )

Initializes internal variables.

Pre-Condition:: None

BOOL UDPIsGetReady ( UDP_SOCKET s )

Check if given socket contains any data that is ready to be read, and that the given socket is valid (not equal to INVALID_UDP_SOCKET for example). It also sets the given socket as the active UDP socket.

Side Effects: Given socket is set as the active UDP Socket.

Note: This function automatically sets supplied socket as the active socket. All subsequent calls will us this socket as the active socket.

Pre-Condition:: UDPInit() is already called.

Parameters:

s

A valid UDP socket that is already "Listen"ed on or opened.

Returns:: TRUE if given socket contains any data, and is a valid socket.
FALSE if not.

Examples:: ex_udp.c, ex_udp_echo.c, and ex_udp_echo2.c.

WORD UDPIsGetReady_ ( UDP_SOCKET s )

UDP function that returns number of UDP bytes that are available

Parameters:

s

A valid UDP socket that is already "Listen"ed on or opened.

Returns:: Number of bytes ready to be read.

BOOL UDPIsPutReady ( UDP_SOCKET s )

Checks if there is a transmit buffer ready for accepting data, and that the given socket is valid (not equal to INVALID_UDP_SOCKET for example).

Side Effects: Given socket is set as the active UDP Socket.

Note: This function automatically sets supplied socket as the active socket. All subsequent calls will us this socket as the active socket.

Parameters:

s

Socket that is to be loaded and made an active UDP socket.

Returns:: TRUE if at least one UDP buffer is ready to transmit, and given socket is valid
FALSE if not

Examples:: ex_udp_client.c, ex_udp_client2.c, ex_udp_echo.c, and ex_udp_echo2.c.

UDP_SOCKET UDPOpen	(	UDP_PORT	localPort,
		NODE_INFO *	remoteNode,
		UDP_PORT	remotePort
	)

A UDP packet header is assembled and loaded into UDP transmit buffer.

A localPort value of '0' is considered nonexistent port. This call must always have nonzero localPort value. This function sets returned socket as an active UDP socket.

Pre-Condition:: UDPInit() is already called

Parameters:

	localPort	A non-zero port number.
	remoteNode	Remote Node info such as MAC and IP address. If NULL, broadcast node address is set.
	remotePort	Remote Port to which to talk to. If INVALID_UDP_PORT, localPort is opened for Listen.

Returns:: A valid UDP socket that is to be used for subsequent UDP communications. If the given port could not be opened, or an error occured, INVALID_UDP_SOCKET is returned.

Examples:: ex_udp.c, ex_udp_client.c, ex_udp_client2.c, ex_udp_echo.c, ex_udp_echo2.c, and ex_udp_init.c.

BOOL UDPProcess	(	NODE_INFO *	remoteNode,
		IP_ADDR *	localIP,
		WORD	len
	)

Performs UDP related tasks. Must continuesly be called.

Pre-Condition:: UDPInit() is already called AND
UDP segment is ready in MAC buffer

Parameters:

	remoteNode	Remote node info
	len	Total length of UDP semgent.
	localIP	The IP Address of the currently received packet.

Returns:: TRUE if this function has completed its task
FALSE otherwise

BOOL UDPPut ( BYTE v )

Given data byte is put into the UDP transmit buffer and active UDP socket buffer length is incremented. The data is NOT sent yet, and the UDPFlush() function must be called to send all data contained in the transmit buffer.

If the transmit buffer filled up, the contents of the transmit buffer will be sent, and this function will return FALSE. In this case, it is VERY IMPORTANT to call the UDPIsPutReady() function again before calling the UDPPut() or UDPPutArray() functions!

Note: This function loads data into an active UDP socket as determined by previous call to UDPIsPutReady().

Pre-Condition:: UDPIsPutReady() == TRUE with desired UDP socket that is to be loaded.

Parameters:

v

- Data byte to loaded into transmit buffer

Returns:: TRUE if transmit buffer is still ready to accept more data bytes
FALSE if transmit buffer can no longer accept any more data byte.
If FALSE is returned, then UDPIsPutReady() has to be called again before calling the UDPPut() or UDPPutArray() functions!

Examples:: ex_udp_client.c, ex_udp_client2.c, and ex_udp_echo.c.

WORD UDPPutArray	(	BYTE *	buffer,
		WORD	count
	)

Given number of data bytes from the given array are put into the UDP transmit buffer and active UDP socket buffer length is incremented by number of bytes. The data is NOT sent yet, and the UDPFlush() function must be called to send all data contained in the transmit buffer.

If there is not enough space in the transmit buffer for all the data, the contents of the transmit buffer will be sent, and this function will return the actual amount of bytes that were sent. In this case, it is VERY IMPORTANT to call the UDPIsPutReady() function again before calling the UDPPut() or UDPPutArray() functions! This will however only happen if the transmit buffer fills up. The transmit buffer for UDP data is = (MAC_TX_BUFFER_SIZE - 42), which is usually 982 bytes. If writing less then this to the transmit buffer before calling UDPFlush(), then this function will always return the requested number of bytes!

Note: This function loads data into an active UDP socket as determined by previous call to UDPIsPutReady().

Pre-Condition:: UDPIsPutReady() == TRUE with desired UDP socket that is to be loaded.

Parameters:

`[in]`	buffer	Buffer containing data that has to be sent.
	count	Number of bytes to send

Returns:: Number of bytes added to the transmit buffer.
!!!!! IMPORTANT !!!!!
If this value is less then the number of bytes we requested to send, then UDPIsPutReady() must be called again before calling the UDPPut() or UDPPutArray() functions!

Examples:: ex_udp_echo2.c.

Variable Documentation

UDP_SOCKET activeUDPSocket

UDP_SOCKET_INFO UDPSocketInfo[MAX_UDP_SOCKETS]


Data Structures
struct	_UDP_HEADER
struct	_UDP_SOCKET_INFO
Defines
#define	INVALID_UDP_PORT (0ul)
#define	INVALID_UDP_SOCKET (0xfful)
#define	SIZEOF_MAC_HEADER (14ul)
#define	UDPGetMaxDataLength() (MAC_TX_BUFFER_SIZE - SIZEOF_MAC_HEADER - sizeof(IP_HEADER) - sizeof(UDP_HEADER))
#define	UDPSetRxBuffer(a) IPSetRxBuffer(a+sizeof(UDP_HEADER))
#define	UDPSetTxBuffer(buffer, offset) (UDPSocketInfo[activeUDPSocket].TxOffset = offset, IPSetTxBuffer(buffer, offset+sizeof(UDP_HEADER)))
Typedefs
typedef struct _UDP_HEADER	UDP_HEADER
typedef WORD	UDP_PORT
typedef BYTE	UDP_SOCKET
typedef struct _UDP_SOCKET_INFO	UDP_SOCKET_INFO
Functions
void	UDPClose (UDP_SOCKET s)
void	UDPDiscard (void)
void	UDPFlush (void)
BOOL	UDPGet (BYTE *v)
WORD	UDPGetArray (BYTE *buffer, WORD count)
NODE_INFO *	UDPGetNodeInfo (void)
void	UDPInit (void)
BOOL	UDPIsGetReady (UDP_SOCKET s)
WORD	UDPIsGetReady_ (UDP_SOCKET s)
BOOL	UDPIsPutReady (UDP_SOCKET s)
UDP_SOCKET	UDPOpen (UDP_PORT localPort, NODE_INFO *remoteNode, UDP_PORT remotePort)
BOOL	UDPProcess (NODE_INFO remoteNode, IP_ADDR localIP, WORD len)
BOOL	UDPPut (BYTE v)
WORD	UDPPutArray (BYTE *buffer, WORD count)
Variables
UDP_SOCKET	activeUDPSocket
UDP_SOCKET_INFO	UDPSocketInfo [MAX_UDP_SOCKETS]