libcoap/include/coap/net.h

/*
 * net.h -- CoAP network interface
 *
 * Copyright (C) 2010-2015 Olaf Bergmann <bergmann@tzi.org>
 *
 * This file is part of the CoAP library libcoap. Please see README for terms
 * of use.
 */

#ifndef _COAP_NET_H_
#define _COAP_NET_H_

#include <assert.h>
#include <stdlib.h>
#include <string.h>
#ifndef _WIN32
#include <sys/time.h>
#endif
#include <time.h>

#ifdef WITH_LWIP
#include <lwip/ip_addr.h>
#endif

#include "coap_io.h"
#include "coap_dtls.h"
#include "coap_event.h"
#include "coap_time.h"
#include "option.h"
#include "pdu.h"
#include "prng.h"
#include "session.h"

struct coap_queue_t;

typedef struct coap_queue_t {
  struct coap_queue_t *next;
  coap_tick_t t;                /**< when to send PDU for the next time */
  unsigned char retransmit_cnt; /**< retransmission counter, will be removed
                                 *    when zero */
  unsigned int timeout;         /**< the randomized timeout value */
  coap_session_t *session;      /**< the CoAP session */
  coap_tid_t id;                /**< CoAP transaction id */
  coap_pdu_t *pdu;              /**< the CoAP PDU to send */
} coap_queue_t;

/** Adds node to given queue, ordered by node->t. */
int coap_insert_node(coap_queue_t **queue, coap_queue_t *node);

/** Destroys specified node. */
int coap_delete_node(coap_queue_t *node);

/** Removes all items from given queue and frees the allocated storage. */
void coap_delete_all(coap_queue_t *queue);

/** Creates a new node suitable for adding to the CoAP sendqueue. */
coap_queue_t *coap_new_node(void);

struct coap_resource_t;
struct coap_context_t;
#ifndef WITHOUT_ASYNC
struct coap_async_state_t;
#endif

/** Message handler that is used as call-back in coap_context_t */
typedef void (*coap_response_handler_t)(struct coap_context_t *,
                                        coap_session_t *session,
                                        coap_pdu_t *sent,
                                        coap_pdu_t *received,
                                        const coap_tid_t id);

#define COAP_MID_CACHE_SIZE 3
typedef struct {
  unsigned char flags[COAP_MID_CACHE_SIZE];
  coap_key_t item[COAP_MID_CACHE_SIZE];
} coap_mid_cache_t;

/** The CoAP stack's global state is stored in a coap_context_t object */
typedef struct coap_context_t {
  coap_opt_filter_t known_options;
  struct coap_resource_t *resources; /**< hash table or list of known resources */

#ifndef WITHOUT_ASYNC
  /**
   * list of asynchronous transactions */
  struct coap_async_state_t *async_state;
#endif /* WITHOUT_ASYNC */

  /**
   * The time stamp in the first element of the sendqeue is relative
   * to sendqueue_basetime. */
  coap_tick_t sendqueue_basetime;
  coap_queue_t *sendqueue;
  coap_endpoint_t *endpoint;      /**< the endpoints used for listening  */
  coap_session_t *sessions;	  /**< client sessions */

#ifdef WITH_CONTIKI
  struct uip_udp_conn *conn;      /**< uIP connection object */
  struct etimer retransmit_timer; /**< fires when the next packet must be sent */
  struct etimer notify_timer;     /**< used to check resources periodically */
#endif /* WITH_CONTIKI */

#ifdef WITH_LWIP
  uint8_t timer_configured;       /**< Set to 1 when a retransmission is
                                   *   scheduled using lwIP timers for this
                                   *   context, otherwise 0. */
#endif /* WITH_LWIP */

  /**
   * The last message id that was used is stored in this field. The initial
   * value is set by coap_new_context() and is usually a random value. A new
   * message id can be created with coap_new_message_id().
   */
  unsigned short message_id;

  /**
   * The next value to be used for Observe. This field is global for all
   * resources and will be updated when notifications are created.
   */
  unsigned int observe;

  coap_response_handler_t response_handler;

  /**
   * Callback function that is used to signal events to the
   * application.  This field is set by coap_set_event_handler().
   */
  coap_event_handler_t handle_event;

  ssize_t (*network_send)(coap_socket_t *sock, const coap_session_t *session, const uint8_t *data, size_t datalen);

  ssize_t (*network_read)(coap_socket_t *sock, struct coap_packet_t **packet);

  unsigned (*get_client_psk)( const coap_session_t *session, const char *hint, char *identity, unsigned max_identity_len, uint8_t *psk, unsigned max_psk_len );
  unsigned (*get_server_psk)( const coap_session_t *session, const char *identity, uint8_t *psk, unsigned max_psk_len );
  int (*get_server_hint)( const coap_session_t *session, char *hint, unsigned max_hint_len );

  void *dtls_context;
  char *psk_hint;
  uint8_t *psk_key;
  unsigned psk_key_len;
  void *app;                    /**< application-specific data */
} coap_context_t;

/**
 * Registers a new message handler that is called whenever a response was
 * received that matches an ongoing transaction.
 *
 * @param context The context to register the handler for.
 * @param handler The response handler to register.
 */
COAP_STATIC_INLINE void
coap_register_response_handler(coap_context_t *context,
                               coap_response_handler_t handler) {
  context->response_handler = handler;
}

/**
 * Registers the option type @p type with the given context object @p ctx.
 *
 * @param ctx  The context to use.
 * @param type The option type to register.
 */
COAP_STATIC_INLINE void
coap_register_option(coap_context_t *ctx, unsigned char type) {
  coap_option_setb(ctx->known_options, type);
}

/**
 * Set sendqueue_basetime in the given context object @p ctx to @p now. This
 * function returns the number of elements in the queue head that have timed
 * out.
 */
unsigned int coap_adjust_basetime(coap_context_t *ctx, coap_tick_t now);

/**
 * Returns the next pdu to send without removing from sendqeue.
 */
coap_queue_t *coap_peek_next( coap_context_t *context );

/**
 * Returns the next pdu to send and removes it from the sendqeue.
 */
coap_queue_t *coap_pop_next( coap_context_t *context );

/**
 * Creates a new coap_context_t object that will hold the CoAP stack status.
 */
coap_context_t *coap_new_context(const coap_address_t *listen_addr);

/**
 * Set the context's default server PSK hint and/or key.
 * These global defaults are used only no PSK callback is specified.
 *
 * @param hint    The default PSK server hint sent to a client. If NULL, PSK authentication is disabled. Empty string is a valid hint.
 * @param key     The default PSK key. If NULL, PSK authentication will fail.
 * @param key_len The default PSK key's lenght. If 0, PSK authentication will fail.
 */

void coap_context_set_psk( coap_context_t *ctx, const char *hint,
                           const uint8_t *key, unsigned key_len );

/**
 * Returns a new message id and updates @p context->message_id accordingly. The
 * message id is returned in network byte order to make it easier to read in
 * tracing tools.
 *
 * @param context The current coap_context_t object.
 *
 * @return        Incremented message id in network byte order.
 */
COAP_STATIC_INLINE unsigned short
coap_new_message_id(coap_context_t *context) {
  context->message_id++;
#ifndef WITH_CONTIKI
  return htons(context->message_id);
#else /* WITH_CONTIKI */
  return uip_htons(context->message_id);
#endif
}

/**
 * CoAP stack context must be released with coap_free_context(). This function
 * clears all entries from the receive queue and send queue and deletes the
 * resources that have been registered with @p context, and frees the attached
 * endpoints.
 */
void coap_free_context(coap_context_t *context);

/**
 * Stores @p data with the given CoAP context. This function
 * overwrites any value that has previously been stored with @p
 * context.
 */
void coap_set_app_data(coap_context_t *context, void *data);

/**
 * Returns any application-specific data that has been stored with @p
 * context using the function coap_set_app_data(). This function will
 * return @c NULL if no data has been stored.
 */
void *coap_get_app_data(coap_context_t *context);

/**
 * Creates a new ACK PDU with specified error @p code. The options specified by
 * the filter expression @p opts will be copied from the original request
 * contained in @p request. Unless @c SHORT_ERROR_RESPONSE was defined at build
 * time, the textual reason phrase for @p code will be added as payload, with
 * Content-Type @c 0.
 * This function returns a pointer to the new response message, or @c NULL on
 * error. The storage allocated for the new message must be relased with
 * coap_free().
 *
 * @param request Specification of the received (confirmable) request.
 * @param code    The error code to set.
 * @param opts    An option filter that specifies which options to copy from
 *                the original request in @p node.
 *
 * @return        A pointer to the new message or @c NULL on error.
 */
coap_pdu_t *coap_new_error_response(coap_pdu_t *request,
                                    unsigned char code,
                                    coap_opt_filter_t opts);

/**
 * Sends an error response with code @p code for request @p request to @p dst.
 * @p opts will be passed to coap_new_error_response() to copy marked options
 * from the request. This function returns the transaction id if the message was
 * sent, or @c COAP_INVALID_TID otherwise.
 *
 * @param session         The CoAP session.
 * @param request         The original request to respond to.
 * @param code            The response code.
 * @param opts            A filter that specifies the options to copy from the
 *                        @p request.
 *
 * @return                The transaction id if the message was sent, or @c
 *                        COAP_INVALID_TID otherwise.
 */
coap_tid_t coap_send_error(coap_session_t *session,
                           coap_pdu_t *request,
                           unsigned char code,
                           coap_opt_filter_t opts);

/**
 * Helper funktion to create and send a message with @p type (usually ACK or
 * RST). This function returns @c COAP_INVALID_TID when the message was not
 * sent, a valid transaction id otherwise.
 *
 * @param session         The CoAP session.
 * @param request         The request that should be responded to.
 * @param type            Which type to set.
 * @return                transaction id on success or @c COAP_INVALID_TID
 *                        otherwise.
 */
coap_tid_t
coap_send_message_type(coap_session_t *session, coap_pdu_t *request, unsigned char type);

/**
 * Sends an ACK message with code @c 0 for the specified @p request to @p dst.
 * This function returns the corresponding transaction id if the message was
 * sent or @c COAP_INVALID_TID on error.
 *
 * @param session         The CoAP session.
 * @param request         The request to be acknowledged.
 *
 * @return                The transaction id if ACK was sent or @c
 *                        COAP_INVALID_TID on error.
 */
coap_tid_t coap_send_ack(coap_session_t *session, coap_pdu_t *request);

/**
 * Sends an RST message with code @c 0 for the specified @p request to @p dst.
 * This function returns the corresponding transaction id if the message was
 * sent or @c COAP_INVALID_TID on error.
 *
 * @param session         The CoAP session.
 * @param request         The request to be reset.
 *
 * @return                The transaction id if RST was sent or @c
 *                        COAP_INVALID_TID on error.
 */
COAP_STATIC_INLINE coap_tid_t
coap_send_rst(coap_session_t *session, coap_pdu_t *request) {
  return coap_send_message_type(session, request, COAP_MESSAGE_RST);
}

/**
* Sends a CoAP message to given peer. The memory that is
* allocated by pdu will be released by coap_send().
* The caller must not use the pdu after calling coap_send().
*
* @param session         The CoAP session.
* @param pdu             The CoAP PDU to send.
*
* @return                The message id of the sent message or @c
*                        COAP_INVALID_TID on error.
*/
coap_tid_t coap_send( coap_session_t *session, coap_pdu_t *pdu );

/**
 * Handles retransmissions of confirmable messages
 */
coap_tid_t coap_retransmit(coap_context_t *context, coap_queue_t *node);

/**
 * Reads all data from the network.
 */
void coap_read(coap_context_t *context);

/**
 * The main message processing loop.
 * @param ctx The CoAP context
 * @param timeout_ms Minimum number of milliseconds to wait for new messages before returning. If zero the call will block until at least one packet is sent or received.
 * @return number of milliseconds spent or -1 if there was an error
 */

int coap_run_once( coap_context_t *ctx, unsigned int timeout_ms );

/**
 * Parses and interprets a CoAP message with context @p ctx. This function
 * returns @c 0 if the message was handled, or a value less than zero on
 * error.
 *
 * @param ctx    The current CoAP context.
 * @param packet The received packet.
 *
 * @return       @c 0 if message was handled successfully, or less than zero on
 *               error.
 */
int coap_handle_message(coap_context_t *ctx, coap_session_t *session, uint8_t *data, size_t data_len);

/**
 * Invokes the event handler of @p context for the given @p event and
 * @p data.
 *
 * @param context The CoAP context whose event handler is to be called.
 * @param event   The event to deliver.
 * @param data    Any data related to @p event.
 * @return The result from the associated event handler or 0 if none was
 * registered.
 */
int coap_handle_event(coap_context_t *context,
                      coap_event_t event,
                      void *data);
/**
 * This function removes the element with given @p id from the list given list.
 * If @p id was found, @p node is updated to point to the removed element. Note
 * that the storage allocated by @p node is @b not released. The caller must do
 * this manually using coap_delete_node(). This function returns @c 1 if the
 * element with id @p id was found, @c 0 otherwise. For a return value of @c 0,
 * the contents of @p node is undefined.
 *
 * @param queue The queue to search for @p id.
 * @param session The session to look for.
 * @param id    The transaction id to look for.
 * @param node  If found, @p node is updated to point to the removed node. You
 *              must release the storage pointed to by @p node manually.
 *
 * @return      @c 1 if @p id was found, @c 0 otherwise.
 */
int coap_remove_from_queue(coap_queue_t **queue,
                           coap_session_t *session,
                           coap_tid_t id,
                           coap_queue_t **node);

/**
 * Removes the transaction identified by @p id from given @p queue. This is a
 * convenience function for coap_remove_from_queue() with automatic deletion of
 * the removed node.
 *
 * @param queue The queue to search for @p id.
 * @param session The session to look for.
 * @param id    The transaction id.
 *
 * @return      @c 1 if node was found, removed and destroyed, @c 0 otherwise.
 */
COAP_STATIC_INLINE int
coap_remove_transaction(coap_queue_t **queue, coap_session_t *session, coap_tid_t id) {
  coap_queue_t *node;
  if (!coap_remove_from_queue(queue, session, id, &node))
    return 0;

  coap_delete_node(node);
  return 1;
}

coap_tid_t
coap_wait_ack( coap_context_t *context, coap_session_t *session,
  coap_pdu_t *pdu, int retransmit_cnt );

/**
 * Retrieves transaction from the queue.
 *
 * @param queue The transaction queue to be searched.
 * @param session The session to find.
 * @param id    The transaction id to find.
 *
 * @return      A pointer to the transaction object or NULL if not found.
 */
coap_queue_t *coap_find_transaction(coap_queue_t *queue, coap_session_t *session, coap_tid_t id);

/**
 * Cancels all outstanding messages for peer @p dst that have the specified
 * token.
 *
 * @param context      The context in use.
 * @param dst          Session of the messages to remove.
 * @param token        Message token.
 * @param token_length Actual length of @p token.
 */
void coap_cancel_all_messages(coap_context_t *context,
                              coap_session_t *session,
                              const unsigned char *token,
                              size_t token_length);

/**
 * Dispatches the PDUs from the receive queue in given context.
 */
void coap_dispatch(coap_context_t *context, coap_queue_t *rcvd);

/**
 * Returns 1 if there are no messages to send or to dispatch in the context's
 * queues. */
int coap_can_exit(coap_context_t *context);

/**
 * Returns the current value of an internal tick counter. The counter counts \c
 * COAP_TICKS_PER_SECOND ticks every second.
 */
void coap_ticks(coap_tick_t *);

/**
 * Verifies that @p pdu contains no unknown critical options. Options must be
 * registered at @p ctx, using the function coap_register_option(). A basic set
 * of options is registered automatically by coap_new_context(). This function
 * returns @c 1 if @p pdu is ok, @c 0 otherwise. The given filter object @p
 * unknown will be updated with the unknown options. As only @c COAP_MAX_OPT
 * options can be signalled this way, remaining options must be examined
 * manually.
 *
 * @code
  coap_opt_filter_t f = COAP_OPT_NONE;
  coap_opt_iterator_t opt_iter;

  if (coap_option_check_critical(ctx, pdu, f) == 0) {
    coap_option_iterator_init(pdu, &opt_iter, f);

    while (coap_option_next(&opt_iter)) {
      if (opt_iter.type & 0x01) {
        ... handle unknown critical option in opt_iter ...
      }
    }
  }
 * @endcode
 *
 * @param ctx      The context where all known options are registered.
 * @param pdu      The PDU to check.
 * @param unknown  The output filter that will be updated to indicate the
 *                 unknown critical options found in @p pdu.
 *
 * @return         @c 1 if everything was ok, @c 0 otherwise.
 */
int coap_option_check_critical(coap_context_t *ctx,
                               coap_pdu_t *pdu,
                               coap_opt_filter_t unknown);

/**
 * Creates a new response for given @p request with the contents of @c
 * .well-known/core. The result is NULL on error or a newly allocated PDU that
 * must be either sent with coap_sent() or released by coap_delete_pdu().
 *
 * @param context The current coap context to use.
 * @param request The request for @c .well-known/core .
 *
 * @return        A new 2.05 response for @c .well-known/core or NULL on error.
 */
coap_pdu_t *coap_wellknown_response(coap_context_t *context,
                                    coap_pdu_t *request);

#endif /* _COAP_NET_H_ */