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