Motivation

After I worked a little bit with other stacks and also had some feedback from the community I would like to propose a change to the conn API, especially to the connection-less part i.e. conn_ip and conn_udp (there is no implementation of conn_tcp yet anyway to my knowledge). Some of these changes are based on already existing PRs (#3921, #4630, #4631).

The API

As an example I use conn_udp, since it is pretty similar to conn_ip (just replace uint16_t port with uint8_t proto ;-)):

#include "net/af.h"

typedef struct conn_udp conn_udp_t;
typedef void (*conn_udp_recv_cb_t)(conn_t *conn, void *data, size_t data_len,
                                   void *addr, uint16_t port);

int conn_udp_create(conn_udp_t *conn, af_t family,
                    conn_udp_recv_cb_t *recv_cb);
int conn_udp_bind(conn_udp_t *conn, void *addr, uint16_t port);
int conn_udp_getlocaladdr(conn_udp_t *conn, void *addr, uint16_t *port);
int conn_udp_recvfrom(conn_udp_t *conn, void *data, size_t data_len,
                      void *addr, uint16_t *port);
int conn_udp_sendto(conn_udp_t *conn, void *data, size_t data_len,
                    void *addr, uint16_t port);

Most of the stuff should be pretty self explanatory so I did not add doxygen for now (Just ask questions if anything is unclear).

Overview over changes

The major changes are:

1. addr_len parameters were removed.
2. conn_udp_create() receives a new callback parameter (an idea already proposed in conn: provide API support for asynchronous IO #4631)
3. conn_udp_bind() is introduced (no implicit bind through conn_udp_create() anymore)
4. conn_udp_sendto() needs a conn parameter now (as introduced in conn: make conn_*_sendto require a conn object #4630)

Discussion

Removal of address length parameters

• For both UDP and IP the address family given to conn_udp_create() should be enough to identify the address length

Callback parameter on connection creation

• Primary reasoning is to allow for asynchronous receiving of packets (and as such implementation of functionalities like select() or epoll() in the POSIX layer)
• A timeout for reception (as proposed in conn: extend API with timeout support #3921) can also be implemented with such a callback. The advantage would be that this would be externally to this API, keeping this API thin and independent from other modules like xtimer

No implicit bind on creation

• A bind to an address is not always needed or desired (for example to send) so forcing it on creation is undesirable

conn parameter on sendto

• simplifies server implementation (see example given in conn: make conn_*_sendto require a conn object #4630)
• most stack implementation as emb6 or lwIP require some kind connection object for sending
  • following from this you need to create a connection in sendto (making this API not thin anymore)
  • both emb6 and lwIP check if a port is already open => sending and receiving from the same port is impossible in the current conn API with those stacks
  • both stack and users are able keep track of open "connections"