csdk/stack/include/ocstack.h

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