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