Package API

This API provides functionalities to install or uninstall packages, and retrieve information about installed packages.

It also provides a listener method so that an application can be notified when there is a change on the installed packages. For more information on the Package features, see Package Guide.

Since: 2.1

Summary of Interfaces and Methods

Interface	Method
PackageManagerObject
PackageManager	void install (DOMString packageFileURI, PackageProgressCallback progressCallback, optional ErrorCallback? errorCallback) void uninstall (PackageId id, PackageProgressCallback progressCallback, optional ErrorCallback? errorCallback) void getPackagesInfo (PackageInformationArraySuccessCallback successCallback, optional ErrorCallback? errorCallback) PackageInformation getPackageInfo (optional PackageId? id) void setPackageInfoEventListener (PackageInformationEventCallback eventCallback) void unsetPackageInfoEventListener ()
PackageInformation
PackageInformationArraySuccessCallback	void onsuccess (PackageInformation[] informationArray)
PackageProgressCallback	void onprogress (PackageId id, short progress) void oncomplete (PackageId id)
PackageInformationEventCallback	void oninstalled (PackageInformation info) void onupdated (PackageInformation info) void onuninstalled (PackageId id)

1. Type Definitions

1.1. PackageId

A unique ID for an installed package.

typedef DOMString PackageId;

Since: 2.1

2. Interfaces

2.1. PackageManagerObject

This interface defines what is instantiated by the Tizen object from the Tizen Platform.

[NoInterfaceObject] interface PackageManagerObject {

    readonly attribute PackageManager package;

};

Tizen implements PackageManagerObject;

Since: 2.1

The tizen.package object allows access to Package API functionality.

2.2. PackageManager

This interface defines the package manager.

[NoInterfaceObject] interface PackageManager {
    void install(DOMString packageFileURI,
                  PackageProgressCallback progressCallback,
                  optional ErrorCallback? errorCallback) raises(WebAPIException);

    void uninstall(PackageId id, 
                    PackageProgressCallback progressCallback,
                    optional ErrorCallback? errorCallback) raises(WebAPIException);

    void getPackagesInfo(PackageInformationArraySuccessCallback successCallback,
                          optional ErrorCallback? errorCallback) raises(WebAPIException);

    PackageInformation getPackageInfo(optional PackageId? id) raises(WebAPIException);

    void setPackageInfoEventListener(PackageInformationEventCallback eventCallback) raises(WebAPIException);

    void unsetPackageInfoEventListener() raises(WebAPIException);
};

Since: 2.1

Methods

install

Installs a package with a specified file on a device.

void install(DOMString packageFileURI, PackageProgressCallback progressCallback, optional ErrorCallback? errorCallback);

Since: 2.1

This API provides a way to notify the progress and completion of an installation request through PackageProgressCallback.

The ErrorCallback() is launched with these error types:

• NotFoundError - If the package is not found at the specified location.
• UnknownError - If it is not allowed to install the package by the platform or any other platform error occurs.

Privilege level: platform

Privilege: http://tizen.org/privilege/packagemanager.install

Remark : Virtual path cannot be used for the parameter. First, you need to convert any virtual path to a file URI path using the resolve function in the Filesystem API before passing it to the function.

Parameters:

• packageFileURI: The location of the package to install
• progressCallback: The method to invoke when the installation is in progress or has been completed
• errorCallback [optional] [nullable]: The method to invoke when an error occurs

Exceptions:

• WebAPIException
  • with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.
  • with error type SecurityError, if the application does not have the privilege to call this method.

Code example:

var onInstallation = {
    onprogress: function(packageId, percentage) {
        console.log("On installation(" + packageId + ") : progress(" + percentage + ")");
    },
    oncomplete: function(packageId) {
        console.log("Installation(" + packageId + ") Complete");
    }
}

var onError = function (err) {
    console.log("Error occurred on installation : " + err.name);
}

// Let's assume that the "test.wgt" file exists in the downloads directory
tizen.filesystem.resolve("downloads/test.wgt",
    function (file) {
        console.log("file URI : " + file.toURI());
        tizen.package.install(file.toURI(), onInstallation, onError);
    },
    function (err) {
        console.log("Error occurred on resolve : " + err.name);
    },
    "r");

uninstall

Uninstalls the package with a specified package ID.

void uninstall(PackageId id, PackageProgressCallback progressCallback, optional ErrorCallback? errorCallback);

Since: 2.1

This API provides a way to notify about the progress and completion of an uninstallation request through PackageProgressCallback.

The ErrorCallback() is launched with these error types:

• NotFoundError - If the package is not found with the specified ID.
• UnknownError - If it is not allowed to uninstall the package from the platform or any other platform error occurs.

Privilege level: platform

Privilege: http://tizen.org/privilege/packagemanager.install

Remark : Some preloaded packages cannot be uninstalled. In this case, ErrorCallback with the UnKnownError type is launched.

Parameters:

• id: The package ID to uninstall
• progressCallback: The method to invoke when uninstallation is in progress or has been completed
• errorCallback [optional] [nullable]: The method to invoke when an error occurs

Exceptions:

• WebAPIException
  • with error type TypeMismatchError, if an input parameter is not compatible with the expected type for that parameter.
  • with error type SecurityError, if the application does not have the privilege to call this method.

Code example:

var onUninstallation = {
    onprogress: function(packageId, percentage) {
        console.log("On Uninstallation(" + packageId + ") : progress(" + percentage + ")");
    },
    oncomplete: function(packageId) {
        console.log("Uninstallation(" + packageId + ") Complete");
    }
};

var onError = function (err) {
    console.log("Error occurred on installation : " + err.name);
};

// Let's assume that the package ID to uninstall is "testapp001"
tizen.package.uninstall("testapp001", onUninstallation, onError);

getPackagesInfo

Gets information of the installed packages.

void getPackagesInfo(PackageInformationArraySuccessCallback successCallback, optional ErrorCallback? errorCallback);

Since: 2.1

The result contains the snapshots of the installed packages information.

The errorCallback() is launched with this error type:

• UnknownError - If any other platform error occurs.

Privilege level: public

Privilege: http://tizen.org/privilege/package.info

Parameters:

• successCallback: The method to call when an invocation ends successfully
• errorCallback [optional] [nullable]: The method to call when an error occurs

Exceptions:

• WebAPIException
  • with error type TypeMismatchError, if an input parameter is not compatible with the expected type for that parameter.
  • with error type SecurityError, if the application does not have the privilege to call this method.

Code example:

function onListInstalledPackages(packages) {
    for (var i = 0; i < packages.length; i++) {
        console.log("Package id["+i+"] : " +packages[i].id);
    }
}

tizen.package.getPackagesInfo(
    onListInstalledPackages,
    function (err) {console.log("Can't obtain packages list" + err.name);});

getPackageInfo

Gets information of an installed package.

PackageInformation getPackageInfo(optional PackageId? id);

Since: 2.1

If the ID is set to null or not set at all, it returns the package information of the current application. The list of installed packages and their package IDs is obtained using getPackagesInfo().

Privilege level: public

Privilege: http://tizen.org/privilege/package.info

Parameters:

• id [optional] [nullable]: A string representing the package ID. If the ID is not provided, the package information of the calling application is returned.

Return value:

PackageInformation The information of a package

Exceptions:

• WebAPIException
  • with error type TypeMismatchError, if an input parameter is not compatible with the expected type for that parameter.
  • with error type SecurityError, if the application does not have the privilege to call this method.
  • with error type NotFoundError, if the package with the specified ID is not found.
  • with error type UnknownError, if the package information cannot be retrieved because of a platform error.

Code example:

var packageInfo = tizen.package.getPackageInfo(null);

console.log("Current Package ID : " + packageInfo.id);

setPackageInfoEventListener

Sets a listener to receive notifications for any changes made to the list of installed packages.

void setPackageInfoEventListener(PackageInformationEventCallback eventCallback);

Since: 2.1

This method sets a PackageInformationEventCallback type callback that is triggered when a package is installed, removed, or updated.

The callback lasts until the unsetPackageInfoEventListener() method is called.

Privilege level: public

Privilege: http://tizen.org/privilege/package.info

Parameters:

• eventCallback: The method to be called when any change is made to the list of installed packages.

Exceptions:

• WebAPIException
  • with error type TypeMismatchError, if an input parameter is not compatible with the expected type for that parameter.
  • with error type SecurityError, if the application does not have the privilege to call this method.
  • with error type UnknownError, if the package list change event cannot be generated because of a platform error.

Code example:

var packageEventCallback = {
  oninstalled: function(packageInfo) {
      console.log('The package ' + packageInfo.name + ' is installed');
  },
  onupdated: function(packageInfo) {
      console.log('The package ' + packageInfo.name + ' is updated');
  },
  onuninstalled: function(packageId) {
      console.log('The package ' + packageId + ' is uninstalled');
  }
};

tizen.package.setPackageInfoEventListener(packageEventCallback);

unsetPackageInfoEventListener

Unsets the listener to stop receiving package notifications.

void unsetPackageInfoEventListener();

Since: 2.1

Privilege level: public

Privilege: http://tizen.org/privilege/package.info

Exceptions:

• WebAPIException
  • with error type SecurityError, if the application does not have the privilege to call this method.
  • with error type UnknownError, if the listener removal request fails because of a platform error.

Code example:

tizen.package.unsetPackageInfoEventListener();

2.3. PackageInformation

This interface defines the general information available to an installed package.

[NoInterfaceObject] interface PackageInformation {
    readonly attribute PackageId id;

    readonly attribute DOMString name;

    readonly attribute DOMString iconPath;

    readonly attribute DOMString version;

    readonly attribute long totalSize;

    readonly attribute long dataSize;

    readonly attribute Date lastModified;

    readonly attribute DOMString author;

    readonly attribute DOMString description;

    readonly attribute ApplicationId[] appIds;
};

Since: 2.1

Attributes

• readonly PackageId id
  
  An attribute to store the identifier of a package.
  
  Since: 2.1

• readonly DOMString name
  
  An attribute to store the package name.
  
  Since: 2.1

• readonly DOMString iconPath
  
  An attribute to store the icon path of a package.
  
  The icon path of the package is the same as the icon path of the relevant application (see the iconPath attribute of the ApplicationInformation interface).
  
  The relevant application is the one with the same packageId as the id of this package.
  
  Since: 2.1

• readonly DOMString version
  
  An attribute to store the package version.
  
  Since: 2.1

• readonly long totalSize
  
  An attribute to store the total installed size(package + data) of a package.
  
  Since: 2.1

• readonly long dataSize
  
  An attribute to store the current data size of a package.
  
  Since: 2.1

• readonly Date lastModified
  
  An attribute to store the latest installed or updated time of a package.
  
  Since: 2.1

• readonly DOMString author
  
  An attribute to store the author of a package.
  
  Since: 2.1

• readonly DOMString description
  
  An attribute to store the package description.
  
  Since: 2.1

• readonly ApplicationId[] appIds
  
  An attribute to store the application ID list of a package.
  
  Since: 2.1

2.4. PackageInformationArraySuccessCallback

This interface invokes the success callback with an array of PackageInformation objects as an input parameter when the installed package list is retrieved.

[Callback=FunctionOnly, NoInterfaceObject] interface PackageInformationArraySuccessCallback {
    void onsuccess(PackageInformation[] informationArray);
};

Since: 2.1

It is used in tizen.package.getPackagesInfo().

Methods

onsuccess

Called when the asynchronous call completes successfully.

void onsuccess(PackageInformation[] informationArray);

Since: 2.1

Parameters:

• informationArray: A list of installed packages' information.

2.5. PackageProgressCallback

This callback interface specifies subscriptions for any notification on the progress or completion of requests.

[Callback, NoInterfaceObject] interface PackageProgressCallback {
    void onprogress(PackageId id, short progress);

    void oncomplete(PackageId id);
};

Since: 2.1

Methods

onprogress

Called while the request is in progress.

void onprogress(PackageId id, short progress);

Since: 2.1

Parameters:

• id: The package ID
• progress: The progress in percentage.

oncomplete

Called when the request is completed.

void oncomplete(PackageId id);

Since: 2.1

Parameters:

• id: The package ID

2.6. PackageInformationEventCallback

This callback interface specifies methods that are invoked when a package is installed, updated, or uninstalled.

void  [Callback, NoInterfaceObject] interface PackageInformationEventCallback {
    void oninstalled(PackageInformation info);

    void onupdated(PackageInformation info);

    void onuninstalled(PackageId id);
};

Since: 2.1

Methods

oninstalled

Called when a package is installed.

void oninstalled(PackageInformation info);

Since: 2.1

Parameters:

• info: The information of the installed package

onupdated

Called when a package is updated.

void onupdated(PackageInformation info);

Since: 2.1

Parameters:

• info: The information of the updated package

onuninstalled

Called when a package is uninstalled.

void onuninstalled(PackageId id);

Since: 2.1

Parameters:

• id: The ID of the uninstalled package

3. Full WebIDL

module Package {
    typedef DOMString PackageId;

    [NoInterfaceObject] interface PackageManagerObject {
        readonly attribute PackageManager package;
    };
    Tizen implements PackageManagerObject;

    [NoInterfaceObject] interface PackageManager {
        void install(DOMString packageFileURI,
                     PackageProgressCallback progressCallback,
                     optional ErrorCallback? errorCallback) raises(WebAPIException);

        void uninstall(PackageId id, 
                       PackageProgressCallback progressCallback,
                       optional ErrorCallback? errorCallback) raises(WebAPIException);

        void getPackagesInfo(PackageInformationArraySuccessCallback successCallback,
                             optional ErrorCallback? errorCallback) raises(WebAPIException);

        PackageInformation getPackageInfo(optional PackageId? id) raises(WebAPIException);

        void setPackageInfoEventListener(PackageInformationEventCallback eventCallback) raises(WebAPIException);

        void unsetPackageInfoEventListener() raises(WebAPIException);
    };

    [NoInterfaceObject] interface PackageInformation {
        readonly attribute PackageId id;

        readonly attribute DOMString name;

        readonly attribute DOMString iconPath;

        readonly attribute DOMString version;

        readonly attribute long totalSize;

        readonly attribute long dataSize;

        readonly attribute Date lastModified;

        readonly attribute DOMString author;

        readonly attribute DOMString description;

        readonly attribute ApplicationId[] appIds;
    };

    [Callback=FunctionOnly, NoInterfaceObject] interface PackageInformationArraySuccessCallback {
        void onsuccess(PackageInformation[] informationArray);
    };

    [Callback, NoInterfaceObject] interface PackageProgressCallback {
        void onprogress(PackageId id, short progress);

        void oncomplete(PackageId id);
    };

    [Callback, NoInterfaceObject] interface PackageInformationEventCallback {
        void oninstalled(PackageInformation info);

        void onupdated(PackageInformation info);

        void onuninstalled(PackageId id);
    };
};