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 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
30 #define USE_RANDOM_PORT (0)
32 //-----------------------------------------------------------------------------
33 // Function prototypes
34 //-----------------------------------------------------------------------------
37 * Initialize the OC Stack. Must be called prior to starting the stack.
40 * IP Address of host device. Deprecated parameter.
42 * Port of host device. Deprecated parameter.
44 * Host device is client, server, or client-server.
46 * @return ::OC_STACK_OK on success, some other value upon failure.
48 OCStackResult OCInit(const char *ipAddr, uint16_t port, OCMode mode);
51 * Stop the OC stack. Use for a controlled shutdown.
53 * Note: OCStop() performs operations similar to OCStopPresence(), as well as OCDeleteResource() on
54 * all resources this server is hosting. OCDeleteResource() performs operations similar to
55 * OCNotifyAllObservers() to notify all client observers that the respective resource is being
58 * @return ::OC_STACK_OK on success, some other value upon failure.
60 OCStackResult OCStop();
63 * Called in main loop of OC client or server. Allows low-level processing of
66 * @return ::OC_STACK_OK on success, some other value upon failure.
68 OCStackResult OCProcess();
71 * Discover or Perform requests on a specified resource (specified by that Resource's respective
74 * @param handle @ref OCDoHandle to refer to the request sent out on behalf of
75 * calling this API. This handle can be used to cancel this operation
76 * via the OCCancel API.
77 * Note: This reference is handled internally, and
78 * should not be free'd by the consumer. A NULL handle is permitted
79 * in the event where the caller has no use for the return value.
80 * @param method @ref OCMethod to perform on the resource.
81 * @param requiredUri URI of the resource to interact with.
82 * @param referenceUri URI of the reference resource.
83 * @param request JSON encoded request.
84 * @param conType @ref OCConnectivityType type of connectivity indicating the
85 * interface. Example: ::OC_WIFI, ::OC_ETHERNET, ::OC_ALL.
86 * @param qos Quality of service. Note that if this API is called on a uri with
87 * the well-known multicast IP address, the qos will be forced to
89 * since it is impractical to send other QOS levels on such addresses.
90 * @param cbData Asynchronous callback function that is invoked
91 * by the stack when discovery or resource interaction is complete.
92 * @param options The address of an array containing the vendor specific
93 * header options to be sent with the request.
94 * @param numOptions Number of header options to be included.
96 * Note: Presence subscription amendments (ie. adding additional resource type filters by calling
97 * this API again) require the use of the same base URI as the original request to successfully
98 * amend the presence filters.
100 * @return ::OC_STACK_OK on success, some other value upon failure.
102 OCStackResult OCDoResource(OCDoHandle *handle, OCMethod method, const char *requiredUri,
103 const char *referenceUri, const char *request, OCConnectivityType conType,
104 OCQualityOfService qos, OCCallbackData *cbData,
105 OCHeaderOption * options, uint8_t numOptions);
108 * Cancel a request associated with a specific @ref OCDoResource invocation.
110 * @param handle - Used to identify a specific OCDoResource invocation.
111 * @param qos - used to specify Quality of Service (read below for more info)
112 * @param options- used to specify vendor specific header options when sending
113 * explicit observe cancellation
114 * @param numOptions- Number of header options to be included
116 * @return ::OC_STACK_OK on success, some other value upon failure.
118 OCStackResult OCCancel(OCDoHandle handle, OCQualityOfService qos, OCHeaderOption * options,
123 * When operating in @ref OCServer or @ref OCClientServer mode, this API will start sending out
124 * presence notifications to clients via multicast. Once this API has been called with a success,
125 * clients may query for this server's presence and this server's stack will respond via multicast.
127 * Server can call this function when it comes online for the first time, or when it comes back
128 * online from offline mode, or when it re enters network.
130 * @param ttl Time To Live in seconds.
131 * Note: If ttl is '0', then the default stack value will be used (60 Seconds).
133 * If ttl is greater than OC_MAX_PRESENCE_TTL_SECONDS, then the ttl will be set to
134 * OC_MAX_PRESENCE_TTL_SECONDS.
136 * @return ::OC_STACK_OK on success, some other value upon failure.
138 OCStackResult OCStartPresence(const uint32_t ttl);
141 * When operating in @ref OCServer or @ref OCClientServer mode, this API will stop sending out
142 * presence notifications to clients via multicast. Once this API has been called with a success,
143 * this server's stack will not respond to clients querying for this server's presence.
145 * Server can call this function when it is terminating, going offline, or when going
148 * @return ::OC_STACK_OK on success, some other value upon failure.
151 OCStackResult OCStopPresence();
156 * Set default device entity handler.
158 * @param entityHandler Entity handler function that is called by ocstack to handle requests for
159 * any undefined resources or default actions.
160 * If NULL is passed it removes the device default entity handler.
162 * @return ::OC_STACK_OK on success, some other value upon failure.
164 OCStackResult OCSetDefaultDeviceEntityHandler(OCDeviceEntityHandler entityHandler);
167 * Set device information.
169 * @param deviceInfo - Structure passed by the server application containing
170 * the device information.
174 * OC_STACK_OK - no errors
175 * OC_STACK_INVALID_PARAM - invalid paramerter
176 * OC_STACK_ERROR - stack process error
178 OCStackResult OCSetDeviceInfo(OCDeviceInfo deviceInfo);
181 * Set platform information.
183 * @param platformInfo - Structure passed by the server application containing
184 * the platform information.
188 * OC_STACK_OK - no errors
189 * OC_STACK_INVALID_PARAM - invalid paramerter
190 * OC_STACK_ERROR - stack process error
192 OCStackResult OCSetPlatformInfo(OCPlatformInfo platformInfo);
197 * @param handle Pointer to handle to newly created resource. Set by ocstack and
198 * used to refer to resource.
199 * @param resourceTypeName Name of resource type. Example: "core.led".
200 * @param resourceInterfaceName Name of resource interface. Example: "core.rw".
201 * @param uri URI of the resource. Example: "/a/led".
202 * @param entityHandler Entity handler function that is called by ocstack to handle requests, etc.
203 * NULL for default entity handler.
204 * @param resourceProperties Properties supported by resource.
205 * Example: ::OC_DISCOVERABLE|::OC_OBSERVABLE.
207 * @return ::OC_STACK_OK on success, some other value upon failure.
209 OCStackResult OCCreateResource(OCResourceHandle *handle,
210 const char *resourceTypeName,
211 const char *resourceInterfaceName,
213 OCEntityHandler entityHandler,
214 uint8_t resourceProperties);
217 * Create a resource. with host ip address for remote resource.
219 * @param handle Pointer to handle to newly created resource. Set by ocstack.
220 * Used to refer to resource.
221 * @param resourceTypeName Name of resource type. Example: "core.led".
222 * @param resourceInterfaceName Name of resource interface. Example: "core.rw".
223 * @param host HOST address of the remote resource. Example: "coap://xxx.xxx.xxx.xxx:xxxxx".
224 * @param uri URI of the resource. Example: "/a/led".
225 * @param entityHandler Entity handler function that is called by ocstack to handle requests, etc.
226 * NULL for default entity handler.
227 * @param resourceProperties Properties supported by resource.
228 * Example: ::OC_DISCOVERABLE|::OC_OBSERVABLE
230 * @return ::OC_STACK_OK on success, some other value upon failure.
232 OCStackResult OCCreateResourceWithHost(OCResourceHandle *handle,
233 const char *resourceTypeName,
234 const char *resourceInterfaceName,
237 OCEntityHandler entityHandler,
238 uint8_t resourceProperties);
241 * Add a resource to a collection resource.
243 * @param collectionHandle Handle to the collection resource.
244 * @param resourceHandle Handle to resource to be added to the collection resource.
246 * @return ::OC_STACK_OK on success, some other value upon failure.
248 OCStackResult OCBindResource(OCResourceHandle collectionHandle, OCResourceHandle resourceHandle);
251 * Remove a resource from a collection resource.
253 * @param collectionHandle Handle to the collection resource.
254 * @param resourceHandle Handle to resource to be removed from the collection resource.
256 * @return ::OC_STACK_OK on success, some other value upon failure.
258 OCStackResult OCUnBindResource(OCResourceHandle collectionHandle, OCResourceHandle resourceHandle);
261 * Bind a resourcetype to a resource.
263 * @param handle Handle to the resource.
264 * @param resourceTypeName Name of resource type. Example: "core.led".
266 * @return ::OC_STACK_OK on success, some other value upon failure.
268 OCStackResult OCBindResourceTypeToResource(OCResourceHandle handle,
269 const char *resourceTypeName);
271 * Bind a resource interface to a resource.
273 * @param handle Handle to the resource.
274 * @param resourceInterfaceName Name of resource interface. Example: "core.rw".
276 * @return ::OC_STACK_OK on success, some other value upon failure.
278 OCStackResult OCBindResourceInterfaceToResource(OCResourceHandle handle,
279 const char *resourceInterfaceName);
282 * Bind an entity handler to the resource.
284 * @param handle Handle to the resource that the contained resource is to be bound.
285 * @param entityHandler Entity handler function that is called by ocstack to handle requests, etc.
286 * @return ::OC_STACK_OK on success, some other value upon failure.
288 OCStackResult OCBindResourceHandler(OCResourceHandle handle, OCEntityHandler entityHandler);
291 * Get the number of resources that have been created in the stack.
293 * @param numResources Pointer to count variable.
295 * @return ::OC_STACK_OK on success, some other value upon failure.
297 OCStackResult OCGetNumberOfResources(uint8_t *numResources);
300 * Get a resource handle by index.
302 * @param index Index of resource, 0 to Count - 1.
304 * @return Found resource handle or NULL if not found.
306 OCResourceHandle OCGetResourceHandle(uint8_t index);
309 * Delete resource specified by handle. Deletes resource and all resourcetype and resourceinterface
312 * Note: OCDeleteResource() performs operations similar to OCNotifyAllObservers() to notify all
313 * client observers that "this" resource is being deleted.
315 * @param handle Handle of resource to be deleted.
317 * @return ::OC_STACK_OK on success, some other value upon failure.
319 OCStackResult OCDeleteResource(OCResourceHandle handle);
322 * Get the URI of the resource specified by handle.
324 * @param handle Handle of resource.
325 * @return URI string if resource found or NULL if not found.
327 const char *OCGetResourceUri(OCResourceHandle handle);
330 * Get the properties of the resource specified by handle.
331 * NOTE: that after a resource is created, the OC_ACTIVE property is set
332 * for the resource by the stack.
334 * @param handle Handle of resource.
335 * @return OCResourceProperty Bitmask or -1 if resource is not found.
337 OCResourceProperty OCGetResourceProperties(OCResourceHandle handle);
340 * Get the number of resource types of the resource.
342 * @param handle Handle of resource.
343 * @param numResourceTypes Pointer to count variable.
345 * @return ::OC_STACK_OK on success, some other value upon failure.
347 OCStackResult OCGetNumberOfResourceTypes(OCResourceHandle handle, uint8_t *numResourceTypes);
350 * Get name of resource type of the resource.
352 * @param handle Handle of resource.
353 * @param index Index of resource, 0 to Count - 1.
355 * @return Resource type name if resource found or NULL if resource not found.
357 const char *OCGetResourceTypeName(OCResourceHandle handle, uint8_t index);
360 * Get the number of resource interfaces of the resource.
362 * @param handle Handle of resource.
363 * @param numResourceInterfaces Pointer to count variable.
365 * @return ::OC_STACK_OK on success, some other value upon failure.
367 OCStackResult OCGetNumberOfResourceInterfaces(OCResourceHandle handle,
368 uint8_t *numResourceInterfaces);
371 * Get name of resource interface of the resource.
373 * @param handle Handle of resource.
374 * @param index Index of resource, 0 to Count - 1.
376 * @return Resource interface name if resource found or NULL if resource not found.
378 const char *OCGetResourceInterfaceName(OCResourceHandle handle, uint8_t index);
381 * Get methods of resource interface of the resource.
383 * @param handle Handle of resource.
384 * @param index Index of resource, 0 to Count - 1.
386 * @return Allowed methods if resource found or NULL if resource not found.
388 uint8_t OCGetResourceInterfaceAllowedMethods(OCResourceHandle handle, uint8_t index);
391 * Get resource handle from the collection resource by index.
393 * @param collectionHandle Handle of collection resource.
394 * @param index Index of contained resource, 0 to Count - 1.
396 * @return Handle to contained resource if resource found or NULL if resource not found.
398 OCResourceHandle OCGetResourceHandleFromCollection(OCResourceHandle collectionHandle,
402 * Get the entity handler for a resource.
404 * @param handle Handle of resource.
406 * @return Entity handler if resource found or NULL resource not found.
408 OCEntityHandler OCGetResourceHandler(OCResourceHandle handle);
411 * Notify all registered observers that the resource representation has
412 * changed. If observation includes a query the client is notified only
413 * if the query is valid after the resource representation has changed.
415 * @param handle Handle of resource.
416 * @param qos Desired quality of service for the observation notifications.
418 * @return ::OC_STACK_OK on success, some other value upon failure.
420 OCStackResult OCNotifyAllObservers(OCResourceHandle handle, OCQualityOfService qos);
423 * Notify specific observers with updated value of representation.
424 * Before this API is invoked by entity handler it has finished processing
425 * queries for the associated observers.
427 * @param handle Handle of resource.
428 * @param obsIdList List of observation ids that need to be notified.
429 * @param numberOfIds Number of observation ids included in obsIdList.
430 * @param notificationJSONPayload JSON encoded payload to send in notification.
431 * @param qos Desired quality of service of the observation notifications.
432 * NOTE: The memory for obsIdList and notificationJSONPayload is managed by the
433 * entity invoking the API. The maximum size of the notification is 1015 bytes
434 * for non-Arduino platforms. For Arduino the maximum size is 247 bytes.
436 * @return ::OC_STACK_OK on success, some other value upon failure.
439 OCNotifyListOfObservers (OCResourceHandle handle,
440 OCObservationId *obsIdList,
442 const char *notificationJSONPayload,
443 OCQualityOfService qos);
447 * Send a response to a request.
448 * The response can be a normal, slow, or block (i.e. a response that
449 * is too large to be sent in a single PDU and must span multiple transmissions).
451 * @param response Pointer to structure that contains response parameters.
453 * @return ::OC_STACK_OK on success, some other value upon failure.
455 OCStackResult OCDoResponse(OCEntityHandlerResponse *response);
461 * This method is used to retrieved the IPv4 address from OCDev address
464 * @param ipAddr OCDevAddr address.
465 * @param a first byte of IPv4 address.
466 * @param b second byte of IPv4 address.
467 * @param c third byte of IPv4 address.
468 * @param d fourth byte of IPv4 address.
469 * @return ::OC_STACK_OK on success, some other value upon failure.
471 int32_t OCDevAddrToIPv4Addr(OCDevAddr *ipAddr, uint8_t *a, uint8_t *b,
472 uint8_t *c, uint8_t *d );
475 * This method is used to retrieve the port number from OCDev address
478 * @param ipAddr OCDevAddr address.
479 * @param port Port number.
480 * @return ::OC_STACK_OK on success, some other value upon failure.
482 int32_t OCDevAddrToPort(OCDevAddr *ipAddr, uint16_t *port);
486 #endif // __cplusplus
488 #endif /* OCSTACK_H_ */