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 /** Remote Endpoint **/
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
56 // force the qos value to CON
58 // next node in this list
59 struct ResourceObserver *next;
64 * Create an observe response and send to all observers in the observe list.
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.
73 OCStackResult SendAllObserverNotification (OCMethod method, OCResource *resPtr, uint32_t maxAge,
74 OCPresenceTrigger trigger, OCResourceType *resourceType, OCQualityOfService qos);
77 * Create an observe response and send to all observers in the observe list.
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.
85 OCStackResult SendAllObserverNotification (OCMethod method, OCResource *resPtr, uint32_t maxAge,
86 OCQualityOfService qos);
90 * Notify specific observers with updated value of representation.
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 notificationJSONPayload - JSON encoded payload to send in notification.
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.
100 OCStackResult SendListObserverNotification (OCResource * resource,
101 OCObservationId *obsIdList, uint8_t numberOfIds,
102 const char *notificationJSONPayload, uint32_t maxAge,
103 OCQualityOfService qos);
106 * Delete all observers in the observe list.
108 void DeleteObserverList();
111 * Create a unique observation ID.
113 * @param observationId Pointer to generated ID.
114 * @return ::OC_STACK_OK on success, some other value upon failure.
116 OCStackResult GenerateObserverId (OCObservationId *observationId);
119 * Add observer for a resource.
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.
131 OCStackResult AddObserver (const char *resUri,
133 OCObservationId obsId,
136 OCResource *resHandle,
137 OCQualityOfService qos,
138 const OCDevAddr *devAddr);
141 * Delete observer with specified token from list of observers.
142 * Free memory that was allocated for the observer in the list.
144 * @param token Token to search for.
145 * @param tokenLength Length of token.
147 * @return ::OC_STACK_OK on success, some other value upon failure.
149 OCStackResult DeleteObserverUsingToken (CAToken_t token, uint8_t tokenLength);
152 * Search the list of observers for the specified token.
154 * @param token Token to search for.
155 * @param tokenLength Length of token.
157 * @return Pointer to found observer.
159 ResourceObserver* GetObserverUsingToken (const CAToken_t token, uint8_t tokenLength);
162 * Search the list of observers for the specified observe ID.
164 * @param observeId Observer ID to search for
166 * @return Pointer to found observer.
168 ResourceObserver* GetObserverUsingId (const OCObservationId observeId);
171 * Add observe header option to a request.
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.
179 * @return ::OC_STACK_OK on success, some other value upon failure.
182 CreateObserveHeaderOption (CAHeaderOption_t **caHdrOpt,
183 OCHeaderOption *ocHdrOpt,
185 uint8_t observeFlag);
188 * Copy the observe option from a received request
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.
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
197 * @return ::OC_STACK_OK on success, some other value upon failure.
200 GetObserveHeaderOption (uint32_t * observationOption,
201 CAHeaderOption_t *options,
202 uint8_t * numOptions);
204 #endif //OC_OBSERVE_H