Use `URI` all caps in documentation
[iotivity.git] / resource / csdk / stack / include / ocstack.h
1 //******************************************************************
2 //
3 // Copyright 2014 Intel Mobile Communications GmbH All Rights Reserved.
4 //
5 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
6 //
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
10 //
11 //      http://www.apache.org/licenses/LICENSE-2.0
12 //
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.
18 //
19 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
20 //
21
22 /**
23  * @file
24  *
25  * This file contains APIs for OIC Stack to be implemented.
26  */
27
28 #ifndef OCSTACK_H_
29 #define OCSTACK_H_
30
31 #include <stdio.h>
32 #include <stdint.h>
33 #include "octypes.h"
34
35 #include "platform_features.h"
36
37 #ifdef __cplusplus
38 extern "C" {
39 #endif // __cplusplus
40
41 /** Macro to use Random port.*/
42 #define USE_RANDOM_PORT (0)
43
44 /*
45  * Function prototypes
46  */
47
48 /**
49  * This function Initializes the OC Stack.  Must be called prior to starting the stack.
50  *
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.
54  *
55  * @return ::OC_STACK_OK on success, some other value upon failure.
56  */
57 OCStackResult OC_CALL OCInit1(OCMode mode, OCTransportFlags serverFlags, OCTransportFlags clientFlags);
58
59 /**
60  * This function Initializes the OC Stack.  Must be called prior to starting the stack.
61  *
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.
66  *
67  * @return ::OC_STACK_OK on success, some other value upon failure.
68  */
69 OCStackResult OC_CALL OCInit2(OCMode mode, OCTransportFlags serverFlags, OCTransportFlags clientFlags,
70                       OCTransportAdapter transportType);
71
72 /**
73  * This function Initializes the OC Stack.  Must be called prior to starting the stack.
74  *
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.
78  *
79  * @return ::OC_STACK_OK on success, some other value upon failure.
80  */
81 OCStackResult OC_CALL OCInit(const char *ipAddr, uint16_t port, OCMode mode);
82
83 #ifdef RA_ADAPTER
84 /**
85  * @brief   Set Remote Access information for XMPP Client.
86  * @param[in] raInfo  remote access info.
87  *
88  * @return  ::OC_STACK_OK on success, some other value upon failure.
89  */
90 OCStackResult OC_CALL OCSetRAInfo(const OCRAInfo_t *raInfo);
91 #endif
92
93 /**
94  * This function Stops the OC stack.  Use for a controlled shutdown.
95  *
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
99  * deleted.
100  *
101  * @return ::OC_STACK_OK on success, some other value upon failure.
102  */
103 OCStackResult OC_CALL OCStop(void);
104
105 /**
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.
109  *
110  * @return ::OC_STACK_OK on success, some other value upon failure.
111  */
112 OCStackResult OC_CALL OCStartMulticastServer(void);
113
114 /**
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.
117  *
118  * Note that other multicast requests, such as those used during ownership
119  * transfer, continue to be responded to.
120  *
121  * @return ::OC_STACK_OK on success, some other value upon failure.
122  */
123 OCStackResult OC_CALL OCStopMulticastServer(void);
124
125 /**
126  * This function is Called in main loop of OC client or server.
127  * Allows low-level processing of stack services.
128  *
129  * @return ::OC_STACK_OK on success, some other value upon failure.
130  */
131 OCStackResult OC_CALL OCProcess(void);
132
133 /**
134  * This function discovers or Perform requests on a specified resource
135  * (specified by that Resource's respective URI).
136  *
137  * @deprecated: Use OCDoRequest instead which does not free given payload.
138  *
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.
162  *
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.
166  *
167  * @return ::OC_STACK_OK on success, some other value upon failure.
168  */
169 OCStackResult OC_CALL OCDoResource(OCDoHandle *handle,
170                            OCMethod method,
171                            const char *requestUri,
172                            const OCDevAddr *destination,
173                            OCPayload* payload,
174                            OCConnectivityType connectivityType,
175                            OCQualityOfService qos,
176                            OCCallbackData *cbData,
177                            OCHeaderOption *options,
178                            uint8_t numOptions);
179
180 /**
181  * This function discovers or Perform requests on a specified resource
182  * (specified by that Resource's respective URI).
183  *
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.
207  *
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.
211  *
212  * @return ::OC_STACK_OK on success, some other value upon failure.
213  */
214 OCStackResult OC_CALL OCDoRequest(OCDoHandle *handle,
215                           OCMethod method,
216                           const char *requestUri,
217                           const OCDevAddr *destination,
218                           OCPayload* payload,
219                           OCConnectivityType connectivityType,
220                           OCQualityOfService qos,
221                           OCCallbackData *cbData,
222                           OCHeaderOption *options,
223                           uint8_t numOptions);
224
225 /**
226  * This function cancels a request associated with a specific @ref OCDoResource invocation.
227  *
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.
233  *
234  * @return ::OC_STACK_OK on success, some other value upon failure.
235  */
236 OCStackResult OC_CALL OCCancel(OCDoHandle handle,
237                        OCQualityOfService qos,
238                        OCHeaderOption * options,
239                        uint8_t numOptions);
240
241 /**
242  * Register Persistent storage callback.
243  * @param   persistentStorageHandler  Pointers to open, read, write, close & unlink handlers.
244  *
245  * @return
246  *     OC_STACK_OK                    No errors; Success.
247  *     OC_STACK_INVALID_PARAM         Invalid parameter.
248  */
249 OCStackResult OC_CALL OCRegisterPersistentStorageHandler(OCPersistentStorage* persistentStorageHandler);
250
251 #ifdef WITH_PRESENCE
252 /**
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.
257  *
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.
260  *
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.
265  *
266  * @return ::OC_STACK_OK on success, some other value upon failure.
267  */
268 OCStackResult OC_CALL OCStartPresence(const uint32_t ttl);
269
270 /**
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.
275  *
276  * Server can call this function when it is terminating, going offline, or when going
277  * away from network.
278  *
279  * @return ::OC_STACK_OK on success, some other value upon failure.
280  */
281
282 OCStackResult OC_CALL OCStopPresence(void);
283 #endif
284
285
286 /**
287  * This function sets default device entity handler.
288  *
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.
293  *
294  * @return ::OC_STACK_OK on success, some other value upon failure.
295  */
296 OCStackResult OC_CALL OCSetDefaultDeviceEntityHandler(OCDeviceEntityHandler entityHandler,
297                                               void* callbackParameter);
298
299 /**
300  * This function sets device information.
301  *
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
305  * Device Type.
306  *
307  * @deprecated Use OCSetPropertyValue instead.
308  *
309  * @param deviceInfo   Structure passed by the server application containing the device
310  *                     information.
311  *
312  * @return
313  *     ::OC_STACK_OK               no errors.
314  *     ::OC_STACK_INVALID_PARAM    invalid parameter.
315  *     ::OC_STACK_ERROR            stack process error.
316  */
317 OCStackResult OC_CALL OCSetDeviceInfo(OCDeviceInfo deviceInfo);
318
319 /**
320  * This function sets platform information.
321  *
322  * @param platformInfo   Structure passed by the server application containing
323  *                       the platform information.
324  *
325  *
326  * @return
327  *     ::OC_STACK_OK               no errors.
328  *     ::OC_STACK_INVALID_PARAM    invalid parameter.
329  *     ::OC_STACK_ERROR            stack process error.
330  */
331 OCStackResult OC_CALL OCSetPlatformInfo(OCPlatformInfo platformInfo);
332
333 /**
334  * This function creates a resource.
335  *
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
342  *                              requests, etc.
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.
347  *
348  * @return ::OC_STACK_OK on success, some other value upon failure.
349  */
350 OCStackResult OC_CALL OCCreateResource(OCResourceHandle *handle,
351                                const char *resourceTypeName,
352                                const char *resourceInterfaceName,
353                                const char *uri,
354                                OCEntityHandler entityHandler,
355                                void* callbackParam,
356                                uint8_t resourceProperties);
357
358 /**
359  * This function creates a resource.
360  *
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
367  *                              requests, etc.
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"
376  *
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.
381  *
382  * @return ::OC_STACK_OK on success, some other value upon failure.
383  */
384 OCStackResult OC_CALL OCCreateResourceWithEp(OCResourceHandle *handle,
385                                      const char *resourceTypeName,
386                                      const char *resourceInterfaceName,
387                                      const char *uri,
388                                      OCEntityHandler entityHandler,
389                                      void *callbackParam,
390                                      uint8_t resourceProperties,
391                                      OCTpsSchemeFlags resourceTpsTypes);
392 /*
393  * This function returns flags of supported endpoint TPS on stack.
394  *
395  * @return Bit combinations of supported OCTpsSchemeFlags.
396  */
397 OCTpsSchemeFlags OC_CALL OCGetSupportedEndpointTpsFlags(void);
398
399 /**
400  * This function adds a resource to a collection resource.
401  *
402  * @param collectionHandle    Handle to the collection resource.
403  * @param resourceHandle      Handle to resource to be added to the collection resource.
404  *
405  * @return ::OC_STACK_OK on success, some other value upon failure.
406  */
407 OCStackResult OC_CALL OCBindResource(OCResourceHandle collectionHandle, OCResourceHandle resourceHandle);
408
409 /**
410  * This function removes a resource from a collection resource.
411  *
412  * @param collectionHandle   Handle to the collection resource.
413  * @param resourceHandle     Handle to resource to be removed from the collection resource.
414  *
415  * @return ::OC_STACK_OK on success, some other value upon failure.
416  */
417 OCStackResult OC_CALL OCUnBindResource(OCResourceHandle collectionHandle, OCResourceHandle resourceHandle);
418
419 /**
420  * This function binds a resource type to a resource.
421  *
422  * @param handle            Handle to the resource.
423  * @param resourceTypeName  Name of resource type.  Example: "core.led".
424  *
425  * @return ::OC_STACK_OK on success, some other value upon failure.
426  */
427 OCStackResult OC_CALL OCBindResourceTypeToResource(OCResourceHandle handle,
428                                            const char *resourceTypeName);
429 /**
430  * This function binds a resource interface to a resource.
431  *
432  * @param handle                  Handle to the resource.
433  * @param resourceInterfaceName   Name of resource interface.  Example: "core.rw".
434  *
435  * @return ::OC_STACK_OK on success, some other value upon failure.
436  */
437 OCStackResult OC_CALL OCBindResourceInterfaceToResource(OCResourceHandle handle,
438                                                 const char *resourceInterfaceName);
439
440 /**
441  * This function binds an entity handler to the resource.
442  *
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.
446  *
447  * @return ::OC_STACK_OK on success, some other value upon failure.
448  */
449 OCStackResult OC_CALL OCBindResourceHandler(OCResourceHandle handle,
450                                     OCEntityHandler entityHandler,
451                                     void *callbackParameter);
452
453 /**
454  * This function gets the number of resources that have been created in the stack.
455  *
456  * @param numResources    Pointer to count variable.
457  *
458  * @return ::OC_STACK_OK on success, some other value upon failure.
459  */
460 OCStackResult OC_CALL OCGetNumberOfResources(uint8_t *numResources);
461
462 /**
463  * This function gets a resource handle by index.
464  *
465  * @param index   Index of resource, 0 to Count - 1.
466  *
467  * @return Found  resource handle or NULL if not found.
468  */
469 OCResourceHandle OC_CALL OCGetResourceHandle(uint8_t index);
470
471 /**
472  * This function deletes resource specified by handle.  Deletes resource and all
473  * resource type and resource interface linked lists.
474  *
475  * @note: OCDeleteResource() performs operations similar to OCNotifyAllObservers() to notify all
476  * client observers that "this" resource is being deleted.
477  *
478  * @param handle          Handle of resource to be deleted.
479  *
480  * @return ::OC_STACK_OK on success, some other value upon failure.
481  */
482 OCStackResult OC_CALL OCDeleteResource(OCResourceHandle handle);
483
484 /**
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.
491  *
492  * @return A string representation  the server instance ID.
493  */
494 const char* OC_CALL OCGetServerInstanceIDString(void);
495
496 /**
497  * This function gets the URI of the resource specified by handle.
498  *
499  * @param handle     Handle of resource.
500  *
501  * @return URI string if resource found or NULL if not found.
502  */
503 const char *OC_CALL OCGetResourceUri(OCResourceHandle handle);
504
505 /**
506  * This function gets the properties of the resource specified by handle.
507  *
508  * @param handle                Handle of resource.
509  *
510  * @return OCResourceProperty   Bitmask or -1 if resource is not found.
511  *
512  * @note that after a resource is created, the OC_ACTIVE property is set for the resource by the
513  * stack.
514  */
515 OCResourceProperty OC_CALL OCGetResourceProperties(OCResourceHandle handle);
516
517 /**
518  * This function sets the properties of the resource specified by handle.
519  *
520  * @param handle                Handle of resource.
521  * @param resourceProperties    Properties supported by resource.
522  *                              Example: ::OC_DISCOVERABLE|::OC_OBSERVABLE.
523  *
524  * @return ::OC_STACK_OK on success, some other value upon failure.
525  */
526 OCStackResult OC_CALL OCSetResourceProperties(OCResourceHandle handle, uint8_t resourceProperties);
527
528 /**
529  * This function removes the properties of the resource specified by handle.
530  *
531  * @param handle                Handle of resource.
532  * @param resourceProperties    Properties not supported by resource.
533  *                              Example: ::OC_DISCOVERABLE|::OC_OBSERVABLE.
534  *
535  * @return ::OC_STACK_OK on success, some other value upon failure.
536  */
537 OCStackResult OC_CALL OCClearResourceProperties(OCResourceHandle handle, uint8_t resourceProperties);
538
539 /**
540  * This function gets the number of resource types of the resource.
541  *
542  * @param handle            Handle of resource.
543  * @param numResourceTypes  Pointer to count variable.
544  *
545  * @return ::OC_STACK_OK on success, some other value upon failure.
546  */
547 OCStackResult OC_CALL OCGetNumberOfResourceTypes(OCResourceHandle handle, uint8_t *numResourceTypes);
548
549 /**
550  * This function gets name of resource type of the resource.
551  *
552  * @param handle       Handle of resource.
553  * @param index        Index of resource, 0 to Count - 1.
554  *
555  * @return Resource type name if resource found or NULL if resource not found.
556  */
557 const char *OC_CALL OCGetResourceTypeName(OCResourceHandle handle, uint8_t index);
558
559 /**
560  * This function gets the number of resource interfaces of the resource.
561  *
562  * @param handle                 Handle of resource.
563  * @param numResourceInterfaces  Pointer to count variable.
564  *
565  * @return ::OC_STACK_OK on success, some other value upon failure.
566  */
567 OCStackResult OC_CALL OCGetNumberOfResourceInterfaces(OCResourceHandle handle,
568         uint8_t *numResourceInterfaces);
569
570 /**
571  * This function gets name of resource interface of the resource.
572  *
573  * @param handle      Handle of resource.
574  * @param index       Index of resource, 0 to Count - 1.
575  *
576  * @return Resource interface name if resource found or NULL if resource not found.
577  */
578 const char *OC_CALL OCGetResourceInterfaceName(OCResourceHandle handle, uint8_t index);
579
580 /**
581  * This function gets resource handle from the collection resource by index.
582  *
583  * @param collectionHandle   Handle of collection resource.
584  * @param index              Index of contained resource, 0 to Count - 1.
585  *
586  * @return Handle to contained resource if resource found or NULL if resource not found.
587  */
588 OCResourceHandle OC_CALL OCGetResourceHandleFromCollection(OCResourceHandle collectionHandle,
589         uint8_t index);
590
591 /**
592  * This function gets the entity handler for a resource.
593  *
594  * @param handle            Handle of resource.
595  *
596  * @return Entity handler if resource found or NULL resource not found.
597  */
598 OCEntityHandler OC_CALL OCGetResourceHandler(OCResourceHandle handle);
599
600 /**
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.
604  *
605  * @param handle   Handle of resource.
606  * @param qos      Desired quality of service for the observation notifications.
607  *
608  * @return ::OC_STACK_OK on success, some other value upon failure.
609  */
610 OCStackResult OC_CALL OCNotifyAllObservers(OCResourceHandle handle, OCQualityOfService qos);
611
612 /**
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.
616  *
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.
622  *
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.
625  *
626  * @return ::OC_STACK_OK on success, some other value upon failure.
627  */
628 OCStackResult OC_CALL OCNotifyListOfObservers (OCResourceHandle handle,
629                                        OCObservationId  *obsIdList,
630                                        uint8_t          numberOfIds,
631                                        const OCRepPayload *payload,
632                                        OCQualityOfService qos);
633
634 /**
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).
638  *
639  * @param response   Pointer to structure that contains response parameters.
640  *
641  * @return ::OC_STACK_OK on success, some other value upon failure.
642  */
643 OCStackResult OC_CALL OCDoResponse(OCEntityHandlerResponse *response);
644
645 /**
646  * This function sets URI being used for proxy.
647  *
648  * @param uri            NULL terminated resource URI for CoAP-HTTP Proxy.
649  */
650 OCStackResult OC_CALL OCSetProxyURI(const char *uri);
651
652 #if defined(RD_CLIENT) || defined(RD_SERVER)
653 /**
654  * This function binds an resource unique id to the resource.
655  *
656  * @param handle            Handle to the resource that the contained resource is to be bound.
657  * @param ins               Unique ID for resource.
658  *
659  * @return ::OC_STACK_OK on success, some other value upon failure.
660  */
661 OCStackResult OC_CALL OCBindResourceInsToResource(OCResourceHandle handle, int64_t ins);
662
663 /**
664  * This function gets the resource unique id for a resource.
665  *
666  * @param handle            Handle of resource.
667  * @param ins               Unique ID for resource.
668  *
669  * @return Ins if resource found or 0 resource not found.
670  */
671 OCStackResult OC_CALL OCGetResourceIns(OCResourceHandle handle, int64_t *ins);
672
673 #ifdef RD_SERVER
674 /**
675  * Sets the filename to be used for database persistent storage.
676  * @param[in] filename  the filename.
677  *
678  * @return  ::OC_STACK_OK on success, some other value upon failure.
679  */
680 OCStackResult OC_CALL OCRDDatabaseSetStorageFilename(const char *filename);
681
682 /**
683  * Returns the filename to be used for database persistent storage.
684  *
685  * @return the filename
686  */
687 const char *OC_CALL OCRDDatabaseGetStorageFilename();
688
689 /**
690 * Search the RD database for queries.
691 *
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.
696 *
697 * @return ::OC_STACK_OK in case of success or else other value.
698 */
699 OCStackResult OC_CALL OCRDDatabaseDiscoveryPayloadCreate(const char *interfaceType,
700                                                  const char *resourceType,
701                                                  OCDiscoveryPayload **discPayload);
702
703 /**
704 * Search the RD database for queries.
705 *
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.
711 *
712 * @return ::OC_STACK_OK in case of success or else other value.
713 */
714 OCStackResult OC_CALL OCRDDatabaseDiscoveryPayloadCreateWithEp(const char *interfaceType,
715                                                  const char *resourceType,
716                                                  OCDevAddr *endpoint,
717                                                  OCDiscoveryPayload **discPayload);
718 #endif // RD_SERVER
719 #endif // RD_CLIENT || RD_SERVER
720
721 /**
722 * This function gets a resource handle by resource uri.
723 *
724 * @param uri URI of Resource to get Resource handle.
725 *
726 * @return Found resource handle or NULL if not found.
727 */
728 OCResourceHandle OC_CALL OCGetResourceHandleAtUri(const char *uri);
729
730 /**
731  *  Add a header option to the given header option array.
732  *
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.
738  *
739  * @return ::OC_STACK_OK on success and other value otherwise.
740  */
741 OCStackResult OC_CALL OCSetHeaderOption(OCHeaderOption* ocHdrOpt,
742                                 size_t* numOptions,
743                                 uint16_t optionID,
744                                 void* optionData,
745                                 size_t optionDataLength);
746
747 /**
748  *  Get data value of the option with specified option ID from given header option array.
749  *
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.
756  *
757  * @return ::OC_STACK_OK on success and other value otherwise.
758  */
759 OCStackResult OC_CALL OCGetHeaderOption(OCHeaderOption* ocHdrOpt,
760                                 size_t numOptions,
761                                 uint16_t optionID,
762                                 void* optionData,
763                                 size_t optionDataLength,
764                                 uint16_t* receivedDatalLength);
765
766 /**
767  * gets the deviceId of the client
768  *
769  * @param deviceId pointer.
770  * @return Returns ::OC_STACK_OK if success.
771  */
772 OCStackResult OC_CALL OCGetDeviceId(OCUUIdentity *deviceId);
773
774 /**
775  * sets the deviceId of the client
776  *
777  * @param deviceId pointer.
778  * @return Returns ::OC_STACK_OK if success.
779  */
780 OCStackResult OC_CALL OCSetDeviceId(const OCUUIdentity *deviceId);
781
782  /**
783  * Gets the bool state of "isOwned" property on the doxm resource.
784  *
785  * @param isOwned a pointer to be assigned to isOwned property
786  * @return Returns ::OC_STACK_OK if success.
787  */
788 OCStackResult OC_CALL OCGetDeviceOwnedState(bool *isOwned);
789
790 /**
791  * Encode an address string to match RFC 6874.
792  *
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.
797  *
798  * @return ::OC_STACK_OK on success and other value otherwise.
799  */
800 OCStackResult OC_CALL OCEncodeAddressForRFC6874(char* outputAddress,
801                                         size_t outputSize,
802                                         const char* inputAddress);
803
804 /**
805  * Decode an address string according to RFC 6874.
806  *
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).
813  *
814  * @return ::OC_STACK_OK on success and other value otherwise.
815  */
816 OCStackResult OC_CALL OCDecodeAddressForRFC6874(char* outputAddress,
817                                         size_t outputSize,
818                                         const char* inputAddress,
819                                         const char* end);
820
821 /**
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.
824  *
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.
829  *
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.
833  *
834  * @return ::OC_STACK_OK on success and other value otherwise.
835  */
836 OCStackResult OC_CALL OCSetPropertyValue(OCPayloadType type, const char *propName, const void *value);
837
838 /**
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.
841  *
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*.
845  *
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).
848  *
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.
852  *
853  * @return ::OC_STACK_OK on success and other value otherwise.
854  */
855 OCStackResult OC_CALL OCGetPropertyValue(OCPayloadType type, const char *propName, void **value);
856
857 /**
858 * Get the registered persistent storage handler. All modules must use this to obtain access to
859 * persistent storage.
860 *
861 * @return pointer to OCPersistentStorage structure on success and NULL otherwise.
862 */
863 OCPersistentStorage *OC_CALL OCGetPersistentStorageHandler(void);
864
865 /**
866 * This function return link local zone id related from ifindex.
867 *
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.
872 */
873 OCStackResult OC_CALL OCGetLinkLocalZoneId(uint32_t ifindex, char **zoneId);
874
875 /**
876  * Select the cipher suite for dtls handshake.
877  *
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)
890  *
891  * @return ::OC_STACK_OK if successful.
892  */
893 OCStackResult OC_CALL OCSelectCipherSuite(uint16_t cipher, OCTransportAdapter adapterType);
894
895 /**
896  * Return the scope level of a given IP address.
897  *
898  * @param[in] addr          remote IP address.
899  * @param[out] scope        scope level of given IP address.
900  *
901  * @return ::OC_STACK_OK if successful.
902  */
903 OCStackResult OC_CALL OCGetIpv6AddrScope(const char *addr, OCTransportFlags *scope);
904
905 /**
906 * Return the Content Format from Entity Handler Request.
907 *
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)
911 *
912 * @return ::OC_STACK_OK if successful.
913 */
914 OCStackResult OC_CALL OCGetRequestPayloadVersion(OCEntityHandlerRequest *ehRequest,
915                                   OCPayloadFormat* pContentFormat, uint16_t* pAcceptVersion);
916
917 #ifdef __cplusplus
918 }
919 #endif // __cplusplus
920
921 #endif /* OCSTACK_H_ */