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_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

NETCONN_FLAG_NON_BLOCKING
#define NETCONN_FLAG_NON_BLOCKING
Definition: api.h:73