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