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 // 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)
28 #define MAX_OBSERVER_FAILED_COMM (2)
29 #define MAX_OBSERVER_NON_COUNT (3)
32 * This information is stored for each registered observer.
34 typedef struct ResourceObserver
36 // Observation Identifier for request
37 OCObservationId observeId;
38 // URI of observed resource
42 //token for the observe request
44 //token length for the observe request
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 CAConnectivityType_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
59 // force the qos value to CON
61 // next node in this list
62 struct ResourceObserver *next;
67 * Create an observe response and send to all observers in the observe list.
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.
76 OCStackResult SendAllObserverNotification (OCMethod method, OCResource *resPtr, uint32_t maxAge,
77 OCResourceType *resourceType, OCQualityOfService qos);
80 * Create an observe response and send to all observers in the observe list.
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.
88 OCStackResult SendAllObserverNotification (OCMethod method, OCResource *resPtr, uint32_t maxAge,
89 OCQualityOfService qos);
93 * Notify specific observers with updated value of representation.
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.
103 OCStackResult SendListObserverNotification (OCResource * resource,
104 OCObservationId *obsIdList, uint8_t numberOfIds,
105 const char *notificationJSONPayload, uint32_t maxAge,
106 OCQualityOfService qos);
109 * Delete all observers in the observe list.
111 void DeleteObserverList();
114 * Create a unique observation ID.
116 * @param observationId Pointer to generated ID.
117 * @return ::OC_STACK_OK on success, some other value upon failure.
119 OCStackResult GenerateObserverId (OCObservationId *observationId);
122 * Add observer for a resource.
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.
135 OCStackResult AddObserver (const char *resUri,
137 OCObservationId obsId,
140 OCResource *resHandle,
141 OCQualityOfService qos,
142 const CAAddress_t *addressInfo,
143 CAConnectivityType_t connectivityType);
146 * Delete observer with specified token from list of observers.
147 * Free memory that was allocated for the observer in the list.
149 * @param token Token to search for.
150 * @param tokenLength Length of token.
152 * @return ::OC_STACK_OK on success, some other value upon failure.
154 OCStackResult DeleteObserverUsingToken (CAToken_t token, uint8_t tokenLength);
157 * Search the list of observers for the specified token.
159 * @param token Token to search for.
160 * @param tokenLength Length of token.
162 * @return Pointer to found observer.
164 ResourceObserver* GetObserverUsingToken (const CAToken_t token, uint8_t tokenLength);
167 * Search the list of observers for the specified observe ID.
169 * @param observeId Observer ID to search for
171 * @return Pointer to found observer.
173 ResourceObserver* GetObserverUsingId (const OCObservationId observeId);
176 * Add observe header option to a request.
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.
184 * @return ::OC_STACK_OK on success, some other value upon failure.
187 CreateObserveHeaderOption (CAHeaderOption_t **caHdrOpt,
188 OCHeaderOption *ocHdrOpt,
190 uint8_t observeFlag);
193 * Copy the observe option from a received request
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.
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
202 * @return ::OC_STACK_OK on success, some other value upon failure.
205 GetObserveHeaderOption (uint32_t * observationOption,
206 CAHeaderOption_t *options,
207 uint8_t * numOptions);
209 #endif //OC_OBSERVE_H