X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=resource%2Fcsdk%2Fstack%2Finclude%2Finternal%2Focobserve.h;h=2fa67241fb3936dfc919efea0ca56dd6c74ae729;hb=refs%2Fchanges%2F72%2F173472%2F3;hp=a84bb9881095c4d2a0c3e0ef2572ede48e65dbe7;hpb=a177361f54d118bab4db1300379b4c7d812eafb9;p=platform%2Fupstream%2Fiotivity.git diff --git a/resource/csdk/stack/include/internal/ocobserve.h b/resource/csdk/stack/include/internal/ocobserve.h index a84bb98..2fa6724 100644 --- a/resource/csdk/stack/include/internal/ocobserve.h +++ b/resource/csdk/stack/include/internal/ocobserve.h @@ -1,4 +1,4 @@ -//****************************************************************** +//******************************************************************** // // Copyright 2014 Intel Mobile Communications GmbH All Rights Reserved. // @@ -18,71 +18,272 @@ // //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= +/** + * @file + * + * This file contains the data structure and APIs for registered resource as an observer. + * + */ + + #ifndef OC_OBSERVE_H #define OC_OBSERVE_H -/* In CoAP sequence number is a 24 bit field */ -#define MAX_SEQUENCE_NUMBER (0xFFFFFF) -#define OC_RESOURCE_OBSERVE_REGISTER (0) -#define OC_RESOURCE_OBSERVE_DEREGISTER (1) -#define OC_RESOURCE_NO_OBSERVE (2) +/** 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) -#define OC_OBSERVER_NOT_INTERESTED (0) -#define OC_OBSERVER_STILL_INTERESTED (1) -#define OC_OBSERVER_FAILED_COMM (2) +/** + * 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) -/* This information is stored for each registerd observer */ -typedef struct ResourceObserver { - // Observation Identifier for request +/** + * Data structure to hold informations for each registered observer. + */ +typedef struct ResourceObserver +{ + /** Observation Identifier for request.*/ OCObservationId observeId; - // URI of observed resource - unsigned char *resUri; - // Query - unsigned char *query; - // CoAP token for the observe request - OCCoAPToken token; - // Resource handle + + /** URI of observed resource.*/ + char *resUri; + + /** Query.*/ + char *query; + + /** token for the observe request.*/ + CAToken_t token; + + /** token length for the observe request.*/ + uint8_t tokenLength; + + /** Resource handle.*/ OCResource *resource; - // IP address & port of client registered for observe - OCDevAddr *addr; - // 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; -OCStackResult OCObserverStatus(OCCoAPToken * token, uint8_t status); +/** + * Initialize observer list. + * + * @return ::OC_STACK_OK on success, some other value upon failure. + */ +OCStackResult InitializeObserverList(); + +/** + * Terminate observer list. + */ +void TerminateObserverList(); -OCStackResult ProcessObserveRequest (OCResource *resource, OCRequest *request); +#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. + * + * @return ::OC_STACK_OK on success, some other value upon failure. + */ +OCStackResult SendAllObserverNotification (OCMethod method, OCResource *resPtr, uint32_t maxAge, + OCPresenceTrigger trigger, OCResourceType *resourceType, OCQualityOfService qos); +#else +/** + * 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 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, + OCQualityOfService qos); +#endif -OCStackResult SendObserverNotification (OCMethod method, OCResource *resPtr, uint32_t maxAge, - OCResourceType *resourceType, OCQualityOfService qos); +/** + * 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. + * + * @return ::OC_STACK_OK on success, some other value upon failure. + */ +OCStackResult SendListObserverNotification (OCResource * resource, + OCObservationId *obsIdList, uint8_t numberOfIds, + const OCRepPayload *payload, uint32_t maxAge, + OCQualityOfService qos); +/** + * Delete all observers in the observe list. + */ void DeleteObserverList(); +/** + * Create a unique observation 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 devAddr Device address. + * + * @return ::OC_STACK_OK on success, some other value upon failure. + */ OCStackResult AddObserver (const char *resUri, const char *query, OCObservationId obsId, - OCCoAPToken *token, - OCDevAddr *addr, + CAToken_t token, + uint8_t tokenLength, OCResource *resHandle, - OCQualityOfService qos); + OCQualityOfService qos, + OCPayloadFormat acceptFormat, + const OCDevAddr *devAddr); -OCStackResult DeleteObserverUsingToken (OCCoAPToken * token); +/** + * Delete observer with specified token from list of observers. + * Free memory that was allocated for the observer in the list. + * + * @param token Token to search for. + * @param tokenLength Length of token. + * + * @return ::OC_STACK_OK on success, some other value upon failure. + */ + OCStackResult DeleteObserverUsingToken (CAToken_t token, uint8_t tokenLength); -ResourceObserver* GetObserverUsingToken (const OCCoAPToken * token); + /** + * 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); +/** + * Search the list of observers for the specified 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. + * + * @return Pointer to found observer. + * This is copy of observer, caller must release its memory using FreeObserver(). + */ ResourceObserver* GetObserverUsingId (const OCObservationId observeId); +/** + * Search the list of observers for the specified observe ID. + * + * @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. + */ +OCStackResult +CreateObserveHeaderOption (CAHeaderOption_t **caHdrOpt, + OCHeaderOption *ocHdrOpt, + uint8_t numOptions, + uint8_t observeFlag); + +/** + * 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 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. + */ +OCStackResult +GetObserveHeaderOption (uint32_t * observationOption, + 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 +