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