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)
void requestPermission (DOMString privilege, PermissionSuccessCallback successCallback, optional ErrorCallback? errorCallback)
PermissionSuccessCallback
void onsuccess (PermissionRequestResult result, DOMString privilege)

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);
    void requestPermission(DOMString privilege, PermissionSuccessCallback 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
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

2.3. 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

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);
    void requestPermission(DOMString privilege, PermissionSuccessCallback successCallback, optional ErrorCallback? errorCallback)
                           raises(WebAPIException);
  };
  [Callback=FunctionOnly, NoInterfaceObject] interface PermissionSuccessCallback {
    void onsuccess(PermissionRequestResult result, DOMString privilege);
  };
};
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.