<commit_before>/*
 * Copyright (c) 2015-2017 <NAME>. All rights reserved.
 *               2017 Freie Universität Berlin
 *
 * This file is subject to the terms and conditions of the GNU Lesser
 * General Public License v2.1. See the file LICENSE in the top level
 * directory for more details.
 */

/**
 * @defgroup    net_gcoap  Gcoap
 * @ingroup     net
 * @brief       High-level interface to CoAP messaging
 *
 * gcoap provides a high-level interface for writing CoAP messages via RIOT's
 * sock networking API. gcoap internalizes network event processing so an
 * application only needs to focus on request/response handling. For a server,
 * gcoap accepts a list of resource paths with callbacks for writing the
 * response. For a client, gcoap provides a function to send a request, with a
 * callback for reading the server response.
 *
 * gcoap allocates a RIOT message processing thread, so a single instance can
 * serve multiple applications. This approach also means gcoap uses a single UDP
 * port, which supports RFC 6282 compression. Internally, gcoap depends on the
 * nanocoap package for base level structs and functionality.
 *
 * gcoap also supports the Observe extension (RFC 7641) for a server. gcoap
 * provides functions to generate and send an observe notification that are
 * similar to the functions to send a client request.
 *
 * *Contents*
 *
 * - Server Operation
 * - Client Operation
 * - Observe Server Operation
 * - Implementation Notes
 * - Implementation Status
 *
 * ## Server Operation ##
 *
 * gcoap listens for requests on GCOAP_PORT, 5683 by default. You can redefine
 * this by uncommenting the appropriate lines in gcoap's make file.
 *
 * gcoap allows an application to specify a collection of request resource paths
 * it wants to be notified about. Create an array of resources (coap_resource_t
 * structs) ordered by the resource path, specifically the ASCII encoding of
 * the path characters (digit and capital precede lower case). Use
 * gcoap_register_listener() at application startup to pass in these resources,
 * wrapped in a gcoap_listener_t. Also see _Server path matching_ in the base
 * [nanocoap](group__net__nanocoap.html) documentation.
 *
 * gcoap itself defines a resource for `/.well-known/core` discovery, which
 * lists all of the registered paths. See the _Resource list creation_ section
 * below for more.
 *
 * ### Creating a response ###
 *
 * An application resource includes a callback function, a coap_handler_t. After
 * reading the request, the callback must use functions provided by gcoap to
 * format the response, as described below. The callback *must* read the request
 * thoroughly before calling the functions, because the response buffer likely
 * reuses the request buffer. See `examples/gcoap/gcoap_cli.c` for a simple
 * example of a callback.
 *
 * Here is the expected sequence for a callback function:
 *
 * Read request completely and parse request payload, if any. Use the
 * coap_pkt_t _payload_ and _payload_len_ attributes.
 *
 * If there is a payload, follow the steps below.
 *
 * -# Call gcoap_resp_init() to initialize the response.
 * -# Use the coap_opt_add_xxx() functions to include any Options, for example
 *    coap_opt_add_format() for Content-Format of the payload.
 * -# Call coap_opt_finish() to complete the PDU metadata. Retain the returned
 *    metadata length.
 * -# Write the response payload, starting at the updated _payload_ pointer
 *    in the coap_pkt_t, for up to _payload_len_ bytes.
 * -# Return the sum of the metadata length and payload length. If some error
 *    has occurred, return a negative errno code from the handler, and gcoap
 *    will send a server error (5.00).
 *
 * If no payload, call only gcoap_response() to write the full response. If you
 * need to add Options, follow the first three steps in the list above instead.
 *
 * ### Resource list creation ###
 *
 * gcoap allows customization of the function that provides the list of registered
 * resources for `/.well-known/core` and CoRE Resource Directory registration.
 * By default gcoap provides gcoap_encode_link(), which lists only the target
 * path for each link. However, an application may specify a custom function in
 * the gcoap_listener_t it registers with gcoap. For example, this function may
 * add parameters to provide more information about the resource, as described
 * in RFC 6690. See the gcoap example for use of a custom encoder function.
 *
 * ## Client Operation ##
 *
 * Client operation includes two phases: creating and sending a request, and
 * handling the response aynchronously in a client supplied callback. See
 * `examples/gcoap/gcoap_cli.c` for a simple example of sending a request and
 * reading the response.
 *
 * ### Creating a request ###
 *
 * Here is the expected sequence to prepare and send a request:
 *
 * Allocate a buffer and a coap_pkt_t for the request.
 *
 * If there is a payload, follow the steps below.
 *
 * -# Call gcoap_req_init() to initialize the request.
 * -# Optionally, mark the request confirmable by calling coap_hdr_set_type()
 *    with COAP_TYPE_CON.
 * -# Use the coap_opt_add_xxx() functions to include any Options beyond
 *    Uri-Path, which was added in the first step.
 * -# Call coap_opt_finish() to complete the PDU metadata. Retain the returned
 *    metadata length.
 * -# Write the request payload, starting at the updated _payload_ pointer
 *    in the coap_pkt_t, for up to _payload_len_ bytes.
 *
 * If no payload, call only gcoap_request() to write the full request. If you
 * need to add Options, follow the first four steps in the list above instead.
 *
 * Finally, call gcoap_req_send() with the sum of the metadata length and
 * payload length, the destination endpoint, and a callback function for the
 * host's response.
 *
 * ### Handling the response ###
 *
 * When gcoap receives the response to a request, it executes the callback from
 * the request. gcoap also executes the callback when a response is not
 * received within GCOAP_RESPONSE_TIMEOUT.
 *
 * Here is the expected sequence for handling a response in the callback.
 *
 * -# Test for a server response or timeout in the _req_state_ callback
 *    parameter. See the GCOAP_MEMO... constants.
 * -# Test the response with coap_get_code_class() and coap_get_code_detail().
 * -# Test the response payload with the coap_pkt_t _payload_len_ and
 *    _content_type_ attributes.
 * -# Read the payload, if any.
 *
 * ## Observe Server Operation
 *
 * A CoAP client may register for Observe notifications for any resource that
 * an application has registered with gcoap. An application does not need to
 * take any action to support Observe client registration. However, gcoap
 * limits registration for a given resource to a _single_ observer.
 *
 * An Observe notification is considered a response to the original client
 * registration request. So, the Observe server only needs to create and send
 * the notification -- no further communication or callbacks are required.
 *
 * ### Creating a notification ###
 *
 * Here is the expected sequence to prepare and send a notification:
 *
 * Allocate a buffer and a coap_pkt_t for the notification, then follow the
 * steps below.
 *
 * -# Call gcoap_obs_init() to initialize the notification for a resource.
 *    Test the return value, which may indicate there is not an observer for
 *    the resource. If so, you are done.
 * -# Use the coap_opt_add_xxx() functions to include any Options, for example
 *    coap_opt_add_format() for Content-Format of the payload.
 * -# Call coap_opt_finish() to complete the PDU metadata. Retain the returned
 *    metadata length.
 * -# Write the notification payload, starting at the updated _payload_ pointer
 *    in the coap_pkt_t, for up to _payload_len_ bytes.
 *
 * Finally, call gcoap_obs_send() for the resource, with the sum of the
 * metadata length and payload length for the representation.
 *
 * ### Other considerations ###
 *
 * By default, the value for the Observe option in a notification is three
 * bytes long. For resources that change slowly, this length can be reduced via
 * GCOAP_OBS_VALUE_WIDTH.
 *
 * A client always may re-register for a resource with the same token or with
 * a new token to indicate continued interest in receiving notifications about
 * it. Of course the client must not already be using any new token in the
 * registration for a different resource. Successful registration always is
 * indicated by the presence of the Observe option in the response.
 *
 * To cancel registration, the server expects to receive a GET request with<commit_msg>net/gcoap: insert doc to add options in order<commit_after>/*
 * Copyright (c) 2015-2017 <NAME>. All rights reserved.
 *               2017 <NAME>ität Berlin
 *
 * This file is subject to the terms and conditions of the GNU Lesser
 * General Public License v2.1. See the file LICENSE in the top level
 * directory for more details.
 */

/**
 * @defgroup    net_gcoap  Gcoap
 * @ingroup     net
 * @brief       High-level interface to CoAP messaging
 *
 * gcoap provides a high-level interface for writing CoAP messages via RIOT's
 * sock networking API. gcoap internalizes network event processing so an
 * application only needs to focus on request/response handling. For a server,
 * gcoap accepts a list of resource paths with callbacks for writing the
 * response. For a client, gcoap provides a function to send a request, with a
 * callback for reading the server response.
 *
 * gcoap allocates a RIOT message processing thread, so a single instance can
 * serve multiple applications. This approach also means gcoap uses a single UDP
 * port, which supports RFC 6282 compression. Internally, gcoap depends on the
 * nanocoap package for base level structs and functionality.
 *
 * gcoap also supports the Observe extension (RFC 7641) for a server. gcoap
 * provides functions to generate and send an observe notification that are
 * similar to the functions to send a client request.
 *
 * *Contents*
 *
 * - Server Operation
 * - Client Operation
 * - Observe Server Operation
 * - Implementation Notes
 * - Implementation Status
 *
 * ## Server Operation ##
 *
 * gcoap listens for requests on GCOAP_PORT, 5683 by default. You can redefine
 * this by uncommenting the appropriate lines in gcoap's make file.
 *
 * gcoap allows an application to specify a collection of request resource paths
 * it wants to be notified about. Create an array of resources (coap_resource_t
 * structs) ordered by the resource path, specifically the ASCII encoding of
 * the path characters (digit and capital precede lower case). Use
 * gcoap_register_listener() at application startup to pass in these resources,
 * wrapped in a gcoap_listener_t. Also see _Server path matching_ in the base
 * [nanocoap](group__net__nanocoap.html) documentation.
 *
 * gcoap itself defines a resource for `/.well-known/core` discovery, which
 * lists all of the registered paths. See the _Resource list creation_ section
 * below for more.
 *
 * ### Creating a response ###
 *
 * An application resource includes a callback function, a coap_handler_t. After
 * reading the request, the callback must use functions provided by gcoap to
 * format the response, as described below. The callback *must* read the request
 * thoroughly before calling the functions, because the response buffer likely
 * reuses the request buffer. See `examples/gcoap/gcoap_cli.c` for a simple
 * example of a callback.
 *
 * Here is the expected sequence for a callback function:
 *
 * Read request completely and parse request payload, if any. Use the
 * coap_pkt_t _payload_ and _payload_len_ attributes.
 *
 * If there is a payload, follow the steps below.
 *
 * -# Call gcoap_resp_init() to initialize the response.
 * -# Use the coap_opt_add_xxx() functions to include any Options, for example
 *    coap_opt_add_format() for Content-Format of the payload. Options *must*
 *    be written in order by option number (see "CoAP option numbers" in
 *    [CoAP defines](group__net__coap.html)).
 * -# Call coap_opt_finish() to complete the PDU metadata. Retain the returned
 *    metadata length.
 * -# Write the response payload, starting at the updated _payload_ pointer
 *    in the coap_pkt_t, for up to _payload_len_ bytes.
 * -# Return the sum of the metadata length and payload length. If some error
 *    has occurred, return a negative errno code from the handler, and gcoap
 *    will send a server error (5.00).
 *
 * If no payload, call only gcoap_response() to write the full response. If you
 * need to add Options, follow the first three steps in the list above instead.
 *
 * ### Resource list creation ###
 *
 * gcoap allows customization of the function that provides the list of registered
 * resources for `/.well-known/core` and CoRE Resource Directory registration.
 * By default gcoap provides gcoap_encode_link(), which lists only the target
 * path for each link. However, an application may specify a custom function in
 * the gcoap_listener_t it registers with gcoap. For example, this function may
 * add parameters to provide more information about the resource, as described
 * in RFC 6690. See the gcoap example for use of a custom encoder function.
 *
 * ## Client Operation ##
 *
 * Client operation includes two phases: creating and sending a request, and
 * handling the response aynchronously in a client supplied callback. See
 * `examples/gcoap/gcoap_cli.c` for a simple example of sending a request and
 * reading the response.
 *
 * ### Creating a request ###
 *
 * Here is the expected sequence to prepare and send a request:
 *
 * Allocate a buffer and a coap_pkt_t for the request.
 *
 * If there is a payload, follow the steps below.
 *
 * -# Call gcoap_req_init() to initialize the request.
 * -# Optionally, mark the request confirmable by calling coap_hdr_set_type()
 *    with COAP_TYPE_CON.
 * -# Use the coap_opt_add_xxx() functions to include any Options beyond
 *    Uri-Path, which was added in the first step. Options *must* be written
 *    in order by option number (see "CoAP option numbers" in
 *    [CoAP defines](group__net__coap.html)).
 * -# Call coap_opt_finish() to complete the PDU metadata. Retain the returned
 *    metadata length.
 * -# Write the request payload, starting at the updated _payload_ pointer
 *    in the coap_pkt_t, for up to _payload_len_ bytes.
 *
 * If no payload, call only gcoap_request() to write the full request. If you
 * need to add Options, follow the first four steps in the list above instead.
 *
 * Finally, call gcoap_req_send() with the sum of the metadata length and
 * payload length, the destination endpoint, and a callback function for the
 * host's response.
 *
 * ### Handling the response ###
 *
 * When gcoap receives the response to a request, it executes the callback from
 * the request. gcoap also executes the callback when a response is not
 * received within GCOAP_RESPONSE_TIMEOUT.
 *
 * Here is the expected sequence for handling a response in the callback.
 *
 * -# Test for a server response or timeout in the _req_state_ callback
 *    parameter. See the GCOAP_MEMO... constants.
 * -# Test the response with coap_get_code_class() and coap_get_code_detail().
 * -# Test the response payload with the coap_pkt_t _payload_len_ and
 *    _content_type_ attributes.
 * -# Read the payload, if any.
 *
 * ## Observe Server Operation
 *
 * A CoAP client may register for Observe notifications for any resource that
 * an application has registered with gcoap. An application does not need to
 * take any action to support Observe client registration. However, gcoap
 * limits registration for a given resource to a _single_ observer.
 *
 * An Observe notification is considered a response to the original client
 * registration request. So, the Observe server only needs to create and send
 * the notification -- no further communication or callbacks are required.
 *
 * ### Creating a notification ###
 *
 * Here is the expected sequence to prepare and send a notification:
 *
 * Allocate a buffer and a coap_pkt_t for the notification, then follow the
 * steps below.
 *
 * -# Call gcoap_obs_init() to initialize the notification for a resource.
 *    Test the return value, which may indicate there is not an observer for
 *    the resource. If so, you are done.
 * -# Use the coap_opt_add_xxx() functions to include any Options, for example
 *    coap_opt_add_format() for Content-Format of the payload. Options *must*
 *    be written in order by option number (see "CoAP option numbers" in
 *    [CoAP defines](group__net__coap.html)).
 * -# Call coap_opt_finish() to complete the PDU metadata. Retain the returned
 *    metadata length.
 * -# Write the notification payload, starting at the updated _payload_ pointer
 *    in the coap_pkt_t, for up to _payload_len_ bytes.
 *
 * Finally, call gcoap_obs_send() for the resource, with the sum of the
 * metadata length and payload length for the representation.
 *
 * ### Other considerations ###
 *
 * By default, the value for the Observe option in a notification is three
 * bytes long. For resources that change slowly, this length can be reduced via
 * GCOAP_OBS_VALUE_WIDTH.
 *
 * A client always may re-register for a resource with the same token or with
 * a new token to indicate continued interest in receiving notifications about
 * it. Of course the client must not already be using any new token in the
 * registration for a different resource. Successful registration always is
 * indicated by the presence of the Observe option in the response.
 *
 * To cancel registration, the server expects to receive a GET request with
{'fraction_non_alphanumeric': 0.061578441895938085, 'fraction_numerical': 0.0037286029037907464, 'mean_word_length': 3.812941816204459, 'pattern_counts': {'":': 0, '<': 6, '<?xml version=': 0, '>': 6, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1170294', 'n_tokens_mistral': 4718, 'n_tokens_neox': 4634, 'n_words': 2395}