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 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
31 #define USE_RANDOM_PORT (0)
33 //-----------------------------------------------------------------------------
34 // Function prototypes
35 //-----------------------------------------------------------------------------
38 * Initialize the OC Stack. Must be called prior to starting the stack.
41 * Host device is client, server, or client-server.
43 * Default server transport flags.
45 * Default client transport flags.
47 * @return ::OC_STACK_OK on success, some other value upon failure.
49 OCStackResult OCInit1(OCMode mode, OCTransportFlags serverFlags, OCTransportFlags clientFlags);
52 * Initialize the OC Stack. Must be called prior to starting the stack.
55 * IP Address of host device. Deprecated parameter.
57 * Port of host device. Deprecated parameter.
59 * Host device is client, server, or client-server.
61 * @return ::OC_STACK_OK on success, some other value upon failure.
63 OCStackResult OCInit(const char *ipAddr, uint16_t port, OCMode mode);
67 * @brief Set Remote Access information for XMPP Client.
68 * @param raInfo [IN] remote access info.
70 * @return #CA_STATUS_OK
72 OCStackResult OCSetRAInfo(const OCRAInfo_t *raInfo);
76 * Stop the OC stack. Use for a controlled shutdown.
78 * Note: OCStop() performs operations similar to OCStopPresence(), as well as OCDeleteResource() on
79 * all resources this server is hosting. OCDeleteResource() performs operations similar to
80 * OCNotifyAllObservers() to notify all client observers that the respective resource is being
83 * @return ::OC_STACK_OK on success, some other value upon failure.
85 OCStackResult OCStop();
88 * Called in main loop of OC client or server. Allows low-level processing of
91 * @return ::OC_STACK_OK on success, some other value upon failure.
93 OCStackResult OCProcess();
96 * Discover or Perform requests on a specified resource (specified by that Resource's respective
99 * @param handle @ref OCDoHandle to refer to the request sent out on behalf of
100 * calling this API. This handle can be used to cancel this operation
101 * via the OCCancel API.
102 * Note: This reference is handled internally, and
103 * should not be free'd by the consumer. A NULL handle is permitted
104 * in the event where the caller has no use for the return value.
105 * @param method @ref OCMethod to perform on the resource.
106 * @param requiredUri URI of the resource to interact with. (Address prefix
107 * is deprecated in favor of destination.)
108 * @param destination Complete description of destination.
109 * @param request JSON encoded request.
110 * @param connectivityType Modifier flags when destination is not given.
111 * @param qos Quality of service. Note that if this API is called on a uri with
112 * the well-known multicast IP address, the qos will be forced to
114 * since it is impractical to send other QOS levels on such addresses.
115 * @param cbData Asynchronous callback function that is invoked
116 * by the stack when discovery or resource interaction is complete.
117 * @param options The address of an array containing the vendor specific
118 * header options to be sent with the request.
119 * @param numOptions Number of header options to be included.
121 * Note: Presence subscription amendments (ie. adding additional resource type filters by calling
122 * this API again) require the use of the same base URI as the original request to successfully
123 * amend the presence filters.
125 * @return ::OC_STACK_OK on success, some other value upon failure.
127 OCStackResult OCDoResource(OCDoHandle *handle,
129 const char *requestUri,
130 const OCDevAddr *destination,
132 OCConnectivityType connectivityType,
133 OCQualityOfService qos,
134 OCCallbackData *cbData,
135 OCHeaderOption *options,
138 * Cancel a request associated with a specific @ref OCDoResource invocation.
140 * @param handle - Used to identify a specific OCDoResource invocation.
141 * @param qos - used to specify Quality of Service (read below for more info)
142 * @param options- used to specify vendor specific header options when sending
143 * explicit observe cancellation
144 * @param numOptions- Number of header options to be included
146 * @return ::OC_STACK_OK on success, some other value upon failure.
148 OCStackResult OCCancel(OCDoHandle handle, OCQualityOfService qos, OCHeaderOption * options,
152 * @brief Register Persistent storage callback.
153 * @param persistentStorageHandler [IN] Pointers to open, read, write, close & unlink handlers.
155 * OC_STACK_OK - No errors; Success
156 * OC_STACK_INVALID_PARAM - Invalid parameter
158 OCStackResult OCRegisterPersistentStorageHandler(OCPersistentStorage* persistentStorageHandler);
162 * When operating in @ref OCServer or @ref OCClientServer mode, this API will start sending out
163 * presence notifications to clients via multicast. Once this API has been called with a success,
164 * clients may query for this server's presence and this server's stack will respond via multicast.
166 * Server can call this function when it comes online for the first time, or when it comes back
167 * online from offline mode, or when it re enters network.
169 * @param ttl Time To Live in seconds.
170 * Note: If ttl is '0', then the default stack value will be used (60 Seconds).
172 * If ttl is greater than OC_MAX_PRESENCE_TTL_SECONDS, then the ttl will be set to
173 * OC_MAX_PRESENCE_TTL_SECONDS.
175 * @return ::OC_STACK_OK on success, some other value upon failure.
177 OCStackResult OCStartPresence(const uint32_t ttl);
180 * When operating in @ref OCServer or @ref OCClientServer mode, this API will stop sending out
181 * presence notifications to clients via multicast. Once this API has been called with a success,
182 * this server's stack will not respond to clients querying for this server's presence.
184 * Server can call this function when it is terminating, going offline, or when going
187 * @return ::OC_STACK_OK on success, some other value upon failure.
190 OCStackResult OCStopPresence();
195 * Set default device entity handler.
197 * @param entityHandler Entity handler function that is called by ocstack to handle requests for
198 * any undefined resources or default actions.
199 * If NULL is passed it removes the device default entity handler.
200 * @param callbackParameter paramter passed back when entityHandler is called.
202 * @return ::OC_STACK_OK on success, some other value upon failure.
204 OCStackResult OCSetDefaultDeviceEntityHandler(OCDeviceEntityHandler entityHandler, void* callbackParameter);
207 * Set device information.
209 * @param deviceInfo - Structure passed by the server application containing
210 * the device information.
214 * OC_STACK_OK - no errors
215 * OC_STACK_INVALID_PARAM - invalid paramerter
216 * OC_STACK_ERROR - stack process error
218 OCStackResult OCSetDeviceInfo(OCDeviceInfo deviceInfo);
221 * Set platform information.
223 * @param platformInfo - Structure passed by the server application containing
224 * the platform information.
228 * OC_STACK_OK - no errors
229 * OC_STACK_INVALID_PARAM - invalid paramerter
230 * OC_STACK_ERROR - stack process error
232 OCStackResult OCSetPlatformInfo(OCPlatformInfo platformInfo);
237 * @param handle Pointer to handle to newly created resource. Set by ocstack and
238 * used to refer to resource.
239 * @param resourceTypeName Name of resource type. Example: "core.led".
240 * @param resourceInterfaceName Name of resource interface. Example: "core.rw".
241 * @param uri URI of the resource. Example: "/a/led".
242 * @param entityHandler Entity handler function that is called by ocstack to handle requests, etc.
243 * NULL for default entity handler.
244 * @param callbackParameter paramter passed back when entityHandler is called.
245 * @param resourceProperties Properties supported by resource.
246 * Example: ::OC_DISCOVERABLE|::OC_OBSERVABLE.
248 * @return ::OC_STACK_OK on success, some other value upon failure.
250 OCStackResult OCCreateResource(OCResourceHandle *handle,
251 const char *resourceTypeName,
252 const char *resourceInterfaceName,
254 OCEntityHandler entityHandler,
256 uint8_t resourceProperties);
260 * Add a resource to a collection resource.
262 * @param collectionHandle Handle to the collection resource.
263 * @param resourceHandle Handle to resource to be added to the collection resource.
265 * @return ::OC_STACK_OK on success, some other value upon failure.
267 OCStackResult OCBindResource(OCResourceHandle collectionHandle, OCResourceHandle resourceHandle);
270 * Remove a resource from a collection resource.
272 * @param collectionHandle Handle to the collection resource.
273 * @param resourceHandle Handle to resource to be removed from the collection resource.
275 * @return ::OC_STACK_OK on success, some other value upon failure.
277 OCStackResult OCUnBindResource(OCResourceHandle collectionHandle, OCResourceHandle resourceHandle);
280 * Bind a resourcetype to a resource.
282 * @param handle Handle to the resource.
283 * @param resourceTypeName Name of resource type. Example: "core.led".
285 * @return ::OC_STACK_OK on success, some other value upon failure.
287 OCStackResult OCBindResourceTypeToResource(OCResourceHandle handle,
288 const char *resourceTypeName);
290 * Bind a resource interface to a resource.
292 * @param handle Handle to the resource.
293 * @param resourceInterfaceName Name of resource interface. Example: "core.rw".
295 * @return ::OC_STACK_OK on success, some other value upon failure.
297 OCStackResult OCBindResourceInterfaceToResource(OCResourceHandle handle,
298 const char *resourceInterfaceName);
301 * Bind an entity handler to the resource.
303 * @param handle Handle to the resource that the contained resource is to be bound.
304 * @param entityHandler Entity handler function that is called by ocstack to handle requests, etc.
305 * @param callbackParameter context paremeter that will be passed to entityHandler
306 * @return ::OC_STACK_OK on success, some other value upon failure.
308 OCStackResult OCBindResourceHandler(OCResourceHandle handle, OCEntityHandler entityHandler,
309 void *callbackParameter);
312 * Get the number of resources that have been created in the stack.
314 * @param numResources Pointer to count variable.
316 * @return ::OC_STACK_OK on success, some other value upon failure.
318 OCStackResult OCGetNumberOfResources(uint8_t *numResources);
321 * Get a resource handle by index.
323 * @param index Index of resource, 0 to Count - 1.
325 * @return Found resource handle or NULL if not found.
327 OCResourceHandle OCGetResourceHandle(uint8_t index);
330 * Delete resource specified by handle. Deletes resource and all resourcetype and resourceinterface
333 * Note: OCDeleteResource() performs operations similar to OCNotifyAllObservers() to notify all
334 * client observers that "this" resource is being deleted.
336 * @param handle Handle of resource to be deleted.
338 * @return ::OC_STACK_OK on success, some other value upon failure.
340 OCStackResult OCDeleteResource(OCResourceHandle handle);
343 * Get the URI of the resource specified by handle.
345 * @param handle Handle of resource.
346 * @return URI string if resource found or NULL if not found.
348 const char *OCGetResourceUri(OCResourceHandle handle);
351 * Get the properties of the resource specified by handle.
352 * NOTE: that after a resource is created, the OC_ACTIVE property is set
353 * for the resource by the stack.
355 * @param handle Handle of resource.
356 * @return OCResourceProperty Bitmask or -1 if resource is not found.
358 OCResourceProperty OCGetResourceProperties(OCResourceHandle handle);
361 * Get the number of resource types of the resource.
363 * @param handle Handle of resource.
364 * @param numResourceTypes Pointer to count variable.
366 * @return ::OC_STACK_OK on success, some other value upon failure.
368 OCStackResult OCGetNumberOfResourceTypes(OCResourceHandle handle, uint8_t *numResourceTypes);
371 * Get name of resource type of the resource.
373 * @param handle Handle of resource.
374 * @param index Index of resource, 0 to Count - 1.
376 * @return Resource type name if resource found or NULL if resource not found.
378 const char *OCGetResourceTypeName(OCResourceHandle handle, uint8_t index);
381 * Get the number of resource interfaces of the resource.
383 * @param handle Handle of resource.
384 * @param numResourceInterfaces Pointer to count variable.
386 * @return ::OC_STACK_OK on success, some other value upon failure.
388 OCStackResult OCGetNumberOfResourceInterfaces(OCResourceHandle handle,
389 uint8_t *numResourceInterfaces);
392 * Get name of resource interface of the resource.
394 * @param handle Handle of resource.
395 * @param index Index of resource, 0 to Count - 1.
397 * @return Resource interface name if resource found or NULL if resource not found.
399 const char *OCGetResourceInterfaceName(OCResourceHandle handle, uint8_t index);
402 * Get methods of resource interface of the resource.
404 * @param handle Handle of resource.
405 * @param index Index of resource, 0 to Count - 1.
407 * @return Allowed methods if resource found or NULL if resource not found.
409 uint8_t OCGetResourceInterfaceAllowedMethods(OCResourceHandle handle, uint8_t index);
412 * Get resource handle from the collection resource by index.
414 * @param collectionHandle Handle of collection resource.
415 * @param index Index of contained resource, 0 to Count - 1.
417 * @return Handle to contained resource if resource found or NULL if resource not found.
419 OCResourceHandle OCGetResourceHandleFromCollection(OCResourceHandle collectionHandle,
423 * Get the entity handler for a resource.
425 * @param handle Handle of resource.
427 * @return Entity handler if resource found or NULL resource not found.
429 OCEntityHandler OCGetResourceHandler(OCResourceHandle handle);
432 * Notify all registered observers that the resource representation has
433 * changed. If observation includes a query the client is notified only
434 * if the query is valid after the resource representation has changed.
436 * @param handle Handle of resource.
437 * @param qos Desired quality of service for the observation notifications.
439 * @return ::OC_STACK_OK on success, some other value upon failure.
441 OCStackResult OCNotifyAllObservers(OCResourceHandle handle, OCQualityOfService qos);
444 * Notify specific observers with updated value of representation.
445 * Before this API is invoked by entity handler it has finished processing
446 * queries for the associated observers.
448 * @param handle Handle of resource.
449 * @param obsIdList List of observation ids that need to be notified.
450 * @param numberOfIds Number of observation ids included in obsIdList.
451 * @param payload OCRepresentationPayload object representing the notification
452 * @param qos Desired quality of service of the observation notifications.
453 * NOTE: The memory for obsIdList and notificationJSONPayload is managed by the
454 * entity invoking the API. The maximum size of the notification is 1015 bytes
455 * for non-Arduino platforms. For Arduino the maximum size is 247 bytes.
457 * @return ::OC_STACK_OK on success, some other value upon failure.
460 OCNotifyListOfObservers (OCResourceHandle handle,
461 OCObservationId *obsIdList,
463 const OCRepPayload *payload,
464 OCQualityOfService qos);
468 * Send a response to a request.
469 * The response can be a normal, slow, or block (i.e. a response that
470 * is too large to be sent in a single PDU and must span multiple transmissions).
472 * @param response Pointer to structure that contains response parameters.
474 * @return ::OC_STACK_OK on success, some other value upon failure.
476 OCStackResult OCDoResponse(OCEntityHandlerResponse *response);
480 #endif // __cplusplus
482 #endif /* OCSTACK_H_ */