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
  83     /** requested payload encoding format. */
  84     OCPayloadFormat acceptFormat;
  85
  86 } ResourceObserver;
  87
  88 #ifdef WITH_PRESENCE
  89 /**
  90  * Create an observe response and send to all observers in the observe list.
  91  *
  92  * @param method          RESTful method.
  93  * @param resPtr          Observed resource.
  94  * @param maxAge          Time To Live (in seconds) of observation.
  95  * @param resourceType    Resource type.  Allows resource type name to be added to response.
  96  * @param qos             Quality of service of resource.
  97  *
  98  * @return ::OC_STACK_OK on success, some other value upon failure.
  99  */
 100 OCStackResult SendAllObserverNotification (OCMethod method, OCResource *resPtr, uint32_t maxAge,
 101         OCPresenceTrigger trigger, OCResourceType *resourceType, OCQualityOfService qos);
 102 #else
 103 /**
 104  * Create an observe response and send to all observers in the observe list.
 105  *
 106  * @param method RESTful method.
 107  * @param resPtr Observed resource.
 108  * @param maxAge Time To Live (in seconds) of observation.
 109  * @param qos Quality of service of resource.
 110  *
 111  * @return ::OC_STACK_OK on success, some other value upon failure.
 112  */
 113 OCStackResult SendAllObserverNotification (OCMethod method, OCResource *resPtr, uint32_t maxAge,
 114         OCQualityOfService qos);
 115 #endif
 116
 117 /**
 118  * Notify specific observers with updated value of representation.
 119  *
 120  * @param resource                  Observed resource.
 121  * @param obsIdList                 List of observation ids that need to be notified.
 122  * @param numberOfIds               Number of observation ids included in obsIdList.
 123  * @param notificationJSONPayload   JSON encoded payload to send in notification.
 124  * @param maxAge                    Time To Live (in seconds) of observation.
 125  * @param qos                       Desired quality of service of the observation notifications.
 126  *
 127  * @return ::OC_STACK_OK on success, some other value upon failure.
 128  */
 129 OCStackResult SendListObserverNotification (OCResource * resource,
 130         OCObservationId  *obsIdList, uint8_t numberOfIds,
 131         const OCRepPayload *payload, uint32_t maxAge,
 132         OCQualityOfService qos);
 133
 134 /**
 135  * Delete all observers in the observe list.
 136  */
 137 void DeleteObserverList();
 138
 139 /**
 140  * Create a unique observation ID.
 141  *
 142  * @param observationId           Pointer to generated ID.
 143  *
 144  * @return ::OC_STACK_OK on success, some other value upon failure.
 145  */
 146 OCStackResult GenerateObserverId (OCObservationId *observationId);
 147
 148 /**
 149  * Add observer for a resource.
 150  *
 151  * @param resUri          Resource URI string.
 152  * @param query           Query string.
 153  * @param obsId           Observation ID.
 154  * @param token           Request token.
 155  * @param tokenLength     Length of token.
 156  * @param resHandle       Resource handle.
 157  * @param qos             Quality of service of observation.
 158  * @param devAddr         Device address.
 159  *
 160  * @return ::OC_STACK_OK on success, some other value upon failure.
 161  */
 162 OCStackResult AddObserver (const char         *resUri,
 163                            const char         *query,
 164                            OCObservationId    obsId,
 165                            CAToken_t          token,
 166                            uint8_t            tokenLength,
 167                            OCResource         *resHandle,
 168                            OCQualityOfService qos,
 169                            OCPayloadFormat    acceptFormat,
 170                            const OCDevAddr    *devAddr);
 171
 172 /**
 173  * Delete observer with specified token from list of observers.
 174  * Free memory that was allocated for the observer in the list.
 175  *
 176  * @param token Token to search for.
 177  * @param tokenLength Length of token.
 178  *
 179  * @return ::OC_STACK_OK on success, some other value upon failure.
 180  */
 181  OCStackResult DeleteObserverUsingToken (CAToken_t token, uint8_t tokenLength);
 182
 183 /**
 184  * Search the list of observers for the specified token.
 185  *
 186  * @param token            Token to search for.
 187  * @param tokenLength      Length of token.
 188  *
 189  * @return Pointer to found observer.
 190  */
 191 ResourceObserver* GetObserverUsingToken (const CAToken_t token, uint8_t tokenLength);
 192
 193 /**
 194  * Search the list of observers for the specified observe ID.
 195  *
 196  * @param observeId        Observer ID to search for.
 197  *
 198  * @return Pointer to found observer.
 199  */
 200 ResourceObserver* GetObserverUsingId (const OCObservationId observeId);
 201
 202 /**
 203  *  Add observe header option to a request.
 204  *
 205  * @param caHdrOpt        Target request CA header option.
 206  * @param ocHdrOpt        Pointer to existing options.
 207  * @param numOptions      Number of existing options.
 208  * @param observeFlag     Register/de-register observation.  Should be either
 209  *                        ::OC_OBSERVE_REGISTER or ::OC_OBSERVE_DEREGISTER.
 210  *
 211  * @return ::OC_STACK_OK on success, some other value upon failure.
 212  */
 213 OCStackResult
 214 CreateObserveHeaderOption (CAHeaderOption_t **caHdrOpt,
 215                            OCHeaderOption *ocHdrOpt,
 216                            uint8_t numOptions,
 217                            uint8_t observeFlag);
 218
 219 /**
 220  *  Copy the observe option from a received request.
 221  *
 222  * @param observationOption      Pointer to observe option value.  Should be either
 223  *                               ::OC_OBSERVE_REGISTER, ::OC_OBSERVE_DEREGISTER, or
 224  *                               ::OC_OBSERVE_NO_OPTION if observe not found.
 225  *
 226  * @param options                Options in received request.  Observe option is removed if found.
 227  * @param numOptions             Number of options in the received request.  Decremented if observe
 228  *                               option is extracted.
 229  *
 230  * @return ::OC_STACK_OK on success, some other value upon failure.
 231  */
 232 OCStackResult
 233 GetObserveHeaderOption (uint32_t * observationOption,
 234                         CAHeaderOption_t *options,
 235                         uint8_t * numOptions);
 236
 237 #endif //OC_OBSERVE_H
 238