Application Layer API Meeting on August 17, 2016

Agenda

1. Agenda Bashing
2. Goals and Priorities
3. Naming of the API
4. Detailed API-discussion:
   1. IP-based transport layer with datagram-based communication (IP raw / UDP)
   2. IP-based transport layer with sequence-based communication (TCP)
5. Future extension
   1. Asynchronous event handling: External vs. native support
   2. Options
   3. Per packet configuration

Meeting Details

Attendees

• Alexander Aring [eintopf]
• Cenk Gündoghan
• Kaspar Schleiser
• Martine Lenders (Chair)
• Peter Kietzmann
• Simon Brummer

Protocol

• Peter
• Simon

Goals / Priorities

1. No need for dynamic memory allocation
2. User friendliness
3. Simplicity
4. Efficiency (at both front- and backend)
5. Easy to implement for network stacks / portability

Naming of the API

• Pro `conn:
  • Name was picked to differ from the old sockets because it isn't socket
• Con conn:
  • conn basically behaves like sockets (just look at the function-calls)
  • New-comers might search for "something like sockets" anyway
  • Name change would show API change better and ultimately would be less confusing for users of conn
• Result: sock as name for the new API
• Side discussion: Documenting API changes
  • Wiki does not work, because it is forgotten after creation
  • Documentation via a dedicated README file is better

Detailed API-discussion

IP-based transport layer with datagram-based communication (IP raw / UDP)

• Reference API
• sock_udp_create/sock_udp_close good as is
• Getter (sock_udp_get_local/sock_udp_get_remote) stay because they don't hurt and are needed for socket wrapper implementation
• Setter: easier and more convenient to create new sock instead
• sock_udp_recv and sock_udp_recvfrom:
  • Order of parameters of sock_udp_recvfrom confusing with that name
  • Static inline in API definition not nice
  • Result:
    • original sock_udp_recv should be removed
    • sock_udp_recvfrom renamed to sock_udp_recv
• sock_udp_send and sock_udp_sendto:
  • There are three sensible use-cases for sock_udp_sendto
    1. sock != NULL, sock is connected, and remote == NULL
    2. sock != NULL, sock is connected, and remote != NULL
    3. sock == NULL and remote != NULL
  • Currently only convenient function for 1., why not for 3.?
  • Also again: static inline in API definition
  • Result:
    • original sock_udp_send should be removed
    • sock_udp_sendto renamed to sock_udp_send

IP-based transport layer with sequence-based communication (TCP)

• Reference API
• Simon wants a sock_tcp_listen function
• Kaspar: two object types required
  • One representing a connection,
  • One representing a listening socket
  • split sock_tcp_create and sock_tcp_close:

/* Connections:
 * (Only port required for local; and even that only in special cases) */
sock_tcp_connect(sock_tcp_t *sock, sock_tcp_ep_t *remote, uint16_t local_port);
sock_tcp_disconnect(sock_tcp_t *sock);

/* Listening Socket / Queue */
sock_tcp_listen(sock_tcp_queue_t *queue, sock_tcp_ep_t *local,
                sock_tcp_t[] queue_array, unsigned queue_len);
sock_tcp_stop_listen(sock_tcp_queue_t *queue);

• later additions: something like tcp_listen_dynamic, as as passing the whole queue as parameter is not suitable for servers with lots of RAM (portability)
• sock_tcp_accept needs adaptation to new object types: sock_tcp_accept(sock_tcp_queue_t *queue, sock_tcp_t **sock)
• rename sock_tcp_send/_recv to sock_tcp_write/_read; better suitable to semantics of streams

Future extension

Asynchronous event handling: External vs. native support

5.1 Asynchronous event handling: External vs. native support

• Callbacks due to questionable context not suitable
• Additional functions for external async event handling are moved to later discussion.

Options

• getter/setter functions added later
• options before bind might need additional parameters for create function
  • only option thinkable at the moment is something like SO_REUSEADDR
  • solvable by flag field in create function

Per packet configuration

• datagram-based stuff needs per packet configuration option (checksum, etc because 6Lo-NHC)
• for now, no decision
• possible solutions:
  • could be solved with options setting before sending
  • message based send as proposed in RFC 3542