1 //******************************************************************
3 // Copyright 2014 Intel Mobile Communications GmbH All Rights Reserved.
5 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
7 // Licensed under the Apache License, Version 2.0 (the "License");
8 // you may not use this file except in compliance with the License.
9 // You may obtain a copy of the License at
11 // http://www.apache.org/licenses/LICENSE-2.0
13 // Unless required by applicable law or agreed to in writing, software
14 // distributed under the License is distributed on an "AS IS" BASIS,
15 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16 // See the License for the specific language governing permissions and
17 // limitations under the License.
19 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
21 /// @file OCPlatform_impl.h
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.
27 #ifndef __OCPLATFORM_IMPL_H
28 #define __OCPLATFORM_IMPL_H
33 #include "OCResource.h"
34 #include "WrapperFactory.h"
35 #include "OCResourceRequest.h"
36 #include "OCResourceResponse.h"
37 #include "OCRepresentation.h"
39 #include "oc_logger.hpp"
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.
52 static PlatformConfig& globalConfig();
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
59 static void Configure(const PlatformConfig& config);
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.
66 static OCPlatform_impl& Instance();
69 // typedef for handle to cancel presence info with
70 typedef OCDoHandle OCPresenceHandle;
75 virtual ~OCPlatform_impl(void);
78 * API for notifying base that resource's attributes have changed.
80 * @param OCResourceHandle resource handle of the resource
81 * @param QualityOfService the quality of communication
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.
88 OCStackResult notifyAllObservers(OCResourceHandle resourceHandle);
89 OCStackResult notifyAllObservers(OCResourceHandle resourceHandle, QualityOfService QoS);
92 * API for notifying only specific clients that resource's attributes have changed.
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
99 * @param QualityOfService the quality of communication
101 * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
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.
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);
118 * API for Service and Resource Discovery.
119 * NOTE: This API applies to client side only.
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
125 * @param handler - Handles callbacks, success states and failure states.
127 * Four modes of discovery defined as follows:
128 * (NULL/Empty, NULL/Empty) - Performs ALL service discovery AND ALL resource
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
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
141 * NOTE: OCStackResult is defined in ocstack.h.
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);
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);
155 * API for Device Discovery
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
161 * @param QualityOfService the quality of communication
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);
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);
177 * This API registers a resource with the server
178 * NOTE: This API applies to server side only.
180 * @param resourceHandle - Upon successful registration, resourceHandle will be filled
181 * @param resourceURI - The URI of the resource. Example: "a/light". See NOTE below
182 * @param resourceTypeName - The resource type. Example: "light"
183 * @param resourceInterface - The resource interface (whether it is collection etc).
184 * @param entityHandler - entity handler callback.
185 * @param resourceProperty - indicates the property of the resource. Defined in ocstack.h.
186 * setting resourceProperty as OC_DISCOVERABLE will allow Discovery of this resource
187 * setting resourceProperty as OC_OBSERVABLE will allow observation
188 * settings resourceProperty as OC_DISCOVERABLE | OC_OBSERVABLE will allow both discovery
191 * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
192 * NOTE: "a/light" is a relative URI.
193 * Above relative URI will be prepended (by core) with a host IP + namespace "oc"
194 * Therefore, fully qualified URI format would be //HostIP-Address/namespace/relativeURI"
195 * Example, a relative URI: 'a/light' will result in a fully qualified URI:
196 * //192.168.1.1/oc/a/light"
197 * First parameter can take a relative URI and core will take care of preparing the fully
199 * first paramter can take fully qualified URI and core will take that as is for further
201 * NOTE: OCStackResult is defined in ocstack.h.
203 OCStackResult registerResource(OCResourceHandle& resourceHandle,
204 std::string& resourceURI,
205 const std::string& resourceTypeName,
206 const std::string& resourceInterface,
207 EntityHandler entityHandler,
208 uint8_t resourceProperty);
211 * This API registers a resource with the server
212 * NOTE: This API applies to server & client side.
214 * @param resourceHandle - Upon successful registration, resourceHandle will be filled
215 * @param OCResource - The instance of OCResource that all data filled.
217 * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
220 OCStackResult registerResource(OCResourceHandle& resourceHandle,
221 const std::shared_ptr<OCResource> resource);
224 * This API registers all the device specific information
226 * @param OCDeviceInfo - Structure containing all the device related information
228 * @return OCStackResult return value of the API. Returns OC_STACK_OK if success
230 * Note: OCDeviceInfo is defined in OCStack.h
232 OCStackResult registerDeviceInfo(const OCDeviceInfo deviceInfo);
235 * Set default device entity handler
237 * @param entityHandler - entity handler to handle requests for
238 * any undefined resources or default actions.
239 * if NULL is passed it removes the device default entity handler.
242 * OC_STACK_OK - no errors
243 * OC_STACK_ERROR - stack process error
245 OCStackResult setDefaultDeviceEntityHandler(EntityHandler entityHandler);
248 * This API unregisters a resource with the server
249 * NOTE: This API applies to server side only.
251 * @param resourceHandle - This is the resource handle which we which to unregister from the
254 * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
255 * NOTE: OCStackResult is defined in ocstack.h.
257 OCStackResult unregisterResource(const OCResourceHandle& resourceHandle) const;
260 * Add a resource to a collection resource.
262 * @param collectionHandle - handle to the collection resource
263 * @param addedResourceHandle - handle to resource to be added to the collection resource
265 * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.<br>
266 * NOTE: OCStackResult is defined in ocstack.h. <br>
267 * NOTE: bindResource must be used only after the both collection resource and
268 * resource to add under a collections are created and respective handles obtained<br>
269 * <b>Example:</b> <br>
270 * Step 1: registerResource(homeResourceHandle, "a/home", "home", Link_Interface,
271 * entityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
272 * Step 2: registerResource(kitchenResourceHandle, "a/kitchen", "kitchen", Link_Interface,
273 * entityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
274 * Step 3: bindResource(homeResourceHandle, kitchenResourceHandle);<br>
275 * At the end of Step 3, resource "a/home" will contain a reference to "a/kitchen".<br>
277 OCStackResult bindResource(const OCResourceHandle collectionHandle,
278 const OCResourceHandle resourceHandle);
281 * Add multiple resources to a collection resource.
283 * @param collectionHandle - handle to the collection resource
284 * @param addedResourceHandleList reference to list of resource handles to be added to
285 * the collection resource
287 * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
288 * NOTE: OCStackResult is defined in ocstack.h. <br>
289 * NOTE: bindResources must be used only after the both collection resource and
290 * list of resources to add under a collection are created and respective handles
292 * <b> Example: </b> <br>
293 * Step 1: registerResource(homeResourceHandle, "a/home", "home", Link_Interface,
294 * homeEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
295 * Step 2: registerResource(kitchenResourceHandle, "a/kitchen", "kitchen", Link_Interface,
296 * kitchenEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
297 * Step 3: registerResource(roomResourceHandle, "a/room", "room", Link_Interface,
298 * roomEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
299 * Step 4: std::vector<OCResourceHandle> rList; rList.push_back(kitchenResourceHandle);
300 * rList.push_back(roomResourceHandle);<br>
301 * Step 5: bindResource(homeResourceHandle, rList);<br>
302 * At the end of Step 5, resource "a/home" will contain a references to "a/kitchen"
305 OCStackResult bindResources(const OCResourceHandle collectionHandle,
306 const std::vector<OCResourceHandle>& addedResourceHandleList);
309 * Unbind a resource from a collection resource.
311 * @param collectionHandle - handle to the collection resource
312 * @param resourceHandle resource handle to be unbound from the collection resource
314 * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
315 * NOTE: OCStackResult is defined in ocstack.h.<br>
316 * NOTE: unbindResource must be used only after the both collection resource and
317 * resource to unbind from a collection are created and respective handles obtained<br>
318 * <b> Example </b> <br>
319 * Step 1: registerResource(homeResourceHandle, "a/home", "home", Link_Interface,
320 * entityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
321 * Step 2: registerResource(kitchenResourceHandle, "a/kitchen", "kitchen", Link_Interface,
322 * entityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
323 * Step 3: bindResource(homeResourceHandle, kitchenResourceHandle);<br>
324 * Step 4: unbindResource(homeResourceHandle, kitchenResourceHandle);<br>
325 * At the end of Step 4, resource "a/home" will no longer reference "a/kitchen". <br>
327 OCStackResult unbindResource(const OCResourceHandle collectionHandle,
328 const OCResourceHandle resourceHandle);
331 * Unbind resources from a collection resource.
333 * @param collectionHandle - handle to the collection resource
334 * @param resourceHandleList List of resource handles to be unbound from the collection
337 * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
339 * NOTE: OCStackResult is defined in ocstack.h.<br>
340 * NOTE: unbindResources must be used only after the both collection resource and
341 * list of resources resource to unbind from a collection are created and respective handles
343 * <b>Example</b> <br>
344 * Step 1: registerResource(homeResourceHandle, "a/home", "home", Link_Interface,
345 * homeEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
346 * Step 2: registerResource(kitchenResourceHandle, "a/kitchen", "kitchen", Link_Interface,
347 * kitchenEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
348 * Step 3: registerResource(roomResourceHandle, "a/room", "room", Link_Interface,
349 * roomEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
350 * Step 4: std::vector<OCResourceHandle> rList; rList.push_back(kitchenResourceHandle);
351 * rList.push_back(roomResourceHandle);<br>
352 * Step 5: bindResource(homeResourceHandle, rList);<br>
353 * Step 6: unbindResources(homeResourceHandle, rList);<br>
354 * At the end of Step 6, resource "a/home" will no longer reference to "a/kitchen"
357 OCStackResult unbindResources(const OCResourceHandle collectionHandle,
358 const std::vector<OCResourceHandle>& resourceHandleList);
361 * Binds a type to a particular resource
362 * @param resourceHandle - handle to the resource
363 * @param resourceTypeName - new typename to bind to the resource
365 * @return OCStackResult - return value of the API. Returns OCSTACK_OK if success <br>
367 OCStackResult bindTypeToResource(const OCResourceHandle& resourceHandle,
368 const std::string& resourceTypeName) const;
371 * Binds an interface to a particular resource
372 * @param resourceHandle - handle to the resource
373 * @param resourceTypeName - new interface to bind to the resource
375 * @return OCStackResult - return value of the API. Returns OCSTACK_OK if success <br>
377 OCStackResult bindInterfaceToResource(const OCResourceHandle& resourceHandle,
378 const std::string& resourceInterfaceName) const;
381 * Start Presence announcements.
383 * @param ttl - time to live
384 * @return OCStackResult - Returns OCSTACK_OK if success <br>
386 * Server can call this function when it comes online for the
387 * first time, or when it comes back online from offline mode,
388 * or when it re enters network.
391 OCStackResult startPresence(const unsigned int ttl);
394 * Stop Presence announcements.
396 * @return OCStackResult - Returns OCSTACK_OK if success <br>
398 * Server can call this function when it is terminating,
399 * going offline, or when going away from network.
402 OCStackResult stopPresence();
405 * subscribes to a server's presence change events. By making this subscription,
406 * every time a server adds/removes/alters a resource, starts or is intentionally
407 * stopped (potentially more to be added later).
409 * @param presenceHandle - a handle object that can be used to identify this subscription
410 * request. It can be used to unsubscribe from these events in the future.
411 * It will be set upon successful return of this method.
412 * @param host - The IP address/addressable name of the server to subscribe to.
413 * @param resourceType - a resource type specified as a filter for subscription callbacks.
414 * @param presenceHandler - callback function that will receive notifications/subscription
417 * @return OCStackResult - return value of the API. Returns OCSTACK_OK if success <br>
420 OCStackResult subscribePresence(OCPresenceHandle& presenceHandle, const std::string& host,
421 uint8_t connectivityType, SubscribeCallback presenceHandler);
422 OCStackResult subscribePresence(OCPresenceHandle& presenceHandle, const std::string& host,
423 const std::string& resourceType, uint8_t connectivityType,
424 SubscribeCallback presenceHandler);
426 OCStackResult subscribePresence(OCPresenceHandle& presenceHandle, const std::string& host,
427 SubscribeCallback presenceHandler);
428 OCStackResult subscribePresence(OCPresenceHandle& presenceHandle, const std::string& host,
429 const std::string& resourceType, SubscribeCallback presenceHandler);
432 * unsubscribes from a previously subscribed server's presence events. Note that
433 * you may for a short time still receive events from the server since it may take time
434 * for the unsubscribe to take effect.
436 * @param presenceHandle - the handle object provided by the subscribePresence call that
437 * identifies this subscription.
439 * @return OCStackResult - return value of the API. Returns OCSTACK_OK if success <br>
441 OCStackResult unsubscribePresence(OCPresenceHandle presenceHandle);
444 * Creates a resource proxy object so that get/put/observe functionality
445 * can be used without discovering the object in advance. Note that the
446 * consumer of this method needs to provide all of the details required to
447 * correctly contact and observe the object. If the consumer lacks any of
448 * this information, they should discover the resource object normally.
449 * Additionally, you can only create this object if OCPlatform was initialized
450 * to be a Client or Client/Server. Otherwise, this will return an empty
453 * @param host - a string containing a resolvable host address of the server
454 * holding the resource. Currently this should be in the format
455 * coap://address:port, though in the future, we expect this to
456 * change to //address:port
458 * @param uri - the rest of the resource's URI that will permit messages to be
459 * properly routed. Example: /a/light
461 * @param isObservable - a boolean containing whether the resource supports observation
463 * @param resourceTypes - a collection of resource types implemented by the resource
465 * @param interfaces - a collection of interfaces that the resource supports/implements
466 * @return OCResource::Ptr - a shared pointer to the new resource object
469 OCResource::Ptr constructResourceObject(const std::string& host, const std::string& uri,
470 uint8_t connectivityType, bool isObservable,
471 const std::vector<std::string>& resourceTypes,
472 const std::vector<std::string>& interfaces);
474 OCResource::Ptr constructResourceObject(const std::string& host, const std::string& uri,
475 bool isObservable, const std::vector<std::string>& resourceTypes,
476 const std::vector<std::string>& interfaces);
479 * Allows application entity handler to send response to an incoming request.
481 * @param pResponse - OCResourceResponse pointer that will permit to set values related
482 * to resource response. <br>
483 * @return OCStackResult - return value of the API. Returns OCSTACK_OK if success <br>
485 OCStackResult sendResponse(const std::shared_ptr<OCResourceResponse> pResponse);
488 PlatformConfig m_cfg;
491 std::unique_ptr<WrapperFactory> m_WrapperInstance;
492 IServerWrapper::Ptr m_server;
493 IClientWrapper::Ptr m_client;
494 std::shared_ptr<std::recursive_mutex> m_csdkLock;
498 * Constructor for OCPlatform. Constructs a new OCPlatform from a given PlatformConfig with
500 * @param config PlatformConfig struct which has details such as modeType
501 * (server/client/both), in-proc/out-of-proc etc.
503 OCPlatform_impl(const PlatformConfig& config);
506 * Private function to initalize the platfrom
508 void init(const PlatformConfig& config);
511 * Private constructor/operators to prevent copying
514 OCPlatform_impl(const OCPlatform_impl& other)= delete;
515 OCPlatform_impl& operator=(const OCPlatform_impl&) = delete;
516 OCPlatform_impl& operator=(const OCPlatform_impl&&) = delete;
520 #endif //__OCPLATFORM_IMPL_H