csdk/libcoap-4.1.1/async.h

   1 /* async.h -- state management for asynchronous messages
   2  *
   3  * Copyright (C) 2010,2011 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 /**
  10  * @file async.h
  11  * @brief state management for asynchronous messages
  12  */
  13
  14
  15 #ifndef _COAP_ASYNC_H_
  16 #define _COAP_ASYNC_H_
  17
  18 #include "config.h"
  19 #include "net.h"
  20
  21 #ifndef WITHOUT_ASYNC
  22
  23 /**
  24  * @defgroup coap_async Asynchronous Messaging
  25  * @{
  26  * Structure for managing asynchronous state of CoAP resources. A
  27  * coap_resource_t object holds a list of coap_async_state_t objects
  28  * that can be used to generate a separate response in case a result
  29  * of an operation cannot be delivered in time, or the resource has
  30  * been explicitly subscribed to with the option @c observe.
  31  */
  32 typedef struct coap_async_state_t {
  33   unsigned char flags;  /**< holds the flags to control behaviour */
  34
  35   /**
  36    * Holds the internal time when the object was registered with a
  37    * resource. This field will be updated whenever
  38    * coap_register_async() is called for a specific resource.
  39    */
  40   coap_tick_t created;
  41
  42   /**
  43    * This field can be used to register opaque application data with
  44    * the asynchronous state object. */
  45   void *appdata;
  46
  47   unsigned short message_id;    /**< id of last message seen */
  48   coap_tid_t id;                /**< transaction id */
  49
  50   struct coap_async_state_t *next; /**< internally used for linking */
  51
  52   coap_address_t peer;          /**< the peer to notify */
  53   size_t tokenlen;              /**< length of the token */
  54 #pragma GCC diagnostic ignored "-pedantic"
  55   unsigned char token[];        /**< the token to use in a response */
  56 #pragma GCC diagnostic warning "-pedantic"
  57 } coap_async_state_t;
  58
  59 /* Definitions for Async Status Flags These flags can be used to
  60  * control the behaviour of asynchronous response generation. */
  61 #define COAP_ASYNC_CONFIRM   0x01 /**< send confirmable response */
  62 #define COAP_ASYNC_SEPARATE  0x02 /**< send separate response */
  63 #define COAP_ASYNC_OBSERVED  0x04 /**< the resource is being observed */
  64
  65 /** release application data on destruction */
  66 #define COAP_ASYNC_RELEASE_DATA  0x08
  67
  68 /**
  69  * Allocates a new coap_async_state_t object and fills its fields
  70  * according to the given @p request. The @p flags are used to control
  71  * generation of empty ACK responses to stop retransmissions and to
  72  * release registered @p data when the resource is deleted by
  73  * coap_free_async().  This function returns a pointer to the registered
  74  * coap_async_t object or @c NULL on error. Note that this function will
  75  * return @c NULL in case that an object with the same identifier is
  76  * already registered.
  77  *
  78  * @param context  The context to use.
  79  * @param peer     The remote peer that is to be asynchronously notified.
  80  * @param request  The request that is handled asynchronously.
  81  * @param flags    Flags to control state management.
  82  * @param data     Opaque application data to register. Note that the
  83  *                 storage occupied by @p data is released on destruction
  84  *                 only if flag COAP_ASYNC_RELEASE_DATA is set.
  85  *
  86  * @return A pointer to the registered coap_async_state_t object or
  87  * @c NULL in case of an error.
  88  */
  89 coap_async_state_t *
  90 coap_register_async(coap_context_t *context, coap_address_t *peer,
  91                     coap_pdu_t *request, unsigned char flags, void *data);
  92
  93 /**
  94  * Removes the state object identified by @p id from @p context. The
  95  * removed object is returned in @p s, if found. Otherwise, @p s is
  96  * undefined. This function returns @c 1 if the object was removed, @c
  97  * 0 otherwise. Note that the storage allocated for the stored object
  98  * is not released by this functions. You will have to call
  99  * coap_free_async() to do so.
 100  *
 101  * @param context The context where the async object is registered.
 102  * @param id      The identifier of the asynchronous transaction.
 103  * @param s       Will be set to the object identified by @p id
 104  * after removal.
 105  *
 106  * @return @c 1 if object was removed and @p s updated, or @c 0 if no
 107  * object was found with the given id. @p s is valid only if the
 108  * return value is @c 1.
 109  */
 110 int coap_remove_async(coap_context_t *context, coap_tid_t id,
 111                       coap_async_state_t **s);
 112
 113 /**
 114  * Releases the memory that was allocated by coap_async_state_init()
 115  * for the object @p s. The registered application data will be
 116  * released automatically if COAP_ASYNC_RELEASE_DATA is set.
 117  *
 118  * @param s The object to delete.
 119  */
 120 void
 121 coap_free_async(coap_async_state_t *state);
 122
 123 /**
 124  * Retrieves the object identified by @p id from the list of asynchronous
 125  * transactions that are registered with @p context. This function returns
 126  * a pointer to that object or @c NULL if not found.
 127  *
 128  * @param context The context where the asynchronous objects are
 129  * registered with.
 130  * @param id      The id of the object to retrieve.
 131  *
 132  * @return A pointer to the object identified by @p id or @c NULL if
 133  * not found.
 134  */
 135 coap_async_state_t *coap_find_async(coap_context_t *context, coap_tid_t id);
 136
 137 /**
 138  * Updates the time stamp of @p s.
 139  *
 140  * @param s The state object to update.
 141  */
 142 static inline void
 143 coap_touch_async(coap_async_state_t *s) { coap_ticks(&s->created); }
 144
 145 /** @} */
 146
 147 #endif /*  WITHOUT_ASYNC */
 148
 149 #endif /* _COAP_ASYNC_H_ */