{"action":"created","issue":{"url":"https://api.github.com/repos/RIOT-OS/RIOT/issues/5091","repository_url":"https://api.github.com/repos/RIOT-OS/RIOT","labels_url":"https://api.github.com/repos/RIOT-OS/RIOT/issues/5091/labels{/name}","comments_url":"https://api.github.com/repos/RIOT-OS/RIOT/issues/5091/comments","events_url":"https://api.github.com/repos/RIOT-OS/RIOT/issues/5091/events","html_url":"https://github.com/RIOT-OS/RIOT/issues/5091","id":141259967,"number":5091,"title":"conn: Reworking the conn API","user":{"login":"authmillenon","id":675644,"avatar_url":"https://avatars.githubusercontent.com/u/675644?v=3","gravatar_id":"","url":"https://api.github.com/users/authmillenon","html_url":"https://github.com/authmillenon","followers_url":"https://api.github.com/users/authmillenon/followers","following_url":"https://api.github.com/users/authmillenon/following{/other_user}","gists_url":"https://api.github.com/users/authmillenon/gists{/gist_id}","starred_url":"https://api.github.com/users/authmillenon/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/authmillenon/subscriptions","organizations_url":"https://api.github.com/users/authmillenon/orgs","repos_url":"https://api.github.com/users/authmillenon/repos","events_url":"https://api.github.com/users/authmillenon/events{/privacy}","received_events_url":"https://api.github.com/users/authmillenon/received_events","type":"User","site_admin":false},"labels":[{"url":"https://api.github.com/repos/RIOT-OS/RIOT/labels/network","name":"network","color":"8f00cc"},{"url":"https://api.github.com/repos/RIOT-OS/RIOT/labels/Request%20for%20Comments","name":"Request for Comments","color":"23F823"}],"state":"open","locked":false,"assignee":{"login":"kaspar030","id":4679640,"avatar_url":"https://avatars.githubusercontent.com/u/4679640?v=3","gravatar_id":"","url":"https://api.github.com/users/kaspar030","html_url":"https://github.com/kaspar030","followers_url":"https://api.github.com/users/kaspar030/followers","following_url":"https://api.github.com/users/kaspar030/following{/other_user}","gists_url":"https://api.github.com/users/kaspar030/gists{/gist_id}","starred_url":"https://api.github.com/users/kaspar030/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/kaspar030/subscriptions","organizations_url":"https://api.github.com/users/kaspar030/orgs","repos_url":"https://api.github.com/users/kaspar030/repos","events_url":"https://api.github.com/users/kaspar030/events{/privacy}","received_events_url":"https://api.github.com/users/kaspar030/received_events","type":"User","site_admin":false},"milestone":null,"comments":8,"created_at":"2016-03-16T12:34:39Z","updated_at":"2016-03-16T15:20:50Z","closed_at":null,"body":"# Motivation\r\n\r\nAfter 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 (https://github.com/RIOT-OS/RIOT/pull/3921, https://github.com/RIOT-OS/RIOT/pull/4630, https://github.com/RIOT-OS/RIOT/pull/4631).\r\n\r\n# The API\r\n\r\nAs an example I use `conn_udp`, since it is pretty similar to `conn_ip` (just replace `uint16_t port` with `uint8_t proto` ;-)):\r\n\r\n```C\r\n#include \"net/af.h\"\r\n\r\ntypedef struct conn_udp conn_udp_t;\r\ntypedef void (*conn_udp_recv_cb_t)(conn_t *conn, void *data, size_t data_len,\r\n                                   void *addr, uint16_t port);\r\n\r\nint conn_udp_create(conn_udp_t *conn, af_t family,\r\n                    conn_udp_recv_cb_t *recv_cb);\r\nint conn_udp_bind(conn_udp_t *conn, void *addr, uint16_t port);\r\nint conn_udp_getlocaladdr(conn_udp_t *conn, void *addr, uint16_t *port);\r\nint conn_udp_recvfrom(conn_udp_t *conn, void *data, size_t data_len,\r\n                      void *addr, uint16_t *port);\r\nint conn_udp_sendto(conn_udp_t *conn, void *data, size_t data_len,\r\n                    void *addr, uint16_t port);\r\n```\r\n\r\nMost of the stuff should be pretty self explanatory so I did not add doxygen for now (Just ask questions if anything is unclear).\r\n\r\n# Overview over changes\r\nThe major changes are:\r\n\r\n1. `addr_len` parameters were removed.\r\n2. `conn_udp_create()` receives a new callback parameter (an idea already proposed in https://github.com/RIOT-OS/RIOT/pull/4631)\r\n3. `conn_udp_bind()` is introduced (no implicit bind through `conn_udp_create()` anymore)\r\n4. `conn_udp_sendto()` needs a `conn` parameter now (as introduced in https://github.com/RIOT-OS/RIOT/pull/4630)\r\n\r\n# Discussion\r\n## Removal of address length parameters\r\n* For both UDP and IP the address family given to `conn_udp_create()` should be enough to identify the address length\r\n\r\n## Callback parameter on connection creation\r\n* Primary reasoning is to allow for asynchronous receiving of packets (and as such implementation of functionalities like `select()` or `epoll()` in the POSIX layer)\r\n* A timeout for reception (as proposed in https://github.com/RIOT-OS/RIOT/pull/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`\r\n\r\n## No implicit bind on creation\r\n* A bind to an address is not always needed or desired (for example to send) so forcing it on creation is undesirable\r\n\r\n## `conn` parameter on sendto\r\n* simplifies server implementation (see example given in #4630)\r\n* most stack implementation as emb6 or lwIP require some kind connection object for sending\r\n   - following from this you need to create a connection in `sendto` (making this API not thin anymore)\r\n   - 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\r\n   - both stack and users are able keep track of open \"connections\""},"comment":{"url":"https://api.github.com/repos/RIOT-OS/RIOT/issues/comments/197379593","html_url":"https://github.com/RIOT-OS/RIOT/issues/5091#issuecomment-197379593","issue_url":"https://api.github.com/repos/RIOT-OS/RIOT/issues/5091","id":197379593,"user":{"login":"kaspar030","id":4679640,"avatar_url":"https://avatars.githubusercontent.com/u/4679640?v=3","gravatar_id":"","url":"https://api.github.com/users/kaspar030","html_url":"https://github.com/kaspar030","followers_url":"https://api.github.com/users/kaspar030/followers","following_url":"https://api.github.com/users/kaspar030/following{/other_user}","gists_url":"https://api.github.com/users/kaspar030/gists{/gist_id}","starred_url":"https://api.github.com/users/kaspar030/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/kaspar030/subscriptions","organizations_url":"https://api.github.com/users/kaspar030/orgs","repos_url":"https://api.github.com/users/kaspar030/repos","events_url":"https://api.github.com/users/kaspar030/events{/privacy}","received_events_url":"https://api.github.com/users/kaspar030/received_events","type":"User","site_admin":false},"created_at":"2016-03-16T15:20:50Z","updated_at":"2016-03-16T15:20:50Z","body":">> For sending, no object should be needed.\r\n> \r\n> Then look into my lwip_conn_udp, please and tell me how I prevent the need for it.\r\n\r\nWhy should it be needed? If the specified \"src_port\" is bound without sth like \"O_REUSEADDR\", the send fails with an error.\r\n\r\n>> And, there is no need for a seperate bind.\r\n> \r\n> Why?\r\n\r\nWhy is it needed?\r\n"}}