resource/csdk/connectivity/lib/libcoap-4.1.1/include/coap/net.h

   1 /* net.h -- CoAP network interface
   2  *
   3  * Copyright (C) 2010--2013 Olaf Bergmann <bergmann@tzi.org>
   4  *
   5  * This file is part of the CoAP library libcoap. Please see
   6  * README for terms of use.
   7  */
   8
   9 #ifndef _COAP_NET_H_
  10 #define _COAP_NET_H_
  11
  12 #ifdef WITH_ARDUINO
  13 #include "Time.h"
  14 #endif /* WITH_ARDUINO */
  15
  16 #ifdef __cplusplus
  17 extern "C"
  18 {
  19 #endif
  20
  21 #include "config.h"
  22
  23 #ifdef HAVE_ASSERT_H
  24 #include <assert.h>
  25 #else
  26 #ifndef assert
  27 #warning "assertions are disabled"
  28 #  define assert(x)
  29 #endif
  30 #endif
  31
  32 #include <stdlib.h>
  33 #include <string.h>
  34 #ifdef HAVE_NETINET_IN_H
  35 #include <netinet/in.h>
  36 #endif
  37 #ifdef HAVE_ARPA_INET_H
  38 #include <arpa/inet.h>
  39 #endif
  40
  41 #ifdef HAVE_TIME_H
  42 #include <time.h>
  43 #endif
  44 #ifdef HAVE_SYS_TIME_H
  45 #include <sys/time.h>
  46 #endif
  47
  48 #ifdef WITH_LWIP
  49 #include <lwip/ip_addr.h>
  50 #endif
  51
  52 #include "option.h"
  53 #include "address.h"
  54 #include "prng.h"
  55 #include "pdu.h"
  56 #include "coap_time.h"
  57
  58     struct coap_queue_t;
  59
  60     typedef struct coap_queue_t
  61     {
  62         struct coap_queue_t *next;
  63
  64         coap_tick_t t; /**< when to send PDU for the next time */
  65         unsigned char retransmit_cnt; /**< retransmission counter, will be removed when zero */
  66         unsigned int timeout; /**< the randomized timeout value */
  67
  68         coap_address_t local; /**< local address */
  69         coap_address_t remote; /**< remote address */
  70         coap_tid_t id; /**< unique transaction id */
  71
  72         coap_pdu_t *pdu; /**< the CoAP PDU to send */
  73     } coap_queue_t;
  74
  75     /** Adds node to given queue, ordered by node->t. */
  76     int coap_insert_node(coap_queue_t **queue, coap_queue_t *node);
  77
  78     /** Destroys specified node. */
  79     int coap_delete_node(coap_queue_t *node);
  80
  81     /** Removes all items from given queue and frees the allocated storage. */
  82     void coap_delete_all(coap_queue_t *queue);
  83
  84     /** Creates a new node suitable for adding to the CoAP sendqueue. */
  85     coap_queue_t *coap_new_node();
  86
  87     struct coap_resource_t;
  88     struct coap_context_t;
  89 #ifndef WITHOUT_ASYNC
  90     struct coap_async_state_t;
  91 #endif
  92
  93     /** Message handler that is used as call-back in coap_context_t */
  94     typedef void (*coap_response_handler_t)(struct coap_context_t *, const coap_address_t *remote,
  95             coap_pdu_t *sent, coap_pdu_t *received, const coap_tid_t id);
  96
  97 #define COAP_MID_CACHE_SIZE 3
  98     typedef struct
  99     {
 100         unsigned char flags[COAP_MID_CACHE_SIZE];
 101         coap_key_t item[COAP_MID_CACHE_SIZE];
 102     } coap_mid_cache_t;
 103
 104     /** The CoAP stack's global state is stored in a coap_context_t object */
 105     typedef struct coap_context_t
 106     {
 107         coap_opt_filter_t known_options;
 108 #ifndef WITH_CONTIKI
 109         struct coap_resource_t *resources; /**< hash table or list of known resources */
 110 #endif /* WITH_CONTIKI */
 111 #ifndef WITHOUT_ASYNC
 112         /** list of asynchronous transactions */
 113         struct coap_async_state_t *async_state;
 114 #endif /* WITHOUT_ASYNC */
 115     /**
 116      * The time stamp in the first element of the sendqeue is relative
 117      * to sendqueue_basetime. */
 118     coap_tick_t sendqueue_basetime;
 119     coap_queue_t *sendqueue, *recvqueue;
 120 #if defined(WITH_POSIX) || defined(WITH_ARDUINO) || defined(_WIN32)
 121     int sockfd; /**< send/receive socket */
 122 #endif /* WITH_POSIX || WITH_ARDUINO */
 123 #ifdef WITH_CONTIKI
 124         struct uip_udp_conn *conn; /**< uIP connection object */
 125
 126         struct etimer retransmit_timer; /**< fires when the next packet must be sent */
 127         struct etimer notify_timer; /**< used to check resources periodically */
 128 #endif /* WITH_CONTIKI */
 129 #ifdef WITH_LWIP
 130         struct udp_pcb *pcb; /**< the underlying lwIP UDP PCB */
 131         struct pbuf *pending_package; /**< pbuf containing the last received package if not handled yet. This is only used to pass the package from the udp_recv callback into the coap_read function, which frees the pbuf and clears this field. */
 132         ip_addr_t pending_address; /**< the address associated with pending_package */
 133         u16_t pending_port; /**< the port associated with pending_package */
 134
 135         uint8_t timer_configured; /**< Set to 1 when a retransmission is scheduled using lwIP timers for this context, otherwise 0. */
 136 #endif /* WITH_LWIP */
 137
 138         /**
 139          * The last message id that was used is stored in this field.  The
 140          * initial value is set by coap_new_context() and is usually a
 141          * random value. A new message id can be created with
 142          * coap_new_message_id().
 143          */
 144         unsigned short message_id;
 145
 146         /**
 147          * The next value to be used for Observe. This field is global for
 148          * all resources and will be updated when notifications are created.
 149          */
 150         unsigned int observe;
 151
 152         coap_response_handler_t response_handler;
 153     } coap_context_t;
 154
 155     /**
 156      * Registers a new message handler that is called whenever a response
 157      * was received that matches an ongoing transaction.
 158      *
 159      * @param context The context to register the handler for.
 160      * @param handler The response handler to register.
 161      */
 162     INLINE_API void coap_register_response_handler(coap_context_t *context,
 163             coap_response_handler_t handler)
 164     {
 165         context->response_handler = handler;
 166     }
 167
 168     /**
 169      * Registers the option type @p type with the given context object @p
 170      * ctx.
 171      *
 172      * @param ctx  The context to use.
 173      * @param type The option type to register.
 174      */
 175     INLINE_API void coap_register_option(coap_context_t *ctx, unsigned char type)
 176     {
 177         coap_option_setb(ctx->known_options, type);
 178     }
 179
 180     /**
 181      * Set sendqueue_basetime in the given context object @p ctx to @p
 182      * now. This function returns the number of elements in the queue
 183      * head that have timed out.
 184      */
 185     unsigned int coap_adjust_basetime(coap_context_t *ctx, coap_tick_t now);
 186
 187     /** Returns the next pdu to send without removing from sendqeue. */
 188     coap_queue_t *coap_peek_next(coap_context_t *context);
 189
 190     /** Returns the next pdu to send and removes it from the sendqeue. */
 191     coap_queue_t *coap_pop_next(coap_context_t *context);
 192
 193     /** Creates a new coap_context_t object that will hold the CoAP stack status.  */
 194     coap_context_t *coap_new_context(const coap_address_t *listen_addr);
 195
 196 /**
 197  * Returns a new message id and updates @p context->message_id
 198  * accordingly. The message id is returned in network byte order
 199  * to make it easier to read in tracing tools.
 200  *
 201  * @param context the current coap_context_t object
 202  * @return incremented message id in network byte order
 203  */
 204 INLINE_API unsigned short coap_new_message_id(coap_context_t *context)
 205 {
 206     ++(context->message_id);
 207 #if defined(WITH_ARDUINO)
 208     return ((context->message_id << 8) | ((context->message_id >> 8) & (0xFF)));
 209 #elif defined(WITH_CONTIKI)
 210     return uip_htons(context->message_id);
 211 #else /* WITH_CONTIKI */
 212     return htons(context->message_id);
 213 #endif
 214     }
 215
 216     /* CoAP stack context must be released with coap_free_context() */
 217     void coap_free_context(coap_context_t *context);
 218
 219     /**
 220      * Sends a confirmed CoAP message to given destination. The memory
 221      * that is allocated by pdu will not be released by
 222      * coap_send_confirmed(). The caller must release the memory.
 223      *
 224      * @param context The CoAP context to use.
 225      * @param dst     The address to send to.
 226      * @param pdu     The CoAP PDU to send.
 227      * @return The message id of the sent message or @c COAP_INVALID_TID on error.
 228      */
 229     coap_tid_t coap_send_confirmed(coap_context_t *context, const coap_address_t *dst,
 230             coap_pdu_t *pdu);
 231
 232     /**
 233      * Creates a new ACK PDU with specified error @p code. The options
 234      * specified by the filter expression @p opts will be copied from the
 235      * original request contained in @p request.  Unless @c
 236      * SHORT_ERROR_RESPONSE was defined at build time, the textual reason
 237      * phrase for @p code will be added as payload, with Content-Type @c
 238      * 0.  This function returns a pointer to the new response message, or
 239      * @c NULL on error. The storage allocated for the new message must be
 240      * relased with coap_free().
 241      *
 242      * @param request Specification of the received (confirmable) request.
 243      * @param code The error code to set.
 244      * @param opts An option filter that specifies which options to copy
 245      *             from the original request in @p node.
 246      *
 247      * @return A pointer to the new message or @c NULL on error.
 248      */
 249     coap_pdu_t *coap_new_error_response(coap_pdu_t *request, unsigned char code,
 250             coap_opt_filter_t opts);
 251     /**
 252      * Sends a non-confirmed CoAP message to given destination. The memory
 253      * that is allocated by pdu will not be released by coap_send().
 254      * The caller must release the memory.
 255      *
 256      * @param context The CoAP context to use.
 257      * @param dst     The address to send to.
 258      * @param pdu     The CoAP PDU to send.
 259      * @return The message id of the sent message or @c COAP_INVALID_TID on error.
 260      */
 261     coap_tid_t coap_send(coap_context_t *context, const coap_address_t *dst, coap_pdu_t *pdu);
 262
 263     /**
 264      * Sends an error response with code @p code for request @p request to
 265      * @p dst.  @p opts will be passed to coap_new_error_response() to
 266      * copy marked options from the request. This function returns the
 267      * transaction id if the message was sent, or @c COAP_INVALID_TID
 268      * otherwise.
 269      *
 270      * @param context The context to use.
 271      * @param request The original request to respond to.
 272      * @param dst     The remote peer that sent the request.
 273      * @param code    The reponse code.
 274      * @param opts    A filter that specifies the options to copy from the
 275      *                @p request.
 276      *
 277      * @return The transaction id if the message was sent, or @c
 278      * COAP_INVALID_TID otherwise.
 279      */
 280     coap_tid_t coap_send_error(coap_context_t *context, coap_pdu_t *request,
 281             const coap_address_t *dst, unsigned char code, coap_opt_filter_t opts);
 282
 283     /**
 284      * Helper funktion to create and send a message with @p type (usually
 285      * ACK or RST).  This function returns @c COAP_INVALID_TID when the
 286      * message was not sent, a valid transaction id otherwise.
 287      *
 288      * @param context The CoAP context.
 289      * @param dst Where to send the context.
 290      * @param request The request that should be responded to.
 291      * @param type Which type to set
 292      * @return transaction id on success or @c COAP_INVALID_TID otherwise.
 293      */
 294     coap_tid_t
 295     coap_send_message_type(coap_context_t *context, const coap_address_t *dst, coap_pdu_t *request,
 296             unsigned char type);
 297     /**
 298      * Sends an ACK message with code @c 0 for the specified @p request to
 299      * @p dst. This function returns the corresponding transaction id if
 300      * the message was sent or @c COAP_INVALID_TID on error.
 301      *
 302      * @param context The context to use.
 303      * @param dst     The destination address.
 304      * @param request The request to be acknowledged.
 305      *
 306      * @return The transaction id if ACK was sent or @c COAP_INVALID_TID
 307      * on error.
 308      */
 309     coap_tid_t coap_send_ack(coap_context_t *context, const coap_address_t *dst,
 310             coap_pdu_t *request);
 311
 312     /**
 313      * Sends an RST message with code @c 0 for the specified @p request to
 314      * @p dst. This function returns the corresponding transaction id if
 315      * the message was sent or @c COAP_INVALID_TID on error.
 316      *
 317      * @param context The context to use.
 318      * @param dst     The destination address.
 319      * @param request The request to be reset.
 320      *
 321      * @return The transaction id if RST was sent or @c COAP_INVALID_TID
 322      * on error.
 323      */
 324     INLINE_API coap_tid_t coap_send_rst(coap_context_t *context, const coap_address_t *dst,
 325             coap_pdu_t *request)
 326     {
 327         return coap_send_message_type(context, dst, request, COAP_MESSAGE_RST);
 328     }
 329
 330     /** Handles retransmissions of confirmable messages */
 331     coap_tid_t coap_retransmit(coap_context_t *context, coap_queue_t *node);
 332
 333     /**
 334      * Reads data from the network and tries to parse as CoAP PDU. On success, 0 is returned
 335      * and a new node with the parsed PDU is added to the receive queue in the specified context
 336      * object.
 337      */
 338     int coap_read(coap_context_t *context);
 339
 340     /**
 341      * Calculates a unique transaction id from given arguments @p peer and
 342      * @p pdu. The id is returned in @p id.
 343      *
 344      * @param peer The remote party who sent @p pdu.
 345      * @param pdu  The message that initiated the transaction.
 346      * @param id   Set to the new id.
 347      */
 348     void coap_transaction_id(const coap_address_t *peer, const coap_pdu_t *pdu, coap_tid_t *id);
 349
 350     /**
 351      * This function removes the element with given @p id from the list
 352      * given list. If @p id was found, @p node is updated to point to the
 353      * removed element. Note that the storage allocated by @p node is
 354      * @b not released. The caller must do this manually using
 355      * coap_delete_node(). This function returns @c 1 if the element with
 356      * id @p id was found, @c 0 otherwise. For a return value of @c 0,
 357      * the contents of @p node is undefined.
 358      *
 359      * @param queue The queue to search for @p id.
 360      * @param id    The node id to look for.
 361      * @param node  If found, @p node is updated to point to the
 362      *   removed node. You must release the storage pointed to by
 363      *   @p node manually.
 364      *
 365      * @return @c 1 if @p id was found, @c 0 otherwise.
 366      */
 367     int coap_remove_from_queue(coap_queue_t **queue, coap_tid_t id, coap_queue_t **node);
 368
 369     /**
 370      * Removes the transaction identified by @p id from given @p queue.
 371      * This is a convenience function for coap_remove_from_queue() with
 372      * automatic deletion of the removed node.
 373      *
 374      * @param queue The queue to search for @p id.
 375      * @param id    The transaction id.
 376      *
 377      * @return @c 1 if node was found, removed and destroyed, @c 0 otherwise.
 378      */
 379     INLINE_API int coap_remove_transaction(coap_queue_t **queue, coap_tid_t id)
 380     {
 381         coap_queue_t *node;
 382         if (!coap_remove_from_queue(queue, id, &node))
 383             return 0;
 384
 385         coap_delete_node(node);
 386         return 1;
 387     }
 388
 389     /**
 390      * Retrieves transaction from queue.
 391      * @queue The transaction queue to be searched
 392      * @id Unique key of the transaction to find.
 393      * @return A pointer to the transaction object or NULL if not found
 394      */
 395     coap_queue_t *coap_find_transaction(coap_queue_t *queue, coap_tid_t id);
 396
 397     /**
 398      * Cancels all outstanding messages for peer @p dst that have the
 399      * specified token.
 400      *
 401      * @param context The context in use
 402      * @param dst     Destination address of the messages to remove.
 403      * @param token   Message token
 404      * @param token_length Actual length of @p token
 405      */
 406     void coap_cancel_all_messages(coap_context_t *context, const coap_address_t *dst,
 407             const unsigned char *token, size_t token_length);
 408
 409     /** Dispatches the PDUs from the receive queue in given context. */
 410     void coap_dispatch(coap_context_t *context, const char* responseData);
 411
 412     /** Returns 1 if there are no messages to send or to dispatch in the context's queues. */
 413     int coap_can_exit(coap_context_t *context);
 414
 415     /**
 416      * Returns the current value of an internal tick counter. The counter
 417      * counts \c COAP_TICKS_PER_SECOND ticks every second.
 418      */
 419     void coap_ticks(coap_tick_t *);
 420
 421     /**
 422      * Verifies that @p pdu contains no unknown critical options. Options
 423      * must be registered at @p ctx, using the function
 424      * coap_register_option(). A basic set of options is registered
 425      * automatically by coap_new_context(). This function returns @c 1 if
 426      * @p pdu is ok, @c 0 otherwise. The given filter object @p unknown
 427      * will be updated with the unknown options. As only @c COAP_MAX_OPT
 428      * options can be signalled this way, remaining options must be
 429      * examined manually.
 430      *
 431      * @code
 432      coap_opt_filter_t f = COAP_OPT_NONE;
 433      coap_opt_iterator_t opt_iter;
 434
 435      if (coap_option_check_critical(ctx, pdu, f) == 0) {
 436      coap_option_iterator_init(pdu, &opt_iter, f);
 437
 438      while (coap_option_next(&opt_iter)) {
 439      if (opt_iter.type & 0x01) {
 440      ... handle unknown critical option in opt_iter ...
 441      }
 442      }
 443      }
 444      * @endcode
 445      *
 446      * @param ctx      The context where all known options are registered.
 447      * @param pdu      The PDU to check.
 448      * @param unknown  The output filter that will be updated to indicate the
 449      *                 unknown critical options found in @p pdu.
 450      *
 451      * @return @c 1 if everything was ok, @c 0 otherwise.
 452      */
 453     int coap_option_check_critical(coap_context_t *ctx, coap_pdu_t *pdu, coap_opt_filter_t unknown);
 454
 455 #ifdef __cplusplus
 456 }
 457 #endif
 458
 459 #endif /* _COAP_NET_H_ */