tcp-socket.h File Reference

Data Structures
struct	tcp_socket

Typedefs
typedef int(*	tcp_socket_data_callback_t )(struct tcp_socket *s, void *ptr, const uint8_t *input_data_ptr, int input_data_len)
	TCP data callback function. More...
typedef void(*	tcp_socket_event_callback_t )(struct tcp_socket *s, void *ptr, tcp_socket_event_t event)
	TCP event callback function. More...

Enumerations
enum	{   TCP_SOCKET_FLAGS_NONE = 0x00,   TCP_SOCKET_FLAGS_LISTENING = 0x01,   TCP_SOCKET_FLAGS_CLOSING = 0x02 }
enum	tcp_socket_event_t {   TCP_SOCKET_CONNECTED,   TCP_SOCKET_CLOSED,   TCP_SOCKET_TIMEDOUT,   TCP_SOCKET_ABORTED,   TCP_SOCKET_DATA_SENT }

Functions
int	tcp_socket_close (struct tcp_socket *s)
	Close a connected TCP socket. More...
int	tcp_socket_connect (struct tcp_socket *s, uip_ipaddr_t *ipaddr, uint16_t port)
	Connect a TCP socket to a remote host. More...
int	tcp_socket_listen (struct tcp_socket *s, uint16_t port)
	Start listening on a specific port. More...
int	tcp_socket_register (struct tcp_socket *s, void *ptr, uint8_t *input_databuf, int input_databuf_len, uint8_t *output_databuf, int output_databuf_len, tcp_socket_data_callback_t data_callback, tcp_socket_event_callback_t event_callback)
	Register a TCP socket. More...
int	tcp_socket_send (struct tcp_socket *s, const uint8_t *dataptr, int datalen)
	Send data on a connected TCP socket. More...
int	tcp_socket_send_str (struct tcp_socket *s, const char *strptr)
	Send a string on a connected TCP socket. More...
int	tcp_socket_unlisten (struct tcp_socket *s)
	Stop listening for new connections. More...
int	tcp_socket_unregister (struct tcp_socket *s)
	Unregister a registered socket. More...

typedef int(* tcp_socket_data_callback_t)(struct tcp_socket *s, void *ptr, const uint8_t *input_data_ptr, int input_data_len)

TCP data callback function.

Parameters

s	A pointer to a TCP socket
ptr	A user-defined pointer
input_data_ptr	A pointer to the incoming data
input_data_len	The length of the incoming data

Returns

The function should return the number of bytes to leave in the input buffer

        The TCP socket input callback function gets
        called whenever there is new data on the socket. The
        function can choose to either consume the data
        directly, or leave it in the buffer for later. The
        function must return the amount of data to leave in the
        buffer. I.e., if the callback function consumes all
        incoming data, it should return 0.

typedef void(* tcp_socket_event_callback_t)(struct tcp_socket *s, void *ptr, tcp_socket_event_t event)

TCP event callback function.

Parameters

s	A pointer to a TCP socket
ptr	A user-defined pointer
event	The event number The TCP socket event callback function gets called whenever there is an event on a socket, such as the socket getting connected or closed.

anonymous enum

Enumerator
TCP_SOCKET_FLAGS_NONE
TCP_SOCKET_FLAGS_LISTENING
TCP_SOCKET_FLAGS_CLOSING

enum tcp_socket_event_t

Enumerator
TCP_SOCKET_CONNECTED
TCP_SOCKET_CLOSED
TCP_SOCKET_TIMEDOUT
TCP_SOCKET_ABORTED
TCP_SOCKET_DATA_SENT

int tcp_socket_close

(

struct tcp_socket *

s

)

Close a connected TCP socket.

Parameters

s	A pointer to a TCP socket that must have been previously registered with tcp_socket_register()

Return values

-1	If an error occurs
1	If the operation succeeds. This function closes a connected TCP socket. When the socket has been successfully closed, the event callback is called with the TCP_SOCKET_CLOSED event.

References tcp_socket::flags, NULL, and TCP_SOCKET_FLAGS_CLOSING.

Referenced by http_socket_close(), input_pt(), parse_header_byte(), and PROCESS_THREAD().

int tcp_socket_connect	(	struct tcp_socket *	s,
		uip_ipaddr_t *	ipaddr,
		uint16_t	port
	)

Connect a TCP socket to a remote host.

Parameters

s	A pointer to a TCP socket that must have been previously registered with tcp_socket_register()
ipaddr	The IP address of the remote host
port	The TCP port number, in host byte order, of the remote host

Return values

-1

If an error occurs

1

If the operation succeeds. This function connects a TCP socket to a remote host. When the socket has connected, the event callback will get called with the TCP_SOCKET_CONNECTED event. If the remote host does not accept the connection, the TCP_SOCKET_ABORTED will be sent to the callback. If the connection times out before conecting to the remote host, the TCP_SOCKET_TIMEDOUT event is sent to the callback.

References tcp_socket::c, NULL, PROCESS_CONTEXT_BEGIN, PROCESS_CONTEXT_END, tcp_connect(), and uip_htons().

Referenced by start_request().

int tcp_socket_listen	(	struct tcp_socket *	s,
		uint16_t	port
	)

Start listening on a specific port.

Parameters

s	A pointer to a TCP socket that must have been previously registered with tcp_socket_register()
port	The TCP port number, in host byte order, of the remote host

Return values

-1	If an error occurs
1	If the operation succeeds. This function causes the TCP socket to start listening on the given TCP port. Several sockets can listen on the same port. If a remote host connects to the port, one of the listening sockets will get connected and the event callback will be called with the TCP_SOCKET_CONNECTED event. When the connection closes, the socket will go back to listening for new connections.

References tcp_socket::flags, tcp_socket::listen_port, NULL, port, PROCESS_CONTEXT_BEGIN, PROCESS_CONTEXT_END, tcp_listen(), TCP_SOCKET_FLAGS_LISTENING, and uip_htons().

int tcp_socket_register	(	struct tcp_socket *	s,
		void *	ptr,
		uint8_t *	input_databuf,
		int	input_databuf_len,
		uint8_t *	output_databuf,
		int	output_databuf_len,
		tcp_socket_data_callback_t	data_callback,
		tcp_socket_event_callback_t	event_callback
	)

Register a TCP socket.

Parameters

s	A pointer to a TCP socket
ptr	A user-defined pointer that will be sent to callbacks for this socket
input_databuf	A pointer to a memory area this socket will use for input data
input_databuf_len	The size of the input data buffer
output_databuf	A pointer to a memory area this socket will use for outgoing data
output_databuf_len	The size of the output data buffer
data_callback	A pointer to the data callback function for this socket
event_callback	A pointer to the event callback function for this socket

Return values

-1

If an error occurs

1

If the operation succeeds. This function registers a TCP socket. The function sets up the output and input buffers for the socket and callback pointers. TCP sockets use input and output buffers for incoming and outgoing data. The memory for these buffers must be allocated by the caller. The size of the buffers determine the amount of data that can be received and sent, and the principle is that the application that sets up the TCP socket will know roughly how large these buffers should be. The rule of thumb is that the input buffer should be large enough to hold the largest application layer message that the application will receive and the output buffer should be large enough to hold the largest application layer message the application will send. TCP throttles incoming data so that if the input buffer is filled, the connection will halt until the application has read out the data from the input buffer.

References tcp_socket::event_callback, tcp_socket::flags, init, tcp_socket::input_callback, input_callback, tcp_socket::input_data_maxlen, tcp_socket::input_data_ptr, list_add(), tcp_socket::listen_port, NULL, tcp_socket::output_data_maxlen, tcp_socket::output_data_ptr, tcp_socket::ptr, ptr, and TCP_SOCKET_FLAGS_NONE.

Referenced by http_socket_get(), and http_socket_post().

int tcp_socket_send	(	struct tcp_socket *	s,
		const uint8_t *	dataptr,
		int	datalen
	)

Send data on a connected TCP socket.

Parameters

s	A pointer to a TCP socket that must have been previously registered with tcp_socket_register()
dataptr	A pointer to the data to be sent
datalen	The length of the data to be sent

Return values

-1	If an error occurs

Returns

The number of bytes that were successfully sent

        This function sends data over a connected TCP
        socket. The data is placed in the output buffer and
        sent to the remote host as soon as possiblce. When the
        data has been acknowledged by the remote host, the
        event callback is sent with the TCP_SOCKET_DATA_SENT
        event.

References len, MIN, NULL, tcp_socket::output_data_len, tcp_socket::output_data_maxlen, and tcp_socket::output_data_ptr.

Referenced by event(), and tcp_socket_send_str().

int tcp_socket_send_str	(	struct tcp_socket *	s,
		const char *	strptr
	)

Send a string on a connected TCP socket.

Parameters

s	A pointer to a TCP socket that must have been previously registered with tcp_socket_register()
strptr	A pointer to the string to be sent

Return values

-1	If an error occurs

Returns

The number of bytes that were successfully sent

        This is a convenience function for sending strings on a
        TCP socket. The function calls 

() to send the string.

References tcp_socket_send().

Referenced by event().

int tcp_socket_unlisten

(

struct tcp_socket *

s

)

Stop listening for new connections.

Parameters

s	A pointer to a TCP socket that must have been previously registered with tcp_socket_register()

Return values

-1	If an error occurs
1	If the operation succeeds. This function causes a listening TCP socket to stop listen. The socket must previously been put into listen mode with tcp_socket_listen().

References tcp_socket::flags, tcp_socket::listen_port, NULL, PROCESS_CONTEXT_BEGIN, PROCESS_CONTEXT_END, TCP_SOCKET_FLAGS_LISTENING, tcp_unlisten(), and uip_htons().

Referenced by tcp_socket_unregister().

int tcp_socket_unregister

(

struct tcp_socket *

s

)

Unregister a registered socket.

Parameters

s	A pointer to a TCP socket that must have been previously registered with tcp_socket_register()

Return values

-1	If an error occurs
1	If the operation succeeds. This function unregisters a previously registered socket. This must be done if the process will be unloaded from memory. If the TCP socket is connected, the connection will be reset.

References tcp_socket::c, list_remove(), NULL, tcp_attach(), and tcp_socket_unlisten().