Browse Source

gnrc.h: extend documentation

pr/spi.typo
Lotte Steenbrink 6 years ago
parent
commit
826282d9e1
  1. 46
      sys/include/net/gnrc.h

46
sys/include/net/gnrc.h

@ -144,9 +144,11 @@
* }
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*
* @note It is necessary to react with a reply message to the other thread for
* @ref GNRC_NETAPI_MSG_TYPE_SET and @ref GNRC_NETAPI_MSG_TYPE_GET
* commands
* @note When receiving a message of type @ref GNRC_NETAPI_MSG_TYPE_SET or
* @ref GNRC_NETAPI_MSG_TYPE_GET, it is necessary to acknowledge it by
* calling @ref msg_reply() with a message of type
* @ref GNRC_NETAPI_MSG_TYPE_ACK which contains the actual size of the
* GET message's content on success or an error code otherwise.
*
* @note Do not forget to unregister with @ref gnrc_netreg_unregister() if you
* leave the function
@ -155,11 +157,22 @@
* Transmitting Packets
* --------------------
*
* To relay the @ref net_gnrc_pkt to interested threads the @ref
* net_gnrc_netapi offers a dispatch functionality. The following example
* sketches the usage and assumes a valid @ref net_gnrc_pkt named `pkt`.
* A packet is transmitted by relaying it to threads interested in handling (and
* dispatching) packets of its type. To do this, the @ref net_gnrc_netapi
* offers dispatch helper functions called @ref gnrc_netapi_dispatch_send()
* and gnrc_netapi_dispatch_receive().
*
* The following example sketches the usage and assumes a valid @ref
* net_gnrc_pkt named `pkt`.
*
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ {.c}
* gnrc_pktsnip_t *pkt;
*
* pkt = gnrc_pktbuf_add(NULL, data, size, GNRC_NETTYPE_UNDEF);
* if (pkt == NULL) {
* puts("Error: unable to copy data to packet buffer\n");
* return;
* }
* if (!gnrc_netapi_dispatch_send(GNRC_NETTYPE_UDP, 80, pkt)) {
* puts("Error: no thread is interested");
* gnrc_pktbuf_release(pkt);
@ -167,14 +180,29 @@
* }
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*
* The @ref net_gnrc_pkt "pkt" will be send to all threads that registered for
* @ref GNRC_NETTYPE_UDP and the demux context `80`. Every registered thread
* First, the data to be sent is added to the @ref net_gnrc_pktbuf "packet buffer".
* This ensures its intactness during the sending process. After the data to be
* sent has been added to the packet buffer, its parent data structure can safely
* be freed or re-used.
*
* Then, the @ref net_gnrc_pkt "pkt" will be sent to all threads that registered
* for @ref GNRC_NETTYPE_UDP and the demux context `80`. Every registered thread
* will receive a @ref GNRC_NETAPI_MSG_TYPE_SND command and can access the @ref
* net_gnrc_pkt. If @ref gnrc_netapi_dispatch_send() is replaced by @ref
* net_gnrc_pkt. Note that at this point, the threads receiving pkt act as its
* owners, so please don't modify pkt after calling any dispatch function.
*
* If @ref gnrc_netapi_dispatch_send() is replaced by @ref
* gnrc_netapi_dispatch_receive() then threads will receive the @ref
* GNRC_NETAPI_MSG_TYPE_RCV command instead, again with access to the @ref
* net_gnrc_pkt.
*
* @note If the data to be sent requires extra headers to be added for successful
* transmission (in the example, this would be IP and UDP headers), these
* have to be built manually before calling @ref gnrc_netapi_dispatch_send().
* In the interest of conciseness, this is omitted in this tutorial;
* please refer to @ref gnrc_udp_hdr_build(), @ref gnrc_ipv6_hdr_build()
* etc. for more information.
*
* How To Use
* ==========
* @ref net_gnrc is highly modular and can be adjusted to include only the

Loading…
Cancel
Save