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 /** Sequence number is a 24 bit field, per https://tools.ietf.org/html/draft-ietf-core-observe-16.*/
  33 #define MAX_SEQUENCE_NUMBER              (0xFFFFFF)
  34
  35 /** Maximum number of observers to reach */
  36
  37 #define MAX_OBSERVER_FAILED_COMM         (2)
  38
  39 /** Maximum number of observers to reach for resources with low QOS */
  40 #define MAX_OBSERVER_NON_COUNT           (3)
  41
  42 /**
  43  * Data structure to hold informations for each registered observer.
  44  */
  45 typedef struct ResourceObserver
  46 {
  47     /** Observation Identifier for request.*/
  48     OCObservationId observeId;
  49
  50     /** URI of observed resource.*/
  51     char *resUri;
  52
  53     /** Query.*/
  54     char *query;
  55
  56     /** token for the observe request.*/
  57     CAToken_t token;
  58
  59     /** token length for the observe request.*/
  60     uint8_t tokenLength;
  61
  62     /** Resource handle.*/
  63     OCResource *resource;
  64
  65     /** Remote Endpoint. */
  66     OCDevAddr devAddr;
  67
  68     /** Quality of service of the request.*/
  69     OCQualityOfService qos;
  70
  71     /** number of times the server failed to reach the observer.*/
  72     uint8_t failedCommCount;
  73
  74     /** number of times the server sent NON notifications.*/
  75     uint8_t lowQosCount;
  76
  77     /** force the qos value to CON.*/
  78     uint8_t forceHighQos;
  79
  80     /** next node in this list.*/
  81     struct ResourceObserver *next;
  82 } ResourceObserver;
  83
  84 #ifdef WITH_PRESENCE
  85 /**
  86  * Create an observe response and send to all observers in the observe list.
  87  *
  88  * @param method          RESTful method.
  89  * @param resPtr          Observed resource.
  90  * @param maxAge          Time To Live (in seconds) of observation.
  91  * @param resourceType    Resource type.  Allows resource type name to be added to response.
  92  * @param qos             Quality of service of resource.
  93  *
  94  * @return ::OC_STACK_OK on success, some other value upon failure.
  95  */
  96 OCStackResult SendAllObserverNotification (OCMethod method, OCResource *resPtr, uint32_t maxAge,
  97         OCPresenceTrigger trigger, OCResourceType *resourceType, OCQualityOfService qos);
  98 #else
  99 /**
 100  * Create an observe response and send to all observers in the observe list.
 101  *
 102  * @param method RESTful method.
 103  * @param resPtr Observed resource.
 104  * @param maxAge Time To Live (in seconds) of observation.
 105  * @param qos Quality of service of resource.
 106  *
 107  * @return ::OC_STACK_OK on success, some other value upon failure.
 108  */
 109 OCStackResult SendAllObserverNotification (OCMethod method, OCResource *resPtr, uint32_t maxAge,
 110         OCQualityOfService qos);
 111 #endif
 112
 113 /**
 114  * Notify specific observers with updated value of representation.
 115  *
 116  * @param resource                  Observed resource.
 117  * @param obsIdList                 List of observation ids that need to be notified.
 118  * @param numberOfIds               Number of observation ids included in obsIdList.
 119  * @param notificationJSONPayload   JSON encoded payload to send in notification.
 120  * @param maxAge                    Time To Live (in seconds) of observation.
 121  * @param qos                       Desired quality of service of the observation notifications.
 122  *
 123  * @return ::OC_STACK_OK on success, some other value upon failure.
 124  */
 125 OCStackResult SendListObserverNotification (OCResource * resource,
 126         OCObservationId  *obsIdList, uint8_t numberOfIds,
 127         const OCRepPayload *payload, uint32_t maxAge,
 128         OCQualityOfService qos);
 129
 130 /**
 131  * Delete all observers in the observe list.
 132  */
 133 void DeleteObserverList();
 134
 135 /**
 136  * Create a unique observation ID.
 137  *
 138  * @param observationId           Pointer to generated ID.
 139  *
 140  * @return ::OC_STACK_OK on success, some other value upon failure.
 141  */
 142 OCStackResult GenerateObserverId (OCObservationId *observationId);
 143
 144 /**
 145  * Add observer for a resource.
 146  *
 147  * @param resUri          Resource URI string.
 148  * @param query           Query string.
 149  * @param obsId           Observation ID.
 150  * @param token           Request token.
 151  * @param tokenLength     Length of token.
 152  * @param resHandle       Resource handle.
 153  * @param qos             Quality of service of observation.
 154  * @param devAddr         Device address.
 155  *
 156  * @return ::OC_STACK_OK on success, some other value upon failure.
 157  */
 158 OCStackResult AddObserver (const char         *resUri,
 159                            const char         *query,
 160                            OCObservationId    obsId,
 161                            CAToken_t          token,
 162                            uint8_t            tokenLength,
 163                            OCResource         *resHandle,
 164                            OCQualityOfService qos,
 165                            const OCDevAddr    *devAddr);
 166
 167 /**
 168  * Delete observer with specified token from list of observers.
 169  * Free memory that was allocated for the observer in the list.
 170  *
 171  * @param token Token to search for.
 172  * @param tokenLength Length of token.
 173  *
 174  * @return ::OC_STACK_OK on success, some other value upon failure.
 175  */
 176  OCStackResult DeleteObserverUsingToken (CAToken_t token, uint8_t tokenLength);
 177
 178 /**
 179  * Search the list of observers for the specified token.
 180  *
 181  * @param token            Token to search for.
 182  * @param tokenLength      Length of token.
 183  *
 184  * @return Pointer to found observer.
 185  */
 186 ResourceObserver* GetObserverUsingToken (const CAToken_t token, uint8_t tokenLength);
 187
 188 /**
 189  * Search the list of observers for the specified observe ID.
 190  *
 191  * @param observeId        Observer ID to search for.
 192  *
 193  * @return Pointer to found observer.
 194  */
 195 ResourceObserver* GetObserverUsingId (const OCObservationId observeId);
 196
 197 /**
 198  *  Add observe header option to a request.
 199  *
 200  * @param caHdrOpt        Target request CA header option.
 201  * @param ocHdrOpt        Pointer to existing options.
 202  * @param numOptions      Number of existing options.
 203  * @param observeFlag     Register/de-register observation.  Should be either
 204  *                        ::OC_OBSERVE_REGISTER or ::OC_OBSERVE_DEREGISTER.
 205  *
 206  * @return ::OC_STACK_OK on success, some other value upon failure.
 207  */
 208 OCStackResult
 209 CreateObserveHeaderOption (CAHeaderOption_t **caHdrOpt,
 210                            OCHeaderOption *ocHdrOpt,
 211                            uint8_t numOptions,
 212                            uint8_t observeFlag);
 213
 214 /**
 215  *  Copy the observe option from a received request.
 216  *
 217  * @param observationOption      Pointer to observe option value.  Should be either
 218  *                               ::OC_OBSERVE_REGISTER, ::OC_OBSERVE_DEREGISTER, or
 219  *                               ::OC_OBSERVE_NO_OPTION if observe not found.
 220  *
 221  * @param options                Options in received request.  Observe option is removed if found.
 222  * @param numOptions             Number of options in the received request.  Decremented if observe
 223  *                               option is extracted.
 224  *
 225  * @return ::OC_STACK_OK on success, some other value upon failure.
 226  */
 227 OCStackResult
 228 GetObserveHeaderOption (uint32_t * observationOption,
 229                         CAHeaderOption_t *options,
 230                         uint8_t * numOptions);
 231
 232 #endif //OC_OBSERVE_H
 233