resource/csdk/stack/include/internal/ocobserve.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  * @file
  23  *
  24  * This file contains the data structure and APIs for registered resource as an observer.
  25  *
  26  */
  27
  28
  29 #ifndef OC_OBSERVE_H
  30 #define OC_OBSERVE_H
  31
  32 /** Maximum number of observers to reach */
  33
  34 #define MAX_OBSERVER_FAILED_COMM         (2)
  35
  36 /** Maximum number of observers to reach for resources with low QOS */
  37 #define MAX_OBSERVER_NON_COUNT           (3)
  38
  39 /**
  40  *  MAX_OBSERVER_TTL_SECONDS sets the maximum time to live (TTL) for notification.
  41  *  60 sec/min * 60 min/hr * 24 hr/day
  42  */
  43 #define MAX_OBSERVER_TTL_SECONDS     (60 * 60 * 24)
  44
  45 #define MILLISECONDS_PER_SECOND   (1000)
  46
  47 /**
  48  * Data structure to hold informations for each registered observer.
  49  */
  50 typedef struct ResourceObserver
  51 {
  52     /** Observation Identifier for request.*/
  53     OCObservationId observeId;
  54
  55     /** URI of observed resource.*/
  56     char *resUri;
  57
  58     /** Query.*/
  59     char *query;
  60
  61     /** token for the observe request.*/
  62     CAToken_t token;
  63
  64     /** token length for the observe request.*/
  65     uint8_t tokenLength;
  66
  67     /** Resource handle.*/
  68     OCResource *resource;
  69
  70     /** Remote Endpoint. */
  71     OCDevAddr devAddr;
  72
  73     /** Quality of service of the request.*/
  74     OCQualityOfService qos;
  75
  76     /** number of times the server failed to reach the observer.*/
  77     uint8_t failedCommCount;
  78
  79     /** number of times the server sent NON notifications.*/
  80     uint8_t lowQosCount;
  81
  82     /** force the qos value to CON.*/
  83     uint8_t forceHighQos;
  84
  85     /** The TTL for this callback. TTL is set to 24 hours.
  86      * A server send a notification in a confirmable message every 24 hours.
  87      * This prevents a client that went away or is no logger interested
  88      * from remaining in the list of observers indefinitely.*/
  89     uint32_t TTL;
  90
  91     /** next node in this list.*/
  92     struct ResourceObserver *next;
  93
  94     /** requested payload encoding format. */
  95     OCPayloadFormat acceptFormat;
  96
  97 } ResourceObserver;
  98
  99 /**
 100  *  Initialize observer list.
 101  *
 102  * @return ::OC_STACK_OK on success, some other value upon failure.
 103  */
 104 OCStackResult InitializeObserverList();
 105
 106 /**
 107  *  Terminate observer list.
 108  */
 109 void TerminateObserverList();
 110
 111 #ifdef WITH_PRESENCE
 112 /**
 113  * Create an observe response and send to all observers in the observe list.
 114  *
 115  * @param method          RESTful method.
 116  * @param resPtr          Observed resource.
 117  * @param maxAge          Time To Live (in seconds) of observation.
 118  * @param resourceType    Resource type.  Allows resource type name to be added to response.
 119  * @param qos             Quality of service of resource.
 120  *
 121  * @return ::OC_STACK_OK on success, some other value upon failure.
 122  */
 123 OCStackResult SendAllObserverNotification (OCMethod method, OCResource *resPtr, uint32_t maxAge,
 124         OCPresenceTrigger trigger, OCResourceType *resourceType, OCQualityOfService qos);
 125 #else
 126 /**
 127  * Create an observe response and send to all observers in the observe list.
 128  *
 129  * @param method RESTful method.
 130  * @param resPtr Observed resource.
 131  * @param maxAge Time To Live (in seconds) of observation.
 132  * @param qos Quality of service of resource.
 133  *
 134  * @return ::OC_STACK_OK on success, some other value upon failure.
 135  */
 136 OCStackResult SendAllObserverNotification (OCMethod method, OCResource *resPtr, uint32_t maxAge,
 137         OCQualityOfService qos);
 138 #endif
 139
 140 /**
 141  * Notify specific observers with updated value of representation.
 142  *
 143  * @param resource                  Observed resource.
 144  * @param obsIdList                 List of observation ids that need to be notified.
 145  * @param numberOfIds               Number of observation ids included in obsIdList.
 146  * @param notificationJSONPayload   JSON encoded payload to send in notification.
 147  * @param maxAge                    Time To Live (in seconds) of observation.
 148  * @param qos                       Desired quality of service of the observation notifications.
 149  *
 150  * @return ::OC_STACK_OK on success, some other value upon failure.
 151  */
 152 OCStackResult SendListObserverNotification (OCResource * resource,
 153         OCObservationId  *obsIdList, uint8_t numberOfIds,
 154         const OCRepPayload *payload, uint32_t maxAge,
 155         OCQualityOfService qos);
 156
 157 /**
 158  * Delete all observers in the observe list.
 159  */
 160 void DeleteObserverList();
 161
 162 /**
 163  * Create a unique observation ID.
 164  *
 165  * @param observationId           Pointer to generated ID.
 166  *
 167  * @return ::OC_STACK_OK on success, some other value upon failure.
 168  */
 169 OCStackResult GenerateObserverId (OCObservationId *observationId);
 170
 171 /**
 172  * Add observer for a resource.
 173  *
 174  * @param resUri          Resource URI string.
 175  * @param query           Query string.
 176  * @param obsId           Observation ID.
 177  * @param token           Request token.
 178  * @param tokenLength     Length of token.
 179  * @param resHandle       Resource handle.
 180  * @param qos             Quality of service of observation.
 181  * @param devAddr         Device address.
 182  *
 183  * @return ::OC_STACK_OK on success, some other value upon failure.
 184  */
 185 OCStackResult AddObserver (const char         *resUri,
 186                            const char         *query,
 187                            OCObservationId    obsId,
 188                            CAToken_t          token,
 189                            uint8_t            tokenLength,
 190                            OCResource         *resHandle,
 191                            OCQualityOfService qos,
 192                            OCPayloadFormat    acceptFormat,
 193                            const OCDevAddr    *devAddr);
 194
 195 /**
 196  * Delete observer with specified token from list of observers.
 197  * Free memory that was allocated for the observer in the list.
 198  *
 199  * @param token Token to search for.
 200  * @param tokenLength Length of token.
 201  *
 202  * @return ::OC_STACK_OK on success, some other value upon failure.
 203  */
 204  OCStackResult DeleteObserverUsingToken (CAToken_t token, uint8_t tokenLength);
 205
 206  /**
 207   * Delete observer with device address from list of observers.
 208   * Free memory that was allocated for the observer in the list.
 209   *
 210   * @param devAddr Device's address.
 211   *
 212   * @return ::OC_STACK_OK on success, some other value upon failure.
 213   */
 214 OCStackResult DeleteObserverUsingDevAddr(const OCDevAddr *devAddr);
 215
 216 /**
 217  * Delete all observers of a resource.
 218  *
 219  * @param resource Handle of resource whose observers needs to be deleted.
 220  *
 221  * @return ::OC_STACK_OK on success, some other value upon failure.
 222  */
 223 OCStackResult DeleteObserverUsingResource(OCResource *res);
 224
 225 /**
 226  * Search the list of observers for the specified token.
 227  *
 228  * @param token            Token to search for.
 229  * @param tokenLength      Length of token.
 230  *
 231  * @return Pointer to found observer.
 232  * This is copy of observer, caller must release its memory using FreeObserver().
 233  */
 234 ResourceObserver* GetObserverUsingToken (const CAToken_t token, uint8_t tokenLength);
 235
 236 /**
 237  * Search the list of observers for the specified observe ID.
 238  *
 239  * @param observeId        Observer ID to search for.
 240  *
 241  * @return Pointer to found observer.
 242  * This is copy of observer, caller must release its memory using FreeObserver().
 243  */
 244 ResourceObserver* GetObserverUsingId (const OCObservationId observeId);
 245
 246 /**
 247  * Search the list of observers for the specified observe ID.
 248  *
 249  * @param observeId        Observer ID to search for.
 250  *
 251  * @return true if observer found matched with observer ID, otherwise false.
 252  */
 253 bool IsObserverAvailable (const OCObservationId observeId);
 254
 255 /**
 256  *  Add observe header option to a request.
 257  *
 258  * @param caHdrOpt        Target request CA header option.
 259  * @param ocHdrOpt        Pointer to existing options.
 260  * @param numOptions      Number of existing options.
 261  * @param observeFlag     Register/de-register observation.  Should be either
 262  *                        ::OC_OBSERVE_REGISTER or ::OC_OBSERVE_DEREGISTER.
 263  *
 264  * @return ::OC_STACK_OK on success, some other value upon failure.
 265  */
 266 OCStackResult
 267 CreateObserveHeaderOption (CAHeaderOption_t **caHdrOpt,
 268                            OCHeaderOption *ocHdrOpt,
 269                            uint8_t numOptions,
 270                            uint8_t observeFlag);
 271
 272 /**
 273  *  Copy the observe option from a received request.
 274  *
 275  * @param observationOption      Pointer to observe option value.  Should be either
 276  *                               ::OC_OBSERVE_REGISTER, ::OC_OBSERVE_DEREGISTER, or
 277  *                               ::OC_OBSERVE_NO_OPTION if observe not found.
 278  *
 279  * @param options                Options in received request.  Observe option is removed if found.
 280  * @param numOptions             Number of options in the received request.  Decremented if observe
 281  *                               option is extracted.
 282  *
 283  * @return ::OC_STACK_OK on success, some other value upon failure.
 284  */
 285 OCStackResult
 286 GetObserveHeaderOption (uint32_t * observationOption,
 287                         CAHeaderOption_t *options,
 288                         uint8_t * numOptions);
 289
 290 /**
 291  *  Free memory associated with observer.
 292  *
 293  * @param obsNode        Observer to be freed.
 294  */
 295 void FreeObserver (ResourceObserver* obsNode);
 296
 297 #endif //OC_OBSERVE_H
 298