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 #ifndef OC_CLIENT_CB
  23 #define OC_CLIENT_CB
  24
  25 #include "ocstack.h"
  26
  27 #include "ocresource.h"
  28 #include "cacommon.h"
  29
  30 typedef struct OCPresence
  31 {
  32     // This is the TTL associated with presence
  33     uint32_t TTL;
  34     uint32_t * timeOut;
  35     uint32_t TTLlevel;
  36 } OCPresence;
  37
  38 typedef struct OCMulticastNode
  39 {
  40     char * uri;
  41     uint32_t nonce;
  42     struct OCMulticastNode * next;
  43 } OCMulticastNode;
  44
  45 typedef struct resourcetype_t OCResourceType;
  46
  47 typedef struct ClientCB {
  48     // callback method defined in application address space
  49     OCClientResponseHandler callBack;
  50     // callback context data
  51     void * context;
  52     // callback method to delete context data
  53     OCClientContextDeleter deleteCallback;
  54     //  when a response is recvd with this token, above callback will be invoked
  55     CAToken_t token;
  56     // a response is recvd with this token length
  57     uint8_t tokenLength;
  58     // Invocation handle tied to original call to OCDoResource()
  59     OCDoHandle handle;
  60     // This is used to determine if all responses should be consumed or not.
  61     // (For now, only pertains to OC_REST_OBSERVE_ALL Vs. OC_REST_OBSERVE functionality)
  62     OCMethod method;
  63     // This is the sequence identifier the server applies to the invocation tied to 'handle'.
  64     uint32_t sequenceNumber;
  65     // The canonical form of the request uri associated with the call back
  66     char * requestUri;
  67     // Remote address complete
  68     OCDevAddr * devAddr;
  69     // Struct to hold TTL info for presence
  70     #ifdef WITH_PRESENCE
  71     OCPresence * presence;
  72     OCResourceType * filterResourceType;
  73     #endif
  74     // The connectivity type on which the request was sent on.
  75     OCConnectivityType conType;
  76     // The TTL for this callback. Holds the time till when this callback can
  77     // still be used. TTL is set to 0 when the callback is for presence and observe.
  78     // Presence has ttl mechanism in the "presence" member of this struct and observes
  79     // can be explicitly cancelled.
  80     uint32_t TTL;
  81     // next node in this list
  82     struct ClientCB    *next;
  83 } ClientCB;
  84
  85 extern struct ClientCB *cbList;
  86
  87 /** @ingroup ocstack
  88  *
  89  * This method is used to add a client callback method in cbList.
  90  *
  91  * @param[out] clientCB
  92  *              The resulting node from making this call. Null if out of memory.
  93  * @param[in] cbData
  94  *              address to client callback function.
  95  * @param[in] token
  96  *              identifier for OTA CoAP comms.
  97  * @param[in] handle
  98  *              Masked in the public API as an 'invocation handle' - Used for callback management.
  99  * @param[in] method
 100  *              OCMethod via which this client callback is expected to operate
 101  * @param[in] requestUri
 102  *              the resource uri of the request.
 103  * @param[in] resourceType
 104  *              the resourceType associated with a presence request.
 105  * @param[in] conType
 106  *              the connectivity type on which the associated request for this clientCB was sent on.
 107  * @param[in] ttl
 108  *              time to live in coap_ticks for the callback.
 109  * @brief If the handle you're looking for does not exist, the stack will reply with a RST message.
 110  *
 111  * @return OC_STACK_OK for Success, otherwise some error value
 112  */
 113 OCStackResult
 114 AddClientCB (ClientCB** clientCB, OCCallbackData* cbData,
 115              CAToken_t token, uint8_t tokenLength,
 116              OCDoHandle *handle, OCMethod method,
 117              OCDevAddr *devAddr, char * requestUri,
 118              char * resourceTypeName, uint32_t ttl);
 119
 120 /** @ingroup ocstack
 121  *
 122  * This method is used to remove a callback node from cbList.
 123  *
 124  * @param[in] cbNode
 125  *              address to client callback node.
 126  */
 127 void DeleteClientCB(ClientCB *cbNode);
 128
 129
 130 /** @ingroup ocstack
 131  *
 132  * This method is used to search and retrieve a cb node in cbList.
 133  *
 134  * @param[in] token
 135  *              token to search for.
 136  * @param[in] handle
 137  *              handle to search for.
 138  * @param[in] requestUri
 139  *              Uri to search for.
 140  *
 141  * @brief You can search by token OR by handle, but not both.
 142  *
 143  * @return address of the node if found, otherwise NULL
 144  */
 145 ClientCB* GetClientCB(const CAToken_t token, uint8_t tokenLength,
 146         OCDoHandle handle, const char * requestUri);
 147
 148 /**
 149  * Inserts a new resource type filter into this cb node.
 150  *
 151  * @param[in] cbNode
 152  *              the node to add the new resourceType filter to
 153  * @param[in] resourceTypeName
 154  *              the value to create the new resourceType filter from
 155  *
 156  * @return
 157  *      OC_STACK_OK on success
 158  *      OC_STACK_ERROR with invalid parameters
 159  *      OC_STACK_NO_MEMORY when out of memory
 160  */
 161 #ifdef WITH_PRESENCE
 162 OCStackResult InsertResourceTypeFilter(ClientCB * cbNode, char * resourceTypeName);
 163 #endif // WITH_PRESENCE
 164
 165 /** @ingroup ocstack
 166  *
 167  * This method is used to clear the cbList.
 168  *
 169  */
 170 void DeleteClientCBList();
 171
 172 /** @ingroup ocstack
 173  *
 174  * This method is used to verify the presence of a cb node in cbList
 175  * and then delete it.
 176  *
 177  * @param[in] cbNode
 178  *              address to client callback node.
 179  */
 180 void FindAndDeleteClientCB(ClientCB * cbNode);
 181
 182 /** @ingroup ocstack
 183  *
 184  * This method is used to search a multicast presence node from list.
 185  *
 186  * @param[in]  uri
 187  *              the uri of the request.
 188  *
 189  * @return OCMulticastNode
 190  *              The resulting node from making this call. Null if doesn't exist.
 191  */
 192 //------------------------------------------------------------------------
 193 OCMulticastNode* GetMCPresenceNode(const char * uri);
 194
 195 /** @ingroup ocstack
 196  *
 197  * This method is used to add a multicast presence node to the list.
 198  *
 199  * @param[out] outnode
 200  *              The resulting node from making this call. Null if out of memory.
 201  * @param[in] uri
 202  *              the uri of the server.
 203  * @param[in] nonce
 204  *              current nonce for the server
 205  *
 206  * @return OC_STACK_OK for Success, otherwise some error value
 207  */
 208 //------------------------------------------------------------------------
 209 OCStackResult AddMCPresenceNode(OCMulticastNode** outnode, char* uri, uint32_t nonce);
 210
 211 #endif //OC_CLIENT_CB
 212