com.datalogic.device.app

Class PackageInstaller

java.lang.Object

com.datalogic.device.app.PackageInstaller

public class PackageInstaller
extends java.lang.Object

PackageInstaller gives developers the ability to install, uninstall and upgrade applications in unattended/silent mode. The install/uninstall/upgrade/selfUpgrade methods are asynchronous. An object that implements PackageInstallerListener must be passed to PackageInstaller to be able to handle the result.
An install/uninstall/upgrade method can be executed alone calling the corresponding method of the PackageInstaller or together with other methods grouped in a PackageInstallerSession. In the former case there will be a result callback for each method, in the latter case there will be only one callback listing the results of each method. The methods grouped in a PackageInstallerSession are executed in best effort.

To install an application do the following steps:

1. Obtain an instance of PackageInstaller with PackageInstaller(android.content.Context).
2. Obtain an instance of PackageInstallerListener that will be used to handle the result of the command. This object must be passed as parameter to the install method.
3. To perform the install session call install(java.lang.String, boolean, com.datalogic.device.app.PackageInstallerListener). The method onResult of the listener will be called when the install session has completely finished, either with success or failure.

To uninstall an application do the following steps:

1. Obtain an instance of PackageInstaller with PackageInstaller(android.content.Context).
2. Obtain an instance of PackageInstallerListener that will be used to handle the result of the command. This object must be passed as parameter to the uninstall method.
3. To perform the uninstall session call uninstall(java.lang.String, com.datalogic.device.app.PackageInstallerListener). The method onResult of the listener will be called when the uninstall session has completely finished, either with success or failure.

To upgrade an application do the following steps:

1. Obtain an instance of PackageInstaller with PackageInstaller(android.content.Context).
2. Obtain an instance of PackageInstallerListener that will be used to handle the result of the command. This object must be passed as parameter to the upgrade method.
3. To perform the upgrade session call upgrade(java.lang.String, com.datalogic.device.app.PackageInstallerListener). The method onResult of the listener will be called when the upgrade session has completely finished, either with success or failure.

To execute more install/uninstall/upgrade methods and be notified of the results when all the methods have completed, do the following steps:

1. Obtain an instance of PackageInstaller with PackageInstaller(android.content.Context).
2. Obtain an instance of PackageInstallerListener that will be used to handle the result of the commands. This object must be passed as parameter to the createSession method.
3. Obtain an instance of PackageInstallerSession with createSession(com.datalogic.device.app.PackageInstallerListener).
4. Open a transaction on the session calling PackageInstallerSession.openSession().
5. Call the methods PackageInstallerSession.install(java.lang.String, boolean), PackageInstallerSession.uninstall(java.lang.String), PackageInstallerSession.upgrade(java.lang.String) that suite you.
6. Close and commit the transaction on the session calling PackageInstallerSession.closeSession().
7. The method onResult of the listener will be called when all the methods listed in the session have completed, either with success or failure.

To upgrade the current application do the following steps:

1. Obtain an instance of PackageInstaller with PackageInstaller(android.content.Context).
2. Call selfUpgrade(java.lang.String) passing as parameter the name of the package to be used to upgrade the current application.

Constructor Summary

Constructors

Constructor and Description
PackageInstaller(android.content.Context context) This is the constructor of PackageInstaller.

Method Summary

Modifier and Type	Method and Description
PackageInstallerSession	createSession(PackageInstallerListener listener) Call this method to create a PackageInstallerSession object.
int	install(java.util.ArrayList<java.lang.String> apks, boolean atomic, PackageInstallerListener listener) Call this method to install the applications contained within the .apk files specified by apks.
int	install(java.lang.String apk, boolean force, PackageInstallerListener listener) Call this method to install the application contained within the .apk file specified by apk.
int	selfUpgrade(java.lang.String apk) Call this method to upgrade the current application.
int	uninstall(java.lang.String packageName, PackageInstallerListener listener) Call this method to unistall an application installed on the device.
int	upgrade(java.lang.String apk, PackageInstallerListener listener) Call this method to upgrade an application installed on the device.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PackageInstaller

public PackageInstaller(android.content.Context context)

This is the constructor of PackageInstaller.

Parameters:

context - Context context of the caller application

Throws:

PackageInstallerException - in case of error.

Method Detail

createSession

public PackageInstallerSession createSession(PackageInstallerListener listener)

Call this method to create a PackageInstallerSession object. The method can be used to request a session on which it will be possible to group the execution of a sequence of install/uninstall/upgrade commands.

Parameters:

listener - PackageInstallerListener instance that implements the method PackageInstallerListener.onResult(java.util.List<com.datalogic.device.app.PackageInstallerResult>) to handle the result of methods executed in the session.

Returns:

int PackageInstallerException.SUCCESS in case of success, otherwise a possible error code, matching one of the PackageInstallerException error constants.

Throws:

PackageInstallerException - in case of error when exceptions are enabled through the ErrorManager singleton.

selfUpgrade

public int selfUpgrade(java.lang.String apk)

Call this method to upgrade the current application.
Do not suspend the UIThread while waiting for the result of the method otherwise an application’s deadlock can occur. In case of success the intent "android.intent.action.MY_PACKAGE_REPLACED" is fired.
In case of failure:
- if the problem is found before contacting the remote service an error is returned; the error code is one of the PackageInstallerException error constants, but when exceptions are enabled @throws PackageInstallerException.
- if the problem is found in the remote service the intent "com.datalogic.app.UPGRADE_ME_STATUS" is fired.
The extra data of the "com.datalogic.app.UPGRADE_ME_STATUS" are:
- "android.content.pm.PackageInstaller.EXTRA_STATUS" int: a possible error code, matching one of the PackageInstallerException error constants.
- "android.content.pm.PackageInstaller.EXTRA_STATUS_MESSAGE" String: an error string message.
- "android.content.pm.PackageInstaller.EXTRA_PACKAGE_NAME" String: Package Name of the application.

Parameters:

apk - String full path of the .apk to be used to upgrade the current application.

Returns:

int PackageInstallerException.SUCCESS in case of success, otherwise a possible error code, matching one of the PackageInstallerException error constants.

Throws:

PackageInstallerException - in case of error, when exceptions are enabled through the ErrorManager singleton.

install

public int install(java.lang.String apk,
                   boolean force,
                   PackageInstallerListener listener)

Call this method to install the application contained within the .apk file specified by apk.
The method is executed alone, not grouped together with other methods as can be done using a PackageInstallerSession. The result of the command is received through the listener method PackageInstallerListener.onResult(java.util.List<com.datalogic.device.app.PackageInstallerResult>). Do not suspend the UIThread while waiting for the result of the method otherwise an application’s deadlock can occur.

Example:

PackageInstaller packageInstaller = new PackageInstaller(context);
PackageInstallerListener listener = new PackageInstallerListener{public void onResult(List results) {...}};
packageInstaller.install("/dir1/dir11/dir116/pkg1.apk", false, listener);

Parameters:

apk - String full path of the .apk to be installed.

force - boolean true force the upgrade in case the application is already installed, otherwise the upgrade is refused.

listener - PackageInstallerListener instance that implements the method PackageInstallerListener.onResult(java.util.List<com.datalogic.device.app.PackageInstallerResult>) to handle the result of the method.

Returns:

int PackageInstallerException.SUCCESS in case of success, otherwise a possible error code, matching one of the PackageInstallerException error constants.

Throws:

PackageInstallerException - in case of error, when exceptions are enabled through the ErrorManager singleton.

install

public int install(java.util.ArrayList<java.lang.String> apks,
                   boolean atomic,
                   PackageInstallerListener listener)

Call this method to install the applications contained within the .apk files specified by apks.
It allows also the installation of an app distributed as multiple split APKs. Only in this case set atomic = true.
The method is executed alone, not grouped together with other methods as can be done using a PackageInstallerSession. The result of the command is received through the listener method PackageInstallerListener.onResult(java.util.List<com.datalogic.device.app.PackageInstallerResult>). Do not suspend the UIThread while waiting for the result of the method otherwise an application’s deadlock can occur.

Example:
public int install(ArrayList pkgs, boolean atomic)
PackageInstaller packageInstaller = new PackageInstaller(context);
PackageInstallerListener listener = new PackageInstallerListener{public void onResult(List results) {...}};
ArrayList apks = new ArrayList();
apks.add("/dir1/dir11/dir116/pkg1.apk");
apks.add("/dir1/dir11/dir116/pkg2.apk");
packageInstaller.install(apks, false);

Parameters:

pkgs - ArrayList list of the .apks files to be installed

atomic - boolean true if "apks" lists the multiple split APKs of the application to be installed

listener - PackageInstallerListener instance that implements the method PackageInstallerListener.onResult(java.util.List<com.datalogic.device.app.PackageInstallerResult>) to handle the result of the method.

Returns:

int PackageInstallerException.SUCCESS in case of success, otherwise a possible error code, matching one of the PackageInstallerException error constants.

Throws:

PackageInstallerException - in case of error, when exceptions are enabled through the ErrorManager singleton.

uninstall

public int uninstall(java.lang.String packageName,
                     PackageInstallerListener listener)

Call this method to unistall an application installed on the device.
The method is executed alone, not grouped together with other methods as can be done using a PackageInstallerSession. The result of the command is received through the listener method PackageInstallerListener.onResult(java.util.List<com.datalogic.device.app.PackageInstallerResult>). Do not suspend the UIThread while waiting for the result of the method otherwise an application’s deadlock can occur.

Example:

PackageInstaller packageInstaller = new PackageInstaller(context);
PackageInstallerListener listener = new PackageInstallerListener{public void onResult(List results) {...}};
packageInstaller.uninstall("com.example.helloandroid", listener);

Parameters:

packageName - String package name of the application to be uninstalled.

listener - PackageInstallerListener instance that implements the method PackageInstallerListener.onResult(java.util.List<com.datalogic.device.app.PackageInstallerResult>) to handle the result of the method.

Returns:

int PackageInstallerException.SUCCESS in case of success, otherwise a possible error code, matching one of the PackageInstallerException error constants.

Throws:

PackageInstallerException - in case of error, when exceptions are enabled through the ErrorManager singleton.

upgrade

public int upgrade(java.lang.String apk,
                   PackageInstallerListener listener)

Call this method to upgrade an application installed on the device.
The method is executed alone, not grouped together with other methods as we can be done using a PackageInstallerSession. The result of the command is received through the listener method PackageInstallerListener.onResult(java.util.List<com.datalogic.device.app.PackageInstallerResult>).

Example:

PackageInstaller packageInstaller = new PackageInstaller(context);
PackageInstallerListener listener = new PackageInstallerListener{public void onResult(List results) {...}};
packageInstaller.upgrade("/dir1/dir11/dir116/pkg1_v2.apk", listener);

Parameters:

apk - String full path of the .apk to be used to upgrade the application already installed that has the same Package Name of this .apk.

listener - PackageInstallerListener instance that implements the method PackageInstallerListener.onResult(java.util.List<com.datalogic.device.app.PackageInstallerResult>) to handle the result of the method.

Returns:

int PackageInstallerException.SUCCESS in case of success, otherwise a possible error code, matching one of the PackageInstallerException error constants.

Throws:

PackageInstallerException - in case of error, when exceptions are enabled through the ErrorManager singleton.