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