PrivacyPrivilege API

This Privacy Privilege API defines a set of APIs that manage the permissions for using a privacy-related privileges of application.

A Tizen Web application has privileges defined in config.xml file, but for legal purposes, in case of privacy-related privileges, there could be a need of asking user directly with proper pop-up. List of privacy-related privileges is available on Security and API Privileges page. Privacy Privilege API allows:

  • Checking if user granted permission for using a privacy-related privilege.
  • Requesting pop-up about giving permission for using privacy-related privilege.

Since: 4.0

Table of Contents

Summary of Interfaces and Methods

Interface Method
PrivacyPrivilegeManagerObject
PrivacyPrivilegeManager
PermissionType checkPermission (DOMString privilege)
PrivilegeStatus[] checkPermissions (DOMString[] privileges)
void requestPermission (DOMString privilege, PermissionSuccessCallback successCallback, optional ErrorCallback? errorCallback)
void requestPermissions (DOMString[] privileges, PermissionRequestSuccessCallback successCallback, optional ErrorCallback? errorCallback)
PrivilegeStatus
RequestStatus
PermissionSuccessCallback
void onsuccess (PermissionRequestResult result, DOMString privilege)
PermissionRequestSuccessCallback
void onsuccess (RequestStatus[] result)

1. Type Definitions

1.1. PermissionType

Specifies the type of given permission. 
  enum PermissionType { "PPM_ALLOW", "PPM_DENY", "PPM_ASK" };

Since: 4.0

The following types are supported:

  • PPM_ALLOW - The application has been granted permission to use a privacy-related privilege.
  • PPM_DENY - The application has not been granted permission to use a privacy-related privilege.
  • PPM_ASK - The user has to be asked whether to grant permission to use a privacy-related privilege.

1.2. PermissionRequestResult

Specifies the result of a permission request. 
  enum PermissionRequestResult { "PPM_ALLOW_FOREVER", "PPM_DENY_FOREVER", "PPM_DENY_ONCE" };

Since: 4.0

The following types are supported:

  • PPM_ALLOW_FOREVER - The user granted permission to use a privacy-related privilege for an indefinite period of time.
  • PPM_DENY_FOREVER - The user denied granting permission to use a privacy-related privilege for an indefinite period of time.
  • PPM_DENY_ONCE - The user denied granting permission to use a privacy-related privilege once.

2. Interfaces

2.1. PrivacyPrivilegeManagerObject

This interface defines what is instantiated for the Privacy Privilege API by the Tizen object from the Tizen Platform. 
  [NoInterfaceObject] interface PrivacyPrivilegeManagerObject {
    readonly attribute PrivacyPrivilegeManager ppm;
  };
  Tizen implements PrivacyPrivilegeManagerObject;

Since: 4.0

tizen.ppm object is available to manage the user permissions to use privacy-related privileges in your Web application.

Attributes

  • readonly PrivacyPrivilegeManager ppm
    Object representing a privacy privilege manager.

    Since: 4.0

2.2. PrivacyPrivilegeManager

This is the top-level interface for the Privacy Privilege API that manages permissions for using privileges in application. 
  [NoInterfaceObject] interface PrivacyPrivilegeManager {
    PermissionType checkPermission(DOMString privilege) raises(WebAPIException);
    PrivilegeStatus[] checkPermissions(DOMString[] privileges) raises(WebAPIException);
    void requestPermission(DOMString privilege, PermissionSuccessCallback successCallback, optional ErrorCallback? errorCallback)
                           raises(WebAPIException);
    void requestPermissions(DOMString[] privileges, PermissionRequestSuccessCallback successCallback,
                            optional ErrorCallback? errorCallback) raises(WebAPIException);
  };

Since: 4.0

Methods

checkPermission
Method allows checking current state of user's permission for using a privilege. 
PermissionType checkPermission(DOMString privilege);

Since: 4.0

For privileges not listed in application's config.xml file (or not privacy-related), always returns PPM_DENY.

Parameters:

  • privilege: Privilege to be checked against user's permission.

Return value:

    PermissionType: State of user's permission for using specified privilege.

Exceptions:

  • WebAPIException

    • with error type AbortError, if any platform error occurs.

    • with error type InvalidValuesError, if the input parameter contains an invalid value, for example empty string.

Code example:

var permission = tizen.ppm.checkPermission("http://tizen.org/privilege/contact.read");
console.log("Current state of permission is: " + permission);

Output example:

Current state of permission is: PPM_ALLOW
checkPermissions
Method allows checking current state of user's permission for using privileges. 
PrivilegeStatus[] checkPermissions(DOMString[] privileges);

Since: 5.0

For privileges not listed in application's config.xml file (or not privacy-related), always returns PPM_DENY. Maximum number of privileges that can be passed to array is 100.

Parameters:

  • privileges: List of privileges to be checked against user's permission.

Return value:

    PrivilegeStatus[]: The array of status of user's permission for using specified privileges.

Exceptions:

  • WebAPIException

    • with error type AbortError, if any platform error occurs.

    • with error type InvalidValuesError, if the input parameter contains an invalid value, for example if there is more than 100 privileges in privileges array.

Code example:

var privileges = ["http://tizen.org/privilege/filesystem.read", "http://tizen.org/privilege/alarm"];
var state = tizen.ppm.checkPermissions(privileges);
for (v in state)
{
  console.log("Current state of " + state[v].privilege + " is " + state[v].type);
}

Output example:

Current state of http://tizen.org/privilege/filesystem.read is PPM_ALLOW
Current state of http://tizen.org/privilege/alarm is PPM_DENY
requestPermission
This method allows launching pop-up for asking user to directly grant permission for given privilege. 
void requestPermission(DOMString privilege, PermissionSuccessCallback successCallback, optional ErrorCallback? errorCallback);

Since: 4.0

Requesting permission for privileges not listed in application's config.xml file (or not privacy-related) will not trigger any pop-up, instead the successCallback will be executed with PPM_DENY_FOREVER.

When the user has already decided to permanently allow or deny access to use a given privilege, subsequent calls of this function will result in immediate invocation of successCallback with an appropriate result: PPM_ALLOW_FOREVER or PPM_DENY_FOREVER. Additionally the asking pop-up will not be shown.

The errorCallback is launched with these error types:

  • AbortError - If any platform error occurs.

Parameters:

  • privilege: Privilege to be asked about user's permission.
  • successCallback: Function to be invoked, if the request operation succeeded.
  • errorCallback [optional] [nullable]: Function to be invoked, if the request operation failed.

Exceptions:

  • WebAPIException

    • with error type AbortError, if any platform error occurs.

    • with error type InvalidValuesError, if any of the input parameters contain an invalid value, for example empty string.

    • with error type TypeMismatchError, if any of the input parameters is not compatible with the expected type for that parameter.

Code example:

/* Defines the error callback. */
function errorCallback(error)
{
  console.log("The following error occurred: " + error.name);
}

/* Defines PermissionSuccessCallback. */
function permissionSuccess(result, privilege)
{
  console.log("User's action for privilege " + privilege + " was to: " + result);
}
tizen.ppm.requestPermission(
    "http://tizen.org/privilege/contact.read", permissionSuccess, errorCallback);

Output example:

User's action for privilege http://tizen.org/privilege/contact.read was to: PPM_ALLOW_FOREVER
requestPermissions
This method allows launching pop-up for asking user to directly grant permission for given privileges. 
void requestPermissions(DOMString[] privileges, PermissionRequestSuccessCallback successCallback,
                        optional ErrorCallback? errorCallback);

Since: 5.0

Requesting permission for privileges not listed in application's config.xml file (or not privacy-related) will not trigger any pop-up, instead the successCallback will be executed with PPM_DENY_FOREVER.

When the user has already decided to permanently allow or deny access to use a given privilege, subsequent calls of this function will result in immediate invocation of successCallback with an appropriate result: PPM_ALLOW_FOREVER or PPM_DENY_FOREVER. Additionally the asking pop-up will not be shown.

Maximum number of privileges that can be passed to array is 100.

The errorCallback is launched with these error types:

  • AbortError - If any platform error occurs.

Parameters:

  • privileges: List of privileges to be asked about user's permission.
  • successCallback: Function to be invoked, if the request operation succeeded.
  • errorCallback [optional] [nullable]: Function to be invoked, if the request operation failed.

Exceptions:

  • WebAPIException

    • with error type AbortError, if any platform error occurs.

    • with error type InvalidValuesError, if any of the input parameters contain an invalid value, for example if there is more than 100 privileges in privileges array.

    • with error type TypeMismatchError, if any of the input parameters is not compatible with the expected type for that parameter.

Code example:

/* Defines the error callback. */
function errorCallback(error)
{
  console.log("The following error occurred: " + error.name);
}

/* Defines PermissionRequestSuccessCallback. */
function permissionRequestSuccess(result)
{
  for (v in result)
  {
    console.log(
        "User's action for privilege " + result[v].privilege + " was to: " + result[v].result);
  }
}

var privileges =
    ["http://tizen.org/privilege/contact.read", "http://tizen.org/privilege/contact.write"];
tizen.ppm.requestPermissions(privileges, permissionRequestSuccess, errorCallback);

Output example:

User's action for privilege http://tizen.org/privilege/contact.read was to: PPM_ALLOW_FOREVER
User's action for privilege http://tizen.org/privilege/contact.write was to: PPM_ALLOW_FOREVER

2.3. PrivilegeStatus

The PrivilegeStatus interface is an abstract interface for status of user permissions. 
  [NoInterfaceObject] interface PrivilegeStatus {
    readonly attribute DOMString privilege;
    readonly attribute PermissionType type;
  };

Since: 5.0

Attributes

  • readonly DOMString privilege
    Privilege which was checked against user's permission.

    Since: 5.0

  • readonly PermissionType type
    State of user's permission for using specified privilege.

    Since: 5.0

2.4. RequestStatus

The RequestStatus interface is an abstract interface for status of user request permissions. 
  [NoInterfaceObject] interface RequestStatus {
    readonly attribute DOMString privilege;
    readonly attribute PermissionRequestResult result;
  };

Since: 5.0

Attributes

  • readonly DOMString privilege
    The requested privilege.

    Since: 5.0

  • readonly PermissionRequestResult result
    Result of the action performed by user.

    Since: 5.0

2.5. PermissionSuccessCallback

The PermissionSuccessCallback interface that implements the success callback used in the asynchronous operation for requesting permission for using privilege. 
  [Callback=FunctionOnly, NoInterfaceObject] interface PermissionSuccessCallback {
    void onsuccess(PermissionRequestResult result, DOMString privilege);
  };

Since: 4.0

Methods

onsuccess
Called when the permission for using privilege was requested successfully. 
void onsuccess(PermissionRequestResult result, DOMString privilege);

Since: 4.0

Parameters:

  • result: Result of the action performed by user.
  • privilege: The requested privilege.

Code example:

/* Defines PermissionSuccessCallback. */
function permissionSuccess(result, privilege)
{
  console.log("User's action for privilege " + privilege + " was to: " + result);
}
tizen.ppm.requestPermission("http://tizen.org/privilege/callhistory.read", permissionSuccess);

Output example:

User's action for privilege http://tizen.org/privilege/callhistory.read was to: PPM_DENY_ONCE

2.6. PermissionRequestSuccessCallback

The PermissionRequestSuccessCallback interface implements the success callback used in the asynchronous operation of requesting permissions for using privilege. 
  [Callback=FunctionOnly, NoInterfaceObject] interface PermissionRequestSuccessCallback {
    void onsuccess(RequestStatus[] result);
  };

Since: 5.0

Methods

onsuccess
Called when the permission for privileges was requested successfully. 
void onsuccess(RequestStatus[] result);

Since: 5.0

Parameters:

  • result: Result of the action performed by user.

Code example:

/* Defines the error callback. */
function errorCallback(error)
{
  console.log("The following error occurred: " + error.name);
}

/* Defines PermissionRequestSuccessCallback. */
function permissionRequestSuccess(result)
{
  for (v in result)
  {
    console.log(
        "User's action for privilege " + result[v].privilege + " was to: " + result[v].result);
  }
}

var privileges =
    ["http://tizen.org/privilege/contact.read", "http://tizen.org/privilege/contact.write"];
tizen.ppm.requestPermissions(privileges, permissionRequestSuccess, errorCallback);

Output example:

User's action for privilege http://tizen.org/privilege/contact.read was to: PPM_ALLOW_FOREVER
User's action for privilege http://tizen.org/privilege/contact.write was to: PPM_ALLOW_FOREVER

3. Full WebIDL

module PrivacyPrivilege {
  enum PermissionType { "PPM_ALLOW", "PPM_DENY", "PPM_ASK" };
  enum PermissionRequestResult { "PPM_ALLOW_FOREVER", "PPM_DENY_FOREVER", "PPM_DENY_ONCE" };
  Tizen implements PrivacyPrivilegeManagerObject;
  [NoInterfaceObject] interface PrivacyPrivilegeManagerObject {
    readonly attribute PrivacyPrivilegeManager ppm;
  };
  [NoInterfaceObject] interface PrivacyPrivilegeManager {
    PermissionType checkPermission(DOMString privilege) raises(WebAPIException);
    PrivilegeStatus[] checkPermissions(DOMString[] privileges) raises(WebAPIException);
    void requestPermission(DOMString privilege, PermissionSuccessCallback successCallback, optional ErrorCallback? errorCallback)
                           raises(WebAPIException);
    void requestPermissions(DOMString[] privileges, PermissionRequestSuccessCallback successCallback,
                            optional ErrorCallback? errorCallback) raises(WebAPIException);
  };
  [NoInterfaceObject] interface PrivilegeStatus {
    readonly attribute DOMString privilege;
    readonly attribute PermissionType type;
  };
  [NoInterfaceObject] interface RequestStatus {
    readonly attribute DOMString privilege;
    readonly attribute PermissionRequestResult result;
  };
  [Callback=FunctionOnly, NoInterfaceObject] interface PermissionSuccessCallback {
    void onsuccess(PermissionRequestResult result, DOMString privilege);
  };
  [Callback=FunctionOnly, NoInterfaceObject] interface PermissionRequestSuccessCallback {
    void onsuccess(RequestStatus[] result);
  };
};
Except as noted, this content - excluding the Code Examples - is licensed under Creative Commons Attribution 3.0 and all of the Code Examples contained herein are licensed under BSD-3-Clause.
For details, see the Content License.