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);
};
};