From 8e2ab341c5fa4c91ffbc808236ceb10b46f81cd8 Mon Sep 17 00:00:00 2001 From: Piotr Sawicki Date: Wed, 19 Jul 2017 09:34:49 +0200 Subject: [PATCH] Add a guide for CAPI Change-Id: I9ba183a703e8e73dab22de44b22afe6eeda1f1db --- src/capi/doc/guide.txt | 91 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100644 src/capi/doc/guide.txt diff --git a/src/capi/doc/guide.txt b/src/capi/doc/guide.txt new file mode 100644 index 0000000..e3ed3ce --- /dev/null +++ b/src/capi/doc/guide.txt @@ -0,0 +1,91 @@ +* Requesting permission for using privacy privileges + +The Privacy Privilege Manager provides functions to determine the status of privacy +privileges during the application run-time. Previously (Tizen 3.0), the pop-up +requesting user's consent to use a particular privilege was triggered by the first +access to a service. Now, the developer may decide in which moment of the application +life-cycle he or she wants to show the pop-up. It may be at the application start-up, +or it may be at the moment when some additional capabilities are to be used. +For example, we can imagine a notepad application which has the ability not only +to make text notes but also to take photos. The access to the camera is not +required to use the application, but when it is needed, the user may be asked if +the application may obtain permission to use a camera. + +* Prerequisites + +To enable your application to use Privacy Privilege Manager include this header file: + +#include + +* Requesting permission + +To check if an application has a permission to use a particular privilege +use ppm_check_permission() function. + + +ppm_check_result_e result; +const char *privilege = "http://tizen.org/privilege/camera"; + +int ret = ppm_check_permission(privilege, &result); +/* handle errors */ + + +When the result of calling this function is PRIVACY_PRIVILEGE_MANAGER_CHECK_RESULT_ALLOW +or PRIVACY_PRIVILEGE_MANAGER_CHECK_RESULT_DENY then the status of the privacy +privilege is resolved and the application needs to react appropriately to it. +For example, the application may have to disable or enable some UI elements. In +case of PRIVACY_PRIVILEGE_MANAGER_CHECK_RESULT_DENY and PRIVACY_PRIVILEGE_MANAGER_CHECK_RESULT_ASK +the application is not allowed to access a service which requires this particular +privilege. Any attempt to use such a service without user's consent will fail. + +When the result of the privilege check is PRIVACY_PRIVILEGE_MANAGER_CHECK_RESULT_ASK +then the application has to call ppm_request_permission() to request a user +permission for using a given privilege. The result of the user decision is passed to +ppm_request_response_cb() callback (the callback argument of ppm_request_permission()). + + +if (ret != PRIVACY_PRIVILEGE_MANAGER_ERROR_NONE) { + switch (result) { + case PRIVACY_PRIVILEGE_MANAGER_CHECK_RESULT_ALLOW: + /* refresh UI */ + break; + case PRIVACY_PRIVILEGE_MANAGER_CHECK_RESULT_DENY: + /* refresh UI */ + break; + case PRIVACY_PRIVILEGE_MANAGER_CHECK_RESULT_ASK: + ret = ppm_request_permission(privilege, app_request_response_cb, NULL); + break; + } +} + +void app_request_response_cb(ppm_call_cause_e cause, ppm_request_result_e result, + const char *privilege, void *user_data) +{ + if (cause == PRIVACY_PRIVILEGE_MANAGER_CALL_CAUSE_ERROR) { + /* log errors */ + return; + } + + switch (result) { + case PRIVACY_PRIVILEGE_MANAGER_REQUEST_RESULT_ALLOW_FOREVER: + /* enable UI elements, refresh view */ + break; + case PRIVACY_PRIVILEGE_MANAGER_REQUEST_RESULT_DENY_FOREVER: + /* show an appropriate message and/or stop the application */ + break; + case PRIVACY_PRIVILEGE_MANAGER_REQUEST_RESULT_DENY_ONCE: + /* update UI */ + break; + } +} + + +After receiving a user response, the application should react appropriately to +user's decision. For example, it may finish its execution, show +some message or redraw UI. The ppm_check_permission() and ppm_request_permission() +functions should be called from the context of the application's main event loop. +When a developer wants to resolve privileges at the application startup, these +functions should be called from the resume event callback. Another solution is +to call these functions from UI event callbacks in reaction to user interaction +(button clicks etc.). + -- 2.7.4