From d894ff4c814045f28620970fa8397281495ecc87 Mon Sep 17 00:00:00 2001 From: Zofia Abramowska Date: Tue, 24 Feb 2015 20:29:29 +0100 Subject: [PATCH] Add description of simple check request in asynch API Change-Id: I63e3da83cb2cc8284b3c56ce52f88a85b6feac90 --- src/include/cynara-client-async.h | 105 ++++++++++++++++++++++++++++++++------ src/include/cynara-client.h | 6 +-- 2 files changed, 91 insertions(+), 20 deletions(-) diff --git a/src/include/cynara-client-async.h b/src/include/cynara-client-async.h index 1a165c2..0fa37d8 100644 --- a/src/include/cynara-client-async.h +++ b/src/include/cynara-client-async.h @@ -58,10 +58,11 @@ typedef enum { * Values indicating the reason of cynara_response_callback call. * * \var cynara_async_call_cause::CYNARA_CALL_CAUSE_ANSWER - * Callback was called due to response to previous cynara_async_create_request() call. + * Callback was called due to response to previous cynara_async_create_request() or + * cynara_async_create_simple_request() call. * * \var cynara_async_call_cause::CYNARA_CALL_CAUSE_CANCEL - * Callback was called due to request cancelation with cynara_async_cancel_request() call. + * Callback was called due to request cancellation with cynara_async_cancel_request() call. * * \var cynara_async_call_cause::CYNARA_CALL_CAUSE_FINISH * Callback was called due to cynara_async_finish() call. @@ -77,8 +78,8 @@ typedef enum { } cynara_async_call_cause; /** - * \brief Response_callback is registered once in cynara_async_create_request() - * and will be triggered exactly once in 4 kind of situations: + * \brief Response_callback is registered once in cynara_async_create_request() or + * cynara_async_create_simple_request() and will be triggered exactly once in 4 kinds of situations: * 1) after response is received from cynara service (CYNARA_CALL_CAUSE_ANSWER) * 2) when request is canceled with cynara_async_cancel_request() (CYNARA_CALL_CAUSE_CANCEL) * 3) when request was pending for response, but cynara_async_finish() was called @@ -90,9 +91,10 @@ typedef enum { * cynara_async_finish() will be ignored if called from within this callback. * * \param[in] check_id Number identifying check request. Number is generated in - * cynara_async_create_request() and returned to user. It can be used to match - * response with sent request. - * Number is valid since cynara_async_create_request() call till callback call. + * cynara_async_create_request() or cynara_async_create_simple_request and returned to + * user. It can be used to match response with sent request. + * Number is valid since cynara_async_create_request() call or + * cynara_async_create_simple_request call till callback call. * After that the number can be reused by cynara to run new request. * \param[in] cause Cause of triggering this callback. * \param[in] response Response for created request. Should be ignored if cause is not @@ -108,8 +110,8 @@ typedef void (*cynara_response_callback) (cynara_check_id check_id, cynara_async /** * \brief Callback used by cynara async API when status of cynara socket is changed in - * cynara_async_initialize(), cynara_async_create_request(), cynara_async_process(), - * cynara_async_cancel_request() or cynara_async_finish(). + * cynara_async_initialize(), cynara_async_create_request(), cynara_async_create_simple_request(), + * cynara_async_process(), cynara_async_cancel_request() or cynara_async_finish(). * File descriptor changes every time cynara library connects or disconnects cynara service. * Status change is triggered when check_request or cancel needs to be send to * cynara service or sending data has finished and there is nothing more to send to cynara @@ -389,11 +391,11 @@ int cynara_async_check_cache(cynara_async *p_cynara, const char *client, const c * will be triggered in event loop after socket is ready to send request to cynara service. * After request is sent and there is nothing more to send to cynara service, status will change * back to CYNARA_STATUS_FOR_READ. Status changes are delivered with cynara_status_callback. - * When function is succesfully called unique check_id is returned. It is used for matching + * When function is successfully called unique check_id is returned. It is used for matching * generated request with response, that will be received by registered callback. * Because check_id is coded as 16-bit unsigned integer, there can be only 2^16 = 65536 pending * requests. When response callback is called either because of getting answer or because - * of cancel check_id used for taht request is released and can be reused by cynara library. + * of cancel check_id used for that request is released and can be reused by cynara library. * When maximum of pending requests is reached cynara_async_create_request() fails with * CYNARA_API_MAX_PENDING_REQUESTS error code. * @@ -409,7 +411,7 @@ int cynara_async_check_cache(cynara_async *p_cynara, const char *client, const c * cynara_async_initialize(). * Call cynara_async_cancel_request() to cancel pending request. * Call cynara_async_process() to receive response. - * It is guaranteed that if cynara_async_create_request() function suceeds (CYNARA_API_SUCCESS) + * It is guaranteed that if cynara_async_create_request() function succeeds (CYNARA_API_SUCCESS) * a callback will be called exactly once and that it will receive user_response_data. * If function fails (returns negative error code) request won't be generated and won't be pending, * callback function won't be ever called and user_response_data won't be remembered by library. @@ -441,6 +443,73 @@ int cynara_async_create_request(cynara_async *p_cynara, const char *client, cynara_check_id *p_check_id, cynara_response_callback callback, void *user_response_data); + +/** + * \par Description: + * Creates simple access check request to cynara service for (potential) permission to take some + * action or access a resource. + * Set callback and user_response_data to be called and passed when request processing is finished. + * + * \par Purpose: + * This API should be used for a quick check if a user running application identified as client + * has access to a given privilege. + * Response can be received with cynara_async_process(). + * Check id is returned to pair request with response for canceling purposes. + * + * \par Typical use case: + * An application may use this API to check if it has (potential) permission to take some action + * or access resource in future (permissions may rarely change). The typical use would be to disable + * or hide some of functionalities if they probably could not be used anyways. + * + * \par Method of function operation: + * This function is very similar to cynara_async_create_request() with the difference, that in case + * of answer not being one of CYNARA_API_PERMISSION_DENIED or CYNARA_API_PERMISSION_ALLOWED, + * no external application will be consulted. Instead, CYNARA_API_ACCESS_NOT_RESOLVED is returned, + * meaning, that only creating full request through cynara_async_create_request API would yield + * eventual answer. + * If access permission cannot be acquired without usage of external agents, callback can be + * called with CYNARA_CALL_CAUSE_ANSWER and response value being CYNARA_API_ACCESS_NOT_RESOLVED. + * + * \par Sync (or) Async: + * This is a synchronous API. + * + * \par Thread-safety: + * This function is NOT thread-safe. If functions from described API are called by multithreaded + * application from different threads, they must be put into mutex protected critical section. + * + * \par Important notes: + * Call to cynara_async_create_simple_request() needs cynara_async structure to be created first + * with cynara_async_initialize(). + * Call cynara_async_cancel_request() to cancel pending request. + * Call cynara_async_process() to send request and receive response. + * The answer will be taken from cynara's database without consulting any external applications. + * If the answer cannot be resolved in one of CYNARA_API_ACCESS_ALLOWED or + * CYNARA_API_ACCESS_DENIED without communicating with external application, response returned + * through callback will have value CYNARA_API_ACCESS_NOT_RESOLVED. + * + * \param[in] p_cynara cynara_async structure. + * \param[in] client Application or process identifier. + * \param[in] client_session Client defined session. + * \param[in] user User of running client. + * \param[in] privilege Privilege that is a subject of a check. + * \param[out] p_check_id Placeholder for check id. If NULL, then no check_id is returned. + * \param[in] callback Function called when matching response is received. + * If NULL then no callback will be called when response, cancel, finish + * or service not availble error happens. + * \param[in] user_response_data User specific data, passed to callback is being only stored by + * library. Cynara library does not take any actions on this pointer, except for giving + * it back to user in cynara_response_callback. + * Can be NULL. + * + * \return CYNARA_API_SUCCESS on success, + * CYNARA_API_MAX_PENDING_REQUESTS on too much pending requests, + * or other negative error code on error. + */ +int cynara_async_create_simple_request(cynara_async *p_cynara, const char *client, + const char *client_session, const char *user, + const char *privilege, cynara_check_id *p_check_id, + cynara_response_callback callback, void *user_response_data); + /** * \par Description: * Process events that appeared on cynara socket. @@ -449,7 +518,8 @@ int cynara_async_create_request(cynara_async *p_cynara, const char *client, * Process events after they appear on cynara socket. * * \par Typical use case: - * After request was queued with cynara_async_create_request() this API will return response. + * After request was queued with cynara_async_create_request() or + * cynara_async_create_simple_request() this API will return response. * When event loop will return readiness on cynara socket, client should use this API. * * \par Method of function operation: @@ -483,19 +553,20 @@ int cynara_async_process(cynara_async *p_cynara); /** * \par Description: - * Cancel request created by cynara_async_create_request(). + * Cancel request created by cynara_async_create_request() or cynara_async_create_simple_request(). * * \par Purpose: * This API should be used to cancel pending check request, - * created by cynara_async_create_request(). + * created by cynara_async_create_request() or cynara_async_create_simple_request(). * * \par Typical use case: * When cynara client is no longer interested in receiving an answer. * Same check_id value should be used to identify proper request as was generated during - * request creation with cynara_async_create_request(). + * request creation with cynara_async_create_request() or cynara_async_create_simple_request(). * * \par Method of function operation: - * Cancels request created by cynara_async_create_request() call. + * Cancels request created by cynara_async_create_request() or cynara_async_create_simple_request() + * call. * cynara_status_callback callback may be triggered to be able to send cancel to cynara. * cynara_response_callback callback will be triggered with with * cynara_async_call_cause::CYNARA_CALL_CAUSE_CANCEL as cause param. diff --git a/src/include/cynara-client.h b/src/include/cynara-client.h index a617246..89a8e7b 100644 --- a/src/include/cynara-client.h +++ b/src/include/cynara-client.h @@ -252,9 +252,9 @@ int cynara_check(cynara *p_cynara, const char *client, const char *client_sessio * * \par Method of function operation: * This function is very similar to cynara_check() with the difference, that in case of answer not - * being one of CYNARA_API_PERMISSION_DENIED or CYNARA_API_PERMISSION_ALLOWED, no external - * application will be consulted. Instead, CYNARA_API_ACCESS_NOT_RESOLVED is returned, meaning, - * that only running full cynara_check() API would yield eventual answer. + * being one of CYNARA_API_ACCESS_DENIED or CYNARA_API_ACCESS_ALLOWED, no external application will + * be consulted. Instead, CYNARA_API_ACCESS_NOT_RESOLVED is returned, meaning, that only running + * full cynara_check() API would yield eventual answer. * Similarly, like in cynara_check(), argument client_session can be used to distinguish client * sessions and grant possibility to yield answer from cache. * -- 2.7.4