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 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
25 * This file contains APIs for OIC Stack to be implemented.
39 /** Macro to use Random port.*/
40 #define USE_RANDOM_PORT (0)
47 * This function Initializes the OC Stack. Must be called prior to starting the stack.
49 * @param mode OCMode Host device is client, server, or client-server.
50 * @param serverFlags OCTransportFlags Default server transport flags.
51 * @param clientFlags OCTransportFlags Default client transport flags.
53 * @return ::OC_STACK_OK on success, some other value upon failure.
55 OCStackResult OCInit1(OCMode mode, OCTransportFlags serverFlags, OCTransportFlags clientFlags);
58 * This function Initializes the OC Stack. Must be called prior to starting the stack.
60 * @param ipAddr IP Address of host device. Deprecated parameter.
61 * @param port Port of host device. Deprecated parameter.
62 * @param mode OCMode Host device is client, server, or client-server.
64 * @return ::OC_STACK_OK on success, some other value upon failure.
66 OCStackResult OCInit(const char *ipAddr, uint16_t port, OCMode mode);
70 * @brief Set Remote Access information for XMPP Client.
71 * @param raInfo [IN] remote access info.
73 * @return #CA_STATUS_OK
75 OCStackResult OCSetRAInfo(const OCRAInfo_t *raInfo);
79 * This function Stops the OC stack. Use for a controlled shutdown.
81 * @note: OCStop() performs operations similar to OCStopPresence(), as well as OCDeleteResource() on
82 * all resources this server is hosting. OCDeleteResource() performs operations similar to
83 * OCNotifyAllObservers() to notify all client observers that the respective resource is being
86 * @return ::OC_STACK_OK on success, some other value upon failure.
88 OCStackResult OCStop();
91 * This function is Called in main loop of OC client or server.
92 * Allows low-level processing of stack services.
94 * @return ::OC_STACK_OK on success, some other value upon failure.
96 OCStackResult OCProcess();
99 * This function discovers or Perform requests on a specified resource
100 * (specified by that Resource's respective URI).
102 * @param handle To refer to the request sent out on behalf of
103 * calling this API. This handle can be used to cancel this operation
104 * via the OCCancel API.
105 * @note: This reference is handled internally, and should not be free'd by
106 * the consumer. A NULL handle is permitted in the event where the caller
107 * has no use for the return value.
108 * @param method To perform on the resource.
109 * @param requestUri URI of the resource to interact with. (Address prefix is deprecated in
110 * favor of destination.)
111 * @param destination Complete description of destination.
112 * @param payload Encoded request payload.
113 * @param connectivityType Modifier flags when destination is not given.
114 * @param qos Quality of service. Note that if this API is called on a uri with the
115 * well-known multicast IP address, the qos will be forced to ::OC_LOW_QOS
116 * since it is impractical to send other QOS levels on such addresses.
117 * @param cbData Asynchronous callback function that is invoked by the stack when
118 * discovery or resource interaction is complete.
119 * @param options The address of an array containing the vendor specific header options
120 * to be sent with the request.
121 * @param numOptions Number of header options to be included.
123 * @note: Presence subscription amendments (i.e. adding additional resource type filters by calling
124 * this API again) require the use of the same base URI as the original request to successfully
125 * amend the presence filters.
127 * @return ::OC_STACK_OK on success, some other value upon failure.
129 OCStackResult OCDoResource(OCDoHandle *handle,
131 const char *requestUri,
132 const OCDevAddr *destination,
134 OCConnectivityType connectivityType,
135 OCQualityOfService qos,
136 OCCallbackData *cbData,
137 OCHeaderOption *options,
140 * This function cancels a request associated with a specific @ref OCDoResource invocation.
142 * @param handle Used to identify a specific OCDoResource invocation.
143 * @param qos Used to specify Quality of Service(read below).
144 * @param options Used to specify vendor specific header options when sending
145 * explicit observe cancellation.
146 * @param numOptions Number of header options to be included.
148 * @return ::OC_STACK_OK on success, some other value upon failure.
150 OCStackResult OCCancel(OCDoHandle handle, OCQualityOfService qos, OCHeaderOption * options,
154 * Register Persistent storage callback.
155 * @param persistentStorageHandler Pointers to open, read, write, close & unlink handlers.
158 * OC_STACK_OK No errors; Success.
159 * OC_STACK_INVALID_PARAM Invalid parameter.
161 OCStackResult OCRegisterPersistentStorageHandler(OCPersistentStorage* persistentStorageHandler);
165 * When operating in OCServer or OCClientServer mode,
166 * this API will start sending out presence notifications to clients via multicast.
167 * Once this API has been called with a success, clients may query for this server's presence and
168 * this server's stack will respond via multicast.
170 * Server can call this function when it comes online for the first time, or when it comes back
171 * online from offline mode, or when it re enters network.
173 * @param ttl Time To Live in seconds.
174 * @note: If ttl is '0', then the default stack value will be used (60 Seconds).
175 * If ttl is greater than ::OC_MAX_PRESENCE_TTL_SECONDS, then the ttl will be
176 * set to ::OC_MAX_PRESENCE_TTL_SECONDS.
178 * @return ::OC_STACK_OK on success, some other value upon failure.
180 OCStackResult OCStartPresence(const uint32_t ttl);
183 * When operating in OCServer or OCClientServer mode, this API will stop sending
184 * out presence notifications to clients via multicast.
185 * Once this API has been called with a success this server's stack will not respond to clients
186 * querying for this server's presence.
188 * Server can call this function when it is terminating, going offline, or when going
191 * @return ::OC_STACK_OK on success, some other value upon failure.
194 OCStackResult OCStopPresence();
199 * This function sets default device entity handler.
201 * @param entityHandler Entity handler function that is called by ocstack to handle requests
202 * for any undefined resources or default actions.If NULL is passed it
203 * removes the device default entity handler.
204 * @param callbackParameter Parameter passed back when entityHandler is called.
206 * @return ::OC_STACK_OK on success, some other value upon failure.
208 OCStackResult OCSetDefaultDeviceEntityHandler(OCDeviceEntityHandler entityHandler, void* callbackParameter);
211 * This function sets device information.
213 * @param deviceInfo Structure passed by the server application containing the device information.
216 * ::OC_STACK_OK no errors.
217 * ::OC_STACK_INVALID_PARAM invalid parameter.
218 * ::OC_STACK_ERROR stack process error.
220 OCStackResult OCSetDeviceInfo(OCDeviceInfo deviceInfo);
223 * This function sets platform information.
225 * @param platformInfo Structure passed by the server application containing
226 * the platform information.
230 * ::OC_STACK_OK no errors.
231 * ::OC_STACK_INVALID_PARAM invalid parameter.
232 * ::OC_STACK_ERROR stack process error.
234 OCStackResult OCSetPlatformInfo(OCPlatformInfo platformInfo);
237 * This function creates a resource.
239 * @param handle Pointer to handle to newly created resource. Set by ocstack and
240 * used to refer to resource.
241 * @param resourceTypeName Name of resource type. Example: "core.led".
242 * @param resourceInterfaceName Name of resource interface. Example: "core.rw".
243 * @param uri URI of the resource. Example: "/a/led".
244 * @param entityHandler Entity handler function that is called by ocstack to handle
246 * NULL for default entity handler.
247 * @param callbackParam parameter passed back when entityHandler is called.
248 * @param resourceProperties Properties supported by resource.
249 * Example: ::OC_DISCOVERABLE|::OC_OBSERVABLE.
251 * @return ::OC_STACK_OK on success, some other value upon failure.
253 OCStackResult OCCreateResource(OCResourceHandle *handle,
254 const char *resourceTypeName,
255 const char *resourceInterfaceName,
257 OCEntityHandler entityHandler,
259 uint8_t resourceProperties);
263 * This function adds a resource to a collection resource.
265 * @param collectionHandle Handle to the collection resource.
266 * @param resourceHandle Handle to resource to be added to the collection resource.
268 * @return ::OC_STACK_OK on success, some other value upon failure.
270 OCStackResult OCBindResource(OCResourceHandle collectionHandle, OCResourceHandle resourceHandle);
273 * This function removes a resource from a collection resource.
275 * @param collectionHandle Handle to the collection resource.
276 * @param resourceHandle Handle to resource to be removed from the collection resource.
278 * @return ::OC_STACK_OK on success, some other value upon failure.
280 OCStackResult OCUnBindResource(OCResourceHandle collectionHandle, OCResourceHandle resourceHandle);
283 * This function binds a resource type to a resource.
285 * @param handle Handle to the resource.
286 * @param resourceTypeName Name of resource type. Example: "core.led".
288 * @return ::OC_STACK_OK on success, some other value upon failure.
290 OCStackResult OCBindResourceTypeToResource(OCResourceHandle handle,
291 const char *resourceTypeName);
293 * This function binds a resource interface to a resource.
295 * @param handle Handle to the resource.
296 * @param resourceInterfaceName Name of resource interface. Example: "core.rw".
298 * @return ::OC_STACK_OK on success, some other value upon failure.
300 OCStackResult OCBindResourceInterfaceToResource(OCResourceHandle handle,
301 const char *resourceInterfaceName);
304 * This function binds an entity handler to the resource.
306 * @param handle Handle to the resource that the contained resource is to be bound.
307 * @param entityHandler Entity handler function that is called by ocstack to handle requests.
308 * @param callbackParameter Context parameter that will be passed to entityHandler.
310 * @return ::OC_STACK_OK on success, some other value upon failure.
312 OCStackResult OCBindResourceHandler(OCResourceHandle handle, OCEntityHandler entityHandler,
313 void *callbackParameter);
316 * This function gets the number of resources that have been created in the stack.
318 * @param numResources Pointer to count variable.
320 * @return ::OC_STACK_OK on success, some other value upon failure.
322 OCStackResult OCGetNumberOfResources(uint8_t *numResources);
325 * This function gets a resource handle by index.
327 * @param index Index of resource, 0 to Count - 1.
329 * @return Found resource handle or NULL if not found.
331 OCResourceHandle OCGetResourceHandle(uint8_t index);
334 * This function deletes resource specified by handle. Deletes resource and all
335 * resource type and resource interface linked lists.
337 * @note: OCDeleteResource() performs operations similar to OCNotifyAllObservers() to notify all
338 * client observers that "this" resource is being deleted.
340 * @param handle Handle of resource to be deleted.
342 * @return ::OC_STACK_OK on success, some other value upon failure.
344 OCStackResult OCDeleteResource(OCResourceHandle handle);
347 * Get a string representation the server instance ID.
348 * The memory is managed internal to this function, so freeing externally will result
349 * in a runtime error.
350 * Note: This will NOT seed the RNG, so it must be called after the RNG is seeded.
351 * This is done automatically during the OCInit process,
352 * so ensure that this call is done after that.
354 * @return A string representation the server instance ID.
356 const char* OCGetServerInstanceIDString(void);
359 * This function gets the URI of the resource specified by handle.
361 * @param handle Handle of resource.
363 * @return URI string if resource found or NULL if not found.
365 const char *OCGetResourceUri(OCResourceHandle handle);
368 * This function gets the properties of the resource specified by handle.
370 * @param handle Handle of resource.
372 * @return OCResourceProperty Bitmask or -1 if resource is not found.
374 * @note that after a resource is created, the OC_ACTIVE property is set for the resource by the
377 OCResourceProperty OCGetResourceProperties(OCResourceHandle handle);
380 * This function gets the number of resource types of the resource.
382 * @param handle Handle of resource.
383 * @param numResourceTypes Pointer to count variable.
385 * @return ::OC_STACK_OK on success, some other value upon failure.
387 OCStackResult OCGetNumberOfResourceTypes(OCResourceHandle handle, uint8_t *numResourceTypes);
390 * This function gets name of resource type of the resource.
392 * @param handle Handle of resource.
393 * @param index Index of resource, 0 to Count - 1.
395 * @return Resource type name if resource found or NULL if resource not found.
397 const char *OCGetResourceTypeName(OCResourceHandle handle, uint8_t index);
400 * This function gets the number of resource interfaces of the resource.
402 * @param handle Handle of resource.
403 * @param numResourceInterfaces Pointer to count variable.
405 * @return ::OC_STACK_OK on success, some other value upon failure.
407 OCStackResult OCGetNumberOfResourceInterfaces(OCResourceHandle handle,
408 uint8_t *numResourceInterfaces);
411 * This function gets name of resource interface of the resource.
413 * @param handle Handle of resource.
414 * @param index Index of resource, 0 to Count - 1.
416 * @return Resource interface name if resource found or NULL if resource not found.
418 const char *OCGetResourceInterfaceName(OCResourceHandle handle, uint8_t index);
421 * This function gets methods of resource interface of the resource.
423 * @param handle Handle of resource.
424 * @param index Index of resource, 0 to Count - 1.
426 * @return Allowed methods if resource found or NULL if resource not found.
428 uint8_t OCGetResourceInterfaceAllowedMethods(OCResourceHandle handle, uint8_t index);
431 * This function gets resource handle from the collection resource by index.
433 * @param collectionHandle Handle of collection resource.
434 * @param index Index of contained resource, 0 to Count - 1.
436 * @return Handle to contained resource if resource found or NULL if resource not found.
438 OCResourceHandle OCGetResourceHandleFromCollection(OCResourceHandle collectionHandle,
442 * This function gets the entity handler for a resource.
444 * @param handle Handle of resource.
446 * @return Entity handler if resource found or NULL resource not found.
448 OCEntityHandler OCGetResourceHandler(OCResourceHandle handle);
451 * This function notify all registered observers that the resource representation has
452 * changed. If observation includes a query the client is notified only if the query is valid after
453 * the resource representation has changed.
455 * @param handle Handle of resource.
456 * @param qos Desired quality of service for the observation notifications.
458 * @return ::OC_STACK_OK on success, some other value upon failure.
460 OCStackResult OCNotifyAllObservers(OCResourceHandle handle, OCQualityOfService qos);
463 * Notify specific observers with updated value of representation.
464 * Before this API is invoked by entity handler it has finished processing
465 * queries for the associated observers.
467 * @param handle Handle of resource.
468 * @param obsIdList List of observation IDs that need to be notified.
469 * @param numberOfIds Number of observation IDs included in obsIdList.
470 * @param payload Object representing the notification
471 * @param qos Desired quality of service of the observation notifications.
473 * @note: The memory for obsIdList and payload is managed by the entity invoking the API.
474 * The maximum size of the notification is 1015 bytes for non-Arduino platforms. For Arduino
475 * the maximum size is 247 bytes.
477 * @return ::OC_STACK_OK on success, some other value upon failure.
480 OCNotifyListOfObservers (OCResourceHandle handle,
481 OCObservationId *obsIdList,
483 const OCRepPayload *payload,
484 OCQualityOfService qos);
488 * This function sends a response to a request.
489 * The response can be a normal, slow, or block (i.e. a response that
490 * is too large to be sent in a single PDU and must span multiple transmissions).
492 * @param response Pointer to structure that contains response parameters.
494 * @return ::OC_STACK_OK on success, some other value upon failure.
496 OCStackResult OCDoResponse(OCEntityHandlerResponse *response);
500 #endif // __cplusplus
502 #endif /* OCSTACK_H_ */