1 //********************************************************************
3 // Copyright 2014 Intel Mobile Communications GmbH All Rights Reserved.
5 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
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
11 // http://www.apache.org/licenses/LICENSE-2.0
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.
19 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
24 * This file contains the data structure and APIs for registered resource as an observer.
32 /** Maximum number of observers to reach */
34 #define MAX_OBSERVER_FAILED_COMM (2)
36 /** Maximum number of observers to reach for resources with low QOS */
37 #define MAX_OBSERVER_NON_COUNT (3)
40 * MAX_OBSERVER_TTL_SECONDS sets the maximum time to live (TTL) for notification.
41 * 60 sec/min * 60 min/hr * 24 hr/day
43 #define MAX_OBSERVER_TTL_SECONDS (60 * 60 * 24)
45 #define MILLISECONDS_PER_SECOND (1000)
48 * Data structure to hold informations for each registered observer.
50 typedef struct ResourceObserver
52 /** Observation Identifier for request.*/
53 OCObservationId observeId;
55 /** URI of observed resource.*/
61 /** token for the observe request.*/
64 /** token length for the observe request.*/
67 /** Resource handle.*/
70 /** Remote Endpoint. */
73 /** Quality of service of the request.*/
74 OCQualityOfService qos;
76 /** number of times the server failed to reach the observer.*/
77 uint8_t failedCommCount;
79 /** number of times the server sent NON notifications.*/
82 /** force the qos value to CON.*/
85 /** The TTL for this callback. TTL is set to 24 hours.
86 * A server send a notification in a confirmable message every 24 hours.
87 * This prevents a client that went away or is no logger interested
88 * from remaining in the list of observers indefinitely.*/
91 /** next node in this list.*/
92 struct ResourceObserver *next;
94 /** requested payload encoding format. */
95 OCPayloadFormat acceptFormat;
101 * Create an observe response and send to all observers in the observe list.
103 * @param method RESTful method.
104 * @param resPtr Observed resource.
105 * @param maxAge Time To Live (in seconds) of observation.
106 * @param resourceType Resource type. Allows resource type name to be added to response.
107 * @param qos Quality of service of resource.
109 * @return ::OC_STACK_OK on success, some other value upon failure.
111 OCStackResult SendAllObserverNotification (OCMethod method, OCResource *resPtr, uint32_t maxAge,
112 OCPresenceTrigger trigger, OCResourceType *resourceType, OCQualityOfService qos);
115 * Create an observe response and send to all observers in the observe list.
117 * @param method RESTful method.
118 * @param resPtr Observed resource.
119 * @param maxAge Time To Live (in seconds) of observation.
120 * @param qos Quality of service of resource.
122 * @return ::OC_STACK_OK on success, some other value upon failure.
124 OCStackResult SendAllObserverNotification (OCMethod method, OCResource *resPtr, uint32_t maxAge,
125 OCQualityOfService qos);
129 * Notify specific observers with updated value of representation.
131 * @param resource Observed resource.
132 * @param obsIdList List of observation ids that need to be notified.
133 * @param numberOfIds Number of observation ids included in obsIdList.
134 * @param notificationJSONPayload JSON encoded payload to send in notification.
135 * @param maxAge Time To Live (in seconds) of observation.
136 * @param qos Desired quality of service of the observation notifications.
138 * @return ::OC_STACK_OK on success, some other value upon failure.
140 OCStackResult SendListObserverNotification (OCResource * resource,
141 OCObservationId *obsIdList, uint8_t numberOfIds,
142 const OCRepPayload *payload, uint32_t maxAge,
143 OCQualityOfService qos);
146 * Delete all observers in the observe list.
148 void DeleteObserverList();
151 * Create a unique observation ID.
153 * @param observationId Pointer to generated ID.
155 * @return ::OC_STACK_OK on success, some other value upon failure.
157 OCStackResult GenerateObserverId (OCObservationId *observationId);
160 * Add observer for a resource.
162 * @param resUri Resource URI string.
163 * @param query Query string.
164 * @param obsId Observation ID.
165 * @param token Request token.
166 * @param tokenLength Length of token.
167 * @param resHandle Resource handle.
168 * @param qos Quality of service of observation.
169 * @param devAddr Device address.
171 * @return ::OC_STACK_OK on success, some other value upon failure.
173 OCStackResult AddObserver (const char *resUri,
175 OCObservationId obsId,
178 OCResource *resHandle,
179 OCQualityOfService qos,
180 OCPayloadFormat acceptFormat,
181 const OCDevAddr *devAddr);
184 * Delete observer with specified token from list of observers.
185 * Free memory that was allocated for the observer in the list.
187 * @param token Token to search for.
188 * @param tokenLength Length of token.
190 * @return ::OC_STACK_OK on success, some other value upon failure.
192 OCStackResult DeleteObserverUsingToken (CAToken_t token, uint8_t tokenLength);
195 * Delete observer with device address from list of observers.
196 * Free memory that was allocated for the observer in the list.
198 * @param devAddr Device's address.
200 * @return ::OC_STACK_OK on success, some other value upon failure.
202 OCStackResult DeleteObserverUsingDevAddr(const OCDevAddr *devAddr);
205 * Search the list of observers for the specified token.
207 * @param token Token to search for.
208 * @param tokenLength Length of token.
210 * @return Pointer to found observer.
212 ResourceObserver* GetObserverUsingToken (const CAToken_t token, uint8_t tokenLength);
215 * Search the list of observers for the specified observe ID.
217 * @param observeId Observer ID to search for.
219 * @return Pointer to found observer.
221 ResourceObserver* GetObserverUsingId (const OCObservationId observeId);
224 * Add observe header option to a request.
226 * @param caHdrOpt Target request CA header option.
227 * @param ocHdrOpt Pointer to existing options.
228 * @param numOptions Number of existing options.
229 * @param observeFlag Register/de-register observation. Should be either
230 * ::OC_OBSERVE_REGISTER or ::OC_OBSERVE_DEREGISTER.
232 * @return ::OC_STACK_OK on success, some other value upon failure.
235 CreateObserveHeaderOption (CAHeaderOption_t **caHdrOpt,
236 OCHeaderOption *ocHdrOpt,
238 uint8_t observeFlag);
241 * Copy the observe option from a received request.
243 * @param observationOption Pointer to observe option value. Should be either
244 * ::OC_OBSERVE_REGISTER, ::OC_OBSERVE_DEREGISTER, or
245 * ::OC_OBSERVE_NO_OPTION if observe not found.
247 * @param options Options in received request. Observe option is removed if found.
248 * @param numOptions Number of options in the received request. Decremented if observe
249 * option is extracted.
251 * @return ::OC_STACK_OK on success, some other value upon failure.
254 GetObserveHeaderOption (uint32_t * observationOption,
255 CAHeaderOption_t *options,
256 uint8_t * numOptions);
258 #endif //OC_OBSERVE_H