resource/csdk/stack/include/ocstack.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 #ifndef OCSTACK_H_
  22 #define OCSTACK_H_
  23
  24 #include <stdint.h>
  25 #include "octypes.h"
  26
  27 #ifdef __cplusplus
  28 extern "C" {
  29 #endif // __cplusplus
  30 #define WITH_PRESENCE
  31 #define USE_RANDOM_PORT (0)
  32
  33 //-----------------------------------------------------------------------------
  34 // Function prototypes
  35 //-----------------------------------------------------------------------------
  36
  37 /**
  38  * Initialize the OC Stack.  Must be called prior to starting the stack.
  39  *
  40  * @param ipAddr
  41  *     IP Address of host device. Deprecated parameter.
  42  * @param port
  43  *     Port of host device. Deprecated parameter.
  44  * @param mode
  45  *     Host device is client, server, or client-server.
  46  *
  47  * @return ::OC_STACK_OK on success, some other value upon failure.
  48  */
  49 OCStackResult OCInit(const char *ipAddr, uint16_t port, OCMode mode);
  50
  51 /**
  52  * Stop the OC stack.  Use for a controlled shutdown.
  53  *
  54  * Note: OCStop() performs operations similar to OCStopPresence(), as well as OCDeleteResource() on
  55  * all resources this server is hosting. OCDeleteResource() performs operations similar to
  56  * OCNotifyAllObservers() to notify all client observers that the respective resource is being
  57  * deleted.
  58  *
  59  * @return ::OC_STACK_OK on success, some other value upon failure.
  60  */
  61 OCStackResult OCStop();
  62
  63 /**
  64  * Called in main loop of OC client or server.  Allows low-level processing of
  65  * stack services.
  66  *
  67  * @return ::OC_STACK_OK on success, some other value upon failure.
  68  */
  69 OCStackResult OCProcess();
  70
  71 /**
  72  * Discover or Perform requests on a specified resource (specified by that Resource's respective
  73  * URI).
  74  *
  75  * @param handle             @ref OCDoHandle to refer to the request sent out on behalf of
  76  *                           calling this API. This handle can be used to cancel this operation
  77  *                           via the OCCancel API.
  78  *                           Note: This reference is handled internally, and
  79  *                           should not be free'd by the consumer.  A NULL handle is permitted
  80  *                           in the event where the caller has no use for the return value.
  81  * @param method             @ref OCMethod to perform on the resource.
  82  * @param requiredUri        URI of the resource to interact with.
  83  * @param referenceUri       URI of the reference resource.
  84  * @param request            JSON encoded request.
  85  * @param conType            @ref OCConnectivityType type of connectivity indicating the
  86  *                           interface. Example: ::OC_WIFI, ::OC_ETHERNET, ::OC_ALL.
  87  * @param qos                Quality of service. Note that if this API is called on a uri with
  88  *                           the well-known multicast IP address, the qos will be forced to
  89  *                           ::OC_LOW_QOS
  90  *                           since it is impractical to send other QOS levels on such addresses.
  91  * @param cbData             Asynchronous callback function that is invoked
  92  *                           by the stack when discovery or resource interaction is complete.
  93  * @param options            The address of an array containing the vendor specific
  94  *                           header options to be sent with the request.
  95  * @param numOptions         Number of header options to be included.
  96  *
  97  * Note: Presence subscription amendments (ie. adding additional resource type filters by calling
  98  * this API again) require the use of the same base URI as the original request to successfully
  99  * amend the presence filters.
 100  *
 101  * @return ::OC_STACK_OK on success, some other value upon failure.
 102  */
 103 OCStackResult OCDoResource(OCDoHandle *handle, OCMethod method, const char *requiredUri,
 104             const char *referenceUri, const char *request, OCConnectivityType conType,
 105             OCQualityOfService qos, OCCallbackData *cbData,
 106             OCHeaderOption * options, uint8_t numOptions);
 107
 108 /**
 109  * Cancel a request associated with a specific @ref OCDoResource invocation.
 110  *
 111  * @param handle - Used to identify a specific OCDoResource invocation.
 112  * @param qos    - used to specify Quality of Service (read below for more info)
 113  * @param options- used to specify vendor specific header options when sending
 114  *                 explicit observe cancellation
 115  * @param numOptions- Number of header options to be included
 116  *
 117  * @return ::OC_STACK_OK on success, some other value upon failure.
 118  */
 119 OCStackResult OCCancel(OCDoHandle handle, OCQualityOfService qos, OCHeaderOption * options,
 120         uint8_t numOptions);
 121
 122 #ifdef WITH_PRESENCE
 123 /**
 124  * When operating in @ref OCServer or @ref OCClientServer mode, this API will start sending out
 125  * presence notifications to clients via multicast. Once this API has been called with a success,
 126  * clients may query for this server's presence and this server's stack will respond via multicast.
 127  *
 128  * Server can call this function when it comes online for the first time, or when it comes back
 129  * online from offline mode, or when it re enters network.
 130  *
 131  * @param ttl Time To Live in seconds.
 132  * Note: If ttl is '0', then the default stack value will be used (60 Seconds).
 133  *
 134  *       If ttl is greater than OC_MAX_PRESENCE_TTL_SECONDS, then the ttl will be set to
 135  *       OC_MAX_PRESENCE_TTL_SECONDS.
 136  *
 137  * @return ::OC_STACK_OK on success, some other value upon failure.
 138  */
 139 OCStackResult OCStartPresence(const uint32_t ttl);
 140
 141 /**
 142  * When operating in @ref OCServer or @ref OCClientServer mode, this API will stop sending out
 143  * presence notifications to clients via multicast. Once this API has been called with a success,
 144  * this server's stack will not respond to clients querying for this server's presence.
 145  *
 146  * Server can call this function when it is terminating, going offline, or when going
 147  * away from network.
 148  *
 149  * @return ::OC_STACK_OK on success, some other value upon failure.
 150  */
 151
 152 OCStackResult OCStopPresence();
 153 #endif
 154
 155
 156 /**
 157  * Set default device entity handler.
 158  *
 159  * @param entityHandler Entity handler function that is called by ocstack to handle requests for
 160  *                      any undefined resources or default actions.
 161  *                      If NULL is passed it removes the device default entity handler.
 162  *
 163  * @return ::OC_STACK_OK on success, some other value upon failure.
 164  */
 165 OCStackResult OCSetDefaultDeviceEntityHandler(OCDeviceEntityHandler entityHandler);
 166
 167 /**
 168  * Set device information.
 169  *
 170  * @param deviceInfo - Structure passed by the server application containing
 171  *                     the device information.
 172  *
 173  *
 174  * @return
 175  *     OC_STACK_OK              - no errors
 176  *     OC_STACK_INVALID_PARAM   - invalid paramerter
 177  *     OC_STACK_ERROR           - stack process error
 178  */
 179 OCStackResult OCSetDeviceInfo(OCDeviceInfo deviceInfo);
 180
 181 /**
 182  * Set platform information.
 183  *
 184  * @param platformInfo - Structure passed by the server application containing
 185  *                     the platform information.
 186  *
 187  *
 188  * @return
 189  *     OC_STACK_OK              - no errors
 190  *     OC_STACK_INVALID_PARAM   - invalid paramerter
 191  *     OC_STACK_ERROR           - stack process error
 192  */
 193 OCStackResult OCSetPlatformInfo(OCPlatformInfo platformInfo);
 194
 195 /**
 196  * Create a resource.
 197  *
 198  * @param handle Pointer to handle to newly created resource.  Set by ocstack and
 199  *               used to refer to resource.
 200  * @param resourceTypeName Name of resource type.  Example: "core.led".
 201  * @param resourceInterfaceName Name of resource interface.  Example: "core.rw".
 202  * @param uri URI of the resource.  Example:  "/a/led".
 203  * @param entityHandler Entity handler function that is called by ocstack to handle requests, etc.
 204  *                      NULL for default entity handler.
 205  * @param resourceProperties Properties supported by resource.
 206  *                           Example: ::OC_DISCOVERABLE|::OC_OBSERVABLE.
 207  *
 208  * @return ::OC_STACK_OK on success, some other value upon failure.
 209  */
 210 OCStackResult OCCreateResource(OCResourceHandle *handle,
 211                                const char *resourceTypeName,
 212                                const char *resourceInterfaceName,
 213                                const char *uri,
 214                                OCEntityHandler entityHandler,
 215                                uint8_t resourceProperties);
 216
 217 /**
 218  * Create a resource. with host ip address for remote resource.
 219  *
 220  * @param handle Pointer to handle to newly created resource.  Set by ocstack.
 221  *               Used to refer to resource.
 222  * @param resourceTypeName Name of resource type.  Example: "core.led".
 223  * @param resourceInterfaceName Name of resource interface.  Example: "core.rw".
 224  * @param host HOST address of the remote resource.  Example:  "coap://xxx.xxx.xxx.xxx:xxxxx".
 225  * @param uri URI of the resource.  Example:  "/a/led".
 226  * @param entityHandler Entity handler function that is called by ocstack to handle requests, etc.
 227  *                      NULL for default entity handler.
 228  * @param resourceProperties Properties supported by resource.
 229  *                           Example: ::OC_DISCOVERABLE|::OC_OBSERVABLE
 230  *
 231  * @return ::OC_STACK_OK on success, some other value upon failure.
 232  */
 233 OCStackResult OCCreateResourceWithHost(OCResourceHandle *handle,
 234                                const char *resourceTypeName,
 235                                const char *resourceInterfaceName,
 236                                const char *host,
 237                                const char *uri,
 238                                OCEntityHandler entityHandler,
 239                                uint8_t resourceProperties);
 240
 241 /**
 242  * Add a resource to a collection resource.
 243  *
 244  * @param collectionHandle Handle to the collection resource.
 245  * @param resourceHandle Handle to resource to be added to the collection resource.
 246  *
 247  * @return ::OC_STACK_OK on success, some other value upon failure.
 248  */
 249 OCStackResult OCBindResource(OCResourceHandle collectionHandle, OCResourceHandle resourceHandle);
 250
 251 /**
 252  * Remove a resource from a collection resource.
 253  *
 254  * @param collectionHandle Handle to the collection resource.
 255  * @param resourceHandle Handle to resource to be removed from the collection resource.
 256  *
 257  * @return ::OC_STACK_OK on success, some other value upon failure.
 258  */
 259 OCStackResult OCUnBindResource(OCResourceHandle collectionHandle, OCResourceHandle resourceHandle);
 260
 261 /**
 262  * Bind a resourcetype to a resource.
 263  *
 264  * @param handle Handle to the resource.
 265  * @param resourceTypeName Name of resource type.  Example: "core.led".
 266  *
 267  * @return ::OC_STACK_OK on success, some other value upon failure.
 268  */
 269 OCStackResult OCBindResourceTypeToResource(OCResourceHandle handle,
 270                                            const char *resourceTypeName);
 271 /**
 272  * Bind a resource interface to a resource.
 273  *
 274  * @param handle Handle to the resource.
 275  * @param resourceInterfaceName Name of resource interface.  Example: "core.rw".
 276  *
 277  * @return ::OC_STACK_OK on success, some other value upon failure.
 278  */
 279 OCStackResult OCBindResourceInterfaceToResource(OCResourceHandle handle,
 280                                                 const char *resourceInterfaceName);
 281
 282 /**
 283  * Bind an entity handler to the resource.
 284  *
 285  * @param handle Handle to the resource that the contained resource is to be bound.
 286  * @param entityHandler Entity handler function that is called by ocstack to handle requests, etc.
 287  * @return ::OC_STACK_OK on success, some other value upon failure.
 288  */
 289 OCStackResult OCBindResourceHandler(OCResourceHandle handle, OCEntityHandler entityHandler);
 290
 291 /**
 292  * Get the number of resources that have been created in the stack.
 293  *
 294  * @param numResources Pointer to count variable.
 295  *
 296  * @return ::OC_STACK_OK on success, some other value upon failure.
 297  */
 298 OCStackResult OCGetNumberOfResources(uint8_t *numResources);
 299
 300 /**
 301  * Get a resource handle by index.
 302  *
 303  * @param index Index of resource, 0 to Count - 1.
 304  *
 305  * @return Found resource handle or NULL if not found.
 306  */
 307 OCResourceHandle OCGetResourceHandle(uint8_t index);
 308
 309 /**
 310  * Delete resource specified by handle.  Deletes resource and all resourcetype and resourceinterface
 311  * linked lists.
 312  *
 313  * Note: OCDeleteResource() performs operations similar to OCNotifyAllObservers() to notify all
 314  * client observers that "this" resource is being deleted.
 315  *
 316  * @param handle Handle of resource to be deleted.
 317  *
 318  * @return ::OC_STACK_OK on success, some other value upon failure.
 319  */
 320 OCStackResult OCDeleteResource(OCResourceHandle handle);
 321
 322 /**
 323  * Get the URI of the resource specified by handle.
 324  *
 325  * @param handle Handle of resource.
 326  * @return URI string if resource found or NULL if not found.
 327  */
 328 const char *OCGetResourceUri(OCResourceHandle handle);
 329
 330 /**
 331  * Get the properties of the resource specified by handle.
 332  * NOTE: that after a resource is created, the OC_ACTIVE property is set
 333  * for the resource by the stack.
 334  *
 335  * @param handle Handle of resource.
 336  * @return OCResourceProperty Bitmask or -1 if resource is not found.
 337  */
 338 OCResourceProperty OCGetResourceProperties(OCResourceHandle handle);
 339
 340 /**
 341  * Get the number of resource types of the resource.
 342  *
 343  * @param handle Handle of resource.
 344  * @param numResourceTypes Pointer to count variable.
 345  *
 346  * @return ::OC_STACK_OK on success, some other value upon failure.
 347  */
 348 OCStackResult OCGetNumberOfResourceTypes(OCResourceHandle handle, uint8_t *numResourceTypes);
 349
 350 /**
 351  * Get name of resource type of the resource.
 352  *
 353  * @param handle Handle of resource.
 354  * @param index Index of resource, 0 to Count - 1.
 355  *
 356  * @return Resource type name if resource found or NULL if resource not found.
 357  */
 358 const char *OCGetResourceTypeName(OCResourceHandle handle, uint8_t index);
 359
 360 /**
 361  * Get the number of resource interfaces of the resource.
 362  *
 363  * @param handle Handle of resource.
 364  * @param numResourceInterfaces Pointer to count variable.
 365  *
 366  * @return ::OC_STACK_OK on success, some other value upon failure.
 367  */
 368 OCStackResult OCGetNumberOfResourceInterfaces(OCResourceHandle handle,
 369         uint8_t *numResourceInterfaces);
 370
 371 /**
 372  * Get name of resource interface of the resource.
 373  *
 374  * @param handle Handle of resource.
 375  * @param index Index of resource, 0 to Count - 1.
 376  *
 377  * @return Resource interface name if resource found or NULL if resource not found.
 378  */
 379 const char *OCGetResourceInterfaceName(OCResourceHandle handle, uint8_t index);
 380
 381 /**
 382  * Get methods of resource interface of the resource.
 383  *
 384  * @param handle Handle of resource.
 385  * @param index Index of resource, 0 to Count - 1.
 386  *
 387  * @return Allowed methods if resource found or NULL if resource not found.
 388  */
 389 uint8_t OCGetResourceInterfaceAllowedMethods(OCResourceHandle handle, uint8_t index);
 390
 391 /**
 392  * Get resource handle from the collection resource by index.
 393  *
 394  * @param collectionHandle Handle of collection resource.
 395  * @param index Index of contained resource, 0 to Count - 1.
 396  *
 397  * @return Handle to contained resource if resource found or NULL if resource not found.
 398  */
 399 OCResourceHandle OCGetResourceHandleFromCollection(OCResourceHandle collectionHandle,
 400         uint8_t index);
 401
 402 /**
 403  * Get the entity handler for a resource.
 404  *
 405  * @param handle Handle of resource.
 406  *
 407  * @return Entity handler if resource found or NULL resource not found.
 408  */
 409 OCEntityHandler OCGetResourceHandler(OCResourceHandle handle);
 410
 411 /**
 412  * Notify all registered observers that the resource representation has
 413  * changed. If observation includes a query the client is notified only
 414  * if the query is valid after the resource representation has changed.
 415  *
 416  * @param handle Handle of resource.
 417  * @param qos    Desired quality of service for the observation notifications.
 418  *
 419  * @return ::OC_STACK_OK on success, some other value upon failure.
 420  */
 421 OCStackResult OCNotifyAllObservers(OCResourceHandle handle, OCQualityOfService qos);
 422
 423 /**
 424  * Notify specific observers with updated value of representation.
 425  * Before this API is invoked by entity handler it has finished processing
 426  * queries for the associated observers.
 427  *
 428  * @param handle Handle of resource.
 429  * @param obsIdList List of observation ids that need to be notified.
 430  * @param numberOfIds Number of observation ids included in obsIdList.
 431  * @param notificationJSONPayload JSON encoded payload to send in notification.
 432  * @param qos Desired quality of service of the observation notifications.
 433  * NOTE: The memory for obsIdList and notificationJSONPayload is managed by the
 434  * entity invoking the API. The maximum size of the notification is 1015 bytes
 435  * for non-Arduino platforms. For Arduino the maximum size is 247 bytes.
 436  *
 437  * @return ::OC_STACK_OK on success, some other value upon failure.
 438  */
 439 OCStackResult
 440 OCNotifyListOfObservers (OCResourceHandle handle,
 441                             OCObservationId  *obsIdList,
 442                             uint8_t          numberOfIds,
 443                             const char    *notificationJSONPayload,
 444                             OCQualityOfService qos);
 445
 446
 447 /**
 448  * Send a response to a request.
 449  * The response can be a normal, slow, or block (i.e. a response that
 450  * is too large to be sent in a single PDU and must span multiple transmissions).
 451  *
 452  * @param response Pointer to structure that contains response parameters.
 453  *
 454  * @return ::OC_STACK_OK on success, some other value upon failure.
 455  */
 456 OCStackResult OCDoResponse(OCEntityHandlerResponse *response);
 457
 458
 459 //Utility methods
 460
 461 /**
 462  * This method is used to retrieved the IPv4 address from OCDev address
 463  * data structure.
 464  *
 465  * @param ipAddr OCDevAddr address.
 466  * @param a first byte of IPv4 address.
 467  * @param b second byte of IPv4 address.
 468  * @param c third byte of IPv4 address.
 469  * @param d fourth byte of IPv4 address.
 470  * @return ::OC_STACK_OK on success, some other value upon failure.
 471  */
 472 int32_t OCDevAddrToIPv4Addr(OCDevAddr *ipAddr, uint8_t *a, uint8_t *b,
 473             uint8_t *c, uint8_t *d );
 474
 475 /**
 476  * This method is used to retrieve the port number from OCDev address
 477  * data structure.
 478  *
 479  * @param ipAddr OCDevAddr address.
 480  * @param port Port number.
 481  * @return ::OC_STACK_OK on success, some other value upon failure.
 482  */
 483 int32_t OCDevAddrToPort(OCDevAddr *ipAddr, uint16_t *port);
 484
 485 #ifdef __cplusplus
 486 }
 487 #endif // __cplusplus
 488
 489 #endif /* OCSTACK_H_ */
 490
 491