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 (256)
  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     uint32_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, OCDoHandle handle, 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 resourceInterfaceName - name of resource interface.  Example: "core.rw"
 281  * @param uri - URI of the resource.  Example:  "/a/led"
 282  * @param entityHandler - entity handler function that is called by ocstack to handle requests, etc
 283  *                        NULL for default entity handler
 284  * @param resourceProperties - properties supported by resource.  Example: OC_DISCOVERABLE|OC_OBSERVABLE
 285  *
 286  * @return
 287  *     OC_STACK_OK    - no errors
 288  *     OC_STACK_ERROR - stack process error
 289  */
 290 OCStackResult OCCreateResource(OCResourceHandle *handle,
 291                                const char *resourceTypeName,
 292                                const char *resourceInterfaceName,
 293                                const char *uri,
 294                                OCEntityHandler entityHandler,
 295                                uint8_t resourceProperties);
 296
 297 /**
 298  * Add a resource to a collection resource.
 299  *
 300  * @param collectionHandle - handle to the collection resource
 301  * @param resourceHandle - handle to resource to be added to the collection resource
 302  *
 303  * @return
 304  *     OC_STACK_OK    - no errors
 305  *     OC_STACK_ERROR - stack process error
 306  *     OC_STACK_INVALID_PARAM - invalid collectionhandle
 307  */
 308 OCStackResult OCBindResource(OCResourceHandle collectionHandle, OCResourceHandle resourceHandle);
 309
 310 /**
 311  * Remove a resource from a collection resource.
 312  *
 313  * @param collectionHandle - handle to the collection resource
 314  * @param resourceHandle - handle to resource to be removed from the collection resource
 315  *
 316  * @return
 317  *     OC_STACK_OK    - no errors
 318  *     OC_STACK_ERROR - stack process error
 319  *     OC_STACK_INVALID_PARAM - invalid collectionhandle
 320  */
 321 OCStackResult OCUnBindResource(OCResourceHandle collectionHandle, OCResourceHandle resourceHandle);
 322
 323 /**
 324  * Bind a resourcetype to a resource.
 325  *
 326  * @param handle - handle to the resource
 327  * @param resourceTypeName - name of resource type.  Example: "core.led"
 328  *
 329  * @return
 330  *     OC_STACK_OK    - no errors
 331  *     OC_STACK_ERROR - stack process error
 332  */
 333 OCStackResult OCBindResourceTypeToResource(OCResourceHandle handle,
 334                                            const char *resourceTypeName);
 335 /**
 336  * Bind a resource interface to a resource.
 337  *
 338  * @param handle - handle to the resource
 339  * @param resourceInterfaceName - name of resource interface.  Example: "core.rw"
 340  *
 341  * @return
 342  *     OC_STACK_OK    - no errors
 343  *     OC_STACK_ERROR - stack process error
 344  */
 345 OCStackResult OCBindResourceInterfaceToResource(OCResourceHandle handle,
 346                                                 const char *resourceInterfaceName);
 347
 348 /**
 349  * Bind an entity handler to the resource.
 350  *
 351  * @param handle - handle to the resource that the contained resource is to be bound
 352  * @param entityHandler - entity handler function that is called by ocstack to handle requests, etc
 353  * @return
 354  *     OC_STACK_OK    - no errors
 355  *     OC_STACK_ERROR - stack process error
 356  */
 357 OCStackResult OCBindResourceHandler(OCResourceHandle handle, OCEntityHandler entityHandler);
 358
 359 /**
 360  * Get the number of resources that have been created in the stack.
 361  *
 362  * @param numResources - pointer to count variable
 363  *
 364  * @return
 365  *     OC_STACK_OK    - no errors
 366  *     OC_STACK_ERROR - stack process error
 367
 368  */
 369 OCStackResult OCGetNumberOfResources(uint8_t *numResources);
 370
 371 /**
 372  * Get a resource handle by index.
 373  *
 374  * @param index - index of resource, 0 to Count - 1
 375  *
 376  * @return
 377  *    Resource handle - if found
 378  *    NULL - if not found
 379  */
 380 OCResourceHandle OCGetResourceHandle(uint8_t index);
 381
 382 /**
 383  * Delete resource specified by handle.  Deletes resource and all resourcetype and resourceinterface
 384  * linked lists.
 385  *
 386  * @param handle - handle of resource to be deleted
 387  *
 388  * @return
 389  *     OC_STACK_OK    - no errors
 390  *     OC_STACK_ERROR - stack process error
 391  */
 392 OCStackResult OCDeleteResource(OCResourceHandle handle);
 393
 394 /**
 395  * Get the URI of the resource specified by handle.
 396  *
 397  * @param handle - handle of resource
 398  * @return
 399  *    URI string - if resource found
 400  *    NULL - resource not found
 401  */
 402 const char *OCGetResourceUri(OCResourceHandle handle);
 403
 404 /**
 405  * Get the properties of the resource specified by handle.
 406  * NOTE: that after a resource is created, the OC_ACTIVE property is set
 407  * for the resource by the stack.
 408  *
 409  * @param handle - handle of resource
 410  * @return
 411  *    property bitmap - if resource found
 412  *    NULL - resource not found
 413  */
 414 uint8_t OCGetResourceProperties(OCResourceHandle handle);
 415
 416 /**
 417  * Get the number of resource types of the resource.
 418  *
 419  * @param handle - handle of resource
 420  * @param numResourceTypes - pointer to count variable
 421  *
 422  * @return
 423  *     OC_STACK_OK    - no errors
 424  *     OC_STACK_ERROR - stack process error
 425  */
 426 OCStackResult OCGetNumberOfResourceTypes(OCResourceHandle handle, uint8_t *numResourceTypes);
 427
 428 /**
 429  * Get name of resource type of the resource.
 430  *
 431  * @param handle - handle of resource
 432  * @param index - index of resource, 0 to Count - 1
 433  *
 434  * @return
 435  *    resource type name - if resource found
 436  *    NULL - resource not found
 437  */
 438 const char *OCGetResourceTypeName(OCResourceHandle handle, uint8_t index);
 439
 440 /**
 441  * Get the number of resource interfaces of the resource.
 442  *
 443  * @param handle - handle of resource
 444  * @param numResources - pointer to count variable
 445  *
 446  * @return
 447  *     OC_STACK_OK    - no errors
 448  *     OC_STACK_ERROR - stack process error
 449
 450  */
 451 OCStackResult OCGetNumberOfResourceInterfaces(OCResourceHandle handle, uint8_t *numResourceInterfaces);
 452
 453 /**
 454  * Get name of resource interface of the resource.
 455  *
 456  * @param handle - handle of resource
 457  * @param index - index of resource, 0 to Count - 1
 458  *
 459  * @return
 460  *    resource interface name - if resource found
 461  *    NULL - resource not found
 462  */
 463 const char *OCGetResourceInterfaceName(OCResourceHandle handle, uint8_t index);
 464
 465 /**
 466  * Get methods of resource interface of the resource.
 467  *
 468  * @param handle - handle of resource
 469  * @param index - index of resource, 0 to Count - 1
 470  *
 471  * @return
 472  *    allowed methods - if resource found
 473  *    NULL - resource not found
 474  */
 475 uint8_t OCGetResourceInterfaceAllowedMethods(OCResourceHandle handle, uint8_t index);
 476
 477 /**
 478  * Get resource handle from the collection resource by index.
 479  *
 480  * @param collectionHandle - handle of collection resource
 481  * @param index - index of contained resource, 0 to Count - 1
 482  *
 483  * @return
 484  *    handle to contained resource - if resource found
 485  *    NULL - resource not found
 486  */
 487 OCResourceHandle OCGetResourceHandleFromCollection(OCResourceHandle collectionHandle, uint8_t index);
 488
 489 /**
 490  * Get the entity handler for a resource.
 491  *
 492  * @param handle - handle of resource
 493  *
 494  * @return
 495  *    entity handler - if resource found
 496  *    NULL - resource not found
 497  */
 498 OCEntityHandler OCGetResourceHandler(OCResourceHandle handle);
 499
 500 /**
 501  * Notify observers that an observed value has changed.
 502  *
 503  *   **NOTE: This API has NOT been finalized!!!**
 504  *
 505  * @param handle - handle of resource
 506  *
 507  * @return
 508  *     OC_STACK_OK    - no errors
 509  *     OC_STACK_ERROR - stack not initialized
 510  */
 511 OCStackResult OCNotifyObservers(OCResourceHandle handle);
 512
 513 #ifdef __cplusplus
 514 }
 515 #endif // __cplusplus
 516
 517 #endif /* OCSTACK_H_ */