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