api_lib.c File Reference

Sequential API External module.

#include "lwip/opt.h"
#include "lwip/api.h"
#include "lwip/tcpip.h"
#include "lwip/memp.h"
#include "lwip/ip.h"
#include "lwip/raw.h"
#include "lwip/udp.h"
#include "lwip/tcp.h"
#include <string.h>

Functions
err_t	netconn_accept (struct netconn *conn, struct netconn **new_conn)
	Accept a new connection on a TCP listening netconn. More...
err_t	netconn_bind (struct netconn *conn, ip_addr_t *addr, u16_t port)
	Bind a netconn to a specific local IP address and port. More...
err_t	netconn_close (struct netconn *conn)
	Close a TCP netconn (doesn't delete it). More...
static err_t	netconn_close_shutdown (struct netconn *conn, u8_t how)
	Close ot shutdown a TCP netconn (doesn't delete it). More...
err_t	netconn_connect (struct netconn *conn, ip_addr_t *addr, u16_t port)
	Connect a netconn to a specific remote IP address and port. More...
err_t	netconn_delete (struct netconn *conn)
	Close a netconn 'connection' and free its resources. More...
err_t	netconn_disconnect (struct netconn *conn)
	Disconnect a netconn from its current peer (only valid for UDP netconns). More...
err_t	netconn_getaddr (struct netconn *conn, ip_addr_t *addr, u16_t *port, u8_t local)
	Get the local or remote IP address and port of a netconn. More...
err_t	netconn_listen_with_backlog (struct netconn *conn, u8_t backlog)
	Set a TCP netconn into listen mode. More...
struct netconn *	netconn_new_with_proto_and_callback (enum netconn_type t, u8_t proto, netconn_callback callback)
	Create a new netconn (of a specific type) that has a callback function. More...
err_t	netconn_recv (struct netconn *conn, struct netbuf **new_buf)
	Receive data (in form of a netbuf containing a packet buffer) from a netconn. More...
static err_t	netconn_recv_data (struct netconn *conn, void **new_buf)
	Receive data: actual implementation that doesn't care whether pbuf or netbuf is received. More...
err_t	netconn_recv_tcp_pbuf (struct netconn *conn, struct pbuf **new_buf)
	Receive data (in form of a pbuf) from a TCP netconn. More...
void	netconn_recved (struct netconn *conn, u32_t length)
	TCP: update the receive window: by calling this, the application tells the stack that it has processed data and is able to accept new data. More...
err_t	netconn_send (struct netconn *conn, struct netbuf *buf)
	Send data over a UDP or RAW netconn (that is already connected). More...
err_t	netconn_sendto (struct netconn *conn, struct netbuf *buf, ip_addr_t *addr, u16_t port)
	Send data (in form of a netbuf) to a specific remote IP address and port. More...
err_t	netconn_shutdown (struct netconn *conn, u8_t shut_rx, u8_t shut_tx)
	Shut down one or both sides of a TCP netconn (doesn't delete it). More...
err_t	netconn_write (struct netconn *conn, const void *dataptr, size_t size, u8_t apiflags)
	Send data over a TCP netconn. More...

err_t netconn_accept	(	struct netconn *	conn,
		struct netconn **	new_conn
	)

Accept a new connection on a TCP listening netconn.

Parameters

conn	the TCP listen netconn
new_conn	pointer where the new connection is stored

Returns

ERR_OK if a new connection has been received or an error code otherwise

References netconn::acceptmbox, API_EVENT, api_msg_msg::conn, do_recv(), ERR_ABRT, ERR_ARG, ERR_IS_FATAL, ERR_OK, ERR_TIMEOUT, api_msg::function, netconn::last_err, LWIP_ERROR(), LWIP_UNUSED_ARG, api_msg::msg, NETCONN_EVT_RCVMINUS, NETCONN_SET_SAFE_ERR, NULL, sys_arch_mbox_fetch(), SYS_ARCH_TIMEOUT, sys_mbox_valid(), and TCPIP_APIMSG.

Referenced by lwip_accept(), and portTASK_FUNCTION().

err_t netconn_bind	(	struct netconn *	conn,
		ip_addr_t *	addr,
		u16_t	port
	)

Bind a netconn to a specific local IP address and port.

Binding one netconn twice might not always be checked correctly!

Parameters

conn	the netconn to bind
addr	the local IP address to bind the netconn to (use IP_ADDR_ANY to bind to all addresses)
port	the local port to bind the netconn to (not used for RAW)

Returns

ERR_OK if bound, any other err_t on failure

References api_msg_msg::bc, api_msg_msg::conn, do_bind(), ERR_ARG, api_msg::function, LWIP_ERROR(), api_msg_msg::msg, api_msg::msg, NETCONN_SET_SAFE_ERR, NULL, and TCPIP_APIMSG.

Referenced by lwip_bind(), and portTASK_FUNCTION().

err_t netconn_close

(

struct netconn *

conn

)

Close a TCP netconn (doesn't delete it).

Parameters

conn	the TCP netconn to close

Returns

ERR_OK if the netconn was closed, any other err_t on error

References netconn_close_shutdown(), and NETCONN_SHUT_RDWR.

Referenced by portTASK_FUNCTION().

static err_t netconn_close_shutdown ( struct netconn *  conn, u8_t  how  )

static

Close ot shutdown a TCP netconn (doesn't delete it).

Parameters

conn	the TCP netconn to close or shutdown
how	fully close or only shutdown one side?

Returns

ERR_OK if the netconn was closed, any other err_t on error

References api_msg_msg::conn, do_close(), ERR_ARG, api_msg::function, LWIP_ERROR(), api_msg_msg::msg, api_msg::msg, NETCONN_SET_SAFE_ERR, NULL, api_msg_msg::sd, and tcpip_apimsg().

Referenced by netconn_close(), and netconn_shutdown().

err_t netconn_connect	(	struct netconn *	conn,
		ip_addr_t *	addr,
		u16_t	port
	)

Connect a netconn to a specific remote IP address and port.

Parameters

conn	the netconn to connect
addr	the remote IP address to connect to
port	the remote port to connect to (no used for RAW)

Returns

ERR_OK if connected, return value of tcp_/udp_/raw_connect otherwise

References api_msg_msg::bc, api_msg_msg::conn, do_connect(), ERR_ARG, api_msg::function, LWIP_ERROR(), api_msg_msg::msg, api_msg::msg, NETCONN_SET_SAFE_ERR, NULL, and tcpip_apimsg().

Referenced by lwip_connect().

err_t netconn_delete

(

struct netconn *

conn

)

Close a netconn 'connection' and free its resources.

UDP and RAW connection are completely closed, TCP pcbs might still be in a waitstate after this returns.

Parameters

conn	the netconn to delete

Returns

ERR_OK if the connection was deleted

References api_msg_msg::conn, do_delconn(), ERR_OK, api_msg::function, api_msg::msg, netconn_free(), NULL, and tcpip_apimsg().

Referenced by lwip_accept(), lwip_close(), lwip_socket(), and portTASK_FUNCTION().

err_t netconn_disconnect

(

struct netconn *

conn

)

Disconnect a netconn from its current peer (only valid for UDP netconns).

Parameters

conn	the netconn to disconnect

Returns

TODO: return value is not set here...

References api_msg_msg::conn, do_disconnect(), ERR_ARG, api_msg::function, LWIP_ERROR(), api_msg::msg, NETCONN_SET_SAFE_ERR, NULL, and TCPIP_APIMSG.

Referenced by lwip_connect().

err_t netconn_getaddr	(	struct netconn *	conn,
		ip_addr_t *	addr,
		u16_t *	port,
		u8_t	local
	)

Get the local or remote IP address and port of a netconn.

For RAW netconns, this returns the protocol instead of a port!

Parameters

conn	the netconn to query
addr	a pointer to which to save the IP address
port	a pointer to which to save the port (or protocol for RAW)
local	1 to get the local IP address, 0 to get the remote one

Returns

ERR_CONN for invalid connections ERR_OK if the information was retrieved

References api_msg_msg::ad, api_msg_msg::conn, do_getaddr(), ERR_ARG, api_msg::function, LWIP_ERROR(), api_msg_msg::msg, api_msg::msg, NETCONN_SET_SAFE_ERR, NULL, and TCPIP_APIMSG.

Referenced by lwip_getaddrname(), and lwip_recvfrom().

err_t netconn_listen_with_backlog	(	struct netconn *	conn,
		u8_t	backlog
	)

Set a TCP netconn into listen mode.

Parameters

conn	the tcp netconn to set to listen mode
backlog	the listen backlog, only used if TCP_LISTEN_BACKLOG==1

Returns

ERR_OK if the netconn was set to listen (UDP and RAW netconns don't return any error (yet?))

References api_msg_msg::conn, do_listen(), ERR_ARG, api_msg::function, LWIP_ERROR(), LWIP_UNUSED_ARG, api_msg_msg::msg, api_msg::msg, NETCONN_SET_SAFE_ERR, NULL, and TCPIP_APIMSG.

Referenced by lwip_listen().

struct netconn* netconn_new_with_proto_and_callback	(	enum netconn_type	t,
		u8_t	proto,
		netconn_callback	callback
	)

Create a new netconn (of a specific type) that has a callback function.

The corresponding pcb is also created.

Parameters

t	the type of 'connection' to create (

See Also

enum netconn_type)

Parameters

proto	the IP protocol for RAW IP pcbs
callback	a function to call on status changes (RX available, TX'ed)

Returns

a newly allocated struct netconn or NULL on memory error

References api_msg_msg::conn, do_newconn(), ERR_OK, api_msg::function, LWIP_ASSERT, memp_free(), api_msg_msg::msg, api_msg::msg, api_msg_msg::n, netconn_alloc(), NULL, sys_mbox_free(), sys_mbox_valid(), sys_sem_free(), sys_sem_valid(), and TCPIP_APIMSG.

Referenced by lwip_socket().

err_t netconn_recv	(	struct netconn *	conn,
		struct netbuf **	new_buf
	)

Receive data (in form of a netbuf containing a packet buffer) from a netconn.

Parameters

conn	the netconn from which to receive data
new_buf	pointer where a new netbuf is stored when received data

Returns

ERR_OK if data has been received, an error code otherwise (timeout, memory error or another error)

References netbuf::addr, ERR_ARG, ERR_CONN, ERR_MEM, ERR_OK, ip_addr_set_any, LWIP_ASSERT, LWIP_ERROR(), memp_free(), memp_malloc(), netconn_recv_data(), NETCONN_SET_SAFE_ERR, NETCONN_TCP, NULL, netbuf::p, netbuf::port, netbuf::ptr, netconn::recvmbox, sys_mbox_valid(), and netconn::type.

Referenced by lwip_recvfrom(), and prvweb_ParseHTMLRequest().

static err_t netconn_recv_data ( struct netconn *  conn, void **  new_buf  )

static

Receive data: actual implementation that doesn't care whether pbuf or netbuf is received.

Parameters

conn	the netconn from which to receive data
new_buf	pointer where a new pbuf/netbuf is stored when received data

Returns

ERR_OK if data has been received, an error code otherwise (timeout, memory error or another error)

References API_EVENT, API_LIB_DEBUG, api_msg_msg::conn, do_recv(), ERR_ARG, ERR_CLSD, ERR_CONN, ERR_IS_FATAL, ERR_OK, ERR_TIMEOUT, api_msg::function, netconn::last_err, LWIP_ASSERT, LWIP_DEBUGF, LWIP_ERROR(), api_msg_msg::msg, api_msg::msg, netbuf_len, NETCONN_EVT_RCVMINUS, netconn_get_noautorecved, NETCONN_SET_SAFE_ERR, NETCONN_TCP, NULL, api_msg_msg::r, netconn::recvmbox, SYS_ARCH_DEC, sys_arch_mbox_fetch(), SYS_ARCH_TIMEOUT, sys_mbox_valid(), TCPIP_APIMSG, netconn::type, and U16_F.

Referenced by netconn_recv(), and netconn_recv_tcp_pbuf().

err_t netconn_recv_tcp_pbuf	(	struct netconn *	conn,
		struct pbuf **	new_buf
	)

Receive data (in form of a pbuf) from a TCP netconn.

Parameters

conn	the netconn from which to receive data
new_buf	pointer where a new pbuf is stored when received data

Returns

ERR_OK if data has been received, an error code otherwise (timeout, memory error or another error) ERR_ARG if conn is not a TCP netconn

References ERR_ARG, LWIP_ERROR(), netconn_recv_data(), NETCONN_TCP, and NULL.

Referenced by lwip_recvfrom().

void netconn_recved	(	struct netconn *	conn,
		u32_t	length
	)

TCP: update the receive window: by calling this, the application tells the stack that it has processed data and is able to accept new data.

ATTENTION: use with care, this is mainly used for sockets! Can only be used when calling netconn_set_noautorecved(conn, 1) before.

Parameters

conn	the netconn for which to update the receive window
length	amount of data processed (ATTENTION: this must be accurate!)

References api_msg_msg::conn, do_recv(), api_msg::function, LWIP_UNUSED_ARG, api_msg_msg::msg, api_msg::msg, netconn_get_noautorecved, NETCONN_TCP, NULL, api_msg_msg::r, TCPIP_APIMSG, and netconn::type.

Referenced by lwip_recvfrom().

err_t netconn_send	(	struct netconn *	conn,
		struct netbuf *	buf
	)

Send data over a UDP or RAW netconn (that is already connected).

Parameters

conn	the UDP or RAW netconn over which to send data
buf	a netbuf containing the data to send

Returns

ERR_OK if data was sent, any other err_t on error

References API_LIB_DEBUG, api_msg_msg::b, api_msg_msg::conn, do_send(), ERR_ARG, api_msg::function, LWIP_DEBUGF, LWIP_ERROR(), api_msg_msg::msg, api_msg::msg, NETCONN_SET_SAFE_ERR, NULL, netbuf::p, TCPIP_APIMSG, pbuf::tot_len, and U16_F.

Referenced by lwip_sendto(), and netconn_sendto().

err_t netconn_sendto	(	struct netconn *	conn,
		struct netbuf *	buf,
		ip_addr_t *	addr,
		u16_t	port
	)

Send data (in form of a netbuf) to a specific remote IP address and port.

Only to be used for UDP and RAW netconns (not TCP).

Parameters

conn	the netconn over which to send data
buf	a netbuf containing the data to send
addr	the remote IP address to which to send the data
port	the remote port to which to send the data

Returns

ERR_OK if data was sent, any other err_t on error

References netbuf::addr, ERR_VAL, ip_addr_set, netconn_send(), NULL, and netbuf::port.

err_t netconn_shutdown	(	struct netconn *	conn,
		u8_t	shut_rx,
		u8_t	shut_tx
	)

Shut down one or both sides of a TCP netconn (doesn't delete it).

Parameters

conn	the TCP netconn to shut down

Returns

ERR_OK if the netconn was closed, any other err_t on error

References netconn_close_shutdown(), NETCONN_SHUT_RD, and NETCONN_SHUT_WR.

Referenced by lwip_shutdown().

err_t netconn_write	(	struct netconn *	conn,
		const void *	dataptr,
		size_t	size,
		u8_t	apiflags
	)

Send data over a TCP netconn.

Parameters

conn	the TCP netconn over which to send data
dataptr	pointer to the application buffer that contains the data to send
size	size of the application data to send
apiflags	combination of following flags : NETCONN_COPY: data will be copied into memory belonging to the stack NETCONN_MORE: for TCP connection, PSH flag will be set on last segment sent NETCONN_DONTBLOCK: only write the data if all dat can be written at once

Returns

ERR_OK if data was sent, any other err_t on error

References api_msg_msg::conn, do_write(), ERR_ARG, ERR_OK, ERR_VAL, api_msg::function, LWIP_ERROR(), api_msg_msg::msg, api_msg::msg, NETCONN_SET_SAFE_ERR, NETCONN_TCP, NULL, TCPIP_APIMSG, netconn::type, and api_msg_msg::w.

Referenced by lwip_send(), prvweb_ParseCGIRequest(), prvweb_SendErrorPage(), and prvweb_SendFile().