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

Macros
#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	API_EVENT(c, e, l)
#define	NETCONN_SET_SAFE_ERR(conn, err)
#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_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_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_tcp_pbuf (struct netconn *conn, struct pbuf **new_buf)
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_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_gethostbyname_addrtype (const char *name, ip_addr_t *addr, u8_t dns_addrtype)

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_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_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) { \
  (conn)->flags |= NETCONN_FLAG_NON_BLOCKING; \
} else { \
  (conn)->flags &= ~ 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_SAFE_ERR

#define NETCONN_SET_SAFE_ERR	(		conn,
			err
	)

Value:

do { if ((conn) != NULL) { \
  SYS_ARCH_DECL_PROTECT(netconn_set_safe_err_lev); \
  SYS_ARCH_PROTECT(netconn_set_safe_err_lev); \
  if (!ERR_IS_FATAL((conn)->last_err)) { \
    (conn)->last_err = err; \
  } \
  SYS_ARCH_UNPROTECT(netconn_set_safe_err_lev); \
}} while(0);

Set conn->last_err to err but don't overwrite fatal errors

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