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 /* NOTE: Insert all new error codes here!*/
193 OC_STACK_PRESENCE_STOPPED = 128,
194 OC_STACK_PRESENCE_TIMEOUT,
195 OC_STACK_PRESENCE_DO_NOT_HANDLE,
198 /* Error status code - END HERE */
202 * Handle to an @ref OCDoResource invocation.
204 typedef void * OCDoHandle;
207 * Handle to an OCResource object owned by the OCStack.
209 typedef void * OCResourceHandle;
211 typedef void * OCRequestHandle;
212 typedef void * OCResponseHandle;
215 * Unique identifier for each observation request. Used when observations are
216 * registered or deregistering. Used by entity handler to signal specific
217 * observers to be notified of resource changes.
218 * There can be maximum of 256 observations per server.
220 typedef uint8_t OCObservationId;
223 * Action associated with observation
226 OC_OBSERVE_REGISTER = 0,
227 OC_OBSERVE_DEREGISTER = 1,
228 OC_OBSERVE_NO_OPTION = 2
232 // Action associated with observation request
233 OCObserveAction action;
234 // Identifier for observation being registered/deregistered
235 OCObservationId obsId;
239 * Possible returned values from entity handler
244 OC_EH_RESOURCE_CREATED,
245 OC_EH_RESOURCE_DELETED,
248 } OCEntityHandlerResult;
250 // following structure will be used to define the vendor specific header options to be included
251 // in communication packets
253 typedef struct OCHeaderOption {
254 // The protocol ID this option applies to
255 OCTransportProtocolID protocolID;
256 // The header option ID which will be added to communication packets
259 uint16_t optionLength;
260 // pointer to its data
261 uint8_t optionData[MAX_HEADER_OPTION_DATA_LENGTH];
265 * Incoming requests handled by the server. Requests are passed in as a parameter to the @ref OCEntityHandler callback API.
266 * @brief The @ref OCEntityHandler callback API must be implemented in the application in order to receive these requests.
269 // Associated resource
270 OCResourceHandle resource;
271 OCRequestHandle requestHandle;
272 // the REST method retrieved from received request PDU
274 // resource query send by client
275 unsigned char * query;
276 // Information associated with observation - valid only when OCEntityHandler
277 // flag includes OC_OBSERVE_FLAG
278 OCObservationInfo obsInfo;
279 // An array of the received vendor specific header options
280 uint8_t numRcvdVendorSpecificHeaderOptions;
281 OCHeaderOption * rcvdVendorSpecificHeaderOptions;
282 // reqJSON is retrieved from the payload of the received request PDU
283 unsigned char * reqJSONPayload;
284 }OCEntityHandlerRequest;
287 * Response from queries to remote servers. Queries are made by calling the @ref OCDoResource API.
290 // Address of remote server
293 // Indicates adaptor type on which the response was received
294 OCConnectivityType connType;
296 // the is the result of our stack, OCStackResult should contain coap/other error codes;
297 OCStackResult result;
298 // If associated with observe, this will represent the sequence of notifications from server.
299 uint32_t sequenceNumber;
300 // resJSONPayload is retrieved from the payload of the received request PDU
301 unsigned const char * resJSONPayload;
302 // An array of the received vendor specific header options
303 uint8_t numRcvdVendorSpecificHeaderOptions;
304 OCHeaderOption rcvdVendorSpecificHeaderOptions[MAX_HEADER_OPTIONS];
308 * Following structure describes the device properties. All non-Null properties will be included
309 * in a device discovery request.
318 char *manufacturerName;
319 char *manufacturerUrl;
321 char *dateOfManufacture;
322 char *platformVersion;
323 char *firmwareVersion;
329 // Request handle is passed to server via the entity handler for each incoming request.
330 // Stack assigns when request is received, server sets to indicate what request response is for
331 OCRequestHandle requestHandle;
332 // New handle for tracking block (or slow) response. Stack assigns, server uses for subsequent calls
333 OCResponseHandle *responseHandle;
335 OCResourceHandle resourceHandle;
336 // Allow the entity handler to pass a result with the response
337 OCEntityHandlerResult ehResult;
338 // this is the pointer to server payload data to be transferred
339 unsigned char *payload;
340 // size of server payload data. I don't think we should rely on null terminated data for size
341 uint16_t payloadSize;
342 // An array of the vendor specific header options the entity handler wishes to use in response
343 uint8_t numSendVendorSpecificHeaderOptions;
344 OCHeaderOption sendVendorSpecificHeaderOptions[MAX_HEADER_OPTIONS];
345 // URI of new resource that entity handler might create
346 unsigned char resourceUri[MAX_URI_LENGTH];
347 // Server sets to true for persistent response buffer, false for non-persistent response buffer
348 uint8_t persistentBufferFlag;
349 } OCEntityHandlerResponse;
352 OC_INIT_FLAG = (1 << 0),
353 OC_REQUEST_FLAG = (1 << 1),
354 OC_OBSERVE_FLAG = (1 << 2)
355 } OCEntityHandlerFlag; //entity_handler_flag_t ;
357 // possible returned values from client application
359 OC_STACK_DELETE_TRANSACTION = 0,
360 OC_STACK_KEEP_TRANSACTION
361 } OCStackApplicationResult;
363 //-----------------------------------------------------------------------------
364 // Callback function definitions
365 //-----------------------------------------------------------------------------
368 * Client applications implement this callback to consume responses received from Servers.
370 typedef OCStackApplicationResult (* OCClientResponseHandler)(void *context, OCDoHandle handle,
371 OCClientResponse * clientResponse);
374 * Client applications using a context pointer implement this callback to delete the
375 * context upon removal of the callback/context pointer from the internal callback-list
377 typedef void (* OCClientContextDeleter)(void *context);
380 * This info is passed from application to OC Stack when initiating a request to Server
384 OCClientResponseHandler cb;
385 OCClientContextDeleter cd;
389 * Application server implementations must implement this callback to consume requests OTA.
390 * Entity handler callback needs to fill the resPayload of the entityHandlerRequest.
392 typedef OCEntityHandlerResult (*OCEntityHandler)
393 (OCEntityHandlerFlag flag, OCEntityHandlerRequest * entityHandlerRequest);
396 * Device Entity handler need to use this call back instead of OCEntityHandler
398 typedef OCEntityHandlerResult (*OCDeviceEntityHandler)
399 (OCEntityHandlerFlag flag, OCEntityHandlerRequest * entityHandlerRequest, char* uri);
401 //-----------------------------------------------------------------------------
402 // Function prototypes
403 //-----------------------------------------------------------------------------
406 * Initialize the OC Stack. Must be called prior to starting the stack.
409 * IP Address of host device
411 * Port of host device
413 * Host device is client, server, or client-server
416 * OC_STACK_OK - no errors
417 * OC_STACK_ERROR - stack init error
419 OCStackResult OCInit(const char *ipAddr, uint16_t port, OCMode mode);
422 * Stop the OC stack. Use for a controlled shutdown.
424 * Note: OCStop() performs operations similar to OCStopPresence(), as well as OCDeleteResource() on
425 * all resources this server is hosting. OCDeleteResource() performs operations similar to
426 * OCNotifyAllObservers() to notify all client observers that the respective resource is being
430 * OC_STACK_OK - no errors
431 * OC_STACK_ERROR - stack not initialized
433 OCStackResult OCStop();
436 * Called in main loop of OC client or server. Allows low-level processing of
440 * OC_STACK_OK - no errors
441 * OC_STACK_ERROR - stack process error
443 OCStackResult OCProcess();
446 * Discover or Perform requests on a specified resource (specified by that Resource's respective
449 * @param handle - @ref OCDoHandle to refer to the request sent out on behalf of
451 * @param method - @ref OCMethod to perform on the resource
452 * @param requiredUri - URI of the resource to interact with
453 * @param referenceUri - URI of the reference resource
454 * @param request - JSON encoded request
455 * @param qos - quality of service. Note that if this API is called on a uri with
456 * the well-known multicast IP address, the qos will be forced to
458 * since it is impractical to send other QOS levels on such addresses.
459 * @param clientApplicationCB- asynchronous callback function that is invoked
460 * by the stack when discovery or resource interaction is complete
461 * @param options - The address of an array containing the vendor specific
462 * header options to be sent with the request
463 * @param numOptions - Number of header options to be included
465 * Note: Presence subscription amendments (ie. adding additional resource type filters by calling
466 * this API again) require the use of the same base URI as the original request to successfully
467 * amend the presence filters.
470 * OC_STACK_OK - no errors
471 * OC_STACK_INVALID_CALLBACK - invalid callback function pointer
472 * OC_STACK_INVALID_METHOD - invalid resource method
473 * OC_STACK_INVALID_URI - invalid required or reference URI
474 * OC_STACK_INVALID_QUERY - number of resource types specified for filtering presence
475 * notifications exceeds @ref MAX_PRESENCE_FILTERS.
478 OCStackResult OCDoResource(OCDoHandle *handle, OCMethod method, const char *requiredUri,
479 const char *referenceUri, const char *request, uint8_t conType,
480 OCQualityOfService qos, OCCallbackData *cbData, OCHeaderOption * options,
483 OCStackResult OCDoResource(OCDoHandle *handle, OCMethod method, const char *requiredUri,
484 const char *referenceUri, const char *request, OCQualityOfService qos,
485 OCCallbackData *cbData, OCHeaderOption * options, uint8_t numOptions);
489 * Cancel a request associated with a specific @ref OCDoResource invocation.
491 * @param handle - Used to identify a specific OCDoResource invocation.
492 * @param qos - used to specify Quality of Service (read below for more info)
493 * @param options- used to specify vendor specific header options when sending
494 * explicit observe cancellation
495 * @param numOptions- Number of header options to be included
498 * OC_STACK_OK - No errors; Success
499 * OC_STACK_INVALID_PARAM - The handle provided is invalid.
501 OCStackResult OCCancel(OCDoHandle handle, OCQualityOfService qos, OCHeaderOption * options,
506 * When operating in @ref OCServer or @ref OCClientServer mode, this API will start sending out
507 * presence notifications to clients via multicast. Once this API has been called with a success,
508 * clients may query for this server's presence and this server's stack will respond via multicast.
510 * Server can call this function when it comes online for the first time, or when it comes back
511 * online from offline mode, or when it re enters network.
513 * @param ttl - Time To Live in seconds
514 * Note: If ttl is '0', then the default stack value will be used (60 Seconds).
517 * OC_STACK_OK - No errors; Success
519 OCStackResult OCStartPresence(const uint32_t ttl);
522 * When operating in @ref OCServer or @ref OCClientServer mode, this API will stop sending out
523 * presence notifications to clients via multicast. Once this API has been called with a success,
524 * this server's stack will not respond to clients querying for this server's presence.
526 * Server can call this function when it is terminating, going offline, or when going
530 * OC_STACK_OK - No errors; Success
533 OCStackResult OCStopPresence();
538 * Set default device entity handler
540 * @param entityHandler - entity handler function that is called by ocstack to handle requests for
541 * any undefined resources or default actions.
542 * if NULL is passed it removes the device default entity handler.
545 * OC_STACK_OK - no errors
546 * OC_STACK_ERROR - stack process error
548 OCStackResult OCSetDefaultDeviceEntityHandler(OCDeviceEntityHandler entityHandler);
551 * Set device information.
553 * @param deviceInfo - Structure passed by the server application containing
554 * the device information.
558 * OC_STACK_OK - no errors
559 * OC_STACK_INVALID_PARAM - invalid paramerter
560 * OC_STACK_ERROR - stack process error
562 OCStackResult OCSetDeviceInfo(OCDeviceInfo deviceInfo);
567 * @param handle - pointer to handle to newly created resource. Set by ocstack. Used to refer to resource
568 * @param resourceTypeName - name of resource type. Example: "core.led"
569 * @param resourceInterfaceName - name of resource interface. Example: "core.rw"
570 * @param uri - URI of the resource. Example: "/a/led"
571 * @param entityHandler - entity handler function that is called by ocstack to handle requests, etc
572 * NULL for default entity handler
573 * @param resourceProperties - properties supported by resource. Example: OC_DISCOVERABLE|OC_OBSERVABLE
576 * OC_STACK_OK - no errors
577 * OC_STACK_ERROR - stack process error
579 OCStackResult OCCreateResource(OCResourceHandle *handle,
580 const char *resourceTypeName,
581 const char *resourceInterfaceName,
583 OCEntityHandler entityHandler,
584 uint8_t resourceProperties);
587 * Create a resource. with host ip address for remote resource
589 * @param handle - pointer to handle to newly created resource. Set by ocstack.
590 * Used to refer to resource
591 * @param resourceTypeName - name of resource type. Example: "core.led"
592 * @param resourceInterfaceName - name of resource interface. Example: "core.rw"
593 * @param host - HOST address of the remote resource. Example: "coap://xxx.xxx.xxx.xxx:xxxxx"
594 * @param uri - URI of the resource. Example: "/a/led"
595 * @param entityHandler - entity handler function that is called by ocstack to handle requests, etc
596 * NULL for default entity handler
597 * @param resourceProperties - properties supported by resource.
598 * Example: OC_DISCOVERABLE|OC_OBSERVABLE
601 * OC_STACK_OK - no errors
602 * OC_STACK_ERROR - stack process error
604 OCStackResult OCCreateResourceWithHost(OCResourceHandle *handle,
605 const char *resourceTypeName,
606 const char *resourceInterfaceName,
609 OCEntityHandler entityHandler,
610 uint8_t resourceProperties);
613 * Add a resource to a collection resource.
615 * @param collectionHandle - handle to the collection resource
616 * @param resourceHandle - handle to resource to be added to the collection resource
619 * OC_STACK_OK - no errors
620 * OC_STACK_ERROR - stack process error
621 * OC_STACK_INVALID_PARAM - invalid collectionhandle
623 OCStackResult OCBindResource(OCResourceHandle collectionHandle, OCResourceHandle resourceHandle);
626 * Remove a resource from a collection resource.
628 * @param collectionHandle - handle to the collection resource
629 * @param resourceHandle - handle to resource to be removed from the collection resource
632 * OC_STACK_OK - no errors
633 * OC_STACK_ERROR - stack process error
634 * OC_STACK_INVALID_PARAM - invalid collectionhandle
636 OCStackResult OCUnBindResource(OCResourceHandle collectionHandle, OCResourceHandle resourceHandle);
639 * Bind a resourcetype to a resource.
641 * @param handle - handle to the resource
642 * @param resourceTypeName - name of resource type. Example: "core.led"
645 * OC_STACK_OK - no errors
646 * OC_STACK_ERROR - stack process error
648 OCStackResult OCBindResourceTypeToResource(OCResourceHandle handle,
649 const char *resourceTypeName);
651 * Bind a resource interface to a resource.
653 * @param handle - handle to the resource
654 * @param resourceInterfaceName - name of resource interface. Example: "core.rw"
657 * OC_STACK_OK - no errors
658 * OC_STACK_ERROR - stack process error
660 OCStackResult OCBindResourceInterfaceToResource(OCResourceHandle handle,
661 const char *resourceInterfaceName);
664 * Bind an entity handler to the resource.
666 * @param handle - handle to the resource that the contained resource is to be bound
667 * @param entityHandler - entity handler function that is called by ocstack to handle requests, etc
669 * OC_STACK_OK - no errors
670 * OC_STACK_ERROR - stack process error
672 OCStackResult OCBindResourceHandler(OCResourceHandle handle, OCEntityHandler entityHandler);
675 * Get the number of resources that have been created in the stack.
677 * @param numResources - pointer to count variable
680 * OC_STACK_OK - no errors
681 * OC_STACK_ERROR - stack process error
684 OCStackResult OCGetNumberOfResources(uint8_t *numResources);
687 * Get a resource handle by index.
689 * @param index - index of resource, 0 to Count - 1
692 * Resource handle - if found
693 * NULL - if not found
695 OCResourceHandle OCGetResourceHandle(uint8_t index);
698 * Delete resource specified by handle. Deletes resource and all resourcetype and resourceinterface
701 * Note: OCDeleteResource() performs operations similar to OCNotifyAllObservers() to notify all
702 * client observers that "this" resource is being deleted.
704 * @param handle - handle of resource to be deleted
707 * OC_STACK_OK - no errors
708 * OC_STACK_ERROR - stack process error
710 OCStackResult OCDeleteResource(OCResourceHandle handle);
713 * Get the URI of the resource specified by handle.
715 * @param handle - handle of resource
717 * URI string - if resource found
718 * NULL - resource not found
720 const char *OCGetResourceUri(OCResourceHandle handle);
723 * Get the properties of the resource specified by handle.
724 * NOTE: that after a resource is created, the OC_ACTIVE property is set
725 * for the resource by the stack.
727 * @param handle - handle of resource
729 * property bitmap - if resource found
730 * NULL - resource not found
732 uint8_t OCGetResourceProperties(OCResourceHandle handle);
735 * Get the number of resource types of the resource.
737 * @param handle - handle of resource
738 * @param numResourceTypes - pointer to count variable
741 * OC_STACK_OK - no errors
742 * OC_STACK_ERROR - stack process error
744 OCStackResult OCGetNumberOfResourceTypes(OCResourceHandle handle, uint8_t *numResourceTypes);
747 * Get name of resource type of the resource.
749 * @param handle - handle of resource
750 * @param index - index of resource, 0 to Count - 1
753 * resource type name - if resource found
754 * NULL - resource not found
756 const char *OCGetResourceTypeName(OCResourceHandle handle, uint8_t index);
759 * Get the number of resource interfaces of the resource.
761 * @param handle - handle of resource
762 * @param numResources - pointer to count variable
765 * OC_STACK_OK - no errors
766 * OC_STACK_ERROR - stack process error
769 OCStackResult OCGetNumberOfResourceInterfaces(OCResourceHandle handle, uint8_t *numResourceInterfaces);
772 * Get name of resource interface of the resource.
774 * @param handle - handle of resource
775 * @param index - index of resource, 0 to Count - 1
778 * resource interface name - if resource found
779 * NULL - resource not found
781 const char *OCGetResourceInterfaceName(OCResourceHandle handle, uint8_t index);
784 * Get methods of resource interface of the resource.
786 * @param handle - handle of resource
787 * @param index - index of resource, 0 to Count - 1
790 * allowed methods - if resource found
791 * NULL - resource not found
793 uint8_t OCGetResourceInterfaceAllowedMethods(OCResourceHandle handle, uint8_t index);
796 * Get resource handle from the collection resource by index.
798 * @param collectionHandle - handle of collection resource
799 * @param index - index of contained resource, 0 to Count - 1
802 * handle to contained resource - if resource found
803 * NULL - resource not found
805 OCResourceHandle OCGetResourceHandleFromCollection(OCResourceHandle collectionHandle, uint8_t index);
808 * Get the entity handler for a resource.
810 * @param handle - handle of resource
813 * entity handler - if resource found
814 * NULL - resource not found
816 OCEntityHandler OCGetResourceHandler(OCResourceHandle handle);
819 * Notify all registered observers that the resource representation has
820 * changed. If observation includes a query the client is notified only
821 * if the query is valid after the resource representation has changed.
823 * @param handle - handle of resource
826 * OC_STACK_OK - no errors
827 * OC_STACK_NO_RESOURCE - invalid resource handle
828 * OC_STACK_NO_OBSERVERS - no more observers intrested in resource
830 OCStackResult OCNotifyAllObservers(OCResourceHandle handle, OCQualityOfService qos);
833 * Notify specific observers with updated value of representation.
834 * Before this API is invoked by entity handler it has finished processing
835 * queries for the associated observers.
837 * @param handle - handle of resource
838 * @param obsIdList - list of observation ids that need to be notified
839 * @param numberOfIds - number of observation ids included in obsIdList
840 * @param notificationJSONPayload - JSON encoded payload to send in notification
841 * @param qos - desired quality of service of the observation notifications
842 * NOTE: The memory for obsIdList and notificationJSONPayload is managed by the
843 * entity invoking the API. The maximum size of the notification is 1015 bytes
844 * for non-Arduino platforms. For Arduino the maximum size is 247 bytes.
847 * OC_STACK_OK - no errors
848 * OC_STACK_NO_RESOURCE - invalid resource handle
851 OCNotifyListOfObservers (OCResourceHandle handle,
852 OCObservationId *obsIdList,
854 unsigned char *notificationJSONPayload,
855 OCQualityOfService qos);
859 * Send a response to a request.
860 * The response can be a normal, slow, or block (i.e. a response that
861 * is too large to be sent in a single PDU and must span multiple transmissions)
863 * @param response - pointer to structure that contains response parameters
866 * OC_STACK_OK - no errors
868 OCStackResult OCDoResponse(OCEntityHandlerResponse *response);
871 * Cancel a response. Applies to a block response
873 * @param responseHandle - response handle set by stack in OCServerResponse after
874 * OCDoResponse is called
877 * OC_STACK_OK - No errors; Success
878 * OC_STACK_INVALID_PARAM - The handle provided is invalid.
880 OCStackResult OCCancelResponse(OCResponseHandle responseHandle);
885 #endif // __cplusplus
887 #endif /* OCSTACK_H_ */