Privacy Privilege Manager

---

The Privacy Privilege Manager API provides functions for retrieving and determining application's permissions for privacy privileges.

Required Header

#include <privacy_privilege_manager.h>

Overview

This library allows an application to check if it has permission to use a given privilege. Furthermore, it allows an application to determine permission by displaying a UI dialogue box (pop-up) and requesting a user response.

Functions
int	ppm_check_permission (const char *privilege, ppm_check_result_e *result)
	Checks if an application, which calls this function, has permission to use the given privilege.
int	ppm_request_permission (const char *privilege, ppm_request_response_cb callback, void *user_data)
	Requests a user's response to obtain permission for using the given privilege.
Typedefs
typedef void(*	ppm_request_response_cb )(ppm_call_cause_e cause, ppm_request_result_e result, const char *privilege, void *user_data)
	Called when the application receives a response upon calling ppm_request_permission().

---

Typedef Documentation

typedef void(* ppm_request_response_cb)(ppm_call_cause_e cause, ppm_request_result_e result, const char *privilege, void *user_data)

Called when the application receives a response upon calling ppm_request_permission().

Since :

4.0

Parameters:

[in]	cause	The value representing a reason why this callback has been called.
[in]	result	The result of a response triggered by calling ppm_request_permission(). This is a valid value only if the cause parameter is equal to PRIVACY_PRIVILEGE_MANAGER_CALL_CAUSE_ANSWER.
[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.
[in]	user_data	User specific data, this pointer has been passed to ppm_request_permission().

See also:

ppm_request_permission()

---

Enumeration Type Documentation

enum ppm_call_cause_e

Enumeration for status codes of a permission request.

Since :

4.0

Enumerator:

PRIVACY_PRIVILEGE_MANAGER_CALL_CAUSE_ANSWER	Callback was called with a valid answer.
PRIVACY_PRIVILEGE_MANAGER_CALL_CAUSE_ERROR	Callback was called because of an error.

enum ppm_check_result_e

Enumeration for results of a permission check.

Since :

4.0

Enumerator:

PRIVACY_PRIVILEGE_MANAGER_CHECK_RESULT_ALLOW	The application has permission to use a privilege.
PRIVACY_PRIVILEGE_MANAGER_CHECK_RESULT_DENY	The application doesn't have permission to use a privilege.
PRIVACY_PRIVILEGE_MANAGER_CHECK_RESULT_ASK	The user has to be asked whether to grant permission to use a privilege.

enum ppm_error_e

Enumeration for error codes of Privacy Privilege Manager.

Since :

4.0

Enumerator:

PRIVACY_PRIVILEGE_MANAGER_ERROR_NONE	Successful
PRIVACY_PRIVILEGE_MANAGER_ERROR_IO_ERROR	I/O error
PRIVACY_PRIVILEGE_MANAGER_ERROR_INVALID_PARAMETER	Invalid parameter
PRIVACY_PRIVILEGE_MANAGER_ERROR_ALREADY_IN_PROGRESS	Operation already in progress
PRIVACY_PRIVILEGE_MANAGER_ERROR_OUT_OF_MEMORY	Out of memory
PRIVACY_PRIVILEGE_MANAGER_ERROR_UNKNOWN	Unknown error

enum ppm_request_result_e

Enumeration for results of a permission request.

Since :

4.0

Enumerator:

PRIVACY_PRIVILEGE_MANAGER_REQUEST_RESULT_ALLOW_FOREVER	The user granted 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 for an indefinite period of time.
PRIVACY_PRIVILEGE_MANAGER_REQUEST_RESULT_DENY_ONCE	The user denied granting permission to use a privilege once.

---

Function Documentation

int ppm_check_permission	(	const char *	privilege,
		ppm_check_result_e *	result
	)

Checks if an application, which calls this function, has permission to use the given privilege.

Since :

4.0

Parameters:

[in]	privilege	The privilege that is to be checked.
[out]	result	The result of the privilege check.

Returns:

0 on success, otherwise a negative error value

Return values:

PRIVACY_PRIVILEGE_MANAGER_ERROR_NONE	Successful
PRIVACY_PRIVILEGE_MANAGER_ERROR_IO_ERROR	I/O error
PRIVACY_PRIVILEGE_MANAGER_ERROR_INVALID_PARAMETER	Invalid parameter
PRIVACY_PRIVILEGE_MANAGER_ERROR_OUT_OF_MEMORY	Out of memory
PRIVACY_PRIVILEGE_MANAGER_ERROR_UNKNOWN	Unknown error

int ppm_request_permission	(	const char *	privilege,
		ppm_request_response_cb	callback,
		void *	user_data
	)

Requests a user's response to obtain permission for using the given privilege.

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 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_REQUEST_RESULT_ALLOW_FOREVER
PRIVACY_PRIVILEGE_MANAGER_REQUEST_RESULT_DENY_FOREVER
PRIVACY_PRIVILEGE_MANAGER_REQUEST_RESULT_DENY_ONCE
The application receives PRIVACY_PRIVILEGE_MANAGER_REQUEST_RESULT_DENY_ONCE value after pressing 'Deny' button while not having selected the 'Don't ask again?' checkbox. If the device has the home and back buttons, pressing either of them gives the PRIVACY_PRIVILEGE_MANAGER_REQUEST_RESULT_DENY_ONCE response. 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
PRIVACY_PRIVILEGE_MANAGER_REQUEST_RESULT_DENY_FOREVER

Since :

4.0

Remarks:

Before calling this function, call ppm_check_permission() to check if the application has permission to use the given privilege. If the 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.

Parameters:

[in]	privilege	The given privilege for which a pop-up must be shown.
[in]	callback	The given callback function which will be invoked when the API receives a response.
[in]	user_data	User specific data which will be passed to the given callback.

Returns:

0 on success, otherwise a negative error value

Return values:

PRIVACY_PRIVILEGE_MANAGER_ERROR_NONE	Successful
PRIVACY_PRIVILEGE_MANAGER_ERROR_IO_ERROR	I/O error
PRIVACY_PRIVILEGE_MANAGER_ERROR_INVALID_PARAMETER	Invalid parameter
PRIVACY_PRIVILEGE_MANAGER_ERROR_OUT_OF_MEMORY	Out of memory
PRIVACY_PRIVILEGE_MANAGER_ERROR_ALREADY_IN_PROGRESS	Operation already in progress
PRIVACY_PRIVILEGE_MANAGER_ERROR_UNKNOWN	Unknown error

Postcondition:

ppm_request_response_cb() will be invoked.

See also:

ppm_request_response_cb()