Package API
It also provides a listener method so that an application can be notified when there is a change on the installed packages.
Remark: In order to access files, a proper privilege has to be defined additionally:
- for accessing only internal storage using this API, a privilege http://tizen.org/privilege/mediastorage must be provided,
- for accessing only external storage using this API, a privilege http://tizen.org/privilege/externalstorage must be provided,
- for accessing internal and external storage using this API, privileges (http://tizen.org/privilege/mediastorage and http://tizen.org/privilege/externalstorage) must be provided.
For more information on the Package features, see Package Guide.
Since: 2.1
Table of Contents
- 1. Type Definitions
- 1.1. PackageId
- 2. Interfaces
- 3. Full WebIDL
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)
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
2. Interfaces
2.1. PackageManagerObject
[NoInterfaceObject] interface PackageManagerObject { readonly attribute PackageManager package; };
Tizen implements PackageManagerObject;
Since: 2.1
The tizen.package object allows access to Package API functionality.
Attributes
-
readonly
PackageManager packageObject representing a package manager.
Since: 2.1
2.2. PackageManager
[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 or the application does not have privilege to access the storage. For more information, see Storage privileges.
Code example:
var onInstallation = { onprogress: function(packageId, percentage) { console.log("On installation(" + packageId + "): progress(" + percentage + ")"); }, oncomplete: function(packageId) { console.log("Installation(" + packageId + ") completed"); } }; var onError = function(err) { console.log("Error occurred on installation: " + err.name); }; /* Assumes 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 + ") completed"); } }; var onError = function(err) { console.log("Error occurred on installation: " + err.name); }; /* Assumes 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
Calling this function has no effect if listener is not set.
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();
- WebAPIException
2.3. PackageInformation
[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 idAn attribute to store the identifier of a package.
Since: 2.1
-
readonly
DOMString nameAn attribute to store the package name.
Since: 2.1
-
readonly
DOMString iconPathAn 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 versionAn attribute to store the package version.
Since: 2.1
-
readonly
long totalSizeAn attribute to store the total installed size(package + data) of a package.
Since: 2.1
-
readonly
long dataSizeAn attribute to store the current data size of a package.
Since: 2.1
-
readonly
Date lastModifiedAn attribute to store the latest installed or updated time of a package.
Since: 2.1
-
readonly
DOMString authorAn attribute to store the author of a package.
Since: 2.1
-
readonly
DOMString descriptionAn attribute to store the package description.
Since: 2.1
-
readonly
ApplicationId[]
appIdsAn attribute to store the application ID list of a package.
Since: 2.1
2.4. PackageInformationArraySuccessCallback
[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
[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
[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; Tizen implements PackageManagerObject; [NoInterfaceObject] interface PackageManagerObject { readonly attribute PackageManager package; }; [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); }; };