api.h File Reference

#include "lwip/opt.h"
#include "lwip/arch.h"
#include "lwip/netbuf.h"
#include "lwip/sys.h"
#include "lwip/ip_addr.h"
#include "lwip/err.h"

Data Structures
struct	netconn
struct	netvector

Macros
#define	NETCONN_FLAG_MBOXCLOSED   0x01
#define	NETCONN_FLAG_NON_BLOCKING   0x02
#define	NETCONN_FLAG_IN_NONBLOCKING_CONNECT   0x04
#define	NETCONN_FLAG_CHECK_WRITESPACE   0x10
#define	NETCONN_FLAG_IPV6_V6ONLY   0x20
#define	NETCONN_FIN_RX_PENDING   0x80
#define	API_EVENT(c, e, l)
#define	netconn_new(t)   netconn_new_with_proto_and_callback(t, 0, NULL)
#define	netconn_type(conn)   (conn->type)
#define	netconn_peer(c, i, p)   netconn_getaddr(c,i,p,0)
#define	netconn_addr(c, i, p)   netconn_getaddr(c,i,p,1)
#define	netconn_listen(conn)   netconn_listen_with_backlog(conn, TCP_DEFAULT_LISTEN_BACKLOG)
#define	netconn_write(conn, dataptr, size, apiflags)   netconn_write_partly(conn, dataptr, size, apiflags, NULL)
#define	netconn_set_nonblocking(conn, val)
#define	netconn_is_nonblocking(conn)   (((conn)->flags & NETCONN_FLAG_NON_BLOCKING) != 0)
#define	netconn_set_ipv6only(conn, val)
#define	netconn_get_ipv6only(conn)   (((conn)->flags & NETCONN_FLAG_IPV6_V6ONLY) != 0)
#define	netconn_set_sendtimeout(conn, timeout)   ((conn)->send_timeout = (timeout))
#define	netconn_get_sendtimeout(conn)   ((conn)->send_timeout)
#define	netconn_set_recvbufsize(conn, recvbufsize)   ((conn)->recv_bufsize = (recvbufsize))
#define	netconn_get_recvbufsize(conn)   ((conn)->recv_bufsize)

Typedefs
typedef void(*	netconn_callback) (struct netconn *, enum netconn_evt, u16_t len)

Enumerations
enum	netconn_type { ,   NETCONN_TCP = 0x10, NETCONN_TCP_IPV6 = NETCONN_TCP | 0x08, NETCONN_UDP = 0x20, NETCONN_UDPLITE = 0x21,   NETCONN_UDPNOCHKSUM = 0x22, NETCONN_UDP_IPV6 = NETCONN_UDP | 0x08, NETCONN_UDPLITE_IPV6 = NETCONN_UDPLITE | 0x08, NETCONN_UDPNOCHKSUM_IPV6 = NETCONN_UDPNOCHKSUM | 0x08,   NETCONN_RAW = 0x40 }
enum	netconn_state
enum	netconn_evt
enum	netconn_igmp

Functions
struct netconn *	netconn_new_with_proto_and_callback (enum netconn_type t, u8_t proto, netconn_callback callback)
err_t	netconn_prepare_delete (struct netconn *conn)
err_t	netconn_delete (struct netconn *conn)
err_t	netconn_getaddr (struct netconn *conn, ip_addr_t *addr, u16_t *port, u8_t local)
err_t	netconn_bind (struct netconn *conn, const ip_addr_t *addr, u16_t port)
err_t	netconn_bind_if (struct netconn *conn, u8_t if_idx)
err_t	netconn_connect (struct netconn *conn, const ip_addr_t *addr, u16_t port)
err_t	netconn_disconnect (struct netconn *conn)
err_t	netconn_listen_with_backlog (struct netconn *conn, u8_t backlog)
err_t	netconn_accept (struct netconn *conn, struct netconn **new_conn)
err_t	netconn_recv (struct netconn *conn, struct netbuf **new_buf)
err_t	netconn_recv_udp_raw_netbuf (struct netconn *conn, struct netbuf **new_buf)
err_t	netconn_recv_udp_raw_netbuf_flags (struct netconn *conn, struct netbuf **new_buf, u8_t apiflags)
err_t	netconn_recv_tcp_pbuf (struct netconn *conn, struct pbuf **new_buf)
err_t	netconn_recv_tcp_pbuf_flags (struct netconn *conn, struct pbuf **new_buf, u8_t apiflags)
err_t	netconn_sendto (struct netconn *conn, struct netbuf *buf, const ip_addr_t *addr, u16_t port)
err_t	netconn_send (struct netconn *conn, struct netbuf *buf)
err_t	netconn_write_partly (struct netconn *conn, const void *dataptr, size_t size, u8_t apiflags, size_t *bytes_written)
err_t	netconn_write_vectors_partly (struct netconn *conn, struct netvector *vectors, u16_t vectorcnt, u8_t apiflags, size_t *bytes_written)
err_t	netconn_close (struct netconn *conn)
err_t	netconn_shutdown (struct netconn *conn, u8_t shut_rx, u8_t shut_tx)
err_t	netconn_join_leave_group (struct netconn *conn, const ip_addr_t *multiaddr, const ip_addr_t *netif_addr, enum netconn_igmp join_or_leave)
err_t	netconn_join_leave_group_netif (struct netconn *conn, const ip_addr_t *multiaddr, u8_t if_idx, enum netconn_igmp join_or_leave)
err_t	netconn_gethostbyname_addrtype (const char *name, ip_addr_t *addr, u8_t dns_addrtype)
err_t	netconn_err (struct netconn *conn)

Detailed Description

netconn API (to be used from non-TCPIP threads)

Macro Definition Documentation

API_EVENT

#define API_EVENT	(		c,
			e,
			l
	)

Value:

if (c->callback) {         \
                           (*c->callback)(c, e, l); \
                         }

Register an Network connection event

NETCONN_FIN_RX_PENDING

#define NETCONN_FIN_RX_PENDING   0x80

A FIN has been received but not passed to the application yet

NETCONN_FLAG_CHECK_WRITESPACE

#define NETCONN_FLAG_CHECK_WRITESPACE   0x10

If a nonblocking write has been rejected before, poll_tcp needs to check if the netconn is writable again

NETCONN_FLAG_IN_NONBLOCKING_CONNECT

#define NETCONN_FLAG_IN_NONBLOCKING_CONNECT   0x04

Was the last connect action a non-blocking one?

NETCONN_FLAG_IPV6_V6ONLY

#define NETCONN_FLAG_IPV6_V6ONLY   0x20

If this flag is set then only IPv6 communication is allowed on the netconn. As per RFC#3493 this features defaults to OFF allowing dual-stack usage by default.

NETCONN_FLAG_MBOXCLOSED

#define NETCONN_FLAG_MBOXCLOSED   0x01

This netconn had an error, don't block on recvmbox/acceptmbox any more

NETCONN_FLAG_NON_BLOCKING

#define NETCONN_FLAG_NON_BLOCKING   0x02

Should this netconn avoid blocking?

netconn_get_recvbufsize

#define netconn_get_recvbufsize

(

conn

)

((conn)->recv_bufsize)

Get the receive buffer in bytes

netconn_get_sendtimeout

#define netconn_get_sendtimeout

(

conn

)

((conn)->send_timeout)

Get the send timeout in milliseconds

netconn_is_nonblocking

#define netconn_is_nonblocking

(

conn

)

(((conn)->flags & NETCONN_FLAG_NON_BLOCKING) != 0)

Get the blocking status of netconn calls (

netconn_set_nonblocking

#define netconn_set_nonblocking	(		conn,
			val
	)

Value:

do { if(val) { \
  netconn_set_flags(conn, NETCONN_FLAG_NON_BLOCKING); \
} else { \
  netconn_clear_flags(conn, NETCONN_FLAG_NON_BLOCKING); }} while(0)

Set the blocking status of netconn calls (

netconn_set_recvbufsize

#define netconn_set_recvbufsize	(		conn,
			recvbufsize
	)		((conn)->recv_bufsize = (recvbufsize))

Set the receive buffer in bytes

netconn_set_sendtimeout

#define netconn_set_sendtimeout	(		conn,
			timeout
	)		((conn)->send_timeout = (timeout))

Set the send timeout in milliseconds

netconn_type

#define netconn_type

(

conn

)

(conn->type)

Get the type of a netconn (as enum netconn_type).

Typedef Documentation

netconn_callback

typedef void(* netconn_callback) (struct netconn *, enum netconn_evt, u16_t len)

A callback prototype to inform about events for a netconn

Enumeration Type Documentation

netconn_evt

enum netconn_evt

Used to inform the callback function about changes

Event explanation:

In the netconn implementation, there are three ways to block a client:

• accept mbox (sys_arch_mbox_fetch(&conn->acceptmbox, &accept_ptr, 0); in netconn_accept())
• receive mbox (sys_arch_mbox_fetch(&conn->recvmbox, &buf, 0); in netconn_recv_data())
• send queue is full (sys_arch_sem_wait(LWIP_API_MSG_SEM(msg), 0); in lwip_netconn_do_write())

The events have to be seen as events signaling the state of these mboxes/semaphores. For non-blocking connections, you need to know in advance whether a call to a netconn function call would block or not, and these events tell you about that.

RCVPLUS events say: Safe to perform a potentially blocking call call once more. They are counted in sockets - three RCVPLUS events for accept mbox means you are safe to call netconn_accept 3 times without being blocked. Same thing for receive mbox.

RCVMINUS events say: Your call to to a possibly blocking function is "acknowledged". Socket implementation decrements the counter.

For TX, there is no need to count, its merely a flag. SENDPLUS means you may send something. SENDPLUS occurs when enough data was delivered to peer so netconn_send() can be called again. A SENDMINUS event occurs when the next call to a netconn_send() would be blocking.

netconn_igmp

enum netconn_igmp

Used for netconn_join_leave_group()

netconn_state

enum netconn_state

Current state of the netconn. Non-TCP netconns are always in state NETCONN_NONE!

Function Documentation

netconn_getaddr()

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

netconn_new_with_proto_and_callback()

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

netconn_recv_udp_raw_netbuf()

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

Receive data (in form of a netbuf) from a UDP or RAW 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) ERR_ARG if conn is not a UDP/RAW netconn

netconn_recv_udp_raw_netbuf_flags()

err_t netconn_recv_udp_raw_netbuf_flags	(	struct netconn *	conn,
		struct netbuf **	new_buf,
		u8_t	apiflags
	)

Receive data (in form of a netbuf) from a UDP or RAW netconn

Parameters

conn	the netconn from which to receive data
new_buf	pointer where a new netbuf is stored when received data
apiflags	flags that control function behaviour. For now only: NETCONN_DONTBLOCK: only read data that is available now, don't wait for more 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 UDP/RAW netconn

netconn_write_vectors_partly()

err_t netconn_write_vectors_partly	(	struct netconn *	conn,
		struct netvector *	vectors,
		u16_t	vectorcnt,
		u8_t	apiflags,
		size_t *	bytes_written
	)

Send vectorized data atomically over a TCP netconn.

Parameters

conn	the TCP netconn over which to send data
vectors	array of vectors containing data to send
vectorcnt	number of vectors in the array
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 data can be written at once
bytes_written	pointer to a location that receives the number of written bytes

Returns

ERR_OK if data was sent, any other err_t on error