net/udp.h File Reference

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].

Configuration

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

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

Data Structures

struct  _UDP_HEADER
struct  _UDP_SOCKET_INFO

Defines

#define INVALID_UDP_PORT   (0L)
#define INVALID_UDP_SOCKET   (0xff)
#define SIZEOF_MAC_HEADER   14
#define UDPGetMaxDataLength()   (MAC_TX_BUFFER_SIZE - SIZEOF_MAC_HEADER - sizeof(IP_HEADER) - sizeof(UDP_HEADER))
#define UDPSetRxBuffer(a)   IPSetRxBuffer(a+sizeof(UDP_HEADER))

Typedefs

typedef _UDP_HEADER UDP_HEADER
typedef BYTE UDP_SOCKET
typedef _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)
BOOL UDPIsPutReady (UDP_SOCKET s)
UDP_SOCKET UDPOpen (WORD localPort, NODE_INFO *remoteNode, WORD 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]

Define Documentation

#define INVALID_UDP_PORT   (0L)
 

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

#define INVALID_UDP_SOCKET   (0xff)
 

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   14
 

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

Typedef Documentation

typedef struct _UDP_HEADER UDP_HEADER
 

UDP Packet header

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.

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 (  WORD  localPort,
NODE_INFO *  remoteNode,
WORD  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]
 

Generated on Tue Feb 21 15:18:07 2006 for SBC65EC Web Server by  doxygen 1.4.5