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
29 #include <OCPlatform_impl.h>
33 * @brief: This namespace contains the main entrance/functionality of the product.
34 * It may be used with OC::OCPlatform::functionName. To set a custom configuration,
35 * the implementer must make a call to OCPlatform::Configure before the first usage
36 * of a function in this namespace.
41 * API for overwriting the default configuration of the OCPlatform object.
42 * Note: Any calls made to this AFTER the first call to OCPlatform::Instance
45 void Configure(const PlatformConfig& config);
47 // typedef for handle to cancel presence info with
48 typedef OCDoHandle OCPresenceHandle;
51 * API for notifying base that resource's attributes have changed.
53 * @param OCResourceHandle resource handle of the resource
54 * @param QualityOfService the quality of communication
56 * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
57 * NOTE: This API is for server side only.
58 * NOTE: OCResourceHandle is defined in ocstack.h.
59 * NOTE: OCStackResult is defined in ocstack.h.
61 OCStackResult notifyAllObservers(OCResourceHandle resourceHandle);
62 OCStackResult notifyAllObservers(OCResourceHandle resourceHandle, QualityOfService QoS);
65 * API for notifying only specific clients that resource's attributes have changed.
67 * @param OCResourceHandle resource handle of the resource
68 * @param observationIds std vector of observationIds. These set of ids are ones which
69 * which will be notified upon resource change.
70 * @param responsePtr OCResourceResponse pointer used by app to fill the response for this
72 * @param QualityOfService the quality of communication
74 * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
76 * NOTE: This API is for server side only.
77 * NOTE: OCResourceHandle is defined in ocstack.h.
78 * NOTE: OCStackResult is defined in ocstack.h.
80 OCStackResult notifyListOfObservers(
81 OCResourceHandle resourceHandle,
82 ObservationIds& observationIds,
83 const std::shared_ptr<OCResourceResponse> responsePtr);
84 OCStackResult notifyListOfObservers(
85 OCResourceHandle resourceHandle,
86 ObservationIds& observationIds,
87 const std::shared_ptr<OCResourceResponse> responsePtr,
88 QualityOfService QoS);
91 * API for Service and Resource Discovery.
92 * NOTE: This API applies to client side only.
94 * @param host - Host IP Address of a service to direct resource discovery query. If null or
95 * empty, performs multicast resource discovery query
96 * @param resourceURI - name of the resource. If null or empty, performs search for all
98 * @param handler - Handles callbacks, success states and failure states.
100 * Four modes of discovery defined as follows:
101 * (NULL/Empty, NULL/Empty) - Performs ALL service discovery AND ALL resource
103 * (NULL/Empty, Not Empty) - Performs query for a filtered/scoped/particular
104 * resource(s) from ALL services.
105 * (Not Empty, NULL/Empty) - Performs ALL resource discovery on a particular service.
106 * (Not Empty, Not Empty) - Performs query for a filtered/scoped/particular
108 * from a particular service.
109 * @param QualityOfService the quality of communication
111 * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
112 * NOTE: First parameter 'host' currently represents an IP address. This will change in
113 * future and will refer to endpoint interface so that we can refer to other transports such
115 * NOTE: OCStackResult is defined in ocstack.h.
118 OCStackResult findResource(const std::string& host, const std::string& resourceURI,
119 OCConnectivityType connectivityType, FindCallback resourceHandler);
120 OCStackResult findResource(const std::string& host, const std::string& resourceURI,
121 OCConnectivityType connectivityType, FindCallback resourceHandler,
122 QualityOfService QoS);
124 OCStackResult findResource(const std::string& host, const std::string& resourceURI,
125 FindCallback resourceHandler);
126 OCStackResult findResource(const std::string& host, const std::string& resourceURI,
127 FindCallback resourceHandler, QualityOfService QoS);
129 * API for Device Discovery
132 * @param host - Host IP Address. If null or empty, Multicast is performed.
133 * @param resourceURI - Uri containing address to the virtual device in C Stack
135 * @param QualityOfService the quality of communication
139 OCStackResult getDeviceInfo(const std::string& host, const std::string& deviceURI,
140 OCConnectivityType connectivityType, FindDeviceCallback deviceInfoHandler);
141 OCStackResult getDeviceInfo(const std::string& host, const std::string& deviceURI,
142 OCConnectivityType connectivityType, FindDeviceCallback deviceInfoHandler,
143 QualityOfService QoS);
145 OCStackResult getDeviceInfo(const std::string& host, const std::string& deviceURI,
146 FindDeviceCallback deviceInfoHandler);
147 OCStackResult getDeviceInfo(const std::string& host, const std::string& deviceURI,
148 FindDeviceCallback deviceInfoHandler, QualityOfService QoS);
151 * This API registers a resource with the server
152 * NOTE: This API applies to server side only.
154 * @param resourceHandle - Upon successful registration, resourceHandle will be filled
155 * @param resourceURI - The URI of the resource. Example: "a/light". See NOTE below
156 * @param resourceTypeName - The resource type. Example: "light"
157 * @param resourceInterface - The resource interface (whether it is collection etc).
158 * @param entityHandler - entity handler callback.
159 * @param resourceProperty - indicates the property of the resource. Defined in ocstack.h.
160 * setting resourceProperty as OC_DISCOVERABLE will allow Discovery of this resource
161 * setting resourceProperty as OC_OBSERVABLE will allow observation
162 * settings resourceProperty as OC_DISCOVERABLE | OC_OBSERVABLE will allow both discovery and
165 * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
166 * NOTE: "a/light" is a relative URI.
167 * Above relative URI will be prepended (by core) with a host IP + namespace "oc"
168 * Therefore, fully qualified URI format would be //HostIP-Address/namespace/relativeURI"
169 * Example, a relative URI: 'a/light' will result in a fully qualified URI:
170 * //192.168.1.1/oc/a/light"
171 * First parameter can take a relative URI and core will take care of preparing the fully
173 * first paramter can take fully qualified URI and core will take that as is for further
175 * NOTE: OCStackResult is defined in ocstack.h.
177 OCStackResult registerResource(OCResourceHandle& resourceHandle,
178 std::string& resourceURI,
179 const std::string& resourceTypeName,
180 const std::string& resourceInterface,
181 EntityHandler entityHandler,
182 uint8_t resourceProperty);
185 * This API registers a resource with the server
186 * NOTE: This API applies to server & client side.
188 * @param resourceHandle - Upon successful registration, resourceHandle will be filled
189 * @param OCResource - The instance of OCResource that all data filled.
191 * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
194 OCStackResult registerResource(OCResourceHandle& resourceHandle,
195 const std::shared_ptr< OCResource > resource);
198 * Register Device Info
200 * @param deviceInfo - structure containing all the device specific information
203 * OC_STACK_OK - no errors
204 * OC_STACK_ERROR - stack process error
207 OCStackResult registerDeviceInfo(const OCDeviceInfo deviceInfo);
210 * Set default device entity handler
212 * @param entityHandler - entity handler to handle requests for
213 * any undefined resources or default actions.
214 * if NULL is passed it removes the device default entity handler.
217 * OC_STACK_OK - no errors
218 * OC_STACK_ERROR - stack process error
220 OCStackResult setDefaultDeviceEntityHandler(EntityHandler entityHandler);
223 * This API unregisters a resource with the server
224 * NOTE: This API applies to server side only.
226 * @param resourceHandle - This is the resource handle which we which to unregister from the
229 * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
230 * NOTE: OCStackResult is defined in ocstack.h.
232 OCStackResult unregisterResource(const OCResourceHandle& resourceHandle);
235 * Add a resource to a collection resource.
237 * @param collectionHandle - handle to the collection resource
238 * @param addedResourceHandle - handle to resource to be added to the collection resource
240 * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.<br>
241 * NOTE: OCStackResult is defined in ocstack.h. <br>
242 * NOTE: bindResource must be used only after the both collection resource and
243 * resource to add under a collections are created and respective handles obtained<br>
244 * <b>Example:</b> <br>
245 * Step 1: registerResource(homeResourceHandle, "a/home", "home", Link_Interface,
246 * entityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
247 * Step 2: registerResource(kitchenResourceHandle, "a/kitchen", "kitchen", Link_Interface,
248 * entityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
249 * Step 3: bindResource(homeResourceHandle, kitchenResourceHandle);<br>
250 * At the end of Step 3, resource "a/home" will contain a reference to "a/kitchen".<br>
252 OCStackResult bindResource(const OCResourceHandle collectionHandle,
253 const OCResourceHandle resourceHandle);
256 * Add multiple resources to a collection resource.
258 * @param collectionHandle - handle to the collection resource
259 * @param addedResourceHandleList reference to list of resource handles to be added to the
260 * collection resource
262 * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
263 * NOTE: OCStackResult is defined in ocstack.h. <br>
264 * NOTE: bindResources must be used only after the both collection resource and
265 * list of resources to add under a collection are created and respective handles
267 * <b> Example: </b> <br>
268 * Step 1: registerResource(homeResourceHandle, "a/home", "home", Link_Interface,
269 * homeEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
270 * Step 2: registerResource(kitchenResourceHandle, "a/kitchen", "kitchen", Link_Interface,
271 * kitchenEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
272 * Step 3: registerResource(roomResourceHandle, "a/room", "room", Link_Interface,
273 * roomEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
274 * Step 4: std::vector<OCResourceHandle> rList; rList.push_back(kitchenResourceHandle);
275 * rList.push_back(roomResourceHandle);<br>
276 * Step 5: bindResource(homeResourceHandle, rList);<br>
277 * At the end of Step 5, resource "a/home" will contain a references to "a/kitchen" and
280 OCStackResult bindResources(const OCResourceHandle collectionHandle,
281 const std::vector<OCResourceHandle>& addedResourceHandleList);
284 * Unbind a resource from a collection resource.
286 * @param collectionHandle - handle to the collection resource
287 * @param resourceHandle resource handle to be unbound from the collection resource
289 * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
290 * NOTE: OCStackResult is defined in ocstack.h.<br>
291 * NOTE: unbindResource must be used only after the both collection resource and
292 * resource to unbind from a collection are created and respective handles obtained<br>
293 * <b> Example </b> <br>
294 * Step 1: registerResource(homeResourceHandle, "a/home", "home", Link_Interface,
295 * entityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
296 * Step 2: registerResource(kitchenResourceHandle, "a/kitchen", "kitchen", Link_Interface,
297 * entityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
298 * Step 3: bindResource(homeResourceHandle, kitchenResourceHandle);<br>
299 * Step 4: unbindResource(homeResourceHandle, kitchenResourceHandle);<br>
300 * At the end of Step 4, resource "a/home" will no longer reference "a/kitchen". <br>
302 OCStackResult unbindResource(const OCResourceHandle collectionHandle,
303 const OCResourceHandle resourceHandle);
306 * Unbind resources from a collection resource.
308 * @param collectionHandle - handle to the collection resource
309 * @param resourceHandleList List of resource handles to be unbound from the collection
312 * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
314 * NOTE: OCStackResult is defined in ocstack.h.<br>
315 * NOTE: unbindResources must be used only after the both collection resource and
316 * list of resources resource to unbind from a collection are created and respective handles
318 * <b>Example</b> <br>
319 * Step 1: registerResource(homeResourceHandle, "a/home", "home", Link_Interface,
320 * homeEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
321 * Step 2: registerResource(kitchenResourceHandle, "a/kitchen", "kitchen", Link_Interface,
322 * kitchenEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
323 * Step 3: registerResource(roomResourceHandle, "a/room", "room", Link_Interface,
324 * roomEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
325 * Step 4: std::vector<OCResourceHandle> rList; rList.push_back(kitchenResourceHandle);
326 * rList.push_back(roomResourceHandle);<br>
327 * Step 5: bindResource(homeResourceHandle, rList);<br>
328 * Step 6: unbindResources(homeResourceHandle, rList);<br>
329 * At the end of Step 6, resource "a/home" will no longer reference to "a/kitchen" and
332 OCStackResult unbindResources(const OCResourceHandle collectionHandle,
333 const std::vector<OCResourceHandle>& resourceHandleList);
336 * Binds a type to a particular resource
337 * @param resourceHandle - handle to the resource
338 * @param resourceTypeName - new typename to bind to the resource
340 * @return OCStackResult - return value of the API. Returns OCSTACK_OK if success <br>
342 OCStackResult bindTypeToResource(const OCResourceHandle& resourceHandle,
343 const std::string& resourceTypeName);
346 * Binds an interface to a particular resource
347 * @param resourceHandle - handle to the resource
348 * @param resourceTypeName - new interface to bind to the resource
350 * @return OCStackResult - return value of the API. Returns OCSTACK_OK if success <br>
352 OCStackResult bindInterfaceToResource(const OCResourceHandle& resourceHandle,
353 const std::string& resourceInterfaceName);
357 * Start Presence announcements.
359 * @param ttl - time to live
360 * @return OCStackResult - Returns OCSTACK_OK if success <br>
362 * Server can call this function when it comes online for the
363 * first time, or when it comes back online from offline mode,
364 * or when it re enters network.
368 OCStackResult startPresence(const unsigned int ttl);
371 * Stop Presence announcements.
373 * @return OCStackResult - Returns OCSTACK_OK if success <br>
375 * Server can call this function when it is terminating,
376 * going offline, or when going away from network.
380 OCStackResult stopPresence();
383 * subscribes to a server's presence change events. By making this subscription,
384 * every time a server adds/removes/alters a resource, starts or is intentionally
385 * stopped (potentially more to be added later).
387 * @param presenceHandle - a handle object that can be used to identify this subscription
388 * request. It can be used to unsubscribe from these events in the future.
389 * It will be set upon successful return of this method.
390 * @param host - The IP address/addressable name of the server to subscribe to.
391 * @param resourceType - a resource type specified as a filter for subscription callbacks.
392 * @param presenceHandler - callback function that will receive notifications/subscription
395 * @return OCStackResult - return value of the API. Returns OCSTACK_OK if success <br>
398 OCStackResult subscribePresence(OCPresenceHandle& presenceHandle, const std::string& host,
399 OCConnectivityType connectivityType, SubscribeCallback presenceHandler);
400 OCStackResult subscribePresence(OCPresenceHandle& presenceHandle, const std::string& host,
401 const std::string& resourceType, OCConnectivityType connectivityType,
402 SubscribeCallback presenceHandler);
404 OCStackResult subscribePresence(OCPresenceHandle& presenceHandle, const std::string& host,
405 SubscribeCallback presenceHandler);
406 OCStackResult subscribePresence(OCPresenceHandle& presenceHandle, const std::string& host,
407 const std::string& resourceType, SubscribeCallback presenceHandler);
409 * unsubscribes from a previously subscribed server's presence events. Note that
410 * you may for a short time still receive events from the server since it may take time
411 * for the unsubscribe to take effect.
413 * @param presenceHandle - the handle object provided by the subscribePresence call that
414 * identifies this subscription.
416 * @return OCStackResult - return value of the API. Returns OCSTACK_OK if success <br>
418 OCStackResult unsubscribePresence(OCPresenceHandle presenceHandle);
421 * Creates a resource proxy object so that get/put/observe functionality
422 * can be used without discovering the object in advance. Note that the
423 * consumer of this method needs to provide all of the details required to
424 * correctly contact and observe the object. If the consumer lacks any of
425 * this information, they should discover the resource object normally.
426 * Additionally, you can only create this object if OCPlatform was initialized
427 * to be a Client or Client/Server. Otherwise, this will return an empty
430 * @param host - a string containing a resolvable host address of the server
431 * holding the resource. Currently this should be in the format
432 * coap://address:port, though in the future, we expect this to
433 * change to //address:port
435 * @param uri - the rest of the resource's URI that will permit messages to be
436 * properly routed. Example: /a/light
438 * @param isObservable - a boolean containing whether the resource supports observation
440 * @param resourceTypes - a collection of resource types implemented by the resource
442 * @param interfaces - a collection of interfaces that the resource supports/implements
443 * @return OCResource::Ptr - a shared pointer to the new resource object
446 OCResource::Ptr constructResourceObject(const std::string& host, const std::string& uri,
447 OCConnectivityType connectivityType, bool isObservable,
448 const std::vector<std::string>& resourceTypes,
449 const std::vector<std::string>& interfaces);
451 OCResource::Ptr constructResourceObject(const std::string& host, const std::string& uri,
452 bool isObservable, const std::vector<std::string>& resourceTypes,
453 const std::vector<std::string>& interfaces);
455 * Allows application entity handler to send response to an incoming request.
457 * @param pResponse - OCResourceResponse pointer that will permit to set values related
458 * to resource response. <br>
459 * @return OCStackResult - return value of the API. Returns OCSTACK_OK if success <br>
461 OCStackResult sendResponse(const std::shared_ptr<OCResourceResponse> pResponse);
465 #endif //__OCPLATFORM_H