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.h
23 /// @brief This file contains the declaration of classes and its members related to
26 #ifndef __OCPLATFORM_H
27 #define __OCPLATFORM_H
32 #include "OCResource.h"
33 #include "OCPlatformHandler.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 mutable boost::iostreams::stream<OC::oc_log_stream> m_log_stream;
55 // typedef for handle to cancel presence info with
56 typedef OCDoHandle OCPresenceHandle;
59 * Constructor for OCPlatform. Constructs a new OCPlatform from a given PlatformConfig with
61 * @param config PlatformConfig struct which has details such as modeType (server/client/both),
62 * in-proc/out-of-proc etc.
64 OCPlatform(const PlatformConfig& config);
65 OCPlatform(const PlatformConfig& config, OC::oc_log_stream& log_target);
70 virtual ~OCPlatform(void);
73 * API for notifying base that resource's attributes have changed.
75 * @param OCResourceHandle resource handle of the resource
77 * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
78 * NOTE: This API is for server side only.
79 * NOTE: OCResourceHandle is defined in ocstack.h.
80 * NOTE: OCStackResult is defined in ocstack.h.
82 static OCStackResult notifyAllObservers(OCResourceHandle resourceHandle);
85 * API for notifying only specific clients that resource's attributes have changed.
87 * @param OCResourceHandle resource handle of the resource
88 * @param observationIds std vector of observationIds. These set of ids are ones which
89 * which will be notified upon resource change.
90 * @param responsePtr OCResourceResponse pointer used by app to fill the response for this
93 * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
95 * NOTE: This API is for server side only.
96 * NOTE: OCResourceHandle is defined in ocstack.h.
97 * NOTE: OCStackResult is defined in ocstack.h.
99 static OCStackResult notifyListOfObservers(
100 OCResourceHandle resourceHandle,
101 ObservationIds& observationIds,
102 const std::shared_ptr<OCResourceResponse> responsePtr);
105 * API for Service and Resource Discovery.
106 * NOTE: This API applies to client side only.
108 * @param host - Host IP Address of a service to direct resource discovery query. If null or
109 * empty, performs multicast resource discovery query
110 * @param resourceURI - name of the resource. If null or empty, performs search for all resource names
111 * @param handler - Handles callbacks, success states and failure states.
113 * Four modes of discovery defined as follows:
114 * (NULL/Empty, NULL/Empty) - Performs ALL service discovery AND ALL resource discovery.
115 * (NULL/Empty, Not Empty) - Performs query for a filtered/scoped/particular resource(s)
117 * (Not Empty, NULL/Empty) - Performs ALL resource discovery on a particular service.
118 * (Not Empty, Not Empty) - Performs query for a filtered/scoped/particular resource(s)
119 * from a particular service.
121 * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
122 * NOTE: First parameter 'host' currently represents an IP address. This will change in future
123 * and will refer to endpoint interface so that we can refer to other transports such as BTH etc.
124 * NOTE: OCStackResult is defined in ocstack.h.
126 OCStackResult findResource(const std::string& host, const std::string& resourceURI,
127 FindCallback resourceHandler);
130 * This API registers a resource with the server
131 * NOTE: This API applies to server side only.
133 * @param resourceHandle - Upon successful registration, resourceHandle will be filled
134 * @param resourceURI - The URI of the resource. Example: "a/light". See NOTE below
135 * @param resourceTypeName - The resource type. Example: "light"
136 * @param resourceInterface - The resource interface (whether it is collection etc).
137 * @param entityHandler - entity handler callback.
138 * @param resourceProperty - indicates the property of the resource. Defined in ocstack.h.
139 * setting resourceProperty as OC_DISCOVERABLE will allow Discovery of this resource
140 * setting resourceProperty as OC_OBSERVABLE will allow observation
141 * settings resourceProperty as OC_DISCOVERABLE | OC_OBSERVABLE will allow both discovery and observation
143 * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
144 * NOTE: "a/light" is a relative URI.
145 * Above relative URI will be prepended (by core) with a host IP + namespace "oc"
146 * Therefore, fully qualified URI format would be //HostIP-Address/namespace/relativeURI"
147 * Example, a relative URI: 'a/light' will result in a fully qualified URI: //192.168.1.1/oc/a/light"
148 * First parameter can take a relative URI and core will take care of preparing the fully qualified URI
150 * first paramter can take fully qualified URI and core will take that as is for further operations
151 * NOTE: OCStackResult is defined in ocstack.h.
153 OCStackResult registerResource(OCResourceHandle& resourceHandle,
154 std::string& resourceURI,
155 const std::string& resourceTypeName,
156 const std::string& resourceInterface,
157 EntityHandler entityHandler,
158 uint8_t resourceProperty);
161 * Set default device entity handler
163 * @param entityHandler - entity handler to handle requests for
164 * any undefined resources or default actions.
165 * if NULL is passed it removes the device default entity handler.
168 * OC_STACK_OK - no errors
169 * OC_STACK_ERROR - stack process error
171 OCStackResult setDefaultDeviceEntityHandler(EntityHandler entityHandler);
174 * This API unregisters a resource with the server
175 * NOTE: This API applies to server side only.
177 * @param resourceHandle - This is the resource handle which we which to unregister from the server
179 * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
180 * NOTE: OCStackResult is defined in ocstack.h.
182 OCStackResult unregisterResource(const OCResourceHandle& resourceHandle) const;
185 * Add a resource to a collection resource.
187 * @param collectionHandle - handle to the collection resource
188 * @param addedResourceHandle - handle to resource to be added to the collection resource
190 * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.<br>
191 * NOTE: OCStackResult is defined in ocstack.h. <br>
192 * NOTE: bindResource must be used only after the both collection resource and
193 * resource to add under a collections are created and respective handles obtained<br>
194 * <b>Example:</b> <br>
195 * Step 1: registerResource(homeResourceHandle, "a/home", "home", Link_Interface, entityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
196 * Step 2: registerResource(kitchenResourceHandle, "a/kitchen", "kitchen", Link_Interface, entityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
197 * Step 3: bindResource(homeResourceHandle, kitchenResourceHandle);<br>
198 * At the end of Step 3, resource "a/home" will contain a reference to "a/kitchen".<br>
200 OCStackResult bindResource(const OCResourceHandle collectionHandle, const OCResourceHandle resourceHandle);
203 * Add multiple resources to a collection resource.
205 * @param collectionHandle - handle to the collection resource
206 * @param addedResourceHandleList reference to list of resource handles to be added to the collection resource
208 * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
209 * NOTE: OCStackResult is defined in ocstack.h. <br>
210 * NOTE: bindResources must be used only after the both collection resource and
211 * list of resources to add under a collection are created and respective handles obtained <br>
212 * <b> Example: </b> <br>
213 * Step 1: registerResource(homeResourceHandle, "a/home", "home", Link_Interface, homeEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
214 * Step 2: registerResource(kitchenResourceHandle, "a/kitchen", "kitchen", Link_Interface, kitchenEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
215 * Step 3: registerResource(roomResourceHandle, "a/room", "room", Link_Interface, roomEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
216 * Step 4: std::vector<OCResourceHandle> rList; rList.push_back(kitchenResourceHandle); rList.push_back(roomResourceHandle);<br>
217 * Step 5: bindResource(homeResourceHandle, rList);<br>
218 * At the end of Step 5, resource "a/home" will contain a references to "a/kitchen" and "a/room" <br>
220 OCStackResult bindResources(const OCResourceHandle collectionHandle, const std::vector<OCResourceHandle>& addedResourceHandleList);
223 * Unbind a resource from a collection resource.
225 * @param collectionHandle - handle to the collection resource
226 * @param resourceHandle resource handle to be unbound from the collection resource
228 * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
229 * NOTE: OCStackResult is defined in ocstack.h.<br>
230 * NOTE: unbindResource must be used only after the both collection resource and
231 * resource to unbind from a collection are created and respective handles obtained<br>
232 * <b> Example </b> <br>
233 * Step 1: registerResource(homeResourceHandle, "a/home", "home", Link_Interface, entityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
234 * Step 2: registerResource(kitchenResourceHandle, "a/kitchen", "kitchen", Link_Interface, entityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
235 * Step 3: bindResource(homeResourceHandle, kitchenResourceHandle);<br>
236 * Step 4: unbindResource(homeResourceHandle, kitchenResourceHandle);<br>
237 * At the end of Step 4, resource "a/home" will no longer reference "a/kitchen". <br>
239 OCStackResult unbindResource(const OCResourceHandle collectionHandle, const OCResourceHandle resourceHandle);
242 * Unbind resources from a collection resource.
244 * @param collectionHandle - handle to the collection resource
245 * @param resourceHandleList List of resource handles to be unbound from the collection resource
247 * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
249 * NOTE: OCStackResult is defined in ocstack.h.<br>
250 * NOTE: unbindResources must be used only after the both collection resource and
251 * list of resources resource to unbind from a collection are created and respective handles obtained. <br>
252 * <b>Example</b> <br>
253 * Step 1: registerResource(homeResourceHandle, "a/home", "home", Link_Interface, homeEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
254 * Step 2: registerResource(kitchenResourceHandle, "a/kitchen", "kitchen", Link_Interface, kitchenEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
255 * Step 3: registerResource(roomResourceHandle, "a/room", "room", Link_Interface, roomEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
256 * Step 4: std::vector<OCResourceHandle> rList; rList.push_back(kitchenResourceHandle); rList.push_back(roomResourceHandle);<br>
257 * Step 5: bindResource(homeResourceHandle, rList);<br>
258 * Step 6: unbindResources(homeResourceHandle, rList);<br>
259 * At the end of Step 6, resource "a/home" will no longer reference to "a/kitchen" and "a/room"<br>
261 OCStackResult unbindResources(const OCResourceHandle collectionHandle, const std::vector<OCResourceHandle>& resourceHandleList);
264 * Binds a type to a particular resource
265 * @param resourceHandle - handle to the resource
266 * @param resourceTypeName - new typename to bind to the resource
268 * @return OCStackResult - return value of the API. Returns OCSTACK_OK if success <br>
270 OCStackResult bindTypeToResource(const OCResourceHandle& resourceHandle,
271 const std::string& resourceTypeName) const;
274 * Binds an interface to a particular resource
275 * @param resourceHandle - handle to the resource
276 * @param resourceTypeName - new interface to bind to the resource
278 * @return OCStackResult - return value of the API. Returns OCSTACK_OK if success <br>
280 OCStackResult bindInterfaceToResource(const OCResourceHandle& resourceHandle,
281 const std::string& resourceInterfaceName) const;
285 * Start Presence announcements.
287 * @param ttl - time to live
288 * @return OCStackResult - Returns OCSTACK_OK if success <br>
290 * Server can call this function when it comes online for the
291 * first time, or when it comes back online from offline mode,
292 * or when it re enters network.
296 OCStackResult startPresence(const unsigned int ttl);
299 * Stop Presence announcements.
301 * @return OCStackResult - Returns OCSTACK_OK if success <br>
303 * Server can call this function when it is terminating,
304 * going offline, or when going away from network.
308 OCStackResult stopPresence();
311 * subscribes to a server's presence change events. By making this subscription,
312 * every time a server adds/removes/alters a resource, starts or is intentionally
313 * stopped (potentially more to be added later).
315 * @param presenceHandle - a handle object that can be used to identify this subscription
316 * request. It can be used to unsubscribe from these events in the future.
317 * It will be set upon successful return of this method.
318 * @param host - The IP address/addressable name of the server to subscribe to.
319 * @param presenceHandler - callback function that will receive notifications/subscription events
321 * @return OCStackResult - return value of the API. Returns OCSTACK_OK if success <br>
323 OCStackResult subscribePresence(OCPresenceHandle& presenceHandle, const std::string& host,
324 SubscribeCallback presenceHandler);
327 * unsubscribes from a previously subscribed server's presence events. Note that
328 * you may for a short time still receive events from the server since it may take time
329 * for the unsubscribe to take effect.
331 * @param presenceHandle - the handle object provided by the subscribePresence call that identifies
334 * @return OCStackResult - return value of the API. Returns OCSTACK_OK if success <br>
336 OCStackResult unsubscribePresence(OCPresenceHandle presenceHandle);
339 * Creates a resource proxy object so that get/put/observe functionality
340 * can be used without discovering the object in advance. Note that the
341 * consumer of this method needs to provide all of the details required to
342 * correctly contact and observe the object. If the consumer lacks any of
343 * this information, they should discover the resource object normally.
344 * Additionally, you can only create this object if OCPlatform was initialized
345 * to be a Client or Client/Server. Otherwise, this will return an empty
348 * @param host - a string containing a resolvable host address of the server
349 * holding the resource. Currently this should be in the format
350 * coap://address:port, though in the future, we expect this to
351 * change to //address:port
353 * @param uri - the rest of the resource's URI that will permit messages to be
354 * properly routed. Example: /a/light
356 * @param isObservable - a boolean containing whether the resource supports observation
358 * @param resourceTypes - a collection of resource types implemented by the resource
360 * @param interfaces - a collection of interfaces that the resource supports/implements
361 * @return OCResource::Ptr - a shared pointer to the new resource object
363 OCResource::Ptr constructResourceObject(const std::string& host, const std::string& uri,
364 bool isObservable, const std::vector<std::string>& resourceTypes,
365 const std::vector<std::string>& interfaces);
368 inline boost::iostreams::stream<OC::oc_log_stream>& log() const { return m_log_stream; }
371 PlatformConfig m_cfg;
374 std::unique_ptr<WrapperFactory> m_WrapperInstance;
375 IServerWrapper::Ptr m_server;
376 IClientWrapper::Ptr m_client;
377 std::shared_ptr<std::recursive_mutex> m_csdkLock;
381 * Private function to initalize the platfrom
383 void init(const PlatformConfig& config);
387 #endif //__OCPLATFORM_H