46bc9d9aacb089445a870becc2d43d6ae4fada20
[platform/upstream/iotivity.git] / resource / include / OCPlatform_impl.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 /// @file OCPlatform_impl.h
22
23 /// @brief Implementation of the OCPlatform functionality.  It contains
24 /// a singleton interface that is used only by the OCPlatform namespace and is the
25 /// central entrance to the stack.
26
27 #ifndef __OCPLATFORM_IMPL_H
28 #define __OCPLATFORM_IMPL_H
29
30 #include <map>
31
32 #include "OCApi.h"
33 #include "OCResource.h"
34 #include "WrapperFactory.h"
35 #include "OCResourceRequest.h"
36 #include "OCResourceResponse.h"
37 #include "OCRepresentation.h"
38
39 #include "oc_logger.hpp"
40
41 namespace OC
42 {
43     /**
44     *   @brief Both server and client must initialize the core platform by instantiating OCPlatform.
45     *          On successful initialization, an instance of the OCPlatform is returned.
46     *          APIs in OCPlatform provide mechanism to register a resource and host the resource
47     *          on the server, find resources on the network etc.
48     */
49     class OCPlatform_impl
50     {
51     private:
52         static PlatformConfig& globalConfig();
53     public:
54         /**
55          * API for overwriting the default configuration of the OCPlatform object.
56          * Note: Any calls made to this AFTER the first call to OCPlatform::Instance
57          * will have no affect
58          */
59         static void Configure(const PlatformConfig& config);
60
61         /**
62          * API for retrieving the current OCPlatform object.  This will use the
63          * default platform config, unless the default is over-written using the
64          * Configure method before the first call to instance.
65          */
66         static OCPlatform_impl& Instance();
67
68     public:
69         // typedef for handle to cancel presence info with
70         typedef OCDoHandle OCPresenceHandle;
71
72         /**
73         * Virtual destructor
74         */
75         virtual ~OCPlatform_impl(void);
76
77         /**
78         * API for notifying base that resource's attributes have changed.
79         *
80         * @param OCResourceHandle resource handle of the resource
81         * @param QualityOfService the quality of communication
82         *
83         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
84         * NOTE: This API is for server side only.
85         * NOTE: OCResourceHandle is defined in ocstack.h.
86         * NOTE: OCStackResult is defined in ocstack.h.
87         */
88         OCStackResult notifyAllObservers(OCResourceHandle resourceHandle);
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 OCResourceHandle 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         * @param QualityOfService the quality of communication
100         *
101         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
102         *
103         * NOTE: This API is for server side only.
104         * NOTE: OCResourceHandle is defined in ocstack.h.
105         * NOTE: OCStackResult is defined in ocstack.h.
106         */
107         OCStackResult notifyListOfObservers(
108                     OCResourceHandle resourceHandle,
109                     ObservationIds& observationIds,
110                     const std::shared_ptr<OCResourceResponse> responsePtr);
111         OCStackResult notifyListOfObservers(
112                     OCResourceHandle resourceHandle,
113                     ObservationIds& observationIds,
114                     const std::shared_ptr<OCResourceResponse> responsePtr,
115                     QualityOfService QoS);
116
117         /**
118         * API for Service and Resource Discovery.
119         * NOTE: This API applies to client side only.
120         *
121         * @param host - Host IP Address of a service to direct resource discovery query. If null or
122         *        empty, performs multicast resource discovery query
123         * @param resourceURI - name of the resource. If null or empty, performs search for all
124         *        resource names
125         * @param handler - Handles callbacks, success states and failure states.
126         *
127         *        Four modes of discovery defined as follows:
128         *        (NULL/Empty, NULL/Empty) - Performs ALL service discovery AND ALL resource
129         *                                   discovery.
130         *        (NULL/Empty, Not Empty) - Performs query for a filtered/scoped/particular
131         *                                   resource(s) from ALL services.
132         *        (Not Empty, NULL/Empty) - Performs ALL resource discovery on a particular service.
133         *        (Not Empty, Not Empty) - Performs query for a filtered/scoped/particular
134         *                                   resource(s) from a particular service.
135         * @param QualityOfService the quality of communication
136         *
137         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
138         * NOTE: First parameter 'host' currently represents an IP address. This will change in
139         * future and will refer to endpoint interface so that we can refer to other transports such
140         * as BTH etc.
141         * NOTE: OCStackResult is defined in ocstack.h.
142         */
143 #ifdef CA_INT
144         OCStackResult findResource(const std::string& host, const std::string& resourceURI,
145                     uint8_t connectivityType, FindCallback resourceHandler);
146         OCStackResult findResource(const std::string& host, const std::string& resourceURI,
147                     uint8_t connectivityType, FindCallback resourceHandler, QualityOfService QoS);
148 #else
149         OCStackResult findResource(const std::string& host, const std::string& resourceURI,
150                     FindCallback resourceHandler);
151         OCStackResult findResource(const std::string& host, const std::string& resourceURI,
152                     FindCallback resourceHandler, QualityOfService QoS);
153 #endif
154         /**
155          * API for Device Discovery
156          *
157          * @param host - Host IP Address. If null or empty, Multicast is performed.
158          * @param resourceURI - Uri containing address to the virtual device in C Stack
159          *                       ("/oc/core/d")
160          *
161          * @param QualityOfService the quality of communication
162          *
163          */
164 #ifdef CA_INT
165         OCStackResult getDeviceInfo(const std::string& host, const std::string& deviceURI,
166                     uint8_t connectivityType, FindDeviceCallback deviceInfoHandler);
167         OCStackResult getDeviceInfo(const std::string& host, const std::string& deviceURI,
168                     uint8_t connectivityType, FindDeviceCallback deviceInfoHandler,
169                     QualityOfService QoS);
170 #else
171         OCStackResult getDeviceInfo(const std::string& host, const std::string& deviceURI,
172                     FindDeviceCallback deviceInfoHandler);
173         OCStackResult getDeviceInfo(const std::string& host, const std::string& deviceURI,
174                     FindDeviceCallback deviceInfoHandler, QualityOfService QoS);
175 #endif
176
177         /**
178         * This API registers a resource with the server
179         * NOTE: This API applies to server side only.
180         *
181         * @param resourceHandle - Upon successful registration, resourceHandle will be filled
182         * @param resourceURI - The URI of the resource. Example: "a/light". See NOTE below
183         * @param resourceTypeName - The resource type. Example: "light"
184         * @param resourceInterface - The resource interface (whether it is collection etc).
185         * @param entityHandler - entity handler callback.
186         * @param resourceProperty - indicates the property of the resource. Defined in ocstack.h.
187         * setting resourceProperty as OC_DISCOVERABLE will allow Discovery of this resource
188         * setting resourceProperty as OC_OBSERVABLE will allow observation
189         * settings resourceProperty as OC_DISCOVERABLE | OC_OBSERVABLE will allow both discovery
190         * and observation
191         *
192         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
193         * NOTE: "a/light" is a relative URI.
194         * Above relative URI will be prepended (by core) with a host IP + namespace "oc"
195         * Therefore, fully qualified URI format would be //HostIP-Address/namespace/relativeURI"
196         * Example, a relative URI: 'a/light' will result in a fully qualified URI:
197         *   //192.168.1.1/oc/a/light"
198         * First parameter can take a relative URI and core will take care of preparing the fully
199         * qualified URI OR
200         * first paramter can take fully qualified URI and core will take that as is for further
201         * operations
202         * NOTE: OCStackResult is defined in ocstack.h.
203         */
204         OCStackResult registerResource(OCResourceHandle& resourceHandle,
205                         std::string& resourceURI,
206                         const std::string& resourceTypeName,
207                         const std::string& resourceInterface,
208                         EntityHandler entityHandler,
209                         uint8_t resourceProperty);
210
211         /**
212          * This API registers a resource with the server
213          * NOTE: This API applies to server & client side.
214
215          * @param resourceHandle - Upon successful registration, resourceHandle will be filled
216          * @param OCResource - The instance of OCResource that all data filled.
217          *
218          * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
219          */
220
221         OCStackResult registerResource(OCResourceHandle& resourceHandle,
222                         const std::shared_ptr<OCResource> resource);
223
224         /**
225          * This API registers all the device specific information
226          *
227          * @param OCDeviceInfo - Structure containing all the device related information
228          *
229          * @return OCStackResult return value of the API. Returns OC_STACK_OK if success
230          *
231          * Note: OCDeviceInfo is defined in OCStack.h
232          */
233         OCStackResult registerDeviceInfo(const OCDeviceInfo deviceInfo);
234
235         /**
236         * Set default device entity handler
237         *
238         * @param entityHandler - entity handler to handle requests for
239         *                        any undefined resources or default actions.
240         *                        if NULL is passed it removes the device default entity handler.
241         *
242         * @return
243         *     OC_STACK_OK    - no errors
244         *     OC_STACK_ERROR - stack process error
245         */
246         OCStackResult setDefaultDeviceEntityHandler(EntityHandler entityHandler);
247
248         /**
249         * This API unregisters a resource with the server
250         * NOTE: This API applies to server side only.
251         *
252         * @param resourceHandle - This is the resource handle which we which to unregister from the
253         *                           server
254         *
255         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
256         * NOTE: OCStackResult is defined in ocstack.h.
257         */
258         OCStackResult unregisterResource(const OCResourceHandle& resourceHandle) const;
259
260         /**
261         * Add a resource to a collection resource.
262         *
263         * @param collectionHandle - handle to the collection resource
264         * @param addedResourceHandle - handle to resource to be added to the collection resource
265         *
266         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.<br>
267         * NOTE: OCStackResult is defined in ocstack.h. <br>
268         * NOTE: bindResource must be used only after the both collection resource and
269         * resource to add under a collections are created and respective handles obtained<br>
270         * <b>Example:</b> <br>
271         * Step 1: registerResource(homeResourceHandle, "a/home", "home", Link_Interface,
272         *               entityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
273         * Step 2: registerResource(kitchenResourceHandle, "a/kitchen", "kitchen", Link_Interface,
274         *               entityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
275         * Step 3: bindResource(homeResourceHandle, kitchenResourceHandle);<br>
276         * At the end of Step 3, resource "a/home" will contain a reference to "a/kitchen".<br>
277         */
278         OCStackResult bindResource(const OCResourceHandle collectionHandle,
279                     const OCResourceHandle resourceHandle);
280
281         /**
282         * Add multiple resources to a collection resource.
283         *
284         * @param collectionHandle - handle to the collection resource
285         * @param addedResourceHandleList reference to list of resource handles to be added to
286         *       the collection resource
287         *
288         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
289         * NOTE: OCStackResult is defined in ocstack.h. <br>
290         * NOTE: bindResources must be used only after the both collection resource and
291         * list of resources to add under a collection are created and respective handles
292         * obtained<br>
293         * <b> Example: </b> <br>
294         * Step 1: registerResource(homeResourceHandle, "a/home", "home", Link_Interface,
295         *           homeEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
296         * Step 2: registerResource(kitchenResourceHandle, "a/kitchen", "kitchen", Link_Interface,
297         *           kitchenEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
298         * Step 3: registerResource(roomResourceHandle, "a/room", "room", Link_Interface,
299         *           roomEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
300         * Step 4: std::vector<OCResourceHandle> rList; rList.push_back(kitchenResourceHandle);
301         *           rList.push_back(roomResourceHandle);<br>
302         * Step 5: bindResource(homeResourceHandle, rList);<br>
303         * At the end of Step 5, resource "a/home" will contain a references to "a/kitchen"
304         *           and "a/room" <br>
305         */
306         OCStackResult bindResources(const OCResourceHandle collectionHandle,
307                     const std::vector<OCResourceHandle>& addedResourceHandleList);
308
309         /**
310         * Unbind a resource from a collection resource.
311         *
312         * @param collectionHandle - handle to the collection resource
313         * @param resourceHandle resource handle to be unbound from the collection resource
314         *
315         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
316         * NOTE: OCStackResult is defined in ocstack.h.<br>
317         * NOTE: unbindResource must be used only after the both collection resource and
318         * resource to unbind from a collection are created and respective handles obtained<br>
319         * <b> Example </b> <br>
320         * Step 1: registerResource(homeResourceHandle, "a/home", "home", Link_Interface,
321         *       entityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
322         * Step 2: registerResource(kitchenResourceHandle, "a/kitchen", "kitchen", Link_Interface,
323         *       entityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
324         * Step 3: bindResource(homeResourceHandle, kitchenResourceHandle);<br>
325         * Step 4: unbindResource(homeResourceHandle, kitchenResourceHandle);<br>
326         * At the end of Step 4, resource "a/home" will no longer reference "a/kitchen". <br>
327         */
328         OCStackResult unbindResource(const OCResourceHandle collectionHandle,
329                     const OCResourceHandle resourceHandle);
330
331         /**
332         * Unbind resources from a collection resource.
333         *
334         * @param collectionHandle - handle to the collection resource
335         * @param resourceHandleList List of resource handles to be unbound from the collection
336         *   resource
337         *
338         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
339         *
340         * NOTE: OCStackResult is defined in ocstack.h.<br>
341         * NOTE: unbindResources must be used only after the both collection resource and
342         * list of resources resource to unbind from a collection are created and respective handles
343         * obtained. <br>
344         * <b>Example</b> <br>
345         * Step 1: registerResource(homeResourceHandle, "a/home", "home", Link_Interface,
346         *       homeEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
347         * Step 2: registerResource(kitchenResourceHandle, "a/kitchen", "kitchen", Link_Interface,
348         *       kitchenEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
349         * Step 3: registerResource(roomResourceHandle, "a/room", "room", Link_Interface,
350         *       roomEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
351         * Step 4: std::vector<OCResourceHandle> rList; rList.push_back(kitchenResourceHandle);
352         *       rList.push_back(roomResourceHandle);<br>
353         * Step 5: bindResource(homeResourceHandle, rList);<br>
354         * Step 6: unbindResources(homeResourceHandle, rList);<br>
355         * At the end of Step 6, resource "a/home" will no longer reference to "a/kitchen"
356         *       and "a/room"<br>
357         */
358         OCStackResult unbindResources(const OCResourceHandle collectionHandle,
359                         const std::vector<OCResourceHandle>& resourceHandleList);
360
361         /**
362         * Binds a type to a particular resource
363         * @param resourceHandle - handle to the resource
364         * @param resourceTypeName - new typename to bind to the resource
365
366         * @return OCStackResult - return value of the API. Returns OCSTACK_OK if success <br>
367         */
368         OCStackResult bindTypeToResource(const OCResourceHandle& resourceHandle,
369                         const std::string& resourceTypeName) const;
370
371         /**
372         * Binds an interface to a particular resource
373         * @param resourceHandle - handle to the resource
374         * @param resourceTypeName - new interface  to bind to the resource
375
376         * @return OCStackResult - return value of the API. Returns OCSTACK_OK if success <br>
377         */
378         OCStackResult bindInterfaceToResource(const OCResourceHandle& resourceHandle,
379                         const std::string& resourceInterfaceName) const;
380
381         /**
382         * Start Presence announcements.
383         *
384         * @param ttl - time to live
385         * @return OCStackResult - Returns OCSTACK_OK if success <br>
386         *
387         * Server can call this function when it comes online for the
388         * first time, or when it comes back online from offline mode,
389         * or when it re enters network.
390         *
391         */
392         OCStackResult startPresence(const unsigned int ttl);
393
394         /**
395         * Stop Presence announcements.
396         *
397         * @return OCStackResult - Returns OCSTACK_OK if success <br>
398         *
399         * Server can call this function when it is terminating,
400         * going offline, or when going away from network.
401         *
402         */
403         OCStackResult stopPresence();
404
405         /**
406         * subscribes to a server's presence change events.  By making this subscription,
407         * every time a server adds/removes/alters a resource, starts or is intentionally
408         * stopped (potentially more to be added later).
409         *
410         * @param presenceHandle - a handle object that can be used to identify this subscription
411         *               request.  It can be used to unsubscribe from these events in the future.
412         *               It will be set upon successful return of this method.
413         * @param host - The IP address/addressable name of the server to subscribe to.
414         * @param resourceType - a resource type specified as a filter for subscription callbacks.
415         * @param presenceHandler - callback function that will receive notifications/subscription
416         *                           events
417         *
418         * @return OCStackResult - return value of the API.  Returns OCSTACK_OK if success <br>
419         */
420 #ifdef CA_INT
421         OCStackResult subscribePresence(OCPresenceHandle& presenceHandle, const std::string& host,
422                         uint8_t connectivityType, SubscribeCallback presenceHandler);
423         OCStackResult subscribePresence(OCPresenceHandle& presenceHandle, const std::string& host,
424                         const std::string& resourceType, uint8_t connectivityType,
425                         SubscribeCallback presenceHandler);
426 #else
427         OCStackResult subscribePresence(OCPresenceHandle& presenceHandle, const std::string& host,
428                         SubscribeCallback presenceHandler);
429         OCStackResult subscribePresence(OCPresenceHandle& presenceHandle, const std::string& host,
430                         const std::string& resourceType, SubscribeCallback presenceHandler);
431 #endif
432         /**
433         * unsubscribes from a previously subscribed server's presence events. Note that
434         * you may for a short time still receive events from the server since it may take time
435         * for the unsubscribe to take effect.
436         *
437         * @param presenceHandle - the handle object provided by the subscribePresence call that
438         *               identifies this subscription.
439         *
440         * @return OCStackResult - return value of the API.  Returns OCSTACK_OK if success <br>
441         */
442         OCStackResult unsubscribePresence(OCPresenceHandle presenceHandle);
443
444         /**
445         * Creates a resource proxy object so that get/put/observe functionality
446         * can be used without discovering the object in advance.  Note that the
447         * consumer of this method needs to provide all of the details required to
448         * correctly contact and observe the object. If the consumer lacks any of
449         * this information, they should discover the resource object normally.
450         * Additionally, you can only create this object if OCPlatform was initialized
451         * to be a Client or Client/Server.  Otherwise, this will return an empty
452         * shared ptr.
453         *
454         * @param host - a string containing a resolvable host address of the server
455         *           holding the resource. Currently this should be in the format
456         *           coap://address:port, though in the future, we expect this to
457         *           change to //address:port
458         *
459         * @param uri - the rest of the resource's URI that will permit messages to be
460         *           properly routed.  Example: /a/light
461         *
462         * @param isObservable - a boolean containing whether the resource supports observation
463         *
464         * @param resourceTypes - a collection of resource types implemented by the resource
465         *
466         * @param interfaces - a collection of interfaces that the resource supports/implements
467         * @return OCResource::Ptr - a shared pointer to the new resource object
468         */
469 #ifdef CA_INT
470         OCResource::Ptr constructResourceObject(const std::string& host, const std::string& uri,
471                         uint8_t connectivityType, bool isObservable,
472                         const std::vector<std::string>& resourceTypes,
473                         const std::vector<std::string>& interfaces);
474 #else
475         OCResource::Ptr constructResourceObject(const std::string& host, const std::string& uri,
476                         bool isObservable, const std::vector<std::string>& resourceTypes,
477                         const std::vector<std::string>& interfaces);
478 #endif
479         /**
480         * Allows application entity handler to send response to an incoming request.
481         *
482         * @param pResponse - OCResourceResponse pointer that will permit to set values related
483         * to resource response. <br>
484         * @return OCStackResult - return value of the API. Returns OCSTACK_OK if success <br>
485         */
486         OCStackResult sendResponse(const std::shared_ptr<OCResourceResponse> pResponse);
487
488     private:
489         PlatformConfig m_cfg;
490
491     private:
492         std::unique_ptr<WrapperFactory> m_WrapperInstance;
493         IServerWrapper::Ptr m_server;
494         IClientWrapper::Ptr m_client;
495         std::shared_ptr<std::recursive_mutex> m_csdkLock;
496
497     private:
498         /**
499         * Constructor for OCPlatform. Constructs a new OCPlatform from a given PlatformConfig with
500         * appropriate fields
501         * @param config PlatformConfig struct which has details such as modeType
502         * (server/client/both), in-proc/out-of-proc etc.
503         */
504         OCPlatform_impl(const PlatformConfig& config);
505
506         /**
507         * Private function to initalize the platfrom
508         */
509         void init(const PlatformConfig& config);
510
511         /**
512         * Private constructor/operators to prevent copying
513         * of this object
514         */
515         OCPlatform_impl(const OCPlatform_impl& other)= delete;
516         OCPlatform_impl& operator=(const OCPlatform_impl&) = delete;
517         OCPlatform_impl& operator=(const OCPlatform_impl&&) = delete;
518     };
519 }
520
521 #endif //__OCPLATFORM_IMPL_H
522
523