api_lib.c File Reference

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)
enum netconn_type	netconn_type (struct netconn *conn)
err_t	netconn_getaddr (struct netconn *conn, struct ip_addr *addr, u16_t *port, u8_t local)
err_t	netconn_bind (struct netconn *conn, struct ip_addr *addr, u16_t port)
err_t	netconn_connect (struct netconn *conn, struct ip_addr *addr, u16_t port)
err_t	netconn_disconnect (struct netconn *conn)
err_t	netconn_listen_with_backlog (struct netconn *conn, u8_t backlog)
struct netconn *	netconn_accept (struct netconn *conn)
struct netbuf *	netconn_recv (struct netconn *conn)
err_t	netconn_sendto (struct netconn *conn, struct netbuf *buf, struct ip_addr *addr, u16_t port)
err_t	netconn_send (struct netconn *conn, struct netbuf *buf)
err_t	netconn_write (struct netconn *conn, const void *dataptr, int size, u8_t apiflags)
err_t	netconn_close (struct netconn *conn)
err_t	netconn_join_leave_group (struct netconn *conn, struct ip_addr *multiaddr, struct ip_addr *interface, enum netconn_igmp join_or_leave)
err_t	netconn_gethostbyname (const char *name, struct ip_addr *addr)

---

Detailed Description

Sequential API External module

---

Function Documentation

struct netconn* netconn_accept

(

struct netconn *

conn

)

[read]

Accept a new connection on a TCP listening netconn.

Parameters:

conn

the TCP listen netconn

Returns:

the newly accepted netconn or NULL on timeout

err_t netconn_bind	(	struct netconn *	conn,
		struct ip_addr *	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

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

err_t netconn_connect	(	struct netconn *	conn,
		struct ip_addr *	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

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

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

err_t netconn_getaddr	(	struct netconn *	conn,
		struct ip_addr *	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

err_t netconn_gethostbyname	(	const char *	name,
		struct ip_addr *	addr
	)

Execute a DNS query, only one IP address is returned

Parameters:

	name	a string representation of the DNS host name to query
	addr	a preallocated struct ip_addr where to store the resolved IP address

Returns:

ERR_OK: resolving succeeded ERR_MEM: memory error, try again later ERR_ARG: dns client not initialized or invalid hostname ERR_VAL: dns server response was invalid

err_t netconn_join_leave_group	(	struct netconn *	conn,
		struct ip_addr *	multiaddr,
		struct ip_addr *	interface,
		enum netconn_igmp	join_or_leave
	)

Join multicast groups for UDP netconns.

Parameters:

	conn	the UDP netconn for which to change multicast addresses
	multiaddr	IP address of the multicast group to join or leave
	interface	the IP address of the network interface on which to send the igmp message
	join_or_leave	flag whether to send a join- or leave-message

Returns:

ERR_OK if the action was taken, any err_t on error

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?))

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

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

struct netbuf* netconn_recv

(

struct netconn *

conn

)

[read]

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

Parameters:

conn

the netconn from which to receive data

Returns:

a new netbuf containing received data or NULL on memory error or timeout

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

err_t netconn_sendto	(	struct netconn *	conn,
		struct netbuf *	buf,
		struct ip_addr *	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

enum netconn_type netconn_type

(

struct netconn *

conn

)

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

Parameters:

conn

the netconn of which to get the type

Returns:

the netconn_type of conn

err_t netconn_write	(	struct netconn *	conn,
		const void *	dataptr,
		int	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 (0x01) data will be copied into memory belonging to the stack NETCONN_MORE (0x02) for TCP connection, PSH flag will be set on last segment sent

Returns:

ERR_OK if data was sent, any other err_t on error

---