* 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.).