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