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 "ocstackconfig.h"
  26
  27 #ifdef __cplusplus
  28 extern "C" {
  29 #endif // __cplusplus
  30 #define WITH_PRESENCE
  31 //-----------------------------------------------------------------------------
  32 // Defines
  33 //-----------------------------------------------------------------------------
  34
  35 //TODO: May want to refactor this in upcoming sprints.
  36 //Don't want to expose to application layer that lower level stack is using CoAP.
  37
  38 #define OC_WELL_KNOWN_QUERY                  "224.0.1.187:5683/oc/core"
  39 #define OC_EXPLICIT_DEVICE_DISCOVERY_URI     "224.0.1.187:5683/oc/core/d?rt=core.led"
  40 #define OC_MULTICAST_PREFIX                  "224.0.1.187:5683"
  41 #define OC_MULTICAST_IP                      "224.0.1.187"
  42
  43 #ifdef WITH_PRESENCE
  44 #define OC_DEFAULT_PRESENCE_TTL (60)
  45 #define OC_PRESENCE_URI                      "/oc/presence"
  46 #endif
  47
  48 //-----------------------------------------------------------------------------
  49 // Typedefs
  50 //-----------------------------------------------------------------------------
  51
  52 /** This would need to be modified for specific platforms and specific
  53  *  technologies
  54  */
  55 #define DEV_ADDR_SIZE_MAX (16)
  56
  57 /**
  58  * Data structure to encapsulate IPv4/IPv6/Contiki/lwIP device addresses
  59  *
  60 */
  61 typedef struct OCDevAddr
  62 {
  63     uint32_t     size;                    /**< length of the address stored in addr field. */
  64     uint8_t      addr[DEV_ADDR_SIZE_MAX]; /**< device address. */
  65 } OCDevAddr;
  66
  67 /**
  68  * OC Virtual resources supported by every OC device
  69  */
  70 typedef enum
  71 {
  72     OC_WELL_KNOWN_URI= 0,       // "/oc/core"
  73     OC_DEVICE_URI,              // "/oc/core/d"
  74     OC_RESOURCE_TYPES_URI,      // "/oc/core/d/type"
  75     #ifdef WITH_PRESENCE
  76     OC_PRESENCE,                // "/oc/presence"
  77     #endif
  78     OC_MAX_VIRTUAL_RESOURCES    // Max items in the list
  79 } OCVirtualResources;
  80
  81 /**
  82  * Standard RESTful HTTP Methods
  83  */
  84 typedef enum
  85 {
  86     OC_REST_NOMETHOD    = 0,
  87     OC_REST_GET         = (1 << 0),     // Read
  88     OC_REST_PUT         = (1 << 1),     // Write
  89     OC_REST_POST        = (1 << 2),     // Update
  90     OC_REST_DELETE      = (1 << 3),     // Delete
  91     // Register observe request for most up date notifications ONLY.
  92     OC_REST_OBSERVE     = (1 << 4),
  93     // Register observe request for all notifications, including stale notifications.
  94     OC_REST_OBSERVE_ALL = (1 << 5),
  95     // Deregister observation, intended for internal use
  96     OC_REST_CANCEL_OBSERVE = (1 << 6),
  97     #ifdef WITH_PRESENCE
  98     // Subscribe for all presence notifications of a particular resource.
  99     OC_REST_PRESENCE    = (1 << 7)
 100     #endif
 101 } OCMethod;
 102
 103 /**
 104  * Host Mode of Operation
 105  */
 106 typedef enum
 107 {
 108     OC_CLIENT = 0,
 109     OC_SERVER,
 110     OC_CLIENT_SERVER
 111 } OCMode;
 112
 113 /**
 114  * Quality of Service
 115  */
 116 typedef enum
 117 {
 118     OC_LOW_QOS = 0,
 119     OC_MEDIUM_QOS,
 120     OC_HIGH_QOS,
 121     OC_NA_QOS // No Quality is defined, let the stack decide
 122 } OCQualityOfService;
 123
 124 /**
 125  * Resource Properties
 126  *
 127  * OC_ACTIVE       - When this bit is set, the resource is initialized, otherwise the resource
 128  *                   is 'inactive'. 'inactive' signifies that the resource has been marked for
 129  *                   deletion or is already deleted.
 130  * OC_DISCOVERABLE - When this bit is set, the resource is allowed to be discovered by clients.
 131  * OC_OBSERVABLE   - When this bit is set, the resource is allowed to be observed by clients.
 132  * OC_SLOW         - When this bit is set, the resource has been marked as 'slow'. 'slow' signifies
 133  *                   that responses from this resource can expect delays in processing its
 134  *                   requests from clients.
 135  * OC_SECURE       - When this bit is set, the resource is a secure resource.
 136  */
 137 typedef enum
 138 {
 139     OC_ACTIVE       = (1 << 0),
 140     OC_DISCOVERABLE = (1 << 1),
 141     OC_OBSERVABLE   = (1 << 2),
 142     OC_SLOW         = (1 << 3),
 143     OC_SECURE       = (1 << 4)
 144 } OCResourceProperty;
 145
 146 /**
 147  * Transport Protocol IDs
 148  */
 149 typedef enum
 150 {
 151     OC_INVALID_ID   = (1 << 0),
 152     OC_COAP_ID      = (1 << 1)
 153 } OCTransportProtocolID;
 154
 155 /**
 156  * Adaptor types
 157  */
 158 typedef enum
 159 {
 160     OC_ETHERNET = 0,
 161     OC_WIFI,
 162     OC_EDR,
 163     OC_LE,
 164     OC_ALL //Multicast message: send over all the interfaces.
 165 } OCConnectivityType;
 166
 167 /**
 168  * Declares Stack Results & Errors
 169  */
 170 typedef enum
 171 {
 172     /* Success status code - START HERE */
 173     OC_STACK_OK = 0,
 174     OC_STACK_RESOURCE_CREATED,
 175     OC_STACK_RESOURCE_DELETED,
 176     OC_STACK_CONTINUE,
 177     /* Success status code - END HERE */
 178     /* Error status code - START HERE */
 179     OC_STACK_INVALID_URI = 20,
 180     OC_STACK_INVALID_QUERY,
 181     OC_STACK_INVALID_IP,
 182     OC_STACK_INVALID_PORT,
 183     OC_STACK_INVALID_CALLBACK,
 184     OC_STACK_INVALID_METHOD,
 185     OC_STACK_INVALID_PARAM,
 186     OC_STACK_INVALID_OBSERVE_PARAM,
 187     OC_STACK_NO_MEMORY,
 188     OC_STACK_COMM_ERROR,
 189     OC_STACK_TIMEOUT,
 190     OC_STACK_ADAPTER_NOT_ENABLED,
 191     OC_STACK_NOTIMPL,
 192     OC_STACK_NO_RESOURCE,               /* resource not found */
 193     OC_STACK_RESOURCE_ERROR,            /* ex: not supported method or interface */
 194     OC_STACK_SLOW_RESOURCE,
 195     OC_STACK_NO_OBSERVERS,              /* resource has no registered observers */
 196     OC_STACK_OBSERVER_NOT_FOUND,
 197     OC_STACK_VIRTUAL_DO_NOT_HANDLE,
 198     OC_STACK_INVALID_OPTION,
 199     OC_STACK_MALFORMED_RESPONSE,        /* the remote reply contained malformed data */
 200     OC_STACK_PERSISTENT_BUFFER_REQUIRED,
 201     OC_STACK_INVALID_REQUEST_HANDLE,
 202     OC_STACK_INVALID_DEVICE_INFO,
 203     OC_STACK_INVALID_JSON,
 204     /* NOTE: Insert all new error codes here!*/
 205     #ifdef WITH_PRESENCE
 206     OC_STACK_PRESENCE_STOPPED = 128,
 207     OC_STACK_PRESENCE_TIMEOUT,
 208     OC_STACK_PRESENCE_DO_NOT_HANDLE,
 209     #endif
 210     OC_STACK_ERROR = 255
 211     /* Error status code - END HERE */
 212 } OCStackResult;
 213
 214 /**
 215  * Handle to an @ref OCDoResource invocation.
 216  */
 217 typedef void * OCDoHandle;
 218
 219 /**
 220  * Handle to an OCResource object owned by the OCStack.
 221  */
 222 typedef void * OCResourceHandle;
 223
 224 typedef void * OCRequestHandle;
 225 typedef void * OCResponseHandle;
 226
 227 /**
 228  * Unique identifier for each observation request. Used when observations are
 229  * registered or deregistering. Used by entity handler to signal specific
 230  * observers to be notified of resource changes.
 231  * There can be maximum of 256 observations per server.
 232  */
 233 typedef uint8_t OCObservationId;
 234
 235 /**
 236  * Action associated with observation
 237  */
 238 typedef enum
 239 {
 240     OC_OBSERVE_REGISTER = 0,
 241     OC_OBSERVE_DEREGISTER = 1,
 242     OC_OBSERVE_NO_OPTION = 2
 243 } OCObserveAction;
 244
 245 typedef struct
 246 {
 247     // Action associated with observation request
 248     OCObserveAction action;
 249     // Identifier for observation being registered/deregistered
 250     OCObservationId obsId;
 251 } OCObservationInfo;
 252
 253 /**
 254  * Possible returned values from entity handler
 255  */
 256 typedef enum
 257 {
 258     OC_EH_OK = 0,
 259     OC_EH_ERROR,
 260     OC_EH_RESOURCE_CREATED,
 261     OC_EH_RESOURCE_DELETED,
 262     OC_EH_SLOW,
 263     OC_EH_FORBIDDEN
 264 } OCEntityHandlerResult;
 265
 266 // following structure will be used to define the vendor specific header options to be included
 267 // in communication packets
 268
 269 typedef struct OCHeaderOption
 270 {
 271     // The protocol ID this option applies to
 272     OCTransportProtocolID protocolID;
 273     // The header option ID which will be added to communication packets
 274     uint16_t optionID;
 275     // its length   191
 276     uint16_t optionLength;
 277     // pointer to its data
 278     uint8_t optionData[MAX_HEADER_OPTION_DATA_LENGTH];
 279 } OCHeaderOption;
 280
 281 /**
 282  * Incoming requests handled by the server. Requests are passed in as a parameter to the
 283  * @ref OCEntityHandler callback API.
 284  * @brief The @ref OCEntityHandler callback API must be implemented in the application in order
 285  * to receive these requests.
 286  */
 287 typedef struct
 288 {
 289     // Associated resource
 290     OCResourceHandle resource;
 291     OCRequestHandle requestHandle;
 292     // the REST method retrieved from received request PDU
 293     OCMethod method;
 294     // resource query send by client
 295     char * query;
 296     // Information associated with observation - valid only when OCEntityHandler
 297     // flag includes OC_OBSERVE_FLAG
 298     OCObservationInfo obsInfo;
 299     // An array of the received vendor specific header options
 300     uint8_t numRcvdVendorSpecificHeaderOptions;
 301     OCHeaderOption * rcvdVendorSpecificHeaderOptions;
 302     // reqJSON is retrieved from the payload of the received request PDU
 303     char * reqJSONPayload;
 304 } OCEntityHandlerRequest;
 305
 306 /**
 307  * Response from queries to remote servers. Queries are made by calling the @ref OCDoResource API.
 308  */
 309 typedef struct
 310 {
 311     // Address of remote server
 312     OCDevAddr * addr;
 313     // Indicates adaptor type on which the response was received
 314     OCConnectivityType connType;
 315     // the is the result of our stack, OCStackResult should contain coap/other error codes;
 316     OCStackResult result;
 317     // If associated with observe, this will represent the sequence of notifications from server.
 318     uint32_t sequenceNumber;
 319     // resJSONPayload is retrieved from the payload of the received request PDU
 320     const char * resJSONPayload;
 321     // An array of the received vendor specific header options
 322     uint8_t numRcvdVendorSpecificHeaderOptions;
 323     OCHeaderOption rcvdVendorSpecificHeaderOptions[MAX_HEADER_OPTIONS];
 324 } OCClientResponse;
 325
 326 /**
 327  * Following structure describes the device properties. All non-Null properties will be included
 328  * in a device discovery request.
 329  */
 330 typedef struct
 331 {
 332     char *deviceName;
 333     char *hostName;
 334     char *deviceUUID;
 335     char *contentType;
 336     char *version;
 337     char *manufacturerName;
 338     char *manufacturerUrl;
 339     char *modelNumber;
 340     char *dateOfManufacture;
 341     char *platformVersion;
 342     char *firmwareVersion;
 343     char *supportUrl;
 344 } OCDeviceInfo;
 345
 346 typedef struct
 347 {
 348     // Request handle is passed to server via the entity handler for each incoming request.
 349     // Stack assigns when request is received, server sets to indicate what request response is for
 350     OCRequestHandle requestHandle;
 351     // New handle for tracking block (or slow) response.  Stack assigns, server uses for subsequent calls
 352     OCResponseHandle  *responseHandle;
 353     // Resource handle
 354     OCResourceHandle resourceHandle;
 355     // Allow the entity handler to pass a result with the response
 356     OCEntityHandlerResult  ehResult;
 357     // this is the pointer to server payload data to be transferred
 358     char *payload;
 359     // size of server payload data.  I don't think we should rely on null terminated data for size
 360     uint16_t payloadSize;
 361     // An array of the vendor specific header options the entity handler wishes to use in response
 362     uint8_t numSendVendorSpecificHeaderOptions;
 363     OCHeaderOption sendVendorSpecificHeaderOptions[MAX_HEADER_OPTIONS];
 364     // URI of new resource that entity handler might create
 365     char resourceUri[MAX_URI_LENGTH];
 366     // Server sets to true for persistent response buffer, false for non-persistent response buffer
 367     uint8_t persistentBufferFlag;
 368 } OCEntityHandlerResponse;
 369
 370 typedef enum
 371 {
 372     OC_INIT_FLAG    = (1 << 0),
 373     OC_REQUEST_FLAG = (1 << 1),
 374     OC_OBSERVE_FLAG = (1 << 2)
 375 } OCEntityHandlerFlag; //entity_handler_flag_t ;
 376
 377 // possible returned values from client application
 378 typedef enum
 379 {
 380     OC_STACK_DELETE_TRANSACTION = 0,
 381     OC_STACK_KEEP_TRANSACTION
 382 } OCStackApplicationResult;
 383
 384 //-----------------------------------------------------------------------------
 385 // Callback function definitions
 386 //-----------------------------------------------------------------------------
 387
 388 /**
 389  * Client applications implement this callback to consume responses received from Servers.
 390  */
 391 typedef OCStackApplicationResult (* OCClientResponseHandler)(void *context, OCDoHandle handle,
 392     OCClientResponse * clientResponse);
 393
 394 /**
 395  * Client applications using a context pointer implement this callback to delete the
 396  * context upon removal of the callback/context pointer from the internal callback-list
 397  */
 398 typedef void (* OCClientContextDeleter)(void *context);
 399
 400 /*
 401  * This info is passed from application to OC Stack when initiating a request to Server
 402  */
 403 typedef struct
 404 {
 405     void *context;
 406     OCClientResponseHandler cb;
 407     OCClientContextDeleter cd;
 408 } OCCallbackData;
 409
 410 /**
 411  * Application server implementations must implement this callback to consume requests OTA.
 412  * Entity handler callback needs to fill the resPayload of the entityHandlerRequest.
 413  */
 414 typedef OCEntityHandlerResult (*OCEntityHandler)
 415 (OCEntityHandlerFlag flag, OCEntityHandlerRequest * entityHandlerRequest);
 416
 417 /**
 418  * Device Entity handler need to use this call back instead of OCEntityHandler
 419  */
 420 typedef OCEntityHandlerResult (*OCDeviceEntityHandler)
 421 (OCEntityHandlerFlag flag, OCEntityHandlerRequest * entityHandlerRequest, char* uri);
 422
 423 //-----------------------------------------------------------------------------
 424 // Function prototypes
 425 //-----------------------------------------------------------------------------
 426
 427 /**
 428  * Initialize the OC Stack.  Must be called prior to starting the stack.
 429  *
 430  * @param ipAddr
 431  *     IP Address of host device
 432  * @param port
 433  *     Port of host device
 434  * @param mode
 435  *     Host device is client, server, or client-server
 436  *
 437  * @return
 438  *     OC_STACK_OK    - no errors
 439  *     OC_STACK_ERROR - stack init error
 440  */
 441 OCStackResult OCInit(const char *ipAddr, uint16_t port, OCMode mode);
 442
 443 /**
 444  * Stop the OC stack.  Use for a controlled shutdown.
 445  *
 446  * Note: OCStop() performs operations similar to OCStopPresence(), as well as OCDeleteResource() on
 447  * all resources this server is hosting. OCDeleteResource() performs operations similar to
 448  * OCNotifyAllObservers() to notify all client observers that the respective resource is being
 449  * deleted.
 450  *
 451  * @return
 452  *     OC_STACK_OK    - no errors
 453  *     OC_STACK_ERROR - stack not initialized
 454  */
 455 OCStackResult OCStop();
 456
 457 /**
 458  * Called in main loop of OC client or server.  Allows low-level processing of
 459  * stack services.
 460  *
 461  * @return
 462  *     OC_STACK_OK    - no errors
 463  *     OC_STACK_ERROR - stack process error
 464  */
 465 OCStackResult OCProcess();
 466
 467 /**
 468  * Discover or Perform requests on a specified resource (specified by that Resource's respective
 469  * URI).
 470  *
 471  * @param handle             - @ref OCDoHandle to refer to the request sent out on behalf of
 472  *                             calling this API. This handle can be used to cancel this operation
 473  *                             via the OCCancel API.
 474  *                             Note: This reference is handled internally, and
 475  *                             should not be free'd by the consumer.  A NULL handle is permitted
 476  *                             in the event where the caller has no use for the return value.
 477  * @param method             - @ref OCMethod to perform on the resource
 478  * @param requiredUri        - URI of the resource to interact with
 479  * @param referenceUri       - URI of the reference resource
 480  * @param request            - JSON encoded request
 481  * @param conType            - @ref OCConnectivityType type of connectivity indicating the
 482  *                             interface. Example: OC_WIFI, OC_ETHERNET, OC_ALL
 483  * @param qos                - quality of service. Note that if this API is called on a uri with
 484  *                             the well-known multicast IP address, the qos will be forced to
 485  *                             OC_LOW_QOS
 486  *                             since it is impractical to send other QOS levels on such addresses.
 487  * @param cbData             - asynchronous callback function that is invoked
 488  *                             by the stack when discovery or resource interaction is complete
 489  * @param options            - The address of an array containing the vendor specific
 490  *                             header options to be sent with the request
 491  * @param numOptions         - Number of header options to be included
 492  *
 493  * Note: Presence subscription amendments (ie. adding additional resource type filters by calling
 494  * this API again) require the use of the same base URI as the original request to successfully
 495  * amend the presence filters.
 496  *
 497  * @return
 498  *     OC_STACK_OK               - no errors
 499  *     OC_STACK_INVALID_CALLBACK - invalid callback function pointer
 500  *     OC_STACK_INVALID_METHOD   - invalid resource method
 501  *     OC_STACK_INVALID_URI      - invalid required or reference URI
 502  *     OC_STACK_INVALID_QUERY    - number of resource types specified for filtering presence
 503  *                                 notifications exceeds @ref MAX_PRESENCE_FILTERS.
 504  */
 505 OCStackResult OCDoResource(OCDoHandle *handle, OCMethod method, const char *requiredUri,
 506             const char *referenceUri, const char *request, OCConnectivityType conType,
 507             OCQualityOfService qos, OCCallbackData *cbData,
 508             OCHeaderOption * options, uint8_t numOptions);
 509
 510 /**
 511  * Cancel a request associated with a specific @ref OCDoResource invocation.
 512  *
 513  * @param handle - Used to identify a specific OCDoResource invocation.
 514  * @param qos    - used to specify Quality of Service (read below for more info)
 515  * @param options- used to specify vendor specific header options when sending
 516  *                 explicit observe cancellation
 517  * @param numOptions- Number of header options to be included
 518  *
 519  * @return
 520  *     OC_STACK_OK               - No errors; Success
 521  *     OC_STACK_INVALID_PARAM    - The handle provided is invalid.
 522  */
 523 OCStackResult OCCancel(OCDoHandle handle, OCQualityOfService qos, OCHeaderOption * options,
 524         uint8_t numOptions);
 525
 526 #ifdef WITH_PRESENCE
 527 /**
 528  * When operating in @ref OCServer or @ref OCClientServer mode, this API will start sending out
 529  * presence notifications to clients via multicast. Once this API has been called with a success,
 530  * clients may query for this server's presence and this server's stack will respond via multicast.
 531  *
 532  * Server can call this function when it comes online for the first time, or when it comes back
 533  * online from offline mode, or when it re enters network.
 534  *
 535  * @param ttl - Time To Live in seconds
 536  * Note: If ttl is '0', then the default stack value will be used (60 Seconds).
 537  *
 538  * @return
 539  *     OC_STACK_OK      - No errors; Success
 540  */
 541 OCStackResult OCStartPresence(const uint32_t ttl);
 542
 543 /**
 544  * When operating in @ref OCServer or @ref OCClientServer mode, this API will stop sending out
 545  * presence notifications to clients via multicast. Once this API has been called with a success,
 546  * this server's stack will not respond to clients querying for this server's presence.
 547  *
 548  * Server can call this function when it is terminating, going offline, or when going
 549  * away from network.
 550  *
 551  * @return
 552  *     OC_STACK_OK      - No errors; Success
 553  */
 554
 555 OCStackResult OCStopPresence();
 556 #endif
 557
 558
 559 /**
 560  * Set default device entity handler
 561  *
 562  * @param entityHandler - entity handler function that is called by ocstack to handle requests for
 563  *                        any undefined resources or default actions.
 564  *                        if NULL is passed it removes the device default entity handler.
 565  *
 566  * @return
 567  *     OC_STACK_OK    - no errors
 568  *     OC_STACK_ERROR - stack process error
 569  */
 570 OCStackResult OCSetDefaultDeviceEntityHandler(OCDeviceEntityHandler entityHandler);
 571
 572 /**
 573  * Set device information.
 574  *
 575  * @param deviceInfo - Structure passed by the server application containing
 576  *                     the device information.
 577  *
 578  *
 579  * @return
 580  *     OC_STACK_OK              - no errors
 581  *     OC_STACK_INVALID_PARAM   - invalid paramerter
 582  *     OC_STACK_ERROR           - stack process error
 583  */
 584 OCStackResult OCSetDeviceInfo(OCDeviceInfo deviceInfo);
 585
 586 /**
 587  * Create a resource.
 588  *
 589  * @param handle - pointer to handle to newly created resource.  Set by ocstack.  Used to refer to resource
 590  * @param resourceTypeName - name of resource type.  Example: "core.led"
 591  * @param resourceInterfaceName - name of resource interface.  Example: "core.rw"
 592  * @param uri - URI of the resource.  Example:  "/a/led"
 593  * @param entityHandler - entity handler function that is called by ocstack to handle requests, etc
 594  *                        NULL for default entity handler
 595  * @param resourceProperties - properties supported by resource.  Example: OC_DISCOVERABLE|OC_OBSERVABLE
 596  *
 597  * @return
 598  *     OC_STACK_OK    - no errors
 599  *     OC_STACK_ERROR - stack process error
 600  */
 601 OCStackResult OCCreateResource(OCResourceHandle *handle,
 602                                const char *resourceTypeName,
 603                                const char *resourceInterfaceName,
 604                                const char *uri,
 605                                OCEntityHandler entityHandler,
 606                                uint8_t resourceProperties);
 607
 608 /**
 609  * Create a resource. with host ip address for remote resource
 610  *
 611  * @param handle - pointer to handle to newly created resource.  Set by ocstack.
 612  *                 Used to refer to resource
 613  * @param resourceTypeName - name of resource type.  Example: "core.led"
 614  * @param resourceInterfaceName - name of resource interface.  Example: "core.rw"
 615  * @param host - HOST address of the remote resource.  Example:  "coap://xxx.xxx.xxx.xxx:xxxxx"
 616  * @param uri - URI of the resource.  Example:  "/a/led"
 617  * @param entityHandler - entity handler function that is called by ocstack to handle requests, etc
 618  *                        NULL for default entity handler
 619  * @param resourceProperties - properties supported by resource.
 620  *                             Example: OC_DISCOVERABLE|OC_OBSERVABLE
 621  *
 622  * @return
 623  *     OC_STACK_OK    - no errors
 624  *     OC_STACK_ERROR - stack process error
 625  */
 626 OCStackResult OCCreateResourceWithHost(OCResourceHandle *handle,
 627                                const char *resourceTypeName,
 628                                const char *resourceInterfaceName,
 629                                const char *host,
 630                                const char *uri,
 631                                OCEntityHandler entityHandler,
 632                                uint8_t resourceProperties);
 633
 634 /**
 635  * Add a resource to a collection resource.
 636  *
 637  * @param collectionHandle - handle to the collection resource
 638  * @param resourceHandle - handle to resource to be added to the collection resource
 639  *
 640  * @return
 641  *     OC_STACK_OK    - no errors
 642  *     OC_STACK_ERROR - stack process error
 643  *     OC_STACK_INVALID_PARAM - invalid collectionhandle
 644  */
 645 OCStackResult OCBindResource(OCResourceHandle collectionHandle, OCResourceHandle resourceHandle);
 646
 647 /**
 648  * Remove a resource from a collection resource.
 649  *
 650  * @param collectionHandle - handle to the collection resource
 651  * @param resourceHandle - handle to resource to be removed from the collection resource
 652  *
 653  * @return
 654  *     OC_STACK_OK    - no errors
 655  *     OC_STACK_ERROR - stack process error
 656  *     OC_STACK_INVALID_PARAM - invalid collectionhandle
 657  */
 658 OCStackResult OCUnBindResource(OCResourceHandle collectionHandle, OCResourceHandle resourceHandle);
 659
 660 /**
 661  * Bind a resourcetype to a resource.
 662  *
 663  * @param handle - handle to the resource
 664  * @param resourceTypeName - name of resource type.  Example: "core.led"
 665  *
 666  * @return
 667  *     OC_STACK_OK    - no errors
 668  *     OC_STACK_ERROR - stack process error
 669  */
 670 OCStackResult OCBindResourceTypeToResource(OCResourceHandle handle,
 671                                            const char *resourceTypeName);
 672 /**
 673  * Bind a resource interface to a resource.
 674  *
 675  * @param handle - handle to the resource
 676  * @param resourceInterfaceName - name of resource interface.  Example: "core.rw"
 677  *
 678  * @return
 679  *     OC_STACK_OK    - no errors
 680  *     OC_STACK_ERROR - stack process error
 681  */
 682 OCStackResult OCBindResourceInterfaceToResource(OCResourceHandle handle,
 683                                                 const char *resourceInterfaceName);
 684
 685 /**
 686  * Bind an entity handler to the resource.
 687  *
 688  * @param handle - handle to the resource that the contained resource is to be bound
 689  * @param entityHandler - entity handler function that is called by ocstack to handle requests, etc
 690  * @return
 691  *     OC_STACK_OK    - no errors
 692  *     OC_STACK_ERROR - stack process error
 693  */
 694 OCStackResult OCBindResourceHandler(OCResourceHandle handle, OCEntityHandler entityHandler);
 695
 696 /**
 697  * Get the number of resources that have been created in the stack.
 698  *
 699  * @param numResources - pointer to count variable
 700  *
 701  * @return
 702  *     OC_STACK_OK    - no errors
 703  *     OC_STACK_ERROR - stack process error
 704
 705  */
 706 OCStackResult OCGetNumberOfResources(uint8_t *numResources);
 707
 708 /**
 709  * Get a resource handle by index.
 710  *
 711  * @param index - index of resource, 0 to Count - 1
 712  *
 713  * @return
 714  *    Resource handle - if found
 715  *    NULL - if not found
 716  */
 717 OCResourceHandle OCGetResourceHandle(uint8_t index);
 718
 719 /**
 720  * Delete resource specified by handle.  Deletes resource and all resourcetype and resourceinterface
 721  * linked lists.
 722  *
 723  * Note: OCDeleteResource() performs operations similar to OCNotifyAllObservers() to notify all
 724  * client observers that "this" resource is being deleted.
 725  *
 726  * @param handle - handle of resource to be deleted
 727  *
 728  * @return
 729  *     OC_STACK_OK    - no errors
 730  *     OC_STACK_ERROR - stack process error
 731  */
 732 OCStackResult OCDeleteResource(OCResourceHandle handle);
 733
 734 /**
 735  * Get the URI of the resource specified by handle.
 736  *
 737  * @param handle - handle of resource
 738  * @return
 739  *    URI string - if resource found
 740  *    NULL - resource not found
 741  */
 742 const char *OCGetResourceUri(OCResourceHandle handle);
 743
 744 /**
 745  * Get the properties of the resource specified by handle.
 746  * NOTE: that after a resource is created, the OC_ACTIVE property is set
 747  * for the resource by the stack.
 748  *
 749  * @param handle - handle of resource
 750  * @return
 751  *    OCResourceProperty Bitmask
 752  *    -1 if resource is not found
 753  */
 754 OCResourceProperty OCGetResourceProperties(OCResourceHandle handle);
 755
 756 /**
 757  * Get the number of resource types of the resource.
 758  *
 759  * @param handle - handle of resource
 760  * @param numResourceTypes - pointer to count variable
 761  *
 762  * @return
 763  *     OC_STACK_OK    - no errors
 764  *     OC_STACK_ERROR - stack process error
 765  */
 766 OCStackResult OCGetNumberOfResourceTypes(OCResourceHandle handle, uint8_t *numResourceTypes);
 767
 768 /**
 769  * Get name of resource type of the resource.
 770  *
 771  * @param handle - handle of resource
 772  * @param index - index of resource, 0 to Count - 1
 773  *
 774  * @return
 775  *    resource type name - if resource found
 776  *    NULL - resource not found
 777  */
 778 const char *OCGetResourceTypeName(OCResourceHandle handle, uint8_t index);
 779
 780 /**
 781  * Get the number of resource interfaces of the resource.
 782  *
 783  * @param handle - handle of resource
 784  * @param numResourceInterfaces - pointer to count variable
 785  *
 786  * @return
 787  *     OC_STACK_OK    - no errors
 788  *     OC_STACK_ERROR - stack process error
 789
 790  */
 791 OCStackResult OCGetNumberOfResourceInterfaces(OCResourceHandle handle,
 792         uint8_t *numResourceInterfaces);
 793
 794 /**
 795  * Get name of resource interface of the resource.
 796  *
 797  * @param handle - handle of resource
 798  * @param index - index of resource, 0 to Count - 1
 799  *
 800  * @return
 801  *    resource interface name - if resource found
 802  *    NULL - resource not found
 803  */
 804 const char *OCGetResourceInterfaceName(OCResourceHandle handle, uint8_t index);
 805
 806 /**
 807  * Get methods of resource interface of the resource.
 808  *
 809  * @param handle - handle of resource
 810  * @param index - index of resource, 0 to Count - 1
 811  *
 812  * @return
 813  *    allowed methods - if resource found
 814  *    NULL - resource not found
 815  */
 816 uint8_t OCGetResourceInterfaceAllowedMethods(OCResourceHandle handle, uint8_t index);
 817
 818 /**
 819  * Get resource handle from the collection resource by index.
 820  *
 821  * @param collectionHandle - handle of collection resource
 822  * @param index - index of contained resource, 0 to Count - 1
 823  *
 824  * @return
 825  *    handle to contained resource - if resource found
 826  *    NULL - resource not found
 827  */
 828 OCResourceHandle OCGetResourceHandleFromCollection(OCResourceHandle collectionHandle,
 829         uint8_t index);
 830
 831 /**
 832  * Get the entity handler for a resource.
 833  *
 834  * @param handle - handle of resource
 835  *
 836  * @return
 837  *    entity handler - if resource found
 838  *    NULL - resource not found
 839  */
 840 OCEntityHandler OCGetResourceHandler(OCResourceHandle handle);
 841
 842 /**
 843  * Notify all registered observers that the resource representation has
 844  * changed. If observation includes a query the client is notified only
 845  * if the query is valid after the resource representation has changed.
 846  *
 847  * @param handle - handle of resource
 848  * @param qos    - desired quality of service for the observation notifications
 849  *
 850  * @return
 851  *     OC_STACK_OK    - no errors
 852  *     OC_STACK_NO_RESOURCE - invalid resource handle
 853  *     OC_STACK_NO_OBSERVERS - no more observers intrested in resource
 854  */
 855 OCStackResult OCNotifyAllObservers(OCResourceHandle handle, OCQualityOfService qos);
 856
 857 /**
 858  * Notify specific observers with updated value of representation.
 859  * Before this API is invoked by entity handler it has finished processing
 860  * queries for the associated observers.
 861  *
 862  * @param handle - handle of resource
 863  * @param obsIdList - list of observation ids that need to be notified
 864  * @param numberOfIds - number of observation ids included in obsIdList
 865  * @param notificationJSONPayload - JSON encoded payload to send in notification
 866  * @param qos - desired quality of service of the observation notifications
 867  * NOTE: The memory for obsIdList and notificationJSONPayload is managed by the
 868  * entity invoking the API. The maximum size of the notification is 1015 bytes
 869  * for non-Arduino platforms. For Arduino the maximum size is 247 bytes.
 870  *
 871  * @return
 872  *     OC_STACK_OK    - no errors
 873  *     OC_STACK_NO_RESOURCE - invalid resource handle
 874  */
 875 OCStackResult
 876 OCNotifyListOfObservers (OCResourceHandle handle,
 877                             OCObservationId  *obsIdList,
 878                             uint8_t          numberOfIds,
 879                             const char    *notificationJSONPayload,
 880                             OCQualityOfService qos);
 881
 882
 883 /**
 884  * Send a response to a request.
 885  * The response can be a normal, slow, or block (i.e. a response that
 886  * is too large to be sent in a single PDU and must span multiple transmissions)
 887  *
 888  * @param response - pointer to structure that contains response parameters
 889  *
 890  * @return
 891  *     OC_STACK_OK    - no errors
 892  */
 893 OCStackResult OCDoResponse(OCEntityHandlerResponse *response);
 894
 895 /**
 896  * Cancel a response.  Applies to a block response
 897  *
 898  * @param responseHandle - response handle set by stack in OCServerResponse after
 899  *                         OCDoResponse is called
 900  *
 901  * @return
 902  *     OC_STACK_OK               - No errors; Success
 903  *     OC_STACK_INVALID_PARAM    - The handle provided is invalid.
 904  */
 905 OCStackResult OCCancelResponse(OCResponseHandle responseHandle);
 906
 907 //Utility methods
 908
 909 //-- OCDevAddrToIPv4Addr -------------------------------------------------
 910 /**
 911  * This method is used to retrieved the IPv4 address from OCDev address
 912  * data structure.
 913  *
 914  * @param[in]  ipAddr
 915  *              OCDevAddr address.
 916  * @param[out]  a first byte of IPv4 address.
 917  * @param[out]  b second byte of IPv4 address.
 918  * @param[out]  c third byte of IPv4 address.
 919  * @param[out]  d fourth byte of IPv4 address.
 920  *
 921  * @retval 0 for Success, otherwise some error value
 922  */
 923 //------------------------------------------------------------------------
 924 int32_t OCDevAddrToIPv4Addr(OCDevAddr *ipAddr, uint8_t *a, uint8_t *b,
 925             uint8_t *c, uint8_t *d );
 926
 927
 928 //-- OCDevAddrToPort -------------------------------------------------
 929 /**
 930  * This method is used to retrieve the port number from OCDev address
 931  * data structure.
 932  *
 933  * @param[in]  ipAddr
 934  *              OCDevAddr address.
 935  * @param[out] port
 936  *              port number
 937  *
 938  * @retval 0 for Success, otherwise some error value
 939  */
 940 //------------------------------------------------------------------------
 941 int32_t OCDevAddrToPort(OCDevAddr *ipAddr, uint16_t *port);
 942
 943 #ifdef __cplusplus
 944 }
 945 #endif // __cplusplus
 946
 947 #endif /* OCSTACK_H_ */
 948
 949