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