X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=resource%2Fcsdk%2Fstack%2Finclude%2Finternal%2Focobserve.h;h=f5fc6c1f6416bfddecda909a360aa75ba1c6bf09;hb=27eeaa55061c3b51cec80e64cfcba38e25281d77;hp=712a93634518fab9406ad419288dd89c36bda0d9;hpb=612b0e0a79106ac3dcaf7b49630fb3072a4eba34;p=platform%2Fupstream%2Fiotivity.git diff --git a/resource/csdk/stack/include/internal/ocobserve.h b/resource/csdk/stack/include/internal/ocobserve.h index 712a936..f5fc6c1 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,63 +18,110 @@ // //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= +/** + * @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**/ - CAConnectivityType_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, - OCResourceType *resourceType, OCQualityOfService qos); + OCPresenceTrigger trigger, OCResourceType *resourceType, OCQualityOfService qos); #else /** * Create an observe response and send to all observers in the observe list. @@ -83,6 +130,7 @@ OCStackResult SendAllObserverNotification (OCMethod method, OCResource *resPtr, * @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, @@ -92,17 +140,18 @@ OCStackResult SendAllObserverNotification (OCMethod method, OCResource *resPtr, /** * 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, + const OCRepPayload *payload, uint32_t maxAge, OCQualityOfService qos); /** @@ -113,7 +162,8 @@ void DeleteObserverList(); /** * 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); @@ -121,15 +171,15 @@ 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, @@ -139,8 +189,8 @@ OCStackResult AddObserver (const char *resUri, uint8_t tokenLength, OCResource *resHandle, OCQualityOfService qos, - const CAAddress_t *addressInfo, - CAConnectivityType_t connectivityType); + OCPayloadFormat acceptFormat, + const OCDevAddr *devAddr); /** * Delete observer with specified token from list of observers. @@ -153,33 +203,63 @@ OCStackResult AddObserver (const char *resUri, */ 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. */ @@ -190,14 +270,15 @@ CreateObserveHeaderOption (CAHeaderOption_t **caHdrOpt, 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. */ @@ -206,5 +287,12 @@ 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