From: Piotr Sawicki Date: Wed, 19 Jul 2017 11:53:34 +0000 (+0200) Subject: Tailor CAPI to meet the requirements of ACR X-Git-Tag: submit/tizen/20170727.154157~1^2~9 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=1f88a9064e45c85499302c6bf9c9bcda992a5754;p=platform%2Fcore%2Fsecurity%2Faskuser.git Tailor CAPI to meet the requirements of ACR * Adjust doxygen documentation * Change names of functions and enums in CAPI * Adapt the source code to the above changes Change-Id: Iaa2bb8817305c755fb9164a2a8013bff8b509723 --- diff --git a/src/capi/impl/privacy_privilege_manager.c b/src/capi/impl/privacy_privilege_manager.c index 63c04fd..98eed15 100644 --- a/src/capi/impl/privacy_privilege_manager.c +++ b/src/capi/impl/privacy_privilege_manager.c @@ -38,7 +38,7 @@ typedef struct ppm_private_s ppm_private; struct ppm_callback_closure_s { void *user_data; - ppm_popup_response_cb callback; + ppm_request_response_cb callback; }; typedef struct ppm_callback_closure_s ppm_callback_closure; @@ -94,21 +94,21 @@ static ppm_check_result_e ask_user_check_result_to_ppm(askuser_check_result resu return PRIVACY_PRIVILEGE_MANAGER_CHECK_RESULT_DENY; } -static ppm_popup_result_e askuser_client_popup_result_to_ppm(askuser_popup_result result) +static ppm_request_result_e askuser_client_request_result_to_ppm(askuser_popup_result result) { switch (result) { case ASKUSER_POPUP_RESULT_ALLOW_FOREVER: - return PRIVACY_PRIVILEGE_MANAGER_POPUP_RESULT_ALLOW_FOREVER; + return PRIVACY_PRIVILEGE_MANAGER_REQUEST_RESULT_ALLOW_FOREVER; case ASKUSER_POPUP_RESULT_DENY_FOREVER: - return PRIVACY_PRIVILEGE_MANAGER_POPUP_RESULT_DENY_FOREVER; + return PRIVACY_PRIVILEGE_MANAGER_REQUEST_RESULT_DENY_FOREVER; case ASKUSER_POPUP_RESULT_DENY_ONCE: - return PRIVACY_PRIVILEGE_MANAGER_POPUP_RESULT_DENY_ONCE; + return PRIVACY_PRIVILEGE_MANAGER_REQUEST_RESULT_DENY_ONCE; } - return PRIVACY_PRIVILEGE_MANAGER_POPUP_RESULT_DENY_ONCE; + return PRIVACY_PRIVILEGE_MANAGER_REQUEST_RESULT_DENY_ONCE; } -static ppm_call_cause_e askuser_client_popup_cause_to_ppm(askuser_call_cause cause) +static ppm_call_cause_e askuser_client_request_cause_to_ppm(askuser_call_cause cause) { switch (cause) { case ASKUSER_CALL_CAUSE_ANSWER: @@ -209,8 +209,8 @@ static void ppm_popup_response_callback(UNUSED int request_id, askuser_call_caus return; } - ppm_call_cause_e ppm_cause = askuser_client_popup_cause_to_ppm(cause); - ppm_check_result_e ppm_result = askuser_client_popup_result_to_ppm(result); + ppm_call_cause_e ppm_cause = askuser_client_request_cause_to_ppm(cause); + ppm_check_result_e ppm_result = askuser_client_request_result_to_ppm(result); callback_closure->callback(ppm_cause, ppm_result, privilege, callback_closure->user_data); @@ -256,7 +256,7 @@ static int ppm_init_client() } EXPORT_API -int ppm_check_privilege(const char *privilege, ppm_check_result_e *result) +int ppm_check_permission(const char *privilege, ppm_check_result_e *result) { if (!privilege || !result) { return PRIVACY_PRIVILEGE_MANAGER_ERROR_INVALID_PARAMETER; @@ -279,7 +279,7 @@ int ppm_check_privilege(const char *privilege, ppm_check_result_e *result) } EXPORT_API -int ppm_popup_request(const char *privilege, ppm_popup_response_cb callback, void *user_data) +int ppm_request_permission(const char *privilege, ppm_request_response_cb callback, void *user_data) { if (!privilege || !callback) { return PRIVACY_PRIVILEGE_MANAGER_ERROR_INVALID_PARAMETER; diff --git a/src/capi/include/privacy_privilege_manager.h b/src/capi/include/privacy_privilege_manager.h index 18aa2b2..6747a2c 100644 --- a/src/capi/include/privacy_privilege_manager.h +++ b/src/capi/include/privacy_privilege_manager.h @@ -29,91 +29,92 @@ extern "C" { */ /** - * @brief Enumeration of error codes for Privacy Privilege Manager. + * @brief Enumeration for error codes for Privacy Privilege Manager. * @since_tizen 4.0 */ typedef enum { - /**< Successful */ + /** Successful */ PRIVACY_PRIVILEGE_MANAGER_ERROR_NONE = TIZEN_ERROR_NONE, - /**< I/O error */ + /** I/O error */ PRIVACY_PRIVILEGE_MANAGER_ERROR_IO_ERROR = TIZEN_ERROR_IO_ERROR, - /**< Invalid parameter */ + /** Invalid parameter */ PRIVACY_PRIVILEGE_MANAGER_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, - /**< Operation already in progress */ + /** Operation already in progress */ PRIVACY_PRIVILEGE_MANAGER_ERROR_ALREADY_IN_PROGRESS = TIZEN_ERROR_ALREADY_IN_PROGRESS, - /**< Out of memory */ + /** Out of memory */ PRIVACY_PRIVILEGE_MANAGER_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, - /**< Unknown error */ + /** Unknown error */ PRIVACY_PRIVILEGE_MANAGER_ERROR_UNKNOWN = TIZEN_ERROR_UNKNOWN, } ppm_error_e; /** - * @brief Enumeration of privilege check results. + * @brief Enumeration for privilege check results. * @since_tizen 4.0 */ typedef enum { - /**< An application has permission to use a privilege. */ + /** The application has permission to use a privilege. */ PRIVACY_PRIVILEGE_MANAGER_CHECK_RESULT_ALLOW, - /**< An application doesn't have permission to use a privilege. */ + /** The application doesn't have permission to use a privilege. */ PRIVACY_PRIVILEGE_MANAGER_CHECK_RESULT_DENY, - /**< A user has to be asked whether to grant permission to use a privilege. */ + /** The user has to be asked whether to grant permission to use a privilege. */ PRIVACY_PRIVILEGE_MANAGER_CHECK_RESULT_ASK, } ppm_check_result_e; /** - * @brief Enumeration of user decision results for the pop-up resonse callback. + * @brief Enumeration for user decision results for the request permission resonse callback. * @since_tizen 4.0 */ typedef enum { - /**< A user granted permission to use a privilege for an indefinite period of time. */ - PRIVACY_PRIVILEGE_MANAGER_POPUP_RESULT_ALLOW_FOREVER, - /**< A user did not grant permission to use a privilege for an indefinite period of time. */ - PRIVACY_PRIVILEGE_MANAGER_POPUP_RESULT_DENY_FOREVER, - /**< A user did not grant permission to use a privilege once. */ - PRIVACY_PRIVILEGE_MANAGER_POPUP_RESULT_DENY_ONCE, -} ppm_popup_result_e; + /** The user granted permission to use a privilege for an indefinite period of time. */ + PRIVACY_PRIVILEGE_MANAGER_REQUEST_RESULT_ALLOW_FOREVER, + /** The user denied granting permission to use a privilege for an indefinite period of time. */ + PRIVACY_PRIVILEGE_MANAGER_REQUEST_RESULT_DENY_FOREVER, + /** The user denied granting permission to use a privilege once. */ + PRIVACY_PRIVILEGE_MANAGER_REQUEST_RESULT_DENY_ONCE, +} ppm_request_result_e; /** - * @brief Enumeration of status codes for the pop-up response callback. + * @brief Enumeration for status codes for the request permission response callback. * @since_tizen 4.0 */ typedef enum { - /**< Callback was called with a valid answer. */ + /** Callback was called with a valid answer. */ PRIVACY_PRIVILEGE_MANAGER_CALL_CAUSE_ANSWER, - /**< Callback was called because of an error. */ + /** Callback was called because of an error. */ PRIVACY_PRIVILEGE_MANAGER_CALL_CAUSE_ERROR, } ppm_call_cause_e; /** - * @brief Called when an application receives a response upon calling ppm_popup_request(). + * @brief Called when the application receives a response upon calling ppm_request_permission(). * * @since_tizen 4.0 * - * @param[in] cause A value representing the reason why this callback + * @param[in] cause The value representing a reason why this callback * has been called. - * @param[in] result A result of a response triggered by calling ppm_popup_request(). + * @param[in] result The result of a response triggered by calling ppm_request_permission(). * This is a valid value only if the @a cause parameter is equal to - * **PRIVACY_PRIVILEGE_MANAGER_CALL_CAUSE_ANSWER**. - * @param[in] privilege A privilege that has been checked. + * #PRIVACY_PRIVILEGE_MANAGER_CALL_CAUSE_ANSWER. + * @param[in] privilege The privilege that has been checked. This pointer is managed by the API and + * it is valid only in the body of the callback function. * @param[in] user_data User specific data, this pointer has been passed - * to ppm_popup_request(). + * to ppm_request_permission(). * - * @see ppm_popup_request() + * @see ppm_request_permission() */ -typedef void (*ppm_popup_response_cb) (ppm_call_cause_e cause, - ppm_popup_result_e result, - const char *privilege, - void *user_data); +typedef void (*ppm_request_response_cb) (ppm_call_cause_e cause, + ppm_request_result_e result, + const char *privilege, + void *user_data); /** - * @brief Checks if an application, which calls this API, has permission to use a + * @brief Checks if an application, which calls this function, has permission to use the * given privilege. * * @since_tizen 4.0 * - * @param[in] privilege A privilege that is to be checked. - * @param[out] result A result of the privilege check. + * @param[in] privilege The privilege that is to be checked. + * @param[out] result The result of the privilege check. * * @return 0 on success, otherwise a negative error value * @retval #PRIVACY_PRIVILEGE_MANAGER_ERROR_NONE Successful @@ -122,39 +123,40 @@ typedef void (*ppm_popup_response_cb) (ppm_call_cause_e cause, * @retval #PRIVACY_PRIVILEGE_MANAGER_ERROR_OUT_OF_MEMORY Out of memory * @retval #PRIVACY_PRIVILEGE_MANAGER_ERROR_UNKNOWN Unknown error */ -int ppm_check_privilege(const char *privilege, ppm_check_result_e *result); +int ppm_check_permission(const char *privilege, ppm_check_result_e *result); /** - * @brief Requests a user's response to obtain permission for using a given privilege. + * @brief Requests a user's response to obtain permission for using the given privilege. * * @details When this function is called, an underlying service may show an appropriate * UI dialogue box (pop-up) with a question about granting the application access - * to a given privilege. Once a user makes a decision, the service may modify + * to the given privilege. Once a user makes a decision, the service may modify * the privacy policy (when it is a definitive decision). After that, the service * sends the response back to the application. The possible response values are as follows: - * PRIVACY_PRIVILEGE_MANAGER_POPUP_RESULT_ALLOW_FOREVER or - * PRIVACY_PRIVILEGE_MANAGER_POPUP_RESULT_DENY_FOREVER or - * PRIVACY_PRIVILEGE_MANAGER_POPUP_RESULT_DENY_ONCE. - * The application is informed about the user's decision by invoking previously - * registered ppm_popup_response_callback. When a privacy policy for the given privilege - * has already been resolved, no pop-up will be shown and the service will reply - * immediately with an appropriate result: - * PRIVACY_PRIVILEGE_MANAGER_POPUP_RESULT_ALLOW_FOREVER or - * PRIVACY_PRIVILEGE_MANAGER_POPUP_RESULT_DENY_FOREVER. + * #PRIVACY_PRIVILEGE_MANAGER_REQUEST_RESULT_ALLOW_FOREVER\n + * #PRIVACY_PRIVILEGE_MANAGER_REQUEST_RESULT_DENY_FOREVER\n + * #PRIVACY_PRIVILEGE_MANAGER_PREQUEST_RESULT_DENY_ONCE\n + * The application receives #PRIVACY_PRIVILEGE_MANAGER_PREQUEST_RESULT_DENY_ONCE value after + * pressing 'Deny' button while not having selected checkbox 'Don't ask again?', or when + * one of the hardware buttons are pressed: home button or back button. + * The application is informed about the user's decision by invoking ppm_request_response_cb(). + * When a privacy policy for the given privilege has already been resolved, no pop-up will + * be shown and the service will reply immediately with an appropriate result: + * #PRIVACY_PRIVILEGE_MANAGER_REQUEST_RESULT_ALLOW_FOREVER\n + * #PRIVACY_PRIVILEGE_MANAGER_REQUEST_RESULT_DENY_FOREVER\n * * @since_tizen 4.0 * - * @remarks Before calling this function, call ppm_check_privilege() to check - * permission to use a given privilege. If a result of calling ppm_check_privilege() is - * **PRIVACY_PRIVILEGE_MANAGER_CHECK_RESULT_ASK**, an application should call - * this function to determine whether a user allows the application to use - * the privilege or not. + * @remarks Before calling this function, call ppm_check_permission() to check if the application has + * permission to use the given privilege. If a result of calling ppm_check_permission() is + * #PRIVACY_PRIVILEGE_MANAGER_CHECK_RESULT_ASK, the application should call + * this function to determine access to the privilege. * - * @param[in] privilege A privilege for which a pop-up must be shown. - * @param[in] callback A callback function which will be invoked - * when the API receives a pop-up response. + * @param[in] privilege The given privilege for which a pop-up must be shown. + * @param[in] callback The given callback function which will be invoked + * when the API receives a response. * @param[in] user_data User specific data which will be passed to - * the registered callback. + * the given callback. * * @return 0 on success, otherwise a negative error value * @retval #PRIVACY_PRIVILEGE_MANAGER_ERROR_NONE Successful @@ -164,12 +166,12 @@ int ppm_check_privilege(const char *privilege, ppm_check_result_e *result); * @retval #PRIVACY_PRIVILEGE_MANAGER_ERROR_ALREADY_IN_PROGRESS Operation already in progress * @retval #PRIVACY_PRIVILEGE_MANAGER_ERROR_UNKNOWN Unknown error * - * @post ppm_popup_response_cb() will be invoked. - * @see ppm_popup_response_cb() + * @post ppm_request_response_cb() will be invoked. + * @see ppm_request_response_cb() */ -int ppm_popup_request(const char *privilege, - ppm_popup_response_cb callback, - void *user_data); +int ppm_request_permission(const char *privilege, + ppm_request_response_cb callback, + void *user_data); /** * @} diff --git a/src/capi/test/privacy_privilege_manager_test.cpp b/src/capi/test/privacy_privilege_manager_test.cpp index 5138b89..5496cf9 100644 --- a/src/capi/test/privacy_privilege_manager_test.cpp +++ b/src/capi/test/privacy_privilege_manager_test.cpp @@ -114,14 +114,14 @@ void printPrompt(Mode mode) fflush(stdout); } -const char *popupResultToString(ppm_popup_result_e result) +const char *requestResultToString(ppm_request_result_e result) { switch (result) { - case PRIVACY_PRIVILEGE_MANAGER_POPUP_RESULT_ALLOW_FOREVER: + case PRIVACY_PRIVILEGE_MANAGER_REQUEST_RESULT_ALLOW_FOREVER: return "ALLOW_FOREVER"; - case PRIVACY_PRIVILEGE_MANAGER_POPUP_RESULT_DENY_FOREVER: + case PRIVACY_PRIVILEGE_MANAGER_REQUEST_RESULT_DENY_FOREVER: return "DENY_FOREVER"; - case PRIVACY_PRIVILEGE_MANAGER_POPUP_RESULT_DENY_ONCE: + case PRIVACY_PRIVILEGE_MANAGER_REQUEST_RESULT_DENY_ONCE: return "DENY_ONCE"; } @@ -131,8 +131,8 @@ const char *popupResultToString(ppm_popup_result_e result) void printClientHelp() { printf("c check privilege status\n"); - printf("r send popup request\n"); - printf("s send popup request, additionally after receiving DENY it finishes this app\n"); + printf("r send permission request\n"); + printf("s send permission request, additionally after receiving DENY it finishes this app\n"); printf("h print help\n"); printf("q quit\n"); printPrompt(Mode::CLIENT); @@ -441,7 +441,7 @@ public: private: - static void popupResponseCallback(ppm_call_cause_e cause, ppm_popup_result_e result, + static void requestResponseCallback(ppm_call_cause_e cause, ppm_request_result_e result, const char *privilege, void *user_data) { ClientRequest *request = static_cast(user_data); if (request == nullptr) { @@ -453,14 +453,14 @@ private: switch (cause) { case PRIVACY_PRIVILEGE_MANAGER_CALL_CAUSE_ANSWER: - printf("popup response ANSWER: %s\n", popupResultToString(result)); + printf("popup response ANSWER: %s\n", requestResultToString(result)); break; case PRIVACY_PRIVILEGE_MANAGER_CALL_CAUSE_ERROR: printf("popup response ERROR cause: PRIVACY_PRIVILEGE_MANAGER_CALL_CAUSE_ERROR\n"); break; } - if (result == PRIVACY_PRIVILEGE_MANAGER_POPUP_RESULT_DENY_FOREVER && request->m_stopAppAfterDeny) { + if (result == PRIVACY_PRIVILEGE_MANAGER_REQUEST_RESULT_DENY_FOREVER && request->m_stopAppAfterDeny) { g_main_loop_quit(request->m_mainLoop); } @@ -483,7 +483,7 @@ private: printClientHelp(); break; } - err = static_cast(ppm_check_privilege(&buffer[2], &result)); + err = static_cast(ppm_check_permission(&buffer[2], &result)); if (err == PRIVACY_PRIVILEGE_MANAGER_ERROR_NONE) { printClientCheckResult(result); } @@ -502,7 +502,7 @@ private: printf("sending localId: %d privilege: \"%s\"\n", clientRequestId, privilege); request = new ClientRequest{ clientRequestId++, m_mainloop, stopAppAfterDeny }; - err = static_cast(ppm_popup_request(privilege, &AppContext::popupResponseCallback, request)); + err = static_cast(ppm_request_permission(privilege, &AppContext::requestResponseCallback, request)); if (err != PRIVACY_PRIVILEGE_MANAGER_ERROR_NONE) { delete request; }