Use `URI` all caps in documentation
[iotivity.git] / resource / include / OCPlatform.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  * @file
23  *
24  * This file contains the declaration of classes and its members related to
25  * OCPlatform.
26  */
27
28 #ifndef OC_PLATFORM_H_
29 #define OC_PLATFORM_H_
30 #include <OCApi.h>
31 #include <OCPlatform_impl.h>
32 namespace OC
33 {
34     /**
35     * This namespace contains the main entrance/functionality of the product.
36     * It may be used with OC::OCPlatform::functionName.  To set a custom configuration,
37     * the implementer must make a call to OCPlatform::Configure before the first usage
38     * of a function in this namespace.
39     */
40     namespace OCPlatform
41     {
42         /**
43         * API for overwriting the default configuration of the OCPlatform object.
44         * @note Any calls made to this AFTER the first call to OCPlatform::Instance
45         * will have no affect
46         */
47         void Configure(const PlatformConfig& config);
48
49         // typedef for handle to cancel presence info with
50         typedef OCDoHandle OCPresenceHandle;
51
52         /**
53          * API for stop Base layer including resource and connectivity abstraction.
54          * The API is reference counted. The calls to start and stop need to be balanced.
55          *
56          * @return Returns ::OC_STACK_OK if success.
57          */
58         OCStackResult stop();
59
60         /**
61          * API for start Base layer including resource and connectivity abstraction.
62          * OCInit will be invoked.
63          * The API is reference counted. The calls to start and stop need to be balanced.
64          *
65          * @return Returns ::OC_STACK_OK if success.
66          */
67         OCStackResult start();
68
69         /**
70          * API for notifying base that resource's attributes have changed.
71          *
72          * @param resourceHandle resource handle of the resource
73          *
74          * @return Returns ::OC_STACK_OK if success.
75          * @note This API is for server side only.
76          * @note OCResourceHandle is defined in ocstack.h
77          * @note OCStackResult is defined in ocstack.h.
78          * @see notifyAllObservers(OCResourceHandle, QualityOfService)
79          */
80         OCStackResult notifyAllObservers(OCResourceHandle resourceHandle);
81
82         /**
83          * @overload
84          *
85          * @param resourceHandle resource handle of the resource
86          * @param QoS the quality of communication
87          * @see notifyAllObservers(OCResourceHandle)
88          */
89         OCStackResult notifyAllObservers(OCResourceHandle resourceHandle, QualityOfService QoS);
90
91         /**
92          * API for notifying only specific clients that resource's attributes have changed.
93          *
94          * @param resourceHandle resource handle of the resource
95          * @param observationIds std vector of observationIds. These set of ids are ones which
96          * which will be notified upon resource change.
97          * @param responsePtr OCResourceResponse pointer used by app to fill the response for this
98          * resource change.
99          *
100          * @return Returns ::OC_STACK_OK if success.
101          * @note This API is for server side only.
102          * @note OCResourceHandle is defined in ocstack.h.
103          * @note OCStackResult is defined in ocstack.h.
104          * @see notifyListOfObservers(OCResourceHandle, ObservationIds&, const std::shared_ptr<OCResourceResponse>, QualityOfService)
105          */
106         OCStackResult notifyListOfObservers(
107                     OCResourceHandle resourceHandle,
108                     ObservationIds& observationIds,
109                     const std::shared_ptr<OCResourceResponse> responsePtr);
110         /**
111          * @overload
112          *
113          * @param resourceHandle resource handle of the resource
114          * @param observationIds std vector of observationIds. These set of ids are ones which
115          * which will be notified upon resource change.
116          * @param responsePtr OCResourceResponse pointer used by app to fill the response for this
117          * resource change.
118          * @param QoS the quality of communication
119          * @see notifyListOfObservers(OCResourceHandle, ObservationIds&, const std::shared_ptr<OCResourceResponse>)
120          */
121         OCStackResult notifyListOfObservers(
122                     OCResourceHandle resourceHandle,
123                     ObservationIds& observationIds,
124                     const std::shared_ptr<OCResourceResponse> responsePtr,
125                     QualityOfService QoS);
126
127         /**
128         * Gets a resource handle by resource URI.
129         *
130         * @param uri   URI of Resource to get Resource handle.
131         *
132         * @return Found resource handle or NULL if not found.
133         */
134         OCResourceHandle getResourceHandleAtUri(const std::string& uri);
135
136         /**
137          * API for Service and Resource Discovery.
138          * @note This API applies to client side only.
139          *
140          * @param host Host IP Address of a service to direct resource discovery query. If null or
141          *        empty, performs multicast resource discovery query
142          * @param resourceURI name of the resource. If null or empty, performs search for all
143          *       resource names
144          * @param connectivityType ::OCConnectivityType type of connectivity indicating the
145          *                           interface. Example: CT_DEFAULT, CT_ADAPTER_IP, CT_ADAPTER_TCP.
146          * @param resourceHandler Handles callbacks, success states and failure states.
147          *
148          *        Four modes of discovery defined as follows:
149          *        (NULL/Empty, NULL/Empty) - Performs ALL service discovery AND ALL resource
150          *           discovery.
151          *        (NULL/Empty, Not Empty) - Performs query for a filtered/scoped/particular
152          *                                   resource(s) from ALL services.
153          *        (Not Empty, NULL/Empty) - Performs ALL resource discovery on a particular service.
154          *        (Not Empty, Not Empty) - Performs query for a filtered/scoped/particular
155          *                                   resource(s)
156          *                                  from a particular service.
157          *
158          * @return Returns ::OC_STACK_OK if success.
159          * @note First parameter 'host' currently represents an IP address. This will change in
160          * future and will refer to endpoint interface so that we can refer to other transports such
161          * as BTH etc.
162          * @note OCStackResult is defined in ocstack.h.
163          * @see findResource(const std::string&, const std::string&, OCConnectivityType, FindCallback, QualityOfService)
164          * @note To get the tcpPort information, user must call getAllHosts() from the OCResource
165            object in FindCallback. To use a TCP endpoint that has been received by getAllHosts(),
166            user must use the setHost() function.
167          */
168         OCStackResult findResource(const std::string& host, const std::string& resourceURI,
169                     OCConnectivityType connectivityType, FindCallback resourceHandler);
170         /**
171          * @overload
172          *
173          * @param host Host IP Address of a service to direct resource discovery query. If null or
174          *        empty, performs multicast resource discovery query
175          * @param resourceURI name of the resource. If null or empty, performs search for all
176          *       resource names
177          * @param connectivityType ::OCConnectivityType type of connectivity indicating the
178          *                           interface. Example: CT_DEFAULT, CT_ADAPTER_IP, CT_ADAPTER_TCP.
179          * @param resourceHandler Handles callbacks, success states and failure states.
180          *
181          *        Four modes of discovery defined as follows:
182          *        (NULL/Empty, NULL/Empty) - Performs ALL service discovery AND ALL resource
183          *           discovery.
184          *        (NULL/Empty, Not Empty) - Performs query for a filtered/scoped/particular
185          *                                   resource(s) from ALL services.
186          *        (Not Empty, NULL/Empty) - Performs ALL resource discovery on a particular service.
187          *        (Not Empty, Not Empty) - Performs query for a filtered/scoped/particular
188          *                                   resource(s)
189          *                                  from a particular service.
190          * @param QoS QualityOfService the quality of communication
191          * @see findResource(const std::string&, const std::string&, OCConnectivityType, FindCallback)
192          * @note To get the tcpPort information, user must call getAllHosts() from the OCResource
193            object in FindCallback. To use a TCP endpoint that has been received by getAllHosts(),
194            user must use the setHost() function.
195          */
196         OCStackResult findResource(const std::string& host, const std::string& resourceURI,
197                     OCConnectivityType connectivityType, FindCallback resourceHandler,
198                     QualityOfService QoS);
199
200         OCStackResult findResource(const std::string& host, const std::string& resourceURI,
201                     OCConnectivityType connectivityType, FindCallback resourceHandler,
202                     FindErrorCallback errorHandler);
203
204         OCStackResult findResource(const std::string& host, const std::string& resourceURI,
205                     OCConnectivityType connectivityType, FindCallback resourceHandler,
206                     FindErrorCallback errorHandler, QualityOfService QoS);
207
208         OCStackResult findResourceList(const std::string& host, const std::string& resourceURI,
209                     OCConnectivityType connectivityType, FindResListCallback resourceHandler,
210                     QualityOfService QoS = QualityOfService::LowQos);
211
212         OCStackResult findResourceList(const std::string& host, const std::string& resourceURI,
213                     OCConnectivityType connectivityType, FindResListCallback resourceHandler,
214                     FindErrorCallback errorHandler, QualityOfService QoS = QualityOfService::LowQos);
215
216         OCStackResult setPropertyValue(OCPayloadType type, const std::string& tag,
217                     const std::string& value);
218         OCStackResult setPropertyValue(OCPayloadType type, const std::string& tag,
219                     const std::vector<std::string>& value);
220         OCStackResult getPropertyValue(OCPayloadType type, const std::string& tag,
221                     std::string& value);
222         OCStackResult getPropertyValue(OCPayloadType type, const std::string& tag,
223                     std::vector<std::string>& value);
224         /**
225          * API for Device Discovery
226          *
227          *
228          * @param host Host IP Address. If null or empty, Multicast is performed.
229          * @param deviceURI URI containing address to the virtual device in C Stack
230                                 ("/oic/d")
231          * @param connectivityType ::OCConnectivityType type of connectivity indicating the
232          *                           interface. Example: CT_DEFAULT, CT_ADAPTER_IP, CT_ADAPTER_TCP.
233          * @param deviceInfoHandler device discovery callback
234          *
235          * @return Returns ::OC_STACK_OK if success.
236          * @note OCStackResult is defined in ocstack.h.
237          * @see getDeviceInfo(const std::string&, const std::string&, OCConnectivityType, FindDeviceCallback, QualityOfService)
238          */
239         OCStackResult getDeviceInfo(const std::string& host, const std::string& deviceURI,
240                     OCConnectivityType connectivityType, FindDeviceCallback deviceInfoHandler);
241         /**
242          * @overload
243          *
244          * @param host Host IP Address. If null or empty, Multicast is performed.
245          * @param deviceURI URI containing address to the virtual device in C Stack
246                                 ("/oic/d")
247          * @param connectivityType ::OCConnectivityType type of connectivity indicating the
248          *                           interface. Example: CT_DEFAULT, CT_ADAPTER_IP, CT_ADAPTER_TCP.
249          * @param deviceInfoHandler device discovery callback
250          * @param QoS the quality of communication
251          * @see getDeviceInfo(const std::string&, const std::string&, OCConnectivityType, FindDeviceCallback)
252          */
253         OCStackResult getDeviceInfo(const std::string& host, const std::string& deviceURI,
254                     OCConnectivityType connectivityType, FindDeviceCallback deviceInfoHandler,
255                     QualityOfService QoS);
256
257         /**
258          * API for Platform Discovery
259          *
260          *
261          * @param host Host IP Address. If null or empty, Multicast is performed.
262          * @param platformURI URI containing address to the virtual platform in C Stack
263                                 ("/oic/p")
264          * @param connectivityType ::OCConnectivityType type of connectivity indicating the
265          *                           interface. Example: CT_DEFAULT, CT_ADAPTER_IP, CT_ADAPTER_TCP.
266          * @param platformInfoHandler platform discovery callback
267          *
268          * @return Returns ::OC_STACK_OK if success.
269          *
270          * @note OCStackResult is defined in ocstack.h.
271          * @see getPlatformInfo(const std::string&, const std::string&, OCConnectivityType, FindPlatformCallback, QualityOfService)
272          */
273         OCStackResult getPlatformInfo(const std::string& host, const std::string& platformURI,
274                     OCConnectivityType connectivityType, FindPlatformCallback platformInfoHandler);
275         /**
276          * @overload
277          *
278          * @param host Host IP Address. If null or empty, Multicast is performed.
279          * @param platformURI URI containing address to the virtual platform in C Stack
280                                 ("/oic/p")
281          * @param connectivityType ::OCConnectivityType type of connectivity indicating the
282          *                           interface. Example: CT_DEFAULT, CT_ADAPTER_IP, CT_ADAPTER_TCP.
283          * @param platformInfoHandler platform discovery callback
284          * @param QoS the quality of communication
285          * @see getPlatformInfo(const std::string&, const std::string&, OCConnectivityType, FindPlatformCallback)
286          */
287         OCStackResult getPlatformInfo(const std::string& host, const std::string& platformURI,
288                     OCConnectivityType connectivityType, FindPlatformCallback platformInfoHandler,
289                     QualityOfService QoS);
290
291         /**
292          * This function returns flags of supported endpoint TPS on stack.
293          *
294          * @param[out] supportedTps Bit combinations of supported OCTpsSchemeFlags.
295          *
296          * @return Returns ::OC_STACK_OK if success.
297          */
298         OCStackResult getSupportedTransportsInfo(OCTpsSchemeFlags& supportedTps);
299
300         /**
301         * This API registers a resource with the server
302         * @note This API applies to server side only.
303         *
304         * @param resourceHandle Upon successful registration, resourceHandle will be filled
305         * @param resourceURI The URI of the resource. Example: "a/light". See NOTE below
306         * @param resourceTypeName The resource type. Example: "core.light"
307         * @param resourceInterface The resource interface (whether it is collection etc).
308         * @param entityHandler entity handler callback.
309         * @param resourceProperty indicates the property of the resource. Defined in octypes.h.
310         * setting resourceProperty as OC_DISCOVERABLE will allow Discovery of this resource
311         * setting resourceProperty as OC_OBSERVABLE will allow observation
312         * setting resourceProperty as OC_DISCOVERABLE | OC_OBSERVABLE will allow both discovery
313         * and observation
314         *
315         * @return Returns ::OC_STACK_OK if success.
316         * @note "a/light" is a relative reference to URI.
317         * Above relative reference to URI will be prepended (by core) with a host IP
318         * Therefore, fully qualified URI format would be
319         * "CoAP(s)+protocol-URI-Scheme://HostIP-Address/relativeURI"
320         * Example, a relative reference to URI: 'a/light' will result in a fully qualified URI:
321         *   "coap://192.168.1.1:5246/a/light", "coaps://192.168.1.1:5246/a/light"
322         * @note OCStackResult is defined in octypes.h.
323         * @note entity handler callback :
324         * When you set specific return value like OC_EH_CHANGED, OC_EH_CONTENT,
325         * OC_EH_SLOW and etc in entity handler callback,
326         * ocstack will be not send response automatically to client
327         * except for error return value like OC_EH_ERROR
328         * If you want to send response to client with specific result,
329         * OCDoResponse API should be called with the result value.
330         */
331         OCStackResult registerResource(OCResourceHandle& resourceHandle,
332                         std::string& resourceURI,
333                         const std::string& resourceTypeName,
334                         const std::string& resourceInterface,
335                         EntityHandler entityHandler,
336                         uint8_t resourceProperty);
337
338         /**
339         * This API registers a resource with the server
340         * @note This API applies to server side only.
341         *
342         * @param resourceHandle Upon successful registration, resourceHandle will be filled
343         * @param resourceURI The URI of the resource. Example: "a/light". See NOTE below
344         * @param resourceTypeName The resource type. Example: "core.light"
345         * @param resourceInterface The resource interface (whether it is collection etc).
346         * @param entityHandler Entity handler callback.
347         * @param resourceProperty indicates the property of the resource. Defined in octypes.h.
348         * @param resourceTpsTypes Transport Protocol Suites(TPS) types of resource for
349                                   open resource to specific transport adapter (e.g., TCP, UDP)
350                                   with messaging protocol(e.g., COAP, COAPS).
351                                   Example: "OC_COAP | OC_COAP_TCP"
352         * setting resourceProperty as OC_DISCOVERABLE will allow Discovery of this resource
353         * setting resourceProperty as OC_OBSERVABLE will allow observation
354         * setting resourceProperty as OC_DISCOVERABLE | OC_OBSERVABLE will allow both discovery
355         * and observation
356         *
357         * @return Returns ::OC_STACK_OK if success.
358         * @note "a/light" is a relative reference to URI.
359         * Above relative reference to URI will be prepended (by core) with a host IP
360         * Therefore, fully qualified URI format would be
361         * "CoAP(s)+protocol-URI-Scheme://HostIP-Address/relativeURI"
362         * Example, a relative reference to URI: 'a/light' will result in a fully qualified URI:
363         *   "coap://192.168.1.1:5246/a/light", "coaps://192.168.1.1:5246/a/light"
364         * @note OCStackResult is defined in octypes.h.
365         * @note entity handler callback :
366         * When you set specific return value like OC_EH_CHANGED, OC_EH_CONTENT,
367         * OC_EH_SLOW and etc in entity handler callback,
368         * ocstack will be not send response automatically to client
369         * except for error return value like OC_EH_ERROR
370         * If you want to send response to client with specific result,
371         * OCDoResponse API should be called with the result value.
372         */
373         OCStackResult registerResource(OCResourceHandle& resourceHandle,
374                         std::string& resourceURI,
375                         const std::string& resourceTypeName,
376                         const std::string& resourceInterface,
377                         EntityHandler entityHandler,
378                         uint8_t resourceProperty,
379                         OCTpsSchemeFlags resourceTpsTypes);
380
381         /**
382          * This API registers a resource with the server
383          * @note This API applies to server & client side.
384          *
385          * @param resourceHandle Upon successful registration, resourceHandle will be filled
386          * @param resource The instance of OCResource that all data filled.
387          *
388          * @return Returns ::OC_STACK_OK if success.
389          * @note OCStackResult is defined in ocstack.h.
390          */
391         OCStackResult registerResource(OCResourceHandle& resourceHandle,
392                         const std::shared_ptr< OCResource > resource);
393
394         /**
395         * Register Device Info
396         *
397         * @deprecated: Use setPropertyValue instead.
398         *
399         * @param deviceInfo structure containing all the device specific information
400         * @return Returns ::OC_STACK_OK  if no errors and ::OC_STACK_ERROR in case of stack process error
401         */
402         OCStackResult registerDeviceInfo(const OCDeviceInfo deviceInfo);
403
404         /**
405         * Register Platform Info
406         *
407         * @param platformInfo structure containing all the platform specific information
408         * @return Returns ::OC_STACK_OK if no errors and ::OC_STACK_ERROR in case of stack process error
409         */
410         OCStackResult registerPlatformInfo(const OCPlatformInfo platformInfo);
411
412         /**
413         * Set default device entity handler
414         *
415         * @param entityHandler entity handler to handle requests for
416         *                      any undefined resources or default actions.
417         *                      if NULL is passed it removes the device default entity handler.
418         * @return Returns ::OC_STACK_OK  if no errors and ::OC_STACK_ERROR in case of stack process error
419         * @note entity handler callback :
420         * When you set specific return value like OC_EH_CHANGED, OC_EH_CONTENT,
421         * OC_EH_SLOW and etc in entity handler callback,
422         * ocstack will be not send response automatically to client
423         * except for error return value like OC_EH_ERROR
424         * If you want to send response to client with specific result,
425         * sendResponse API should be called with the result value.
426         */
427         OCStackResult setDefaultDeviceEntityHandler(EntityHandler entityHandler);
428
429         /**
430         * This API unregisters a resource with the server
431         * @note This API applies to server side only.
432         *
433         * @param resourceHandle This is the resource handle which we need to unregister from the
434         * server
435         *
436         * @return Returns ::OC_STACK_OK if success.
437         * @note OCStackResult is defined in ocstack.h.
438         */
439         OCStackResult unregisterResource(const OCResourceHandle& resourceHandle);
440
441         /**
442         * Add a resource to a collection resource.
443         *
444         * @param collectionHandle handle to the collection resource
445         * @param resourceHandle handle to resource to be added to the collection resource
446         *
447         * @return Returns ::OC_STACK_OK if success.
448         * @note OCStackResult is defined in ocstack.h.
449         * @note bindResource must be used only after the both collection resource and
450         * resource to add under a collections are created and respective handles obtained
451         *
452         * @par Example:
453         * -# registerResource(homeResourceHandle, "a/home", "home", Link_Interface,
454         *   entityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);
455         * -# registerResource(kitchenResourceHandle, "a/kitchen", "kitchen", Link_Interface,
456         *   entityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);
457         * -# bindResource(homeResourceHandle, kitchenResourceHandle);
458         * @par
459         * At the end of Step 3, resource "a/home" will contain a reference to "a/kitchen".
460         */
461         OCStackResult bindResource(const OCResourceHandle collectionHandle,
462                 const OCResourceHandle resourceHandle);
463
464         /**
465         * Add multiple resources to a collection resource.
466         *
467         * @param collectionHandle handle to the collection resource
468         * @param addedResourceHandleList reference to list of resource handles to be added to the
469         *   collection resource
470         *
471         * @return Returns ::OC_STACK_OK if success.
472         * @note OCStackResult is defined in ocstack.h.
473         * @note bindResources must be used only after the both collection resource and
474         * list of resources to add under a collection are created and respective handles
475         * obtained.
476         *
477         * @par Example:
478         * -# registerResource(homeResourceHandle, "a/home", "home", Link_Interface,
479         *   homeEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);
480         * -# registerResource(kitchenResourceHandle, "a/kitchen", "kitchen", Link_Interface,
481         *   kitchenEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);
482         * -# registerResource(roomResourceHandle, "a/room", "room", Link_Interface,
483         *   roomEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);
484         * -# std::vector<OCResourceHandle> rList; rList.push_back(kitchenResourceHandle);
485         *   rList.push_back(roomResourceHandle);
486         * -# bindResource(homeResourceHandle, rList);
487         * @par
488         * At the end of Step 5, resource "a/home" will contain a references to "a/kitchen" and
489         *   "a/room"
490         */
491         OCStackResult bindResources(const OCResourceHandle collectionHandle,
492                 const std::vector<OCResourceHandle>& addedResourceHandleList);
493
494         /**
495         * Unbind a resource from a collection resource.
496         *
497         * @param collectionHandle handle to the collection resource
498         * @param resourceHandle resource handle to be unbound from the collection resource
499         *
500         * @return Returns ::OC_STACK_OK if success.
501         * @note OCStackResult is defined in ocstack.h.
502         * @note unbindResource must be used only after the both collection resource and
503         * resource to unbind from a collection are created and respective handles obtained
504         *
505         * @par Example:
506         * -# registerResource(homeResourceHandle, "a/home", "home", Link_Interface,
507         *   entityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);
508         * -# registerResource(kitchenResourceHandle, "a/kitchen", "kitchen", Link_Interface,
509         *   entityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);
510         * -# bindResource(homeResourceHandle, kitchenResourceHandle);
511         * -# unbindResource(homeResourceHandle, kitchenResourceHandle);
512         * @par
513         * At the end of Step 4, resource "a/home" will no longer reference "a/kitchen".
514         */
515         OCStackResult unbindResource(const OCResourceHandle collectionHandle,
516                     const OCResourceHandle resourceHandle);
517
518         /**
519         * Unbind resources from a collection resource.
520         *
521         * @param collectionHandle handle to the collection resource
522         * @param resourceHandleList List of resource handles to be unbound from the collection
523         *   resource
524         *
525         * @return Returns ::OC_STACK_OK if success.
526         * @note OCStackResult is defined in ocstack.h.
527         * @note unbindResources must be used only after the both collection resource and
528         * list of resources resource to unbind from a collection are created and respective handles
529         *   obtained.
530         *
531         * @par Example:
532         * -# registerResource(homeResourceHandle, "a/home", "home", Link_Interface,
533         *   homeEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);
534         * -# registerResource(kitchenResourceHandle, "a/kitchen", "kitchen", Link_Interface,
535         *   kitchenEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);
536         * -# registerResource(roomResourceHandle, "a/room", "room", Link_Interface,
537         *   roomEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);
538         * -# std::vector<OCResourceHandle> rList; rList.push_back(kitchenResourceHandle);
539         *   rList.push_back(roomResourceHandle);
540         * -# bindResource(homeResourceHandle, rList);
541         * -# unbindResources(homeResourceHandle, rList);
542         * @par
543         * At the end of Step 6, resource "a/home" will no longer reference to "a/kitchen" and
544         *   "a/room"
545         */
546         OCStackResult unbindResources(const OCResourceHandle collectionHandle,
547                         const std::vector<OCResourceHandle>& resourceHandleList);
548
549         /**
550         * Binds a type to a particular resource
551         * @param resourceHandle handle to the resource
552         * @param resourceTypeName new typename to bind to the resource
553         *
554         * @return Returns ::OC_STACK_OK if success.
555         */
556         OCStackResult bindTypeToResource(const OCResourceHandle& resourceHandle,
557                         const std::string& resourceTypeName);
558
559         /**
560         * Binds an interface to a particular resource
561         * @param resourceHandle handle to the resource
562         * @param resourceInterfaceName new interface  to bind to the resource
563         *
564         * @return Returns ::OC_STACK_OK if success.
565         */
566         OCStackResult bindInterfaceToResource(const OCResourceHandle& resourceHandle,
567                         const std::string& resourceInterfaceName);
568
569
570         /**
571         * Start Presence announcements.
572         *
573         * @param ttl time to live
574         * @par
575         * If ttl is '0', then the default stack value will be used (60 Seconds).
576         * If ttl is greater than OC_MAX_PRESENCE_TTL_SECONDS, then the ttl will be set to
577         * OC_MAX_PRESENCE_TTL_SECONDS.
578         * @par
579         * @return Returns ::OC_STACK_OK if success.
580         *
581         * Server can call this function when it comes online for the
582         * first time, or when it comes back online from offline mode,
583         * or when it re enters network.
584         *
585         */
586         OCStackResult startPresence(const unsigned int ttl);
587
588         /**
589         * Stop Presence announcements.
590         *
591         * @return Returns ::OC_STACK_OK if success.
592         *
593         * Server can call this function when it is terminating,
594         * going offline, or when going away from network.
595         *
596         */
597         OCStackResult stopPresence();
598
599         /**
600          * subscribes to a server's presence change events.  By making this subscription,
601          * every time a server adds/removes/alters a resource, starts or is intentionally
602          * stopped (potentially more to be added later).
603          *
604          * @param presenceHandle a handle object that can be used to identify this subscription
605          *               request.  It can be used to unsubscribe from these events in the future.
606          *               It will be set upon successful return of this method.
607          * @param host The IP address/addressable name of the server to subscribe to.
608          *               This should be in the format coap://address:port
609          *               If empty, the multicast subscribe presence is performed.
610          * @param connectivityType ::OCConnectivityType type of connectivity indicating the
611          *                           interface. Example: CT_DEFAULT, CT_ADAPTER_IP, CT_ADAPTER_TCP.
612          * @param presenceHandler callback function that will receive notifications/subscription
613          *               events
614          *
615          * @return Returns ::OC_STACK_OK if success.
616          */
617         OCStackResult subscribePresence(OCPresenceHandle& presenceHandle, const std::string& host,
618                         OCConnectivityType connectivityType, SubscribeCallback presenceHandler);
619         /**
620          * @overload
621          *
622          * subscribes to a server's presence change events.  By making this subscription,
623          * every time a server adds/removes/alters a resource, starts or is intentionally
624          * stopped (potentially more to be added later).
625          *
626          * @param presenceHandle a handle object that can be used to identify this subscription
627          *               request.  It can be used to unsubscribe from these events in the future.
628          *               It will be set upon successful return of this method.
629          * @param host The IP address/addressable name of the server to subscribe to.
630          *               This should be in the format coap://address:port
631          *               If empty, the multicast subscribe presence is performed.
632          * @param resourceType a resource type specified as a filter for subscription callbacks.
633          * @param connectivityType ::OCConnectivityType type of connectivity indicating the
634          *                           interface. Example: CT_DEFAULT, CT_ADAPTER_IP, CT_ADAPTER_TCP.
635          * @param presenceHandler callback function that will receive notifications/subscription
636          *               events
637          *
638          * @see subscribePresence(OCPresenceHandle&, const std::string&, OCConnectivityType, SubscribeCallback)
639          */
640         OCStackResult subscribePresence(OCPresenceHandle& presenceHandle, const std::string& host,
641                         const std::string& resourceType, OCConnectivityType connectivityType,
642                         SubscribeCallback presenceHandler);
643
644         /**
645          * unsubscribes from a previously subscribed server's presence events. Note that
646          * you may for a short time still receive events from the server since it may take time
647          * for the unsubscribe to take effect.
648          *
649          * @param presenceHandle the handle object provided by the subscribePresence call that
650          *               identifies this subscription.
651          *
652          * @return Returns ::OC_STACK_OK if success.
653          */
654         OCStackResult unsubscribePresence(OCPresenceHandle presenceHandle);
655
656 #ifdef WITH_CLOUD
657         /**
658          * Subscribes to a server's device presence change events.
659          *
660          * @param presenceHandle a handle object that can be used to identify this subscription
661          *               request.  It can be used to unsubscribe from these events in the future.
662          *               It will be set upon successful return of this method.
663          * @param host The IP address/addressable name of the server to subscribe to.
664          *               This should be in the format coap://address:port
665          * @param di Vector which can have the devices id.
666          * @param connectivityType ::OCConnectivityType type of connectivity indicating the
667          *                           interface. Example: CT_DEFAULT, CT_ADAPTER_IP, CT_ADAPTER_TCP.
668          * @param observeHandler handles callback
669          *        The callback function will be invoked with a map of attribute name and values.
670          *        The callback function will also have the result from this observe operation
671          *        This will have error codes
672          *
673          * @return Returns ::OC_STACK_OK if success.
674          */
675         OCStackResult subscribeDevicePresence(OCPresenceHandle& presenceHandle,
676                                               const std::string& host,
677                                               const std::vector<std::string>& di,
678                                               OCConnectivityType connectivityType,
679                                               ObserveCallback callback);
680 #endif
681
682         /**
683          * Creates a resource proxy object so that get/put/observe functionality
684          * can be used without discovering the object in advance.  Note that the
685          * consumer of this method needs to provide all of the details required to
686          * correctly contact and observe the object. If the consumer lacks any of
687          * this information, they should discover the resource object normally.
688          * Additionally, you can only create this object if OCPlatform was initialized
689          * to be a Client or Client/Server.  Otherwise, this will return an empty
690          * shared ptr.
691          *
692          * @param host a string containing a resolvable "coap(s)", "coap(s)+protocol" URI scheme
693          *        of the server holding the resource.
694          *        Currently this should be in the format coap(s)://address:port or
695          *        coap(s)+protocol://address:port, though in the future, we expect this to
696          *        change to //address:port
697          *
698          * @param uri the rest of the resource's URI that will permit messages to be
699          *           properly routed.  Example: /a/light
700          *
701          * @param connectivityType ::OCConnectivityType type of connectivity indicating the
702          *                           transport method and IP address scope.
703          *                           Example: CT_DEFAULT, CT_ADAPTER_IP, CT_ADAPTER_TCP.
704          *                           if you want to use a specific Flag like IPv4,
705          *                           you should apply OR operation for the flag in here.
706          *                           Example: static_cast<OCConnectivityType>(CT_ADAPTER_TCP
707          *                                                                    | OC_IP_USE_V4)
708          *
709          * @param isObservable a boolean containing whether the resource supports observation
710          *
711          * @param resourceTypes a collection of resource types implemented by the resource
712          *
713          * @param interfaces a collection of interfaces that the resource supports/implements
714          * @return OCResource::Ptr a shared pointer to the new resource object
715          */
716         OCResource::Ptr constructResourceObject(const std::string& host,
717                         const std::string& uri,
718                         OCConnectivityType connectivityType, bool isObservable,
719                         const std::vector<std::string>& resourceTypes,
720                         const std::vector<std::string>& interfaces);
721
722         /**
723          * Allows application entity handler to send response to an incoming request.
724          *
725          * @param pResponse OCResourceResponse pointer that will permit to set values related
726          * to resource response.
727          *
728          * @return Returns ::OC_STACK_OK if success.
729          */
730         OCStackResult sendResponse(const std::shared_ptr<OCResourceResponse> pResponse);
731
732 #ifdef WITH_CLOUD
733         /**
734          * Create an account manager object that can be used for doing request to account server.
735          * You can only create this object if OCPlatform was initialized to be a Client or
736          * Client/Server. Otherwise, this will return an empty shared ptr.
737          *
738          * @note For now, OCPlatform SHOULD be initialized to be a Client/Server(Both) for the
739          *       methods of this object to work since device id is not generated on Client mode.
740          *
741          * @param host Host IP Address of a account server.
742          * @param connectivityType ::OCConnectivityType type of connectivity indicating the
743          *                           interface. Example: CT_DEFAULT, CT_ADAPTER_IP, CT_ADAPTER_TCP.
744          *                           if you want to use a specific Flag like IPv4,
745          *                           you should apply OR operation for the flag in here.
746          *                           Example: static_cast<OCConnectivityType>(CT_ADAPTER_TCP
747          *                                                                    | OC_IP_USE_V4)
748          *
749          * @return OCAccountManager::Ptr a shared pointer to the new account manager object
750          */
751         OCAccountManager::Ptr constructAccountManagerObject(const std::string& host,
752                                                             OCConnectivityType connectivityType);
753 #endif // WITH_CLOUD
754
755         /**
756          * gets the deviceId of the client
757          *
758          * @param deviceId pointer.
759          * @return Returns ::OC_STACK_OK if success.
760          */
761         OCStackResult getDeviceId(OCUUIdentity *deviceId);
762
763         /**
764          * sets the deviceId of the client
765          *
766          * @param deviceId pointer.
767          * @return Returns ::OC_STACK_OK if success.
768          */
769         OCStackResult setDeviceId(const OCUUIdentity *deviceId);
770     }
771 }
772
773 #endif // OC_PLATFORM_H_