1 //******************************************************************
3 // Copyright 2014 Intel Mobile Communications GmbH All Rights Reserved.
5 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
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
11 // http://www.apache.org/licenses/LICENSE-2.0
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.
19 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
25 #include "ocstackconfig.h"
31 //-----------------------------------------------------------------------------
33 //-----------------------------------------------------------------------------
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.
39 #define OC_WELL_KNOWN_QUERY "224.0.1.187:5298/oc/core"
40 #define OC_EXPLICIT_DEVICE_DISCOVERY_URI "224.0.1.187:5298/oc/core/d?rt=core.led"
41 #define OC_MULTICAST_PREFIX "224.0.1.187:5298"
42 #define OC_MULTICAST_IP "224.0.1.187"
45 #define OC_WELL_KNOWN_QUERY "coap://224.0.1.187:5683/oc/core"
46 #define OC_EXPLICIT_DEVICE_DISCOVERY_URI "coap://224.0.1.187:5683/oc/core/d?rt=core.led"
47 #define OC_MULTICAST_PREFIX "coap://224.0.1.187:5683"
48 #define OC_MULTICAST_IP "coap://224.0.1.187"
51 #define USE_RANDOM_PORT (0)
53 #define OC_DEFAULT_PRESENCE_TTL (60)
54 #define OC_PRESENCE_URI "/oc/presence"
55 extern uint8_t PresenceTimeOutSize; // length of PresenceTimeOut - 1
56 extern uint32_t PresenceTimeOut[];
58 //-----------------------------------------------------------------------------
60 //-----------------------------------------------------------------------------
63 * OC Virtual resources supported by every OC device
66 OC_WELL_KNOWN_URI= 0, // "/oc/core"
67 OC_DEVICE_URI, // "/oc/core/d"
68 OC_RESOURCE_TYPES_URI, // "/oc/core/d/type"
70 OC_PRESENCE, // "/oc/presence"
72 OC_MAX_VIRTUAL_RESOURCES // Max items in the list
76 * Standard RESTful HTTP Methods
80 OC_REST_GET = (1 << 0), // Read
81 OC_REST_PUT = (1 << 1), // Write
82 OC_REST_POST = (1 << 2), // Update
83 OC_REST_DELETE = (1 << 3), // Delete
84 // Register observe request for most up date notifications ONLY.
85 OC_REST_OBSERVE = (1 << 4),
86 // Register observe request for all notifications, including stale notifications.
87 OC_REST_OBSERVE_ALL = (1 << 5),
88 // Deregister observation, intended for internal use
89 OC_REST_CANCEL_OBSERVE = (1 << 6),
91 // Subscribe for all presence notifications of a particular resource.
92 OC_REST_PRESENCE = (1 << 7)
97 * Host Mode of Operation
105 extern OCMode myStackMode;
113 OC_NA_QOS // No Quality is defined, let the stack decide
114 } OCQualityOfService;
117 * Resource Properties
119 * OC_ACTIVE - When this bit is set, the resource is initialized, otherwise the resource
120 * is 'inactive'. 'inactive' signifies that the resource has been marked for
121 * deletion or is already deleted.
122 * OC_DISCOVERABLE - When this bit is set, the resource is allowed to be discovered by clients.
123 * OC_OBSERVABLE - When this bit is set, the resource is allowed to be observed by clients.
124 * OC_SLOW - When this bit is set, the resource has been marked as 'slow'. 'slow' signifies
125 * that responses from this resource can expect delays in processing its
126 * requests from clients.
127 * OC_SECURE - When this bit is set, the resource is a secure resource.
130 OC_ACTIVE = (1 << 0),
131 OC_DISCOVERABLE = (1 << 1),
132 OC_OBSERVABLE = (1 << 2),
135 } OCResourceProperty;
138 * Transport Protocol IDs
141 OC_INVALID_ID = (1 << 0),
142 OC_COAP_ID = (1 << 1)
143 } OCTransportProtocolID;
154 OC_ALL //Multicast message: send over all the interfaces.
155 } OCConnectivityType;
159 * Declares Stack Results & Errors
162 /* Success status code - START HERE */
164 OC_STACK_RESOURCE_CREATED,
165 OC_STACK_RESOURCE_DELETED,
167 /* Success status code - END HERE */
168 /* Error status code - START HERE */
169 OC_STACK_INVALID_URI = 20,
170 OC_STACK_INVALID_QUERY,
172 OC_STACK_INVALID_PORT,
173 OC_STACK_INVALID_CALLBACK,
174 OC_STACK_INVALID_METHOD,
175 OC_STACK_INVALID_PARAM,
176 OC_STACK_INVALID_OBSERVE_PARAM,
180 OC_STACK_NO_RESOURCE, /* resource not found */
181 OC_STACK_RESOURCE_ERROR, /* ex: not supported method or interface */
182 OC_STACK_SLOW_RESOURCE,
183 OC_STACK_NO_OBSERVERS, /* resource has no registered observers */
184 OC_STACK_OBSERVER_NOT_FOUND,
185 OC_STACK_VIRTUAL_DO_NOT_HANDLE,
186 OC_STACK_INVALID_OPTION,
187 OC_STACK_MALFORMED_RESPONSE, /* the remote reply contained malformed data */
188 OC_STACK_PERSISTENT_BUFFER_REQUIRED,
189 OC_STACK_INVALID_REQUEST_HANDLE,
190 OC_STACK_INVALID_DEVICE_INFO,
191 OC_STACK_INVALID_JSON,
192 /* NOTE: Insert all new error codes here!*/
194 OC_STACK_PRESENCE_STOPPED = 128,
195 OC_STACK_PRESENCE_TIMEOUT,
196 OC_STACK_PRESENCE_DO_NOT_HANDLE,
199 /* Error status code - END HERE */
203 * Handle to an @ref OCDoResource invocation.
205 typedef void * OCDoHandle;
208 * Handle to an OCResource object owned by the OCStack.
210 typedef void * OCResourceHandle;
212 typedef void * OCRequestHandle;
213 typedef void * OCResponseHandle;
216 * Unique identifier for each observation request. Used when observations are
217 * registered or deregistering. Used by entity handler to signal specific
218 * observers to be notified of resource changes.
219 * There can be maximum of 256 observations per server.
221 typedef uint8_t OCObservationId;
224 * Action associated with observation
227 OC_OBSERVE_REGISTER = 0,
228 OC_OBSERVE_DEREGISTER = 1,
229 OC_OBSERVE_NO_OPTION = 2
233 // Action associated with observation request
234 OCObserveAction action;
235 // Identifier for observation being registered/deregistered
236 OCObservationId obsId;
240 * Possible returned values from entity handler
245 OC_EH_RESOURCE_CREATED,
246 OC_EH_RESOURCE_DELETED,
249 } OCEntityHandlerResult;
251 // following structure will be used to define the vendor specific header options to be included
252 // in communication packets
254 typedef struct OCHeaderOption {
255 // The protocol ID this option applies to
256 OCTransportProtocolID protocolID;
257 // The header option ID which will be added to communication packets
260 uint16_t optionLength;
261 // pointer to its data
262 uint8_t optionData[MAX_HEADER_OPTION_DATA_LENGTH];
266 * Incoming requests handled by the server. Requests are passed in as a parameter to the @ref OCEntityHandler callback API.
267 * @brief The @ref OCEntityHandler callback API must be implemented in the application in order to receive these requests.
270 // Associated resource
271 OCResourceHandle resource;
272 OCRequestHandle requestHandle;
273 // the REST method retrieved from received request PDU
275 // resource query send by client
276 unsigned char * query;
277 // Information associated with observation - valid only when OCEntityHandler
278 // flag includes OC_OBSERVE_FLAG
279 OCObservationInfo obsInfo;
280 // An array of the received vendor specific header options
281 uint8_t numRcvdVendorSpecificHeaderOptions;
282 OCHeaderOption * rcvdVendorSpecificHeaderOptions;
283 // reqJSON is retrieved from the payload of the received request PDU
284 unsigned char * reqJSONPayload;
285 }OCEntityHandlerRequest;
288 * Response from queries to remote servers. Queries are made by calling the @ref OCDoResource API.
291 // Address of remote server
294 // Indicates adaptor type on which the response was received
295 OCConnectivityType connType;
297 // the is the result of our stack, OCStackResult should contain coap/other error codes;
298 OCStackResult result;
299 // If associated with observe, this will represent the sequence of notifications from server.
300 uint32_t sequenceNumber;
301 // resJSONPayload is retrieved from the payload of the received request PDU
302 unsigned const char * resJSONPayload;
303 // An array of the received vendor specific header options
304 uint8_t numRcvdVendorSpecificHeaderOptions;
305 OCHeaderOption rcvdVendorSpecificHeaderOptions[MAX_HEADER_OPTIONS];
309 * Following structure describes the device properties. All non-Null properties will be included
310 * in a device discovery request.
319 char *manufacturerName;
320 char *manufacturerUrl;
322 char *dateOfManufacture;
323 char *platformVersion;
324 char *firmwareVersion;
330 // Request handle is passed to server via the entity handler for each incoming request.
331 // Stack assigns when request is received, server sets to indicate what request response is for
332 OCRequestHandle requestHandle;
333 // New handle for tracking block (or slow) response. Stack assigns, server uses for subsequent calls
334 OCResponseHandle *responseHandle;
336 OCResourceHandle resourceHandle;
337 // Allow the entity handler to pass a result with the response
338 OCEntityHandlerResult ehResult;
339 // this is the pointer to server payload data to be transferred
340 unsigned char *payload;
341 // size of server payload data. I don't think we should rely on null terminated data for size
342 uint16_t payloadSize;
343 // An array of the vendor specific header options the entity handler wishes to use in response
344 uint8_t numSendVendorSpecificHeaderOptions;
345 OCHeaderOption sendVendorSpecificHeaderOptions[MAX_HEADER_OPTIONS];
346 // URI of new resource that entity handler might create
347 unsigned char resourceUri[MAX_URI_LENGTH];
348 // Server sets to true for persistent response buffer, false for non-persistent response buffer
349 uint8_t persistentBufferFlag;
350 } OCEntityHandlerResponse;
353 OC_INIT_FLAG = (1 << 0),
354 OC_REQUEST_FLAG = (1 << 1),
355 OC_OBSERVE_FLAG = (1 << 2)
356 } OCEntityHandlerFlag; //entity_handler_flag_t ;
358 // possible returned values from client application
360 OC_STACK_DELETE_TRANSACTION = 0,
361 OC_STACK_KEEP_TRANSACTION
362 } OCStackApplicationResult;
364 //-----------------------------------------------------------------------------
365 // Callback function definitions
366 //-----------------------------------------------------------------------------
369 * Client applications implement this callback to consume responses received from Servers.
371 typedef OCStackApplicationResult (* OCClientResponseHandler)(void *context, OCDoHandle handle,
372 OCClientResponse * clientResponse);
375 * Client applications using a context pointer implement this callback to delete the
376 * context upon removal of the callback/context pointer from the internal callback-list
378 typedef void (* OCClientContextDeleter)(void *context);
381 * This info is passed from application to OC Stack when initiating a request to Server
385 OCClientResponseHandler cb;
386 OCClientContextDeleter cd;
390 * Application server implementations must implement this callback to consume requests OTA.
391 * Entity handler callback needs to fill the resPayload of the entityHandlerRequest.
393 typedef OCEntityHandlerResult (*OCEntityHandler)
394 (OCEntityHandlerFlag flag, OCEntityHandlerRequest * entityHandlerRequest);
397 * Device Entity handler need to use this call back instead of OCEntityHandler
399 typedef OCEntityHandlerResult (*OCDeviceEntityHandler)
400 (OCEntityHandlerFlag flag, OCEntityHandlerRequest * entityHandlerRequest, char* uri);
402 //-----------------------------------------------------------------------------
403 // Function prototypes
404 //-----------------------------------------------------------------------------
407 * Initialize the OC Stack. Must be called prior to starting the stack.
410 * IP Address of host device
412 * Port of host device
414 * Host device is client, server, or client-server
417 * OC_STACK_OK - no errors
418 * OC_STACK_ERROR - stack init error
420 OCStackResult OCInit(const char *ipAddr, uint16_t port, OCMode mode);
423 * Stop the OC stack. Use for a controlled shutdown.
425 * Note: OCStop() performs operations similar to OCStopPresence(), as well as OCDeleteResource() on
426 * all resources this server is hosting. OCDeleteResource() performs operations similar to
427 * OCNotifyAllObservers() to notify all client observers that the respective resource is being
431 * OC_STACK_OK - no errors
432 * OC_STACK_ERROR - stack not initialized
434 OCStackResult OCStop();
437 * Called in main loop of OC client or server. Allows low-level processing of
441 * OC_STACK_OK - no errors
442 * OC_STACK_ERROR - stack process error
444 OCStackResult OCProcess();
447 * Discover or Perform requests on a specified resource (specified by that Resource's respective
450 * @param handle - @ref OCDoHandle to refer to the request sent out on behalf of
452 * @param method - @ref OCMethod to perform on the resource
453 * @param requiredUri - URI of the resource to interact with
454 * @param referenceUri - URI of the reference resource
455 * @param request - JSON encoded request
456 * @param qos - quality of service. Note that if this API is called on a uri with
457 * the well-known multicast IP address, the qos will be forced to
459 * since it is impractical to send other QOS levels on such addresses.
460 * @param clientApplicationCB- asynchronous callback function that is invoked
461 * by the stack when discovery or resource interaction is complete
462 * @param options - The address of an array containing the vendor specific
463 * header options to be sent with the request
464 * @param numOptions - Number of header options to be included
466 * Note: Presence subscription amendments (ie. adding additional resource type filters by calling
467 * this API again) require the use of the same base URI as the original request to successfully
468 * amend the presence filters.
471 * OC_STACK_OK - no errors
472 * OC_STACK_INVALID_CALLBACK - invalid callback function pointer
473 * OC_STACK_INVALID_METHOD - invalid resource method
474 * OC_STACK_INVALID_URI - invalid required or reference URI
475 * OC_STACK_INVALID_QUERY - number of resource types specified for filtering presence
476 * notifications exceeds @ref MAX_PRESENCE_FILTERS.
479 OCStackResult OCDoResource(OCDoHandle *handle, OCMethod method, const char *requiredUri,
480 const char *referenceUri, const char *request, uint8_t conType,
481 OCQualityOfService qos, OCCallbackData *cbData, OCHeaderOption * options,
484 OCStackResult OCDoResource(OCDoHandle *handle, OCMethod method, const char *requiredUri,
485 const char *referenceUri, const char *request, OCQualityOfService qos,
486 OCCallbackData *cbData, OCHeaderOption * options, uint8_t numOptions);
490 * Cancel a request associated with a specific @ref OCDoResource invocation.
492 * @param handle - Used to identify a specific OCDoResource invocation.
493 * @param qos - used to specify Quality of Service (read below for more info)
494 * @param options- used to specify vendor specific header options when sending
495 * explicit observe cancellation
496 * @param numOptions- Number of header options to be included
499 * OC_STACK_OK - No errors; Success
500 * OC_STACK_INVALID_PARAM - The handle provided is invalid.
502 OCStackResult OCCancel(OCDoHandle handle, OCQualityOfService qos, OCHeaderOption * options,
507 * When operating in @ref OCServer or @ref OCClientServer mode, this API will start sending out
508 * presence notifications to clients via multicast. Once this API has been called with a success,
509 * clients may query for this server's presence and this server's stack will respond via multicast.
511 * Server can call this function when it comes online for the first time, or when it comes back
512 * online from offline mode, or when it re enters network.
514 * @param ttl - Time To Live in seconds
515 * Note: If ttl is '0', then the default stack value will be used (60 Seconds).
518 * OC_STACK_OK - No errors; Success
520 OCStackResult OCStartPresence(const uint32_t ttl);
523 * When operating in @ref OCServer or @ref OCClientServer mode, this API will stop sending out
524 * presence notifications to clients via multicast. Once this API has been called with a success,
525 * this server's stack will not respond to clients querying for this server's presence.
527 * Server can call this function when it is terminating, going offline, or when going
531 * OC_STACK_OK - No errors; Success
534 OCStackResult OCStopPresence();
539 * Set default device entity handler
541 * @param entityHandler - entity handler function that is called by ocstack to handle requests for
542 * any undefined resources or default actions.
543 * if NULL is passed it removes the device default entity handler.
546 * OC_STACK_OK - no errors
547 * OC_STACK_ERROR - stack process error
549 OCStackResult OCSetDefaultDeviceEntityHandler(OCDeviceEntityHandler entityHandler);
552 * Set device information.
554 * @param deviceInfo - Structure passed by the server application containing
555 * the device information.
559 * OC_STACK_OK - no errors
560 * OC_STACK_INVALID_PARAM - invalid paramerter
561 * OC_STACK_ERROR - stack process error
563 OCStackResult OCSetDeviceInfo(OCDeviceInfo deviceInfo);
568 * @param handle - pointer to handle to newly created resource. Set by ocstack. Used to refer to resource
569 * @param resourceTypeName - name of resource type. Example: "core.led"
570 * @param resourceInterfaceName - name of resource interface. Example: "core.rw"
571 * @param uri - URI of the resource. Example: "/a/led"
572 * @param entityHandler - entity handler function that is called by ocstack to handle requests, etc
573 * NULL for default entity handler
574 * @param resourceProperties - properties supported by resource. Example: OC_DISCOVERABLE|OC_OBSERVABLE
577 * OC_STACK_OK - no errors
578 * OC_STACK_ERROR - stack process error
580 OCStackResult OCCreateResource(OCResourceHandle *handle,
581 const char *resourceTypeName,
582 const char *resourceInterfaceName,
584 OCEntityHandler entityHandler,
585 uint8_t resourceProperties);
588 * Create a resource. with host ip address for remote resource
590 * @param handle - pointer to handle to newly created resource. Set by ocstack.
591 * Used to refer to resource
592 * @param resourceTypeName - name of resource type. Example: "core.led"
593 * @param resourceInterfaceName - name of resource interface. Example: "core.rw"
594 * @param host - HOST address of the remote resource. Example: "coap://xxx.xxx.xxx.xxx:xxxxx"
595 * @param uri - URI of the resource. Example: "/a/led"
596 * @param entityHandler - entity handler function that is called by ocstack to handle requests, etc
597 * NULL for default entity handler
598 * @param resourceProperties - properties supported by resource.
599 * Example: OC_DISCOVERABLE|OC_OBSERVABLE
602 * OC_STACK_OK - no errors
603 * OC_STACK_ERROR - stack process error
605 OCStackResult OCCreateResourceWithHost(OCResourceHandle *handle,
606 const char *resourceTypeName,
607 const char *resourceInterfaceName,
610 OCEntityHandler entityHandler,
611 uint8_t resourceProperties);
614 * Add a resource to a collection resource.
616 * @param collectionHandle - handle to the collection resource
617 * @param resourceHandle - handle to resource to be added to the collection resource
620 * OC_STACK_OK - no errors
621 * OC_STACK_ERROR - stack process error
622 * OC_STACK_INVALID_PARAM - invalid collectionhandle
624 OCStackResult OCBindResource(OCResourceHandle collectionHandle, OCResourceHandle resourceHandle);
627 * Remove a resource from a collection resource.
629 * @param collectionHandle - handle to the collection resource
630 * @param resourceHandle - handle to resource to be removed from the collection resource
633 * OC_STACK_OK - no errors
634 * OC_STACK_ERROR - stack process error
635 * OC_STACK_INVALID_PARAM - invalid collectionhandle
637 OCStackResult OCUnBindResource(OCResourceHandle collectionHandle, OCResourceHandle resourceHandle);
640 * Bind a resourcetype to a resource.
642 * @param handle - handle to the resource
643 * @param resourceTypeName - name of resource type. Example: "core.led"
646 * OC_STACK_OK - no errors
647 * OC_STACK_ERROR - stack process error
649 OCStackResult OCBindResourceTypeToResource(OCResourceHandle handle,
650 const char *resourceTypeName);
652 * Bind a resource interface to a resource.
654 * @param handle - handle to the resource
655 * @param resourceInterfaceName - name of resource interface. Example: "core.rw"
658 * OC_STACK_OK - no errors
659 * OC_STACK_ERROR - stack process error
661 OCStackResult OCBindResourceInterfaceToResource(OCResourceHandle handle,
662 const char *resourceInterfaceName);
665 * Bind an entity handler to the resource.
667 * @param handle - handle to the resource that the contained resource is to be bound
668 * @param entityHandler - entity handler function that is called by ocstack to handle requests, etc
670 * OC_STACK_OK - no errors
671 * OC_STACK_ERROR - stack process error
673 OCStackResult OCBindResourceHandler(OCResourceHandle handle, OCEntityHandler entityHandler);
676 * Get the number of resources that have been created in the stack.
678 * @param numResources - pointer to count variable
681 * OC_STACK_OK - no errors
682 * OC_STACK_ERROR - stack process error
685 OCStackResult OCGetNumberOfResources(uint8_t *numResources);
688 * Get a resource handle by index.
690 * @param index - index of resource, 0 to Count - 1
693 * Resource handle - if found
694 * NULL - if not found
696 OCResourceHandle OCGetResourceHandle(uint8_t index);
699 * Delete resource specified by handle. Deletes resource and all resourcetype and resourceinterface
702 * Note: OCDeleteResource() performs operations similar to OCNotifyAllObservers() to notify all
703 * client observers that "this" resource is being deleted.
705 * @param handle - handle of resource to be deleted
708 * OC_STACK_OK - no errors
709 * OC_STACK_ERROR - stack process error
711 OCStackResult OCDeleteResource(OCResourceHandle handle);
714 * Get the URI of the resource specified by handle.
716 * @param handle - handle of resource
718 * URI string - if resource found
719 * NULL - resource not found
721 const char *OCGetResourceUri(OCResourceHandle handle);
724 * Get the properties of the resource specified by handle.
725 * NOTE: that after a resource is created, the OC_ACTIVE property is set
726 * for the resource by the stack.
728 * @param handle - handle of resource
730 * property bitmap - if resource found
731 * NULL - resource not found
733 uint8_t OCGetResourceProperties(OCResourceHandle handle);
736 * Get the number of resource types of the resource.
738 * @param handle - handle of resource
739 * @param numResourceTypes - pointer to count variable
742 * OC_STACK_OK - no errors
743 * OC_STACK_ERROR - stack process error
745 OCStackResult OCGetNumberOfResourceTypes(OCResourceHandle handle, uint8_t *numResourceTypes);
748 * Get name of resource type of the resource.
750 * @param handle - handle of resource
751 * @param index - index of resource, 0 to Count - 1
754 * resource type name - if resource found
755 * NULL - resource not found
757 const char *OCGetResourceTypeName(OCResourceHandle handle, uint8_t index);
760 * Get the number of resource interfaces of the resource.
762 * @param handle - handle of resource
763 * @param numResources - pointer to count variable
766 * OC_STACK_OK - no errors
767 * OC_STACK_ERROR - stack process error
770 OCStackResult OCGetNumberOfResourceInterfaces(OCResourceHandle handle, uint8_t *numResourceInterfaces);
773 * Get name of resource interface of the resource.
775 * @param handle - handle of resource
776 * @param index - index of resource, 0 to Count - 1
779 * resource interface name - if resource found
780 * NULL - resource not found
782 const char *OCGetResourceInterfaceName(OCResourceHandle handle, uint8_t index);
785 * Get methods of resource interface of the resource.
787 * @param handle - handle of resource
788 * @param index - index of resource, 0 to Count - 1
791 * allowed methods - if resource found
792 * NULL - resource not found
794 uint8_t OCGetResourceInterfaceAllowedMethods(OCResourceHandle handle, uint8_t index);
797 * Get resource handle from the collection resource by index.
799 * @param collectionHandle - handle of collection resource
800 * @param index - index of contained resource, 0 to Count - 1
803 * handle to contained resource - if resource found
804 * NULL - resource not found
806 OCResourceHandle OCGetResourceHandleFromCollection(OCResourceHandle collectionHandle, uint8_t index);
809 * Get the entity handler for a resource.
811 * @param handle - handle of resource
814 * entity handler - if resource found
815 * NULL - resource not found
817 OCEntityHandler OCGetResourceHandler(OCResourceHandle handle);
820 * Notify all registered observers that the resource representation has
821 * changed. If observation includes a query the client is notified only
822 * if the query is valid after the resource representation has changed.
824 * @param handle - handle of resource
827 * OC_STACK_OK - no errors
828 * OC_STACK_NO_RESOURCE - invalid resource handle
829 * OC_STACK_NO_OBSERVERS - no more observers intrested in resource
831 OCStackResult OCNotifyAllObservers(OCResourceHandle handle, OCQualityOfService qos);
834 * Notify specific observers with updated value of representation.
835 * Before this API is invoked by entity handler it has finished processing
836 * queries for the associated observers.
838 * @param handle - handle of resource
839 * @param obsIdList - list of observation ids that need to be notified
840 * @param numberOfIds - number of observation ids included in obsIdList
841 * @param notificationJSONPayload - JSON encoded payload to send in notification
842 * @param qos - desired quality of service of the observation notifications
843 * NOTE: The memory for obsIdList and notificationJSONPayload is managed by the
844 * entity invoking the API. The maximum size of the notification is 1015 bytes
845 * for non-Arduino platforms. For Arduino the maximum size is 247 bytes.
848 * OC_STACK_OK - no errors
849 * OC_STACK_NO_RESOURCE - invalid resource handle
852 OCNotifyListOfObservers (OCResourceHandle handle,
853 OCObservationId *obsIdList,
855 unsigned char *notificationJSONPayload,
856 OCQualityOfService qos);
860 * Send a response to a request.
861 * The response can be a normal, slow, or block (i.e. a response that
862 * is too large to be sent in a single PDU and must span multiple transmissions)
864 * @param response - pointer to structure that contains response parameters
867 * OC_STACK_OK - no errors
869 OCStackResult OCDoResponse(OCEntityHandlerResponse *response);
872 * Cancel a response. Applies to a block response
874 * @param responseHandle - response handle set by stack in OCServerResponse after
875 * OCDoResponse is called
878 * OC_STACK_OK - No errors; Success
879 * OC_STACK_INVALID_PARAM - The handle provided is invalid.
881 OCStackResult OCCancelResponse(OCResponseHandle responseHandle);
886 #endif // __cplusplus
888 #endif /* OCSTACK_H_ */