csdk/stack/include/ocstack.h

   1 //******************************************************************
   2 //
   3 // Copyright 2014 Intel Corporation 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 <ocsocket.h>
  25 #include <logger.h>
  26 #include <ocrandom.h>
  27
  28 #ifdef __cplusplus
  29 extern "C" {
  30 #endif // __cplusplus
  31
  32 //-----------------------------------------------------------------------------
  33 // Defines
  34 //-----------------------------------------------------------------------------
  35
  36 //May want to refactor this in upcoming sprints. Don't want to expose to application layer that lower level stack is using CoAP.
  37 #define OC_WELL_KNOWN_QUERY                  PCF("coap://224.0.1.187:5683/oc/core")
  38 #define OC_EXPLICIT_DEVICE_DISCOVERY_URI     PCF("coap://224.0.1.187:5683/oc/core?rt=core.led")
  39 #define OC_MULTICAST_PREFIX                  PCF("coap://224.0.1.187:5683")
  40
  41 #define USE_RANDOM_PORT (0)
  42 #define MAX_RESPONSE_LENGTH (128)
  43 #define MAX_REQUEST_LENGTH (128)
  44 #define MAX_URI_LENGTH (64)
  45 #define MAX_QUERY_LENGTH (64)
  46 #define MAX_CONTAINED_RESOURCES  (5)
  47
  48 //-----------------------------------------------------------------------------
  49 // Typedefs
  50 //-----------------------------------------------------------------------------
  51
  52 /**
  53  * OC Virtual resources supported by every OC device
  54  */
  55 typedef enum {
  56     OC_WELL_KNOWN_URI= 0,    // "/oc/core"
  57     OC_DEVICE_URI,           // "/oc/core/d"
  58     OC_RESOURCE_TYPES_URI,   // "/oc/core/d/type"
  59     OC_MAX_RESOURCES         // Max items in the list
  60 } OCVirtualResources;
  61
  62 /**
  63  * Standard RESTful HTTP Methods
  64  */
  65 typedef enum {
  66     OC_REST_NOMETHOD = 0,
  67     OC_REST_GET      = (1 << 0),      // Read
  68     OC_REST_PUT      = (1 << 1),      // Write
  69     OC_REST_POST     = (1 << 2),      // Update
  70     OC_REST_DELETE   = (1 << 3),      // Delete
  71     OC_REST_OBSERVE  = (1 << 4),      // Register observe request for most up date notifications ONLY.
  72     OC_REST_OBSERVE_ALL  = (1 << 5)   // Register observe request for all notifications, including stale notifications.
  73 } OCMethod;
  74
  75 /**
  76  * Host Mode of Operation
  77  */
  78 typedef enum {
  79     OC_CLIENT = 0,
  80     OC_SERVER,
  81     OC_CLIENT_SERVER
  82 } OCMode;
  83
  84 /**
  85  * Quality of Service
  86  */
  87 typedef enum {
  88     OC_NON_CONFIRMABLE = 0,
  89     OC_CONFIRMABLE
  90 } OCQualityOfService;
  91
  92 /**
  93  * Resource Properties
  94  */
  95 typedef enum {
  96     OC_ACTIVE       = (1 << 0),  // set == initialized; unset == deleted
  97     OC_DISCOVERABLE = (1 << 1),  // Discovery of this resource allowed
  98     OC_OBSERVABLE   = (1 << 2),  // Observe allowed
  99     OC_SLOW         = (1 << 3)   // Expect delay in processing requests. Send ACK to request and send response later
 100 } OCResourceProperty;
 101
 102 /**
 103  * Declares Stack Results & Errors
 104  */
 105 typedef enum {
 106     OC_STACK_OK = 0,
 107     OC_STACK_INVALID_URI,
 108     OC_STACK_INVALID_QUERY,
 109     OC_STACK_INVALID_IP,
 110     OC_STACK_INVALID_PORT,
 111     OC_STACK_INVALID_CALLBACK,
 112     OC_STACK_INVALID_METHOD,
 113     OC_STACK_INVALID_PARAM,
 114     OC_STACK_INVALID_OBSERVE_PARAM,
 115     OC_STACK_NO_MEMORY,
 116     OC_STACK_COMM_ERROR,
 117     OC_STACK_NOTIMPL,
 118     OC_STACK_NO_RESOURCE, /* resource not found*/
 119     OC_STACK_RESOURCE_ERROR, /*ex: not supported method or interface*/
 120     OC_STACK_SLOW_RESOURCE,
 121     OC_STACK_NO_OBSERVERS, /* resource has no registered observers */
 122     OC_STACK_ERROR
 123 } OCStackResult;
 124
 125 /**
 126  * Handle to an @ref OCDoResource invocation.
 127  */
 128 typedef void * OCDoHandle;
 129
 130 /**
 131  * Handle to an OCResource object owned by the OCStack.
 132  */
 133 typedef void * OCResourceHandle;
 134
 135 /**
 136  * Incoming requests handled by the server. Requests are passed in as a parameter to the @ref OCEntityHandler callback API.
 137  * @brief The @ref OCEntityHandler callback API must be implemented in the application in order to receive these requests.
 138  */
 139 typedef struct {
 140     // Associated resource
 141     OCResourceHandle resource;
 142     // resource query send by client
 143     unsigned char * query;
 144     // the REST method retrieved from received request PDU
 145     OCMethod method;
 146     // reqJSON is retrieved from the payload of the received request PDU
 147     unsigned const char * reqJSONPayload;
 148     // resJSON is allocated in the stack and will be used by entity handler to fill in its response
 149     unsigned char * resJSONPayload;
 150     // Length of maximum allowed response
 151     uint16_t resJSONPayloadLen;
 152 }OCEntityHandlerRequest;
 153
 154 /**
 155  * Response from queries to remote servers. Queries are made by calling the @ref OCDoResource API.
 156  */
 157 typedef struct {
 158     // the is the result of our stack, OCStackResult should contain coap/other error codes;
 159     OCStackResult result;
 160     // Address of remote server
 161     OCDevAddr * addr;
 162     // If associated with observe, this will represent the sequence of notifications from server.
 163     uint8_t sequenceNumber;
 164     // resJSONPayload is retrieved from the payload of the received request PDU
 165     unsigned  const char * resJSONPayload;
 166 }OCClientResponse;
 167
 168 typedef enum {
 169     OC_INIT_FLAG    = (1 << 0),
 170     OC_REQUEST_FLAG = (1 << 1),
 171     OC_OBSERVE_FLAG = (1 << 2)
 172 } OCEntityHandlerFlag; //entity_handler_flag_t ;
 173
 174 // possible returned values from client application
 175 typedef enum {
 176     OC_STACK_DELETE_TRANSACTION = 0,
 177     OC_STACK_KEEP_TRANSACTION
 178 } OCStackApplicationResult;
 179
 180 //-----------------------------------------------------------------------------
 181 // Callback function definitions
 182 //-----------------------------------------------------------------------------
 183
 184 /**
 185  * Client applications implement this callback to consume responses received from Servers.
 186  */
 187 typedef OCStackApplicationResult (* OCClientResponseHandler)(void *context, OCClientResponse * clientResponse);
 188
 189
 190 /*
 191  * This info is passed from application to OC Stack when initiating a request to Server
 192  */
 193 typedef struct {
 194     void *context;
 195     OCClientResponseHandler cb;
 196 } OCCallbackData;
 197
 198 /**
 199  * Application server implementations must implement this callback to consume requests OTA.
 200  * TODO: Need a clear explanation that the Entity handler callback needs to fill in the data inside the OCEntityHandlerRequest and then simply return from the callback.
 201  */
 202 typedef OCStackResult (*OCEntityHandler) (OCEntityHandlerFlag flag, OCEntityHandlerRequest * entityHandlerRequest);
 203
 204
 205 //-----------------------------------------------------------------------------
 206 // Function prototypes
 207 //-----------------------------------------------------------------------------
 208
 209 /**
 210  * Initialize the OC Stack.  Must be called prior to starting the stack.
 211  *
 212  * @param ipAddr
 213  *     IP Address of host device
 214  * @param port
 215  *     Port of host device
 216  * @param mode
 217  *     Host device is client, server, or client-server
 218  *
 219  * @return
 220  *     OC_STACK_OK    - no errors
 221  *     OC_STACK_ERROR - stack init error
 222  */
 223 OCStackResult OCInit(const char *ipAddr, uint16_t port, OCMode mode);
 224
 225 /**
 226  * Stop the OC stack.  Use for a controlled shutdown.
 227  * @return
 228  *     OC_STACK_OK    - no errors
 229  *     OC_STACK_ERROR - stack not initialized
 230  */
 231 OCStackResult OCStop();
 232
 233 /**
 234  * Called in main loop of OC client or server.  Allows low-level processing of
 235  * stack services.
 236  *
 237  * @return
 238  *     OC_STACK_OK    - no errors
 239  *     OC_STACK_ERROR - stack process error
 240  */
 241 OCStackResult OCProcess();
 242
 243 /**
 244  * Discover or Perform requests on a specified resource (specified by that Resource's respective URI).
 245  *
 246  * @param handle             - @ref OCDoHandle to refer to the request sent out on behalf of calling this API.
 247  * @param method             - @ref OCMethod to perform on the resource
 248  * @param requiredUri        - URI of the resource to interact with
 249  * @param referenceUri       - URI of the reference resource
 250  * @param request            - JSON encoded request
 251  * @param qos                - quality of service
 252  * @param clientApplicationCB- asynchronous callback function that is invoked
 253  *                             by the stack when discovery or resource interaction is complete
 254  *
 255  * @return
 256  *     OC_STACK_OK               - no errors
 257  *     OC_STACK_INVALID_CALLBACK - invalid callback function pointer
 258  *     OC_STACK_INVALID_METHOD   - invalid resource method
 259  *     OC_STACK_INVALID_URI      - invalid required or reference URI
 260  */
 261 OCStackResult OCDoResource(OCDoHandle *handle, OCMethod method, const char  *requiredUri, const char  *referenceUri,
 262                 const char *request, OCQualityOfService qos, OCCallbackData *cbData);
 263
 264 /**
 265  * Cancel a request associated with a specific @ref OCDoResource invocation.
 266  *
 267  * @param handle - Used to identify a specific OCDoResource invocation.
 268  *
 269  * @return
 270  *     OC_STACK_OK               - No errors; Success
 271  *     OC_STACK_INVALID_PARAM    - The handle provided is invalid.
 272  */
 273 OCStackResult OCCancel(OCDoHandle handle);
 274
 275 /**
 276  * Create a resource.
 277  *
 278  * @param handle - pointer to handle to newly created resource.  Set by ocstack.  Used to refer to resource
 279  * @param resourceTypeName - name of resource type.  Example: "core.led"
 280  * @param resourceAttributeRepresentation - attribute representation.  list of attributes:type, with each pair
 281  *                                          separated by semicolons.  Example:  "state:oc.bt.b;power:oc.bt.i"
 282  * @param resourceInterfaceName - name of resource interface.  Example: "core.rw"
 283  * @param allowedMethods - methods permitted on interface.  Example: OC_REST_GET|OC_REST_PUT
 284  * @param uri - URI of the resource.  Example:  "/a/led"
 285  * @param entityHandler - entity handler function that is called by ocstack to handle requests, etc
 286  * @param resourceProperties - properties supported by resource.  Example: OC_DISCOVERABLE|OC_OBSERVABLE
 287  *
 288  * @return
 289  *     OC_STACK_OK    - no errors
 290  *     OC_STACK_ERROR - stack process error
 291  */
 292 OCStackResult OCCreateResource(OCResourceHandle *handle,
 293                                const char *resourceTypeName,
 294                                const char *resourceAttributeRepresentation,
 295                                const char *resourceInterfaceName,
 296                                uint8_t allowedMethods,
 297                                const char *uri,
 298                                OCEntityHandler entityHandler,
 299                                uint8_t resourceProperties);
 300
 301 /**
 302  * Add a resource to a container resource.
 303  *
 304  * @param containerHandle - handle to the container resource
 305  * @param addedResourceHandle - handle to resource to be added to the container resource
 306  *
 307  * @return
 308  *     OC_STACK_OK    - no errors
 309  *     OC_STACK_ERROR - stack process error
 310  */
 311 OCStackResult OCBindContainedResourceToResource(OCResourceHandle containerHandle, OCResourceHandle addedResourceHandle);
 312
 313 /**
 314  * Bind a resourcetype to a resource.
 315  *
 316  * @param handle - handle to the container resource
 317  * @param resourceTypeName - name of resource type.  Example: "core.led"
 318  * @param resourceAttributeRepresentation - attribute representation.  list of attributes:type, with each pair
 319  *                                          separated by semicolons.  Example:  "state:oc.bt.b;power:oc.bt.i"
 320  *
 321  * @return
 322  *     OC_STACK_OK    - no errors
 323  *     OC_STACK_ERROR - stack process error
 324  */
 325 OCStackResult OCBindResourceTypeToResource(OCResourceHandle handle,
 326                                            const char *resourceTypeName,
 327                                            const char *resourceAttributeRepresentation);
 328 /**
 329  * Bind a resource interface to a resource.
 330  *
 331  * @param handle - handle to the container resource
 332  * @param resourceInterfaceName - name of resource interface.  Example: "core.rw"
 333  * @param allowedMethods - methods permitted on interface.  Example: OC_REST_GET|OC_REST_PUT
 334  *
 335  * @return
 336  *     OC_STACK_OK    - no errors
 337  *     OC_STACK_ERROR - stack process error
 338  */
 339 OCStackResult OCBindResourceInterfaceToResource(OCResourceHandle handle,
 340                                                 const char *resourceInterfaceName,
 341                                                 uint8_t allowedMethods);
 342
 343 /**
 344  * Bind an entity handler to the resource.
 345  *
 346  * @param handle - handle to the resource that the contained resource is to be bound
 347  * @param entityHandler - entity handler function that is called by ocstack to handle requests, etc
 348  * @return
 349  *     OC_STACK_OK    - no errors
 350  *     OC_STACK_ERROR - stack process error
 351  */
 352 OCStackResult OCBindResourceHandler(OCResourceHandle handle, OCEntityHandler entityHandler);
 353
 354 /**
 355  * Get the number of resources that have been created in the stack.
 356  *
 357  * @param numResources - pointer to count variable
 358  *
 359  * @return
 360  *     OC_STACK_OK    - no errors
 361  *     OC_STACK_ERROR - stack process error
 362
 363  */
 364 OCStackResult OCGetNumberOfResources(uint8_t *numResources);
 365
 366 /**
 367  * Get a resource handle by index.
 368  *
 369  * @param index - index of resource, 0 to Count - 1
 370  *
 371  * @return
 372  *    Resource handle - if found
 373  *    NULL - if not found
 374  */
 375 OCResourceHandle OCGetResourceHandle(uint8_t index);
 376
 377 /**
 378  * Delete resource specified by handle.  Deletes resource and all resourcetype and resourceinterface
 379  * linked lists.
 380  *
 381  * @param handle - handle of resource to be deleted
 382  *
 383  * @return
 384  *     OC_STACK_OK    - no errors
 385  *     OC_STACK_ERROR - stack process error
 386  */
 387 OCStackResult OCDeleteResource(OCResourceHandle handle);
 388
 389 /**
 390  * Get the URI of the resource specified by handle.
 391  *
 392  * @param handle - handle of resource
 393  * @return
 394  *    URI string - if resource found
 395  *    NULL - resource not found
 396  */
 397 const char *OCGetResourceUri(OCResourceHandle handle);
 398
 399 /**
 400  * Get the properties of the resource specified by handle.
 401  * NOTE: that after a resource is created, the OC_ACTIVE property is set
 402  * for the resource by the stack.
 403  *
 404  * @param handle - handle of resource
 405  * @return
 406  *    property bitmap - if resource found
 407  *    NULL - resource not found
 408  */
 409 uint8_t OCGetResourceProperties(OCResourceHandle handle);
 410
 411 /**
 412  * Get the number of resource types of the resource.
 413  *
 414  * @param handle - handle of resource
 415  * @param numResourceTypes - pointer to count variable
 416  *
 417  * @return
 418  *     OC_STACK_OK    - no errors
 419  *     OC_STACK_ERROR - stack process error
 420  */
 421 OCStackResult OCGetNumberOfResourceTypes(OCResourceHandle handle, uint8_t *numResourceTypes);
 422
 423 /**
 424  * Get name of resource type of the resource.
 425  *
 426  * @param handle - handle of resource
 427  * @param index - index of resource, 0 to Count - 1
 428  *
 429  * @return
 430  *    resource type name - if resource found
 431  *    NULL - resource not found
 432  */
 433 const char *OCGetResourceTypeName(OCResourceHandle handle, uint8_t index);
 434
 435 /**
 436  * Get attributes of resource type of the resource.
 437  *
 438  * @param handle - handle of resource
 439  * @param index - index of resource, 0 to Count - 1
 440  *
 441  * @return
 442  *    resource type attributes - if resource found
 443  *    NULL - resource not found
 444  */
 445 const char *OCGetResourceAttributeRepresentation(OCResourceHandle handle, uint8_t index);
 446
 447 /**
 448  * Get the number of resource interfaces of the resource.
 449  *
 450  * @param handle - handle of resource
 451  * @param numResources - pointer to count variable
 452  *
 453  * @return
 454  *     OC_STACK_OK    - no errors
 455  *     OC_STACK_ERROR - stack process error
 456
 457  */
 458 OCStackResult OCGetNumberOfResourceInterfaces(OCResourceHandle handle, uint8_t *numResourceInterfaces);
 459
 460 /**
 461  * Get name of resource interface of the resource.
 462  *
 463  * @param handle - handle of resource
 464  * @param index - index of resource, 0 to Count - 1
 465  *
 466  * @return
 467  *    resource interface name - if resource found
 468  *    NULL - resource not found
 469  */
 470 const char *OCGetResourceInterfaceName(OCResourceHandle handle, uint8_t index);
 471
 472 /**
 473  * Get methods of resource interface of the resource.
 474  *
 475  * @param handle - handle of resource
 476  * @param index - index of resource, 0 to Count - 1
 477  *
 478  * @return
 479  *    allowed methods - if resource found
 480  *    NULL - resource not found
 481  */
 482 uint8_t OCGetResourceInterfaceAllowedMethods(OCResourceHandle handle, uint8_t index);
 483
 484 /**
 485  * Get name of resource interface of the resource.
 486  *
 487  * @param containerHandle - handle of container resource
 488  * @param index - index of contained resource, 0 to Count - 1
 489  *
 490  * @return
 491  *    handle to contained resource - if resource found
 492  *    NULL - resource not found
 493  */
 494 OCResourceHandle OCGetContainedResourceHandle(OCResourceHandle containerHandle, uint8_t index);
 495
 496 /**
 497  * Get the entity handler for a resource.
 498  *
 499  * @param handle - handle of resource
 500  *
 501  * @return
 502  *    entity handler - if resource found
 503  *    NULL - resource not found
 504  */
 505 OCEntityHandler OCGetResourceHandler(OCResourceHandle handle);
 506
 507 /**
 508  * Notify observers that an observed value has changed.
 509  *
 510  *   **NOTE: This API has NOT been finalized!!!**
 511  *
 512  * @param handle - handle of resource
 513  *
 514  * @return
 515  *     OC_STACK_OK    - no errors
 516  *     OC_STACK_ERROR - stack not initialized
 517  */
 518 OCStackResult OCNotifyObservers(OCResourceHandle handle);
 519
 520 #ifdef __cplusplus
 521 }
 522 #endif // __cplusplus
 523
 524 #endif /* OCSTACK_H_ */