resource/csdk/stack/include/internal/occlientcb.h

   1 //*******************************************************************
   2 //
   3 // Copyright 2014 Intel Mobile Communications GmbH All Rights Reserved.
   4 //
   5 //
   6 //
   7 // Licensed under the Apache License, Version 2.0 (the "License");
   8 // you may not use this file except in compliance with the License.
   9 // You may obtain a copy of the License at
  10 //
  11 //      http://www.apache.org/licenses/LICENSE-2.0
  12 //
  13 // Unless required by applicable law or agreed to in writing, software
  14 // distributed under the License is distributed on an "AS IS" BASIS,
  15 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16 // See the License for the specific language governing permissions and
  17 // limitations under the License.
  18 //
  19 //
  20 // ******************************************************************/
  21
  22
  23 /**
  24  * @file
  25  *
  26  * This file contains the definition and types for client's callback mode and functions.
  27  *
  28  */
  29
  30
  31 #ifndef OC_CLIENT_CB
  32 #define OC_CLIENT_CB
  33
  34 #include "ocstack.h"
  35
  36 #include "ocresource.h"
  37 #include "cacommon.h"
  38
  39 /**
  40  * Data structure For presence Discovery.
  41  * This is the TTL associated with presence.
  42  */
  43 typedef struct OCPresence
  44 {
  45     /** Time to Live. */
  46     uint32_t TTL;
  47
  48     /** Time out. */
  49     uint32_t * timeOut;
  50
  51     /** TTL Level. */
  52     uint32_t TTLlevel;
  53 } OCPresence;
  54
  55 /**
  56  * Data structure to hold Multicast node identity for resource discovery.
  57  */
  58 typedef struct OCMulticastNode
  59 {
  60     /** URI of new resource.*/
  61     char * uri;
  62
  63     /** URI of new resource that entity handler might create.*/
  64     uint32_t nonce;
  65
  66     /** Linked list; for multicast nodes.*/
  67     struct OCMulticastNode * next;
  68 } OCMulticastNode;
  69
  70 /**
  71  * Forward declaration of resource type.
  72  */
  73 typedef struct resourcetype_t OCResourceType;
  74
  75
  76 /**
  77  * Data structure for holding client's callback context, methods and Time to Live,
  78  * connectivity Types, presence and resource type, request uri etc.
  79  */
  80
  81 typedef struct ClientCB {
  82     /** callback method defined in application address space. */
  83     OCClientResponseHandler callBack;
  84
  85     /** callback context data. */
  86     void * context;
  87
  88     /** callback method to delete context data. */
  89     OCClientContextDeleter deleteCallback;
  90
  91     /**  when a response is recvd with this token, above callback will be invoked. */
  92     CAToken_t token;
  93
  94     /** a response is recvd with this token length.*/
  95     uint8_t tokenLength;
  96
  97     /** Invocation handle tied to original call to OCDoResource().*/
  98     OCDoHandle handle;
  99
 100     /** This is used to determine if all responses should be consumed or not.
 101      * (For now, only pertains to OC_REST_OBSERVE_ALL vs. OC_REST_OBSERVE functionality).*/
 102     OCMethod method;
 103
 104     /** This is the sequence identifier the server applies to the invocation tied to 'handle'.*/
 105     uint32_t sequenceNumber;
 106
 107     /** The canonical form of the request uri associated with the call back.*/
 108     char * requestUri;
 109
 110     /** Remote address complete.*/
 111     OCDevAddr * devAddr;
 112
 113     /** Struct to hold TTL info for presence.*/
 114
 115     #ifdef WITH_PRESENCE
 116     OCPresence * presence;
 117     OCResourceType * filterResourceType;
 118     #endif
 119
 120     /** The connectivity type on which the request was sent on.*/
 121     OCConnectivityType conType;
 122
 123     /** The TTL for this callback. Holds the time till when this callback can
 124      * still be used. TTL is set to 0 when the callback is for presence and observe.
 125      * Presence has ttl mechanism in the "presence" member of this struct and observes
 126      * can be explicitly cancelled.*/
 127     uint32_t TTL;
 128
 129     /** next node in this list.*/
 130     struct ClientCB    *next;
 131 } ClientCB;
 132
 133 /**
 134  * Linked list of ClientCB node.
 135  */
 136 extern struct ClientCB *cbList;
 137
 138 /** @ingroup ocstack
 139  *
 140  * This method is used to add a client callback method in cbList.
 141  *
 142  * @param[out] clientCB          The resulting node from making this call. Null if out of memory.
 143  * @param[in] cbData             Address to client callback function.
 144  * @param[in] token              Identifier for OTA CoAP comms.
 145  * @param[in] tokenLength        Length for OTA CoAP comms.
 146  * @param[in] handle             masked in the public API as an 'invocation handle'
 147  *                               Used for callback management.
 148  * @param[in] method             A method via which this client callback is expected to operate
 149  * @param[in] devAddr            The Device address.
 150  * @param[in] requestUri         The resource uri of the request.
 151  * @param[in] resourceTypeName   The resource type associated with a presence request.
 152  * @param[in] ttl           time to live in coap_ticks for the callback.
 153  *
 154  * @note If the handle you're looking for does not exist, the stack will reply with a RST message.
 155  *
 156  * @return OC_STACK_OK for Success, otherwise some error value.
 157  */
 158 OCStackResult
 159 AddClientCB (ClientCB** clientCB, OCCallbackData* cbData,
 160              CAToken_t token, uint8_t tokenLength,
 161              OCDoHandle *handle, OCMethod method,
 162              OCDevAddr *devAddr, char * requestUri,
 163              char * resourceTypeName, uint32_t ttl);
 164
 165 /** @ingroup ocstack
 166  *
 167  * This method is used to remove a callback node from cbList.
 168  *
 169  * @param[in] cbNode        Address to client callback node.
 170  */
 171 void DeleteClientCB(ClientCB *cbNode);
 172
 173
 174 /** @ingroup ocstack
 175  *
 176  * This method is used to search and retrieve a cb node in cbList.
 177  *
 178  * @param[in] token        Token to search for.
 179  * @param[in] tokenLength  The Length of the token.
 180  * @param[in] handle       Handle to search for.
 181  * @param[in] requestUri   Uri to search for.
 182  *
 183  * @brief You can search by token OR by handle, but not both.
 184  *
 185  * @return address of the node if found, otherwise NULL
 186  */
 187 ClientCB* GetClientCB(const CAToken_t token, uint8_t tokenLength,
 188         OCDoHandle handle, const char * requestUri);
 189
 190 #ifdef WITH_PRESENCE
 191 /**
 192  * Inserts a new resource type filter into this cb node.
 193  *
 194  * @param[in] cbNode              the node to add the new resourceType filter to.
 195  * @param[in] resourceTypeName    the value to create the new resourceType filter from.
 196  *
 197  * @return
 198  *      OC_STACK_OK on success
 199  *      OC_STACK_ERROR with invalid parameters
 200  *      OC_STACK_NO_MEMORY when out of memory
 201  */
 202
 203 OCStackResult InsertResourceTypeFilter(ClientCB * cbNode, char * resourceTypeName);
 204 #endif // WITH_PRESENCE
 205
 206 /** @ingroup ocstack
 207  *
 208  * This method is used to clear the cbList.
 209  *
 210  */
 211 void DeleteClientCBList();
 212
 213 /** @ingroup ocstack
 214  *
 215  * This method is used to verify the presence of a cb node in cbList
 216  * and then delete it.
 217  *
 218  * @param[in] cbNode    Address to client callback node.
 219  */
 220 void FindAndDeleteClientCB(ClientCB * cbNode);
 221
 222 /** @ingroup ocstack
 223  *
 224  * This method is used to search a multicast presence node from list.
 225  *
 226  * @param[in]  uri   the uri of the request.
 227  *
 228  * @return OCMulticastNode
 229  *              The resulting node from making this call. Null if doesn't exist.
 230  */
 231
 232 OCMulticastNode* GetMCPresenceNode(const char * uri);
 233
 234 /** @ingroup ocstack
 235  *
 236  * This method is used to add a multicast presence node to the list.
 237  * @param[out] outnode  the resulting node from making this call. Null if out of memory.
 238  * @param[in] uri       the uri of the server.
 239  * @param[in] nonce     current nonce for the server
 240  *
 241  * @return OC_STACK_OK for Success, otherwise some error value
 242  */
 243
 244 OCStackResult AddMCPresenceNode(OCMulticastNode** outnode, char* uri, uint32_t nonce);
 245
 246 #endif //OC_CLIENT_CB
 247