Tizen(Headed) Native API  6.5
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_check_app_permission (const char *app_id, const char *privilege, ppm_check_result_e *result)
 Checks if an application, with given app_id, has permission to use the given privilege.
int ppm_check_permissions (const char **privileges, size_t privileges_count, ppm_check_result_e *results)
 Checks if an application, which calls this function, has permission to use the given privileges.
int ppm_check_app_permissions (const char *app_id, const char **privileges, size_t privileges_count, ppm_check_result_e *results)
 Checks if an application, with given app_id, has permission to use the given privileges.
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.
int ppm_request_permissions (const char **privileges, size_t privileges_count, ppm_request_multiple_response_cb callback, void *user_data)
 Requests a user's response to obtain permission for using the given privileges.

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 void(* ppm_request_multiple_response_cb )(ppm_call_cause_e cause, const ppm_request_result_e *results, const char **privileges, size_t privileges_count, void *user_data)
 Called when the application receives a response upon calling ppm_request_permissions().

Typedef Documentation

typedef void(* ppm_request_multiple_response_cb)(ppm_call_cause_e cause, const ppm_request_result_e *results, const char **privileges, size_t privileges_count, void *user_data)

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

Since :
5.0
Parameters:
[in]causeThe value representing a reason why this callback has been called.
[in]resultsThe results of a response triggered by calling ppm_request_permissions(). This is a valid value only if the cause parameter is equal to PRIVACY_PRIVILEGE_MANAGER_CALL_CAUSE_ANSWER.
[in]privilegesThe privileges array that has been checked. This pointer is managed by the API and it is valid only in the body of the callback function.
[in]privileges_countThe number of elements in the privileges and results arrays.
[in]user_dataUser specific data, this pointer has been passed to ppm_request_permissions().
See also:
ppm_request_permissions()
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]causeThe value representing a reason why this callback has been called.
[in]resultThe 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]privilegeThe 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_dataUser specific data, this pointer has been passed to ppm_request_permission().
See also:
ppm_request_permission()

Enumeration Type Documentation

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.

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.

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_PERMISSION_DENIED 

Permission denied

PRIVACY_PRIVILEGE_MANAGER_ERROR_UNKNOWN 

Unknown error

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_app_permission ( const char *  app_id,
const char *  privilege,
ppm_check_result_e result 
)

Checks if an application, with given app_id, has permission to use the given privilege.

Warning:
This is not for use by third-party applications.
Since :
5.0
Privilege Level:
platform
Privilege:
http://tizen.org/privilege/permission.check
Parameters:
[in]app_idThe app_id of the app that is to be checked.
[in]privilegeThe privilege that is to be checked.
[out]resultThe result of the privilege check.
Returns:
0 on success, otherwise a negative error value
Return values:
PRIVACY_PRIVILEGE_MANAGER_ERROR_NONESuccessful
PRIVACY_PRIVILEGE_MANAGER_ERROR_IO_ERRORI/O error
PRIVACY_PRIVILEGE_MANAGER_ERROR_INVALID_PARAMETERInvalid parameter
PRIVACY_PRIVILEGE_MANAGER_ERROR_OUT_OF_MEMORYOut of memory
PRIVACY_PRIVILEGE_MANAGER_ERROR_PERMISSION_DENIEDPermission denied
PRIVACY_PRIVILEGE_MANAGER_ERROR_UNKNOWNUnknown error
int ppm_check_app_permissions ( const char *  app_id,
const char **  privileges,
size_t  privileges_count,
ppm_check_result_e results 
)

Checks if an application, with given app_id, has permission to use the given privileges.

Warning:
This is not for use by third-party applications.
Since :
5.0
Privilege Level:
platform
Privilege:
http://tizen.org/privilege/permission.check
Parameters:
[in]app_idThe app_id of the app that is to be checked.
[in]privilegesThe privileges array that is to be checked.
[in]privileges_countThe number of elements in the privileges and results arrays.
[out]resultsThe results of the privilege check. Caller is responsible for allocating this array with proper size and freeing it afterwards.
Returns:
0 on success, otherwise a negative error value
Return values:
PRIVACY_PRIVILEGE_MANAGER_ERROR_NONESuccessful
PRIVACY_PRIVILEGE_MANAGER_ERROR_IO_ERRORI/O error
PRIVACY_PRIVILEGE_MANAGER_ERROR_INVALID_PARAMETERNon unique privileges passed in first argument, privileges_count is more than 100 or other invalid parameter
PRIVACY_PRIVILEGE_MANAGER_ERROR_OUT_OF_MEMORYOut of memory
PRIVACY_PRIVILEGE_MANAGER_ERROR_PERMISSION_DENIEDPermission denied
PRIVACY_PRIVILEGE_MANAGER_ERROR_UNKNOWNUnknown error
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]privilegeThe privilege that is to be checked.
[out]resultThe result of the privilege check.
Returns:
0 on success, otherwise a negative error value
Return values:
PRIVACY_PRIVILEGE_MANAGER_ERROR_NONESuccessful
PRIVACY_PRIVILEGE_MANAGER_ERROR_IO_ERRORI/O error
PRIVACY_PRIVILEGE_MANAGER_ERROR_INVALID_PARAMETERInvalid parameter
PRIVACY_PRIVILEGE_MANAGER_ERROR_OUT_OF_MEMORYOut of memory
PRIVACY_PRIVILEGE_MANAGER_ERROR_UNKNOWNUnknown error
int ppm_check_permissions ( const char **  privileges,
size_t  privileges_count,
ppm_check_result_e results 
)

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

Since :
5.0
Parameters:
[in]privilegesThe privileges array that is to be checked.
[in]privileges_countThe number of elements in the privileges and results arrays.
[out]resultsThe results of the privilege check. Caller is responsible for allocating this array with proper size and freeing it afterwards.
Returns:
0 on success, otherwise a negative error value
Return values:
PRIVACY_PRIVILEGE_MANAGER_ERROR_NONESuccessful
PRIVACY_PRIVILEGE_MANAGER_ERROR_IO_ERRORI/O error
PRIVACY_PRIVILEGE_MANAGER_ERROR_INVALID_PARAMETERNon unique privileges passed in first argument, privileges_count is more than 100 or other invalid parameter
PRIVACY_PRIVILEGE_MANAGER_ERROR_OUT_OF_MEMORYOut of memory
PRIVACY_PRIVILEGE_MANAGER_ERROR_UNKNOWNUnknown 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]privilegeThe given privilege for which a pop-up must be shown.
[in]callbackThe given callback function which will be invoked when the API receives a response.
[in]user_dataUser 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_NONESuccessful
PRIVACY_PRIVILEGE_MANAGER_ERROR_IO_ERRORI/O error
PRIVACY_PRIVILEGE_MANAGER_ERROR_INVALID_PARAMETERInvalid parameter
PRIVACY_PRIVILEGE_MANAGER_ERROR_OUT_OF_MEMORYOut of memory
PRIVACY_PRIVILEGE_MANAGER_ERROR_ALREADY_IN_PROGRESSOperation already in progress
PRIVACY_PRIVILEGE_MANAGER_ERROR_UNKNOWNUnknown error
Postcondition:
ppm_request_response_cb() will be invoked.
See also:
ppm_request_response_cb()
int ppm_request_permissions ( const char **  privileges,
size_t  privileges_count,
ppm_request_multiple_response_cb  callback,
void *  user_data 
)

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

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 privileges. 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_multiple_response_cb(). When a privacy policy for the given privileges has already been resolved, no pop-up will be shown and the service will reply immediately with an appropriate results:
PRIVACY_PRIVILEGE_MANAGER_REQUEST_RESULT_ALLOW_FOREVER
PRIVACY_PRIVILEGE_MANAGER_REQUEST_RESULT_DENY_FOREVER

Since :
5.0
Remarks:
Before calling this function, call ppm_check_permission() or ppm_check_permissions() to check if the application has permission to use the given privileges. This function should be called for each privilege with result PRIVACY_PRIVILEGE_MANAGER_CHECK_RESULT_ASK returned from ppm_check_permission() or ppm_check_permissions().
Parameters:
[in]privilegesThe given privileges array for which a pop-up must be shown.
[in]privileges_countThe number of elements in the privileges array.
[in]callbackThe given callback function which will be invoked when the API receives a response.
[in]user_dataUser 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_NONESuccessful
PRIVACY_PRIVILEGE_MANAGER_ERROR_IO_ERRORI/O error
PRIVACY_PRIVILEGE_MANAGER_ERROR_INVALID_PARAMETERNon unique privileges passed in first argument, privileges_count is more than 100 or other invalid parameter
PRIVACY_PRIVILEGE_MANAGER_ERROR_OUT_OF_MEMORYOut of memory
PRIVACY_PRIVILEGE_MANAGER_ERROR_ALREADY_IN_PROGRESSOperation already in progress
PRIVACY_PRIVILEGE_MANAGER_ERROR_UNKNOWNUnknown error
Postcondition:
ppm_request_multiple_response_cb() will be invoked.
See also:
ppm_request_multiple_response_cb()