Functions
Functions
Sockets

Functions

int32_t user_callback (SOCKET *so, void *data, uint32_t len, uint32_t ec)
 This function is called each time new data is received on a specific socket or the error status has changed (MSB set in error code) More...
 
SOCKET * socket_open (char *dest_addr, uint16_t dest_port, uint16_t src_port, uint8_t data_type, int32_t(*init_func)(SOCKET *))
 Create a new socket. More...
 
int32_t socket_close (SOCKET *so)
 Close a socket and free all associated memory. More...
 
void socket_define_callback (SOCKET *so, int32_t(*call_back_function)(SOCKET *, void *, uint32_t, uint32_t), void *data, uint16_t maxdata)
 Install a user callback function for a specific socket. More...
 
void * socket_get_data_pointer (SOCKET *so)
 Retrieve a data pointer from socket. More...
 
uint32_t set_socket_option (SOCKET *so, uint32_t option)
 Modify socket options. More...
 

Detailed Description

Function Documentation

int32_t user_callback ( SOCKET *  so,
void *  data,
uint32_t  len,
uint32_t  ec 
)
Parameters
so- socket
data- pointer to received data
len- received data length
ec- error code
Returns
>= 0L - if message processed or < 0L - if socket was closed
See also
socket_define_callback(), set_recv_buffer()

Use a callback function for event notification on a specific socket. The advantage is that no additional net_recv() function call has to be performed and the latency from the moment a packet is read from Ethernet to the moment it is signalled to the user is minimized.
The user callback function is assigned to a specific socket with function socket_define_callback().
After a callback function was assigned to a socket, function net_isq() calls this function any time new data is received on this socket or an error condition has occurred and needs to be signalled to the user.
The user is responsible to maintain the receive buffer. That means after returning from a callback function the main network process (net_isq()) re-uses this buffer. If a buffer cannot be processed immediately and is flagged for later processing somewhere in the application, a new buffer must be assigned with set_recv_buffer() to prevent the net_isq() to overwrite the buffer content with new incoming data.

Example TCP callback function:

int32_t tcp_callback (SOCKET *so, void *data, uint32_t len, uint32_t ec)
{
//**************************************************************************
// It's safe to use ec unmasked, because the event flag (MSB) is reset before
// this callback is called
//**************************************************************************
switch (ec)
{
case SO_NO_ERROR:
//******************************************************************
// New data is available in buffer that has been previously assigned
// by socket_define_callback() function.
//******************************************************************
//******************************************************************
// Process buffer or set flags for later processing
//******************************************************************
...
//******************************************************************
// Do other things
//******************************************************************
...
//******************************************************************
// If the socket must be closed (e.g. due to the requirement to
// free memory), return (-1) to signal invalid socket data to
// calling function (usually net_isq())
//******************************************************************
if (force_close)
{
shutdown(so, 0);
socket_close(so);
return (-1L);
}
//******************************************************************
// If a new buffer is needed for the next incoming data, assign a
// new buffer. This is necessary when buffer processing would take a
// long time and any succeeding call to net_isq() could overwrite
// this buffer with new incoming data
//******************************************************************
set_recv_buffer ( so, new_buffer, sizeof(new_buffer));
break;
case SO_CONNECTION_CLOSED:
//******************************************************************
// Connection closed
//******************************************************************
//******************************************************************
// Check special case:
// The last packet may contain data
//******************************************************************
if ( len != 0L )
{
//**************************************************************
// TCP data received. Process last buffer
//**************************************************************
} // if
net_print_error (ec, CPrintf);
break;
case SO_CONNECTION_ESTABLISHED:
//******************************************************************
// New connection established
//******************************************************************
//~ net_print_error (ec, CPrintf);
//~ break;
case SO_CONNECTION_RESET:
//******************************************************************
// Connection was reset
//******************************************************************
net_print_error (ec, CPrintf);
break;
case SO_TIMED_OUT:
//******************************************************************
// Connection is timed out, peer not available
// Shutdown connection to prevent a dangling socket
//******************************************************************
shutdown (so, 10L);
net_print_error (ec, CPrintf);
CPrintf (" connection closed\r\n");
break;
default:
//******************************************************************
// Else print error
//******************************************************************
net_print_error (ec, CPrintf);
break;
}
//**************************************************************************
// Return true, if socket was not closed before
//**************************************************************************
return (1L);
}
...
//****************************************************************************
//
// @brief Initialize MAC, sockets and protocols
// @param -
// @return 0 - success or >0 - error occurred
//
//****************************************************************************
int InitializeNetwork (void)
{
...
//**************************************************************************
// open sockets
//**************************************************************************
tcp_socket = socket_open (ANY_ADDRESS,
ANY_PORT,
5031,
DATATYPE_CHAR,
TCP_INIT_FUNC);
if ( tcp_socket == INVALID_SOCKET )
{
prg_exit ("socket_open() failed");
} // if
//**************************************************************************
// define callback function for received TCP packets
//**************************************************************************
socket_define_callback (tcp_socket, tcp_callback, tcp_buffer, sizeof(tcp_buffer));
...
}

Example UDP callback function

int32_t udp_callback (SOCKET *so, void *data, uint32_t len, uint32_t ec)
{
switch (ec)
{
case SO_NO_ERROR:
//**********************************************************************
// send echo
//**********************************************************************
net_send (so, data, (uint16_t)len);
break;
default :
//**********************************************************************
// else print error
//**********************************************************************
net_print_error (ec, CPrintf);
break;
}
//************************************************************************
// return true, if message processed
//************************************************************************
return (1L);
}
...
//****************************************************************************
//
// @brief Initialize MAC, sockets and protocols
// @param -
// @return 0 - success or >0 - error occurred
//
//****************************************************************************
int InitializeNetwork (void)
{
...
//**************************************************************************
// create UDP echo socket
//**************************************************************************
udp_echo = socket_open (ANY_ADDRESS,
ANY_PORT,
ECHO_PORT,
DATATYPE_CHAR,
UDP_INIT_FUNC);
if ( udp_echo == INVALID_SOCKET )
{
prg_exit ("socket_open() failed");
}
//**************************************************************************
// define callback function for received UDP packets
//**************************************************************************
socket_define_callback (udp_echo, udp_callback, udp_buffer, sizeof(udp_buffer));
...
}
SOCKET * socket_open ( char *  dest_addr,
uint16_t  dest_port,
uint16_t  src_port,
uint8_t  data_type,
int32_t(*)(SOCKET *)  init_func 
)
Parameters
dest_addr- Destination address string (zero terminated)
  • destination (remote) IP address (e.g. "192.168.1.12")
  • or host name if DNS is used (e.g. "host_pc.system.net")
dest_port- Destination port
  • well known (remote) port (<1025), e.g. 13 for time server
  • user-defined ports starting at 1025, use ANY_PORT if a server (e.g. echo server) should run on the DSP
src_port- Source (local) port
data_type- Type of data to be transmitted/received
  • DATATYPE_CHAR (8 bits)
  • DATATYPE_SHORT (16 bits) or
  • DATATYPE_INT (32 bit integers and floats)
init_func- Function to initialize socket, use UDP_INIT_FUNC or TCP_INIT_FUNC
Returns
pointer to socket, NULL if socket cannot be created
Library:
net.lib
Prototype:
net.h
See also
UDP_INIT_FUNC, TCP_INIT_FUNC
DATATYPE_CHAR, DATATYPE_SHORT, DATATYPE_INT,
ANY_PORT, ANY_ADDRESS, Sockets,
set_socket_option(), tcp_listen(), shutdown()

A socket describes either a server or a client connection. As a server, the DSP waits for incoming data on its local port (parameter src_port). If ANY_IP was specified for the dest_addr parameter, any client can access this server. If a host name or IP address was specified, only the specified client can access this service. The response of the DSP server is sent to the port specified as dest_port. Typically a server socket will use ANY_PORT and let the client specify its preferred port.

A client socket will connect to a specific server and a specific port, ANY_IP and ANY_PORT cannot be used as dest_addr and dest_port parameters for client sockets. As a client, the DSP sends data to the specified server and the specified port (dest_addr and dest_port), and expects a response (if any) on the src_port. If ANY_PORT is specified as src_port, the TCP/IP software will determine a suitable port itself.

The last parameter, init_func, is a pointer to a function which handles either the UDP or TCP protocol. Use only the pre-defined UDP_INIT_FUNC or - for a TCP socket - TCP_INIT_FUNC. This technique results in only the actually used protocol code being loaded from the netlib library and helps to reduce code size.

Attention
To reduce processing time for TCP sockets, by default the TCP state machine in the netlib starts in listening state. Also after shutting down the connection the TCP socket is falling back to listening state. This facilitates TCP server socket programming on the DSP side.
Is this behaviour unsuitable (e.g. for parallel server socket handling) use set_socket_option() with option SO_TCP_STATE_CLOSED. This option adds two additional states to the TCP state machine (TCP_CLOSED and TCPS_FIN_WAIT_2) and lets the TCP socket start in closed state. use function tcp_listen() to switch the socket to listening state. After shutting down the connection, the state TCPS_FIN_WAIT_2 prevents the TCP socket for being connected again for a certain time.

Example:
create an UDP socket to receive the current time from a network time server which is running on a machine with IP address 192.168.1.12 on UDP port 13 (well known port for time server)

1 SOCKET *udp_time; // socket handle
2 int8_t udp_timedata[32]; // buffer to hold the time
3 
4 udp_time = socket_open ("192.168.1.12",
5  TIME_SERVER_PORT,
6  1061,
7  DATATYPE_CHAR,
8  UDP_INIT_FUNC);
9 if ( udp_time == INVALID_SOCKET )
10 {
11  printf ("could not create socket - out of memory ?");
12 }
Examples:
Blocksend.c, Chat.c, Echo.c, Multicast.c, NetTest.c, Receive.c, Send.c, and SMTP.c.
int32_t socket_close ( SOCKET *  so)
Parameters
so- the socket to close
Returns
  • TRUE if successful
  • FALSE if socket does not exist
Library:
net.lib
Prototype:
net.h
See also
shutdown()

If a socket is no longer used, it can be closed to free the memory occupied by the socket structure.

Attention
A TCP socket should only be closed if the connection was properly shutdown().
Examples:
Blocksend.c, and SMTP.c.
void socket_define_callback ( SOCKET *  so,
int32_t(*)(SOCKET *, void *, uint32_t, uint32_t)  call_back_function,
void *  data,
uint16_t  maxdata 
)

Define a callback function for event notification of a specific socket. Possible events are new received data or socket errors. This function calls set_recv_buffer() with parameters so, data and maxdata to pre-initialize a receive buffer.

Note
If data pointer is NULL, data and maxdata is ignored. Use this option to enable/disable the callback function.
If parameter callback_function is NULL, the user callback function is disabled.
Attention
Make sure to call socket_define_callback() with a valid data pointer different from NULL only for initializing or within a user callback function or immediately after a net_recv() function call.
Parameters
so- Socket for callback
call_back_function- User defined call back function or NULL
data- pointer to receive buffer or NULL
maxdata- receive buffer size
Returns
-
Library:
net.lib
Prototype:
net.h
See also
user_callback()

Example:

1 //****************************************************************************
2 //
3 // @brief Initialize MAC, sockets and protocols
4 // @param -
5 // @return 0 - success or >0 - error occurred
6 //
7 //****************************************************************************
8 int InitializeNetwork (void)
9 {
10 ...
11 
12  //**************************************************************************
13  // create UDP echo socket
14  //**************************************************************************
15  udp_echo = socket_open (ANY_ADDRESS,
16  ANY_PORT,
17  ECHO_PORT,
18  DATATYPE_CHAR,
19  UDP_INIT_FUNC);
20 
21  if ( udp_echo == INVALID_SOCKET )
22  {
23  prg_exit ("socket_open() failed");
24  }
25 
26  //**************************************************************************
27  // define callback function for received UDP packets
28  //**************************************************************************
29  socket_define_callback (udp_echo, udp_callback, udp_buffer, sizeof(udp_buffer));
30  ...
31 }

or disabling a receive function:

1 //**************************************************************************
2 // define callback function for received TCP packets
3 //**************************************************************************
4 socket_define_callback (tcp_socket, tcp_callback, tcp_buffer, TCP_BUFFER_SIZE);
5 ...
6 
7 
8 //**************************************************************************
9 // disable callback function for TCP packets before long operation
10 //**************************************************************************
11 socket_define_callback (tcp_socket, NULL, NULL, NULL);
12 
13 some_long_operation_without_receive_callback();
14 
15 //**************************************************************************
16 // re-enable callback function for TCP packets
17 //**************************************************************************
18 socket_define_callback (tcp_socket, tcp_callback, NULL, NULL);
Examples:
Blocksend.c, Echo.c, Multicast.c, NetTest.c, Ping2.c, PServer.c, and Receive.c.
void * socket_get_data_pointer ( SOCKET *  so)

This function returns the current data buffer of socket so.

Parameters
so- Socket to get the data pointer from
Returns
current data pointer
Library:
net.lib
Prototype:
net.h

Retrieve associated data buffer when the buffer is unknown.

1 //****************************************************************************
2 // install ICMP socket (for ping)
3 //****************************************************************************
4 if ( (icmp_so = install_icmp_socket (MAX_PING_DATA)) == INVALID_SOCKET )
5 {
6  prg_exit ("ICMP socket error"); // possibly insufficient heap
7 }
8 
9 //****************************************************************************
10 // define callback function for received ICMP packets. The associated data
11 // buffer is unknown, retrieve the buffer with socket_get_data_pointer()
12 //****************************************************************************
13 socket_define_callback (icmp_so, icmp_msg, socket_get_data_pointer(icmp_so), MAX_PING_DATA);
Examples:
Ping2.c.
uint32_t set_socket_option ( SOCKET *  so,
uint32_t  option 
)
Parameters
so- the socket to modify
option- options, use SO_xxx constants
Returns
nothing
Library:
net.lib
Prototype:
net.h

This function is used to specify non-standard socket options. Currently implemented are

1 //****************************************************************************
2 // create UDP echo socket
3 //****************************************************************************
4 udp_socket = socket_open (ANY_ADDRESS,
5  ANY_PORT,
6  53096,
7  DATATYPE_CHAR,
8  UDP_INIT_FUNC);
9 
10 //****************************************************************************
11 // disable checksum calculation
12 //****************************************************************************
13 set_socket_option(udp_socket,SO_UDP_NO_CHECKSUM);