Add a guide for CAPI

Change-Id: I9ba183a703e8e73dab22de44b22afe6eeda1f1db

diff --git a/src/capi/doc/guide.txt b/src/capi/doc/guide.txt
new file mode 100644 (file)
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 <privacy_privilege_manager.h>
+
+* Requesting permission
+
+To check if an application has a permission to use a particular privilege
+use ppm_check_permission() function.
+
+<code>
+ppm_check_result_e result;
+const char *privilege = "http://tizen.org/privilege/camera";
+
+int ret = ppm_check_permission(privilege, &result);
+/* handle errors */
+</code>
+
+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()).
+
+<code>
+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;
+    }
+}
+</code>
+
+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.).
+