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.
35 #include "platform_features.h"
41 /** Macro to use Random port.*/
42 #define USE_RANDOM_PORT (0)
49 * This function Initializes the OC Stack. Must be called prior to starting the stack.
51 * @param mode OCMode Host device is client, server, or client-server.
52 * @param serverFlags OCTransportFlags Default server transport flags.
53 * @param clientFlags OCTransportFlags Default client transport flags.
55 * @return ::OC_STACK_OK on success, some other value upon failure.
57 OCStackResult OC_CALL OCInit1(OCMode mode, OCTransportFlags serverFlags, OCTransportFlags clientFlags);
60 * This function Initializes the OC Stack. Must be called prior to starting the stack.
62 * @param mode OCMode Host device is client, server, or client-server.
63 * @param serverFlags OCTransportFlags Default server transport flags.
64 * @param clientFlags OCTransportFlags Default client transport flags.
65 * @param transportType OCTransportAdapter value to initialize.
67 * @return ::OC_STACK_OK on success, some other value upon failure.
69 OCStackResult OC_CALL OCInit2(OCMode mode, OCTransportFlags serverFlags, OCTransportFlags clientFlags,
70 OCTransportAdapter transportType);
73 * This function Initializes the OC Stack. Must be called prior to starting the stack.
75 * @param ipAddr IP Address of host device. Deprecated parameter.
76 * @param port Port of host device. Deprecated parameter.
77 * @param mode OCMode Host device is client, server, or client-server.
79 * @return ::OC_STACK_OK on success, some other value upon failure.
81 OCStackResult OC_CALL OCInit(const char *ipAddr, uint16_t port, OCMode mode);
85 * @brief Set Remote Access information for XMPP Client.
86 * @param[in] raInfo remote access info.
88 * @return ::OC_STACK_OK on success, some other value upon failure.
90 OCStackResult OC_CALL OCSetRAInfo(const OCRAInfo_t *raInfo);
94 * This function Stops the OC stack. Use for a controlled shutdown.
96 * @note: OCStop() performs operations similar to OCStopPresence(), as well as OCDeleteResource() on
97 * all resources this server is hosting. OCDeleteResource() performs operations similar to
98 * OCNotifyAllObservers() to notify all client observers that the respective resource is being
101 * @return ::OC_STACK_OK on success, some other value upon failure.
103 OCStackResult OC_CALL OCStop(void);
106 * This function starts responding to multicast /oic/res requests. This can be
107 * only called when stack is in OC_STACK_INITIALIZED state but device is not
108 * receiving multicast traffic.
110 * @return ::OC_STACK_OK on success, some other value upon failure.
112 OCStackResult OC_CALL OCStartMulticastServer(void);
115 * This function stops responding to multicast /oic/res requests. This is to be
116 * used for devices that uses other entity to push resources.
118 * Note that other multicast requests, such as those used during ownership
119 * transfer, continue to be responded to.
121 * @return ::OC_STACK_OK on success, some other value upon failure.
123 OCStackResult OC_CALL OCStopMulticastServer(void);
126 * This function is Called in main loop of OC client or server.
127 * Allows low-level processing of stack services.
129 * @return ::OC_STACK_OK on success, some other value upon failure.
131 OCStackResult OC_CALL OCProcess(void);
134 * This function discovers or Perform requests on a specified resource
135 * (specified by that Resource's respective URI).
137 * @deprecated: Use OCDoRequest instead which does not free given payload.
139 * @param handle To refer to the request sent out on behalf of
140 * calling this API. This handle can be used to cancel this operation
141 * via the OCCancel API.
142 * @note: This reference is handled internally, and should not be free'd by
143 * the consumer. A NULL handle is permitted in the event where the caller
144 * has no use for the return value.
145 * @param method To perform on the resource.
146 * @param requestUri URI of the resource to interact with. (Address prefix is deprecated in
147 * favor of destination.)
148 * @param destination Complete description of destination.
149 * @param payload Encoded request payload,
150 OCDoResource will free given payload when return OC_STATUS_OK.
151 * @param connectivityType Modifier flags when destination is not given.
152 * @param qos Quality of service. Note that if this API is called on a URI with the
153 * well-known multicast IP address, the qos will be forced to ::OC_LOW_QOS
154 * since it is impractical to send other QOS levels on such addresses.
155 * @param cbData Asynchronous callback function that is invoked by the stack when
156 * discovery or resource interaction is received. The discovery could be
157 * related to filtered/scoped/particular resource. The callback is
158 * generated for each response received.
159 * @param options The address of an array containing the vendor specific header options
160 * to be sent with the request.
161 * @param numOptions Number of header options to be included.
163 * @note: Presence subscription amendments (i.e. adding additional resource type filters by calling
164 * this API again) require the use of the same base URI as the original request to successfully
165 * amend the presence filters.
167 * @return ::OC_STACK_OK on success, some other value upon failure.
169 OCStackResult OC_CALL OCDoResource(OCDoHandle *handle,
171 const char *requestUri,
172 const OCDevAddr *destination,
174 OCConnectivityType connectivityType,
175 OCQualityOfService qos,
176 OCCallbackData *cbData,
177 OCHeaderOption *options,
181 * This function discovers or Perform requests on a specified resource
182 * (specified by that Resource's respective URI).
184 * @param handle To refer to the request sent out on behalf of
185 * calling this API. This handle can be used to cancel this operation
186 * via the OCCancel API.
187 * @note: This reference is handled internally, and should not be free'd by
188 * the consumer. A NULL handle is permitted in the event where the caller
189 * has no use for the return value.
190 * @param method To perform on the resource.
191 * @param requestUri URI of the resource to interact with. (Address prefix is deprecated in
192 * favor of destination.)
193 * @param destination Complete description of destination.
194 * @param payload Encoded request payload.
195 OCDoRequest does not free given payload.
196 * @param connectivityType Modifier flags when destination is not given.
197 * @param qos Quality of service. Note that if this API is called on a URI with the
198 * well-known multicast IP address, the qos will be forced to ::OC_LOW_QOS
199 * since it is impractical to send other QOS levels on such addresses.
200 * @param cbData Asynchronous callback function that is invoked by the stack when
201 * discovery or resource interaction is received. The discovery could be
202 * related to filtered/scoped/particular resource. The callback is
203 * generated for each response received.
204 * @param options The address of an array containing the vendor specific header options
205 * to be sent with the request.
206 * @param numOptions Number of header options to be included.
208 * @note: Presence subscription amendments (i.e. adding additional resource type filters by calling
209 * this API again) require the use of the same base URI as the original request to successfully
210 * amend the presence filters.
212 * @return ::OC_STACK_OK on success, some other value upon failure.
214 OCStackResult OC_CALL OCDoRequest(OCDoHandle *handle,
216 const char *requestUri,
217 const OCDevAddr *destination,
219 OCConnectivityType connectivityType,
220 OCQualityOfService qos,
221 OCCallbackData *cbData,
222 OCHeaderOption *options,
226 * This function cancels a request associated with a specific @ref OCDoResource invocation.
228 * @param handle Used to identify a specific OCDoResource invocation.
229 * @param qos Used to specify Quality of Service(read below).
230 * @param options Used to specify vendor specific header options when sending
231 * explicit observe cancellation.
232 * @param numOptions Number of header options to be included.
234 * @return ::OC_STACK_OK on success, some other value upon failure.
236 OCStackResult OC_CALL OCCancel(OCDoHandle handle,
237 OCQualityOfService qos,
238 OCHeaderOption * options,
242 * Register Persistent storage callback.
243 * @param persistentStorageHandler Pointers to open, read, write, close & unlink handlers.
246 * OC_STACK_OK No errors; Success.
247 * OC_STACK_INVALID_PARAM Invalid parameter.
249 OCStackResult OC_CALL OCRegisterPersistentStorageHandler(OCPersistentStorage* persistentStorageHandler);
253 * When operating in OCServer or OCClientServer mode,
254 * this API will start sending out presence notifications to clients via multicast.
255 * Once this API has been called with a success, clients may query for this server's presence and
256 * this server's stack will respond via multicast.
258 * Server can call this function when it comes online for the first time, or when it comes back
259 * online from offline mode, or when it re enters network.
261 * @param ttl Time To Live in seconds.
262 * @note: If ttl is '0', then the default stack value will be used (60 Seconds).
263 * If ttl is greater than ::OC_MAX_PRESENCE_TTL_SECONDS, then the ttl will be
264 * set to ::OC_MAX_PRESENCE_TTL_SECONDS.
266 * @return ::OC_STACK_OK on success, some other value upon failure.
268 OCStackResult OC_CALL OCStartPresence(const uint32_t ttl);
271 * When operating in OCServer or OCClientServer mode, this API will stop sending
272 * out presence notifications to clients via multicast.
273 * Once this API has been called with a success this server's stack will not respond to clients
274 * querying for this server's presence.
276 * Server can call this function when it is terminating, going offline, or when going
279 * @return ::OC_STACK_OK on success, some other value upon failure.
282 OCStackResult OC_CALL OCStopPresence(void);
287 * This function sets default device entity handler.
289 * @param entityHandler Entity handler function that is called by ocstack to handle requests
290 * for any undefined resources or default actions.If NULL is passed it
291 * removes the device default entity handler.
292 * @param callbackParameter Parameter passed back when entityHandler is called.
294 * @return ::OC_STACK_OK on success, some other value upon failure.
296 OCStackResult OC_CALL OCSetDefaultDeviceEntityHandler(OCDeviceEntityHandler entityHandler,
297 void* callbackParameter);
300 * This function sets device information.
302 * Upon call to OCInit, the default Device Type (i.e. "rt") has already been set to the default
303 * Device Type "oic.wk.d". You do not have to specify "oic.wk.d" in the OCDeviceInfo.types linked
304 * list. The default Device Type is mandatory and always specified by this Device as the first
307 * @deprecated Use OCSetPropertyValue instead.
309 * @param deviceInfo Structure passed by the server application containing the device
313 * ::OC_STACK_OK no errors.
314 * ::OC_STACK_INVALID_PARAM invalid parameter.
315 * ::OC_STACK_ERROR stack process error.
317 OCStackResult OC_CALL OCSetDeviceInfo(OCDeviceInfo deviceInfo);
320 * This function sets platform information.
322 * @param platformInfo Structure passed by the server application containing
323 * the platform information.
327 * ::OC_STACK_OK no errors.
328 * ::OC_STACK_INVALID_PARAM invalid parameter.
329 * ::OC_STACK_ERROR stack process error.
331 OCStackResult OC_CALL OCSetPlatformInfo(OCPlatformInfo platformInfo);
334 * This function creates a resource.
336 * @param handle Pointer to handle to newly created resource. Set by ocstack and
337 * used to refer to resource.
338 * @param resourceTypeName Name of resource type. Example: "core.led".
339 * @param resourceInterfaceName Name of resource interface. Example: "core.rw".
340 * @param uri URI of the resource. Example: "/a/led".
341 * @param entityHandler Entity handler function that is called by ocstack to handle
343 * NULL for default entity handler.
344 * @param callbackParam parameter passed back when entityHandler is called.
345 * @param resourceProperties Properties supported by resource.
346 * Example: ::OC_DISCOVERABLE|::OC_OBSERVABLE.
348 * @return ::OC_STACK_OK on success, some other value upon failure.
350 OCStackResult OC_CALL OCCreateResource(OCResourceHandle *handle,
351 const char *resourceTypeName,
352 const char *resourceInterfaceName,
354 OCEntityHandler entityHandler,
356 uint8_t resourceProperties);
359 * This function creates a resource.
361 * @param handle Pointer to handle to newly created resource. Set by ocstack and
362 * used to refer to resource.
363 * @param resourceTypeName Name of resource type. Example: "core.led".
364 * @param resourceInterfaceName Name of resource interface. Example: "core.rw".
365 * @param uri URI of the resource. Example: "/a/led".
366 * @param entityHandler Entity handler function that is called by ocstack to handle
368 * NULL for default entity handler.
369 * @param callbackParam parameter passed back when entityHandler is called.
370 * @param resourceProperties Properties supported by resource.
371 * Example: ::OC_DISCOVERABLE|::OC_OBSERVABLE.
372 * @param resourceTpsTypes Transport Protocol Suites(TPS) types of resource for expose
373 resource to specific transport adapter (e.g., TCP, UDP)
374 with messaging protocol (e.g., COAP, COAPS).
375 Example: "OC_COAP | OC_COAP_TCP"
377 * @note Only supported TPS types on stack will be mapped to resource.
378 It means "OC_COAPS" and "OC_COAPS_TCP" flags will be ignored if secure option
379 not enabled on stack. Also "COAP_TCP" and "COAPS_TCP" flags will be ignored
380 if stack does not support tcp mode.
382 * @return ::OC_STACK_OK on success, some other value upon failure.
384 OCStackResult OC_CALL OCCreateResourceWithEp(OCResourceHandle *handle,
385 const char *resourceTypeName,
386 const char *resourceInterfaceName,
388 OCEntityHandler entityHandler,
390 uint8_t resourceProperties,
391 OCTpsSchemeFlags resourceTpsTypes);
393 * This function returns flags of supported endpoint TPS on stack.
395 * @return Bit combinations of supported OCTpsSchemeFlags.
397 OCTpsSchemeFlags OC_CALL OCGetSupportedEndpointTpsFlags(void);
400 * This function adds a resource to a collection resource.
402 * @param collectionHandle Handle to the collection resource.
403 * @param resourceHandle Handle to resource to be added to the collection resource.
405 * @return ::OC_STACK_OK on success, some other value upon failure.
407 OCStackResult OC_CALL OCBindResource(OCResourceHandle collectionHandle, OCResourceHandle resourceHandle);
410 * This function removes a resource from a collection resource.
412 * @param collectionHandle Handle to the collection resource.
413 * @param resourceHandle Handle to resource to be removed from the collection resource.
415 * @return ::OC_STACK_OK on success, some other value upon failure.
417 OCStackResult OC_CALL OCUnBindResource(OCResourceHandle collectionHandle, OCResourceHandle resourceHandle);
420 * This function binds a resource type to a resource.
422 * @param handle Handle to the resource.
423 * @param resourceTypeName Name of resource type. Example: "core.led".
425 * @return ::OC_STACK_OK on success, some other value upon failure.
427 OCStackResult OC_CALL OCBindResourceTypeToResource(OCResourceHandle handle,
428 const char *resourceTypeName);
430 * This function binds a resource interface to a resource.
432 * @param handle Handle to the resource.
433 * @param resourceInterfaceName Name of resource interface. Example: "core.rw".
435 * @return ::OC_STACK_OK on success, some other value upon failure.
437 OCStackResult OC_CALL OCBindResourceInterfaceToResource(OCResourceHandle handle,
438 const char *resourceInterfaceName);
441 * This function binds an entity handler to the resource.
443 * @param handle Handle to the resource that the contained resource is to be bound.
444 * @param entityHandler Entity handler function that is called by ocstack to handle requests.
445 * @param callbackParameter Context parameter that will be passed to entityHandler.
447 * @return ::OC_STACK_OK on success, some other value upon failure.
449 OCStackResult OC_CALL OCBindResourceHandler(OCResourceHandle handle,
450 OCEntityHandler entityHandler,
451 void *callbackParameter);
454 * This function gets the number of resources that have been created in the stack.
456 * @param numResources Pointer to count variable.
458 * @return ::OC_STACK_OK on success, some other value upon failure.
460 OCStackResult OC_CALL OCGetNumberOfResources(uint8_t *numResources);
463 * This function gets a resource handle by index.
465 * @param index Index of resource, 0 to Count - 1.
467 * @return Found resource handle or NULL if not found.
469 OCResourceHandle OC_CALL OCGetResourceHandle(uint8_t index);
472 * This function deletes resource specified by handle. Deletes resource and all
473 * resource type and resource interface linked lists.
475 * @note: OCDeleteResource() performs operations similar to OCNotifyAllObservers() to notify all
476 * client observers that "this" resource is being deleted.
478 * @param handle Handle of resource to be deleted.
480 * @return ::OC_STACK_OK on success, some other value upon failure.
482 OCStackResult OC_CALL OCDeleteResource(OCResourceHandle handle);
485 * Get a string representation the server instance ID.
486 * The memory is managed internal to this function, so freeing externally will result
487 * in a runtime error.
488 * Note: This will NOT seed the RNG, so it must be called after the RNG is seeded.
489 * This is done automatically during the OCInit process,
490 * so ensure that this call is done after that.
492 * @return A string representation the server instance ID.
494 const char* OC_CALL OCGetServerInstanceIDString(void);
497 * This function gets the URI of the resource specified by handle.
499 * @param handle Handle of resource.
501 * @return URI string if resource found or NULL if not found.
503 const char *OC_CALL OCGetResourceUri(OCResourceHandle handle);
506 * This function gets the properties of the resource specified by handle.
508 * @param handle Handle of resource.
510 * @return OCResourceProperty Bitmask or -1 if resource is not found.
512 * @note that after a resource is created, the OC_ACTIVE property is set for the resource by the
515 OCResourceProperty OC_CALL OCGetResourceProperties(OCResourceHandle handle);
518 * This function sets the properties of the resource specified by handle.
520 * @param handle Handle of resource.
521 * @param resourceProperties Properties supported by resource.
522 * Example: ::OC_DISCOVERABLE|::OC_OBSERVABLE.
524 * @return ::OC_STACK_OK on success, some other value upon failure.
526 OCStackResult OC_CALL OCSetResourceProperties(OCResourceHandle handle, uint8_t resourceProperties);
529 * This function removes the properties of the resource specified by handle.
531 * @param handle Handle of resource.
532 * @param resourceProperties Properties not supported by resource.
533 * Example: ::OC_DISCOVERABLE|::OC_OBSERVABLE.
535 * @return ::OC_STACK_OK on success, some other value upon failure.
537 OCStackResult OC_CALL OCClearResourceProperties(OCResourceHandle handle, uint8_t resourceProperties);
540 * This function gets the number of resource types of the resource.
542 * @param handle Handle of resource.
543 * @param numResourceTypes Pointer to count variable.
545 * @return ::OC_STACK_OK on success, some other value upon failure.
547 OCStackResult OC_CALL OCGetNumberOfResourceTypes(OCResourceHandle handle, uint8_t *numResourceTypes);
550 * This function gets name of resource type of the resource.
552 * @param handle Handle of resource.
553 * @param index Index of resource, 0 to Count - 1.
555 * @return Resource type name if resource found or NULL if resource not found.
557 const char *OC_CALL OCGetResourceTypeName(OCResourceHandle handle, uint8_t index);
560 * This function gets the number of resource interfaces of the resource.
562 * @param handle Handle of resource.
563 * @param numResourceInterfaces Pointer to count variable.
565 * @return ::OC_STACK_OK on success, some other value upon failure.
567 OCStackResult OC_CALL OCGetNumberOfResourceInterfaces(OCResourceHandle handle,
568 uint8_t *numResourceInterfaces);
571 * This function gets name of resource interface of the resource.
573 * @param handle Handle of resource.
574 * @param index Index of resource, 0 to Count - 1.
576 * @return Resource interface name if resource found or NULL if resource not found.
578 const char *OC_CALL OCGetResourceInterfaceName(OCResourceHandle handle, uint8_t index);
581 * This function gets resource handle from the collection resource by index.
583 * @param collectionHandle Handle of collection resource.
584 * @param index Index of contained resource, 0 to Count - 1.
586 * @return Handle to contained resource if resource found or NULL if resource not found.
588 OCResourceHandle OC_CALL OCGetResourceHandleFromCollection(OCResourceHandle collectionHandle,
592 * This function gets the entity handler for a resource.
594 * @param handle Handle of resource.
596 * @return Entity handler if resource found or NULL resource not found.
598 OCEntityHandler OC_CALL OCGetResourceHandler(OCResourceHandle handle);
601 * This function notify all registered observers that the resource representation has
602 * changed. If observation includes a query the client is notified only if the query is valid after
603 * the resource representation has changed.
605 * @param handle Handle of resource.
606 * @param qos Desired quality of service for the observation notifications.
608 * @return ::OC_STACK_OK on success, some other value upon failure.
610 OCStackResult OC_CALL OCNotifyAllObservers(OCResourceHandle handle, OCQualityOfService qos);
613 * Notify specific observers with updated value of representation.
614 * Before this API is invoked by entity handler it has finished processing
615 * queries for the associated observers.
617 * @param handle Handle of resource.
618 * @param obsIdList List of observation IDs that need to be notified.
619 * @param numberOfIds Number of observation IDs included in obsIdList.
620 * @param payload Object representing the notification
621 * @param qos Desired quality of service of the observation notifications.
623 * @note: The memory for obsIdList and payload is managed by the entity invoking the API.
624 * The maximum size of the notification is 1015 bytes.
626 * @return ::OC_STACK_OK on success, some other value upon failure.
628 OCStackResult OC_CALL OCNotifyListOfObservers (OCResourceHandle handle,
629 OCObservationId *obsIdList,
631 const OCRepPayload *payload,
632 OCQualityOfService qos);
635 * This function sends a response to a request.
636 * The response can be a normal, slow, or block (i.e. a response that
637 * is too large to be sent in a single PDU and must span multiple transmissions).
639 * @param response Pointer to structure that contains response parameters.
641 * @return ::OC_STACK_OK on success, some other value upon failure.
643 OCStackResult OC_CALL OCDoResponse(OCEntityHandlerResponse *response);
646 * This function sets URI being used for proxy.
648 * @param uri NULL terminated resource URI for CoAP-HTTP Proxy.
650 OCStackResult OC_CALL OCSetProxyURI(const char *uri);
652 #if defined(RD_CLIENT) || defined(RD_SERVER)
654 * This function binds an resource unique id to the resource.
656 * @param handle Handle to the resource that the contained resource is to be bound.
657 * @param ins Unique ID for resource.
659 * @return ::OC_STACK_OK on success, some other value upon failure.
661 OCStackResult OC_CALL OCBindResourceInsToResource(OCResourceHandle handle, int64_t ins);
664 * This function gets the resource unique id for a resource.
666 * @param handle Handle of resource.
667 * @param ins Unique ID for resource.
669 * @return Ins if resource found or 0 resource not found.
671 OCStackResult OC_CALL OCGetResourceIns(OCResourceHandle handle, int64_t *ins);
675 * Sets the filename to be used for database persistent storage.
676 * @param[in] filename the filename.
678 * @return ::OC_STACK_OK on success, some other value upon failure.
680 OCStackResult OC_CALL OCRDDatabaseSetStorageFilename(const char *filename);
683 * Returns the filename to be used for database persistent storage.
685 * @return the filename
687 const char *OC_CALL OCRDDatabaseGetStorageFilename();
690 * Search the RD database for queries.
692 * @param interfaceType is the interface type that is queried.
693 * @param resourceType is the resource type that is queried.
694 * @param discPayload NULL if no resource found or else OCDiscoveryPayload with the details
695 * about the resources.
697 * @return ::OC_STACK_OK in case of success or else other value.
699 OCStackResult OC_CALL OCRDDatabaseDiscoveryPayloadCreate(const char *interfaceType,
700 const char *resourceType,
701 OCDiscoveryPayload **discPayload);
704 * Search the RD database for queries.
706 * @param interfaceType is the interface type that is queried.
707 * @param resourceType is the resource type that is queried.
708 * @param endpoint is the requesting endpoint to filter created eps value against.
709 * @param discPayload NULL if no resource found or else OCDiscoveryPayload with the details
710 * about the resources.
712 * @return ::OC_STACK_OK in case of success or else other value.
714 OCStackResult OC_CALL OCRDDatabaseDiscoveryPayloadCreateWithEp(const char *interfaceType,
715 const char *resourceType,
717 OCDiscoveryPayload **discPayload);
719 #endif // RD_CLIENT || RD_SERVER
722 * This function gets a resource handle by resource uri.
724 * @param uri URI of Resource to get Resource handle.
726 * @return Found resource handle or NULL if not found.
728 OCResourceHandle OC_CALL OCGetResourceHandleAtUri(const char *uri);
731 * Add a header option to the given header option array.
733 * @param ocHdrOpt Pointer to existing options.
734 * @param numOptions Number of existing options.
735 * @param optionID COAP option ID.
736 * @param optionData Option data value.
737 * @param optionDataLength Size of Option data value.
739 * @return ::OC_STACK_OK on success and other value otherwise.
741 OCStackResult OC_CALL OCSetHeaderOption(OCHeaderOption* ocHdrOpt,
745 size_t optionDataLength);
748 * Get data value of the option with specified option ID from given header option array.
750 * @param ocHdrOpt Pointer to existing options.
751 * @param numOptions Number of existing options.
752 * @param optionID COAP option ID.
753 * @param optionData Pointer to option data.
754 * @param optionDataLength Size of option data value.
755 * @param receivedDatalLength Pointer to the actual length of received data.
757 * @return ::OC_STACK_OK on success and other value otherwise.
759 OCStackResult OC_CALL OCGetHeaderOption(OCHeaderOption* ocHdrOpt,
763 size_t optionDataLength,
764 uint16_t* receivedDatalLength);
767 * gets the deviceId of the client
769 * @param deviceId pointer.
770 * @return Returns ::OC_STACK_OK if success.
772 OCStackResult OC_CALL OCGetDeviceId(OCUUIdentity *deviceId);
775 * sets the deviceId of the client
777 * @param deviceId pointer.
778 * @return Returns ::OC_STACK_OK if success.
780 OCStackResult OC_CALL OCSetDeviceId(const OCUUIdentity *deviceId);
783 * Gets the bool state of "isOwned" property on the doxm resource.
785 * @param isOwned a pointer to be assigned to isOwned property
786 * @return Returns ::OC_STACK_OK if success.
788 OCStackResult OC_CALL OCGetDeviceOwnedState(bool *isOwned);
791 * Encode an address string to match RFC 6874.
793 * @param outputAddress a char array to be written with the encoded string.
794 * @param outputSize size of outputAddress buffer.
795 * @param inputAddress a char array of size <= CA_MAX_URI_LENGTH
796 * containing a valid IPv6 address string.
798 * @return ::OC_STACK_OK on success and other value otherwise.
800 OCStackResult OC_CALL OCEncodeAddressForRFC6874(char* outputAddress,
802 const char* inputAddress);
805 * Decode an address string according to RFC 6874.
807 * @param outputAddress a char array to be written with the decoded string.
808 * @param outputSize size of outputAddress buffer.
809 * @param inputAddress a valid percent-encoded address string.
810 * @param end NULL if the entire entire inputAddress is a null-terminated percent-
811 * encoded address string. Otherwise, a pointer to the first byte that
812 * is not part of the address string (e.g., ']' in a URI).
814 * @return ::OC_STACK_OK on success and other value otherwise.
816 OCStackResult OC_CALL OCDecodeAddressForRFC6874(char* outputAddress,
818 const char* inputAddress,
822 * Set the value of /oic/d and /oic/p properties. This function is a generic function that sets for
823 * all OCF defined properties.
825 * For PAYLOAD_TYPE_DEVICE and OC_RSRVD_DATA_MODEL_VERSION, value must be a const char* CSV string.
826 * For PAYLOAD_TYPE_DEVICE and OC_RSRVD_DEVICE_DESCRIPTION, or OC_RSRVD_DEVICE_MFG_NAME, value must
827 * be an OCStringLL* with pairs of language tag and value elements. For all other
828 * PAYLOAD_TYPE_DEVICE properties, value must be a const char* string.
830 * @param type the payload type for device and platform as defined in @ref OCPayloadType.
831 * @param propName the pre-defined property as per OCF spec.
832 * @param value the value of the property to be set.
834 * @return ::OC_STACK_OK on success and other value otherwise.
836 OCStackResult OC_CALL OCSetPropertyValue(OCPayloadType type, const char *propName, const void *value);
839 * Get the value of /oic/d and /oic/p properties. This function is a generic function that gets the
840 * value for all OCF defined properties.
842 * For PAYLOAD_TYPE_DEVICE and OC_RSRVD_RESOURCE_TYPE, OC_RSRVD_INTERFACE,
843 * OC_RSRVD_DATA_MODEL_VERSION, OC_RSRVD_DEVICE_DESCRIPTION, or OC_RSRVD_DEVICE_MFG_NAME, the value
844 * will be an OCStringLL*. For all other PAYLOAD_TYPE_DEVICE properties, value will be a char*.
846 * When the returned value is non-NULL, the memory must be OCFreeOCStringLL()'d or OICFree()'d by
847 * the caller (depending on the underlying type returned).
849 * @param type the payload type for device and platform as defined in @ref OCPayloadType.
850 * @param propName the pre-defined as per OCF spec.
851 * @param value this holds the return value. In case of error will be set to NULL.
853 * @return ::OC_STACK_OK on success and other value otherwise.
855 OCStackResult OC_CALL OCGetPropertyValue(OCPayloadType type, const char *propName, void **value);
858 * Get the registered persistent storage handler. All modules must use this to obtain access to
859 * persistent storage.
861 * @return pointer to OCPersistentStorage structure on success and NULL otherwise.
863 OCPersistentStorage *OC_CALL OCGetPersistentStorageHandler(void);
866 * This function return link local zone id related from ifindex.
868 * @param[in] ifindex interface index.
869 * @param[out] zoneId pointer of zoneId string, caller should free
870 * zoneId using OICFree() when it returned CA_STATUS_OK.
871 * @return ::OC_STACK_OK if successful.
873 OCStackResult OC_CALL OCGetLinkLocalZoneId(uint32_t ifindex, char **zoneId);
876 * Select the cipher suite for dtls handshake.
878 * @param[in] cipher cipher suite (Note : Make sure endianness).
879 * TLS_RSA_WITH_AES_256_CBC_SHA256 0x3D
880 * TLS_RSA_WITH_AES_128_GCM_SHA256 0x009C
881 * TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 0xC02B
882 * TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8 0xC0AE
883 * TLS_ECDHE_ECDSA_WITH_AES_128_CCM 0xC0AC
884 * TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 0xC023
885 * TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 0xC024
886 * TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 0xC02C
887 * TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA256 0xC037
888 * TLS_ECDH_anon_WITH_AES_128_CBC_SHA 0xC018
889 * @param[in] adapterType transport adapter (TCP/IP/BLE)
891 * @return ::OC_STACK_OK if successful.
893 OCStackResult OC_CALL OCSelectCipherSuite(uint16_t cipher, OCTransportAdapter adapterType);
896 * Return the scope level of a given IP address.
898 * @param[in] addr remote IP address.
899 * @param[out] scope scope level of given IP address.
901 * @return ::OC_STACK_OK if successful.
903 OCStackResult OC_CALL OCGetIpv6AddrScope(const char *addr, OCTransportFlags *scope);
906 * Return the Content Format from Entity Handler Request.
908 * @param[in] ehRequest client request on entity handler
909 * @param[out] pContentFormat media content format enum OCPayloadFormat
910 * @param[out] pAcceptVersion accept version (e.g: 2048 for "1.0.0", NULL input is accepted)
912 * @return ::OC_STACK_OK if successful.
914 OCStackResult OC_CALL OCGetRequestPayloadVersion(OCEntityHandlerRequest *ehRequest,
915 OCPayloadFormat* pContentFormat, uint16_t* pAcceptVersion);
919 #endif // __cplusplus
921 #endif /* OCSTACK_H_ */