-//******************************************************************
+//********************************************************************
//
// Copyright 2014 Intel Mobile Communications GmbH All Rights Reserved.
//
//
//-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
+/**
+ * @file
+ *
+ * This file contains the data structure and APIs for registered resource as an observer.
+ *
+ */
+
+
#ifndef OC_OBSERVE_H
#define OC_OBSERVE_H
-// Sequence number is a 24 bit field, per
-// https://tools.ietf.org/html/draft-ietf-core-observe-16
-#define MAX_SEQUENCE_NUMBER (0xFFFFFF)
+/** Maximum number of observers to reach */
#define MAX_OBSERVER_FAILED_COMM (2)
+
+/** Maximum number of observers to reach for resources with low QOS */
#define MAX_OBSERVER_NON_COUNT (3)
/**
- * This information is stored for each registered observer.
+ * MAX_OBSERVER_TTL_SECONDS sets the maximum time to live (TTL) for notification.
+ * 60 sec/min * 60 min/hr * 24 hr/day
+ */
+#define MAX_OBSERVER_TTL_SECONDS (60 * 60 * 24)
+
+#define MILLISECONDS_PER_SECOND (1000)
+
+/**
+ * Data structure to hold informations for each registered observer.
*/
typedef struct ResourceObserver
{
- // Observation Identifier for request
+ /** Observation Identifier for request.*/
OCObservationId observeId;
- // URI of observed resource
+
+ /** URI of observed resource.*/
char *resUri;
- // Query
+
+ /** Query.*/
char *query;
- //token for the observe request
+
+ /** token for the observe request.*/
CAToken_t token;
- //token length for the observe request
+
+ /** token length for the observe request.*/
uint8_t tokenLength;
- // Resource handle
+
+ /** Resource handle.*/
OCResource *resource;
- //TODO bundle it in Endpoint structure(address, uri, type, secured)
- /** Remote Endpoint address **/
- CAAddress_t addressInfo;
- /** Connectivity of the endpoint**/
- CATransportType_t connectivityType;
- // Quality of service of the request
+
+ /** Remote Endpoint. */
+ OCDevAddr devAddr;
+
+ /** Quality of service of the request.*/
OCQualityOfService qos;
- // number of times the server failed to reach the observer
+
+ /** number of times the server failed to reach the observer.*/
uint8_t failedCommCount;
- // number of times the server sent NON notifications
+
+ /** number of times the server sent NON notifications.*/
uint8_t lowQosCount;
- // force the qos value to CON
+
+ /** force the qos value to CON.*/
uint8_t forceHighQos;
- // next node in this list
+
+ /** The TTL for this callback. TTL is set to 24 hours.
+ * A server send a notification in a confirmable message every 24 hours.
+ * This prevents a client that went away or is no logger interested
+ * from remaining in the list of observers indefinitely.*/
+ uint32_t TTL;
+
+ /** next node in this list.*/
struct ResourceObserver *next;
+
+ /** requested payload encoding format. */
+ OCPayloadFormat acceptFormat;
+
} ResourceObserver;
+/**
+ * Initialize observer list.
+ *
+ * @return ::OC_STACK_OK on success, some other value upon failure.
+ */
+OCStackResult InitializeObserverList();
+
+/**
+ * Terminate observer list.
+ */
+void TerminateObserverList();
+
#ifdef WITH_PRESENCE
/**
* Create an observe response and send to all observers in the observe list.
*
- * @param method RESTful method.
- * @param resPtr Observed resource.
- * @param maxAge Time To Live (in seconds) of observation.
- * @param resourceType Resource type. Allows resource type name to be added to response.
- * @param qos Quality of service of resource.
+ * @param method RESTful method.
+ * @param resPtr Observed resource.
+ * @param maxAge Time To Live (in seconds) of observation.
+ * @param resourceType Resource type. Allows resource type name to be added to response.
+ * @param qos Quality of service of resource.
+ *
* @return ::OC_STACK_OK on success, some other value upon failure.
*/
OCStackResult SendAllObserverNotification (OCMethod method, OCResource *resPtr, uint32_t maxAge,
* @param resPtr Observed resource.
* @param maxAge Time To Live (in seconds) of observation.
* @param qos Quality of service of resource.
+ *
* @return ::OC_STACK_OK on success, some other value upon failure.
*/
OCStackResult SendAllObserverNotification (OCMethod method, OCResource *resPtr, uint32_t maxAge,
/**
* Notify specific observers with updated value of representation.
*
- * @param resource Observed resource
- * @param obsIdList List of observation ids that need to be notified.
- * @param numberOfIds Number of observation ids included in obsIdList.
- * @param notificationJSONPayload - JSON encoded payload to send in notification.
- * @param maxAge Time To Live (in seconds) of observation.
- * @param qos Desired quality of service of the observation notifications.
+ * @param resource Observed resource.
+ * @param obsIdList List of observation ids that need to be notified.
+ * @param numberOfIds Number of observation ids included in obsIdList.
+ * @param notificationJSONPayload JSON encoded payload to send in notification.
+ * @param maxAge Time To Live (in seconds) of observation.
+ * @param qos Desired quality of service of the observation notifications.
+ *
* @return ::OC_STACK_OK on success, some other value upon failure.
*/
OCStackResult SendListObserverNotification (OCResource * resource,
- OCObservationId *obsIdList, uint8_t numberOfIds,
- const char *notificationJSONPayload, uint32_t maxAge,
+ OCObservationId *obsIdList, uint16_t numberOfIds,
+ const OCRepPayload *payload, uint32_t maxAge,
OCQualityOfService qos);
/**
/**
* Create a unique observation ID.
*
- * @param observationId Pointer to generated ID.
+ * @param observationId Pointer to generated ID.
+ *
* @return ::OC_STACK_OK on success, some other value upon failure.
*/
OCStackResult GenerateObserverId (OCObservationId *observationId);
/**
* Add observer for a resource.
*
- * @param resUri Resource URI string.
- * @param query Query string.
- * @param obsId Observation ID.
- * @param token Request token.
- * @param tokenLength Length of token.
- * @param resHandle Resource handle.
- * @param qos Quality of service of observation.
- * @param addressInfo Address of observer.
- * @param connectivityType Connection type.
+ * @param resUri Resource URI string.
+ * @param query Query string.
+ * @param obsId Observation ID.
+ * @param token Request token.
+ * @param tokenLength Length of token.
+ * @param resHandle Resource handle.
+ * @param qos Quality of service of observation.
+ * @param devAddr Device address.
+ *
* @return ::OC_STACK_OK on success, some other value upon failure.
*/
OCStackResult AddObserver (const char *resUri,
uint8_t tokenLength,
OCResource *resHandle,
OCQualityOfService qos,
- const CAAddress_t *addressInfo,
- CATransportType_t connectivityType);
+ OCPayloadFormat acceptFormat,
+ const OCDevAddr *devAddr);
/**
* Delete observer with specified token from list of observers.
*/
OCStackResult DeleteObserverUsingToken (CAToken_t token, uint8_t tokenLength);
+ /**
+ * Delete observer with device address from list of observers.
+ * Free memory that was allocated for the observer in the list.
+ *
+ * @param devAddr Device's address.
+ *
+ * @return ::OC_STACK_OK on success, some other value upon failure.
+ */
+OCStackResult DeleteObserverUsingDevAddr(const OCDevAddr *devAddr);
+
+/**
+ * Delete all observers of a resource.
+ *
+ * @param resource Handle of resource whose observers needs to be deleted.
+ *
+ * @return ::OC_STACK_OK on success, some other value upon failure.
+ */
+OCStackResult DeleteObserverUsingResource(OCResource *res);
+
/**
* Search the list of observers for the specified token.
*
- * @param token Token to search for.
- * @param tokenLength Length of token.
+ * @param token Token to search for.
+ * @param tokenLength Length of token.
*
* @return Pointer to found observer.
+ * This is copy of observer, caller must release its memory using FreeObserver().
*/
ResourceObserver* GetObserverUsingToken (const CAToken_t token, uint8_t tokenLength);
/**
* Search the list of observers for the specified observe ID.
*
- * @param observeId Observer ID to search for
+ * @param observeId Observer ID to search for.
*
* @return Pointer to found observer.
+ * This is copy of observer, caller must release its memory using FreeObserver().
*/
ResourceObserver* GetObserverUsingId (const OCObservationId observeId);
/**
- * Add observe header option to a request.
+ * Search the list of observers for the specified observe ID.
*
- * @param caHdrOpt Target request CA header option.
- * @param ocHdrOpt Pointer to existing options.
- * @param numOptions Number of existing options.
- * @param observeFlag Register/de-register observation. Should be either
- * ::OC_OBSERVE_REGISTER or ::OC_OBSERVE_DEREGISTER.
+ * @param observeId Observer ID to search for.
+ *
+ * @return true if observer found matched with observer ID, otherwise false.
+ */
+bool IsObserverAvailable (const OCObservationId observeId);
+
+/**
+ * Add observe header option to a request.
+ *
+ * @param caHdrOpt Target request CA header option.
+ * @param ocHdrOpt Pointer to existing options.
+ * @param numOptions Number of existing options.
+ * @param observeFlag Register/de-register observation. Should be either
+ * ::OC_OBSERVE_REGISTER or ::OC_OBSERVE_DEREGISTER.
*
* @return ::OC_STACK_OK on success, some other value upon failure.
*/
uint8_t observeFlag);
/**
- * Copy the observe option from a received request
+ * Copy the observe option from a received request.
*
- * @param observationOption Pointer to observe option value. Should be either
- * ::OC_OBSERVE_REGISTER, ::OC_OBSERVE_DEREGISTER, or ::OC_OBSERVE_NO_OPTION if observe not found.
+ * @param observationOption Pointer to observe option value. Should be either
+ * ::OC_OBSERVE_REGISTER, ::OC_OBSERVE_DEREGISTER, or
+ * ::OC_OBSERVE_NO_OPTION if observe not found.
*
- * @param options Options in received request. Observe option is removed if found.
- * @param numOptions Number of options in the received request. Decremented if observe option is
- * extracted.
+ * @param options Options in received request. Observe option is removed if found.
+ * @param numOptions Number of options in the received request. Decremented if observe
+ * option is extracted.
*
* @return ::OC_STACK_OK on success, some other value upon failure.
*/
CAHeaderOption_t *options,
uint8_t * numOptions);
+/**
+ * Free memory associated with observer.
+ *
+ * @param obsNode Observer to be freed.
+ */
+void FreeObserver (ResourceObserver* obsNode);
+
#endif //OC_OBSERVE_H