resource/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 #if defined(__GNUC__) && !defined(__clang__) && !defined(__INTEL_COMPILER)
  55 #pragma GCC diagnostic push
  56 #pragma GCC diagnostic ignored "-pedantic"
  57 #endif
  58   __extension__ unsigned char token[];  /**< the token to use in a response */
  59 #if defined(__GNUC__) && !defined(__clang__) && !defined(__INTEL_COMPILER)
  60 #pragma GCC diagnostic pop
  61 #endif
  62 } coap_async_state_t;
  63
  64 /* Definitions for Async Status Flags These flags can be used to
  65  * control the behaviour of asynchronous response generation. */
  66 #define COAP_ASYNC_CONFIRM   0x01 /**< send confirmable response */
  67 #define COAP_ASYNC_SEPARATE  0x02 /**< send separate response */
  68 #define COAP_ASYNC_OBSERVED  0x04 /**< the resource is being observed */
  69
  70 /** release application data on destruction */
  71 #define COAP_ASYNC_RELEASE_DATA  0x08
  72
  73 /**
  74  * Allocates a new coap_async_state_t object and fills its fields
  75  * according to the given @p request. The @p flags are used to control
  76  * generation of empty ACK responses to stop retransmissions and to
  77  * release registered @p data when the resource is deleted by
  78  * coap_free_async().  This function returns a pointer to the registered
  79  * coap_async_t object or @c NULL on error. Note that this function will
  80  * return @c NULL in case that an object with the same identifier is
  81  * already registered.
  82  *
  83  * @param context  The context to use.
  84  * @param peer     The remote peer that is to be asynchronously notified.
  85  * @param request  The request that is handled asynchronously.
  86  * @param flags    Flags to control state management.
  87  * @param data     Opaque application data to register. Note that the
  88  *                 storage occupied by @p data is released on destruction
  89  *                 only if flag COAP_ASYNC_RELEASE_DATA is set.
  90  *
  91  * @return A pointer to the registered coap_async_state_t object or
  92  * @c NULL in case of an error.
  93  */
  94 coap_async_state_t *
  95 coap_register_async(coap_context_t *context, coap_address_t *peer,
  96                     coap_pdu_t *request, unsigned char flags, void *data);
  97
  98 /**
  99  * Removes the state object identified by @p id from @p context. The
 100  * removed object is returned in @p s, if found. Otherwise, @p s is
 101  * undefined. This function returns @c 1 if the object was removed, @c
 102  * 0 otherwise. Note that the storage allocated for the stored object
 103  * is not released by this functions. You will have to call
 104  * coap_free_async() to do so.
 105  *
 106  * @param context The context where the async object is registered.
 107  * @param id      The identifier of the asynchronous transaction.
 108  * @param s       Will be set to the object identified by @p id
 109  * after removal.
 110  *
 111  * @return @c 1 if object was removed and @p s updated, or @c 0 if no
 112  * object was found with the given id. @p s is valid only if the
 113  * return value is @c 1.
 114  */
 115 int coap_remove_async(coap_context_t *context, coap_tid_t id,
 116                       coap_async_state_t **s);
 117
 118 /**
 119  * Releases the memory that was allocated by coap_async_state_init()
 120  * for the object @p s. The registered application data will be
 121  * released automatically if COAP_ASYNC_RELEASE_DATA is set.
 122  *
 123  * @param s The object to delete.
 124  */
 125 void
 126 coap_free_async(coap_async_state_t *state);
 127
 128 /**
 129  * Retrieves the object identified by @p id from the list of asynchronous
 130  * transactions that are registered with @p context. This function returns
 131  * a pointer to that object or @c NULL if not found.
 132  *
 133  * @param context The context where the asynchronous objects are
 134  * registered with.
 135  * @param id      The id of the object to retrieve.
 136  *
 137  * @return A pointer to the object identified by @p id or @c NULL if
 138  * not found.
 139  */
 140 coap_async_state_t *coap_find_async(coap_context_t *context, coap_tid_t id);
 141
 142 /**
 143  * Updates the time stamp of @p s.
 144  *
 145  * @param s The state object to update.
 146  */
 147 static inline void
 148 coap_touch_async(coap_async_state_t *s) { coap_ticks(&s->created); }
 149
 150 /** @} */
 151
 152 #endif /*  WITHOUT_ASYNC */
 153
 154 #endif /* _COAP_ASYNC_H_ */