How to remove "stray" packages from a removable drive

It is possible for users of a Symbian phone to install a package onto a removable media card if one is present in the phone. Normally phone users will expect to be able freely both to install and remove packages from a media card. However, in some situations, it can become impossible for the user to remove a package from a media card. When this happens, the package that cannot be removed is known as a “stray” package.

One possible reason for a package on a media card becoming “stray” is that the phone’s user, after installing the package onto the media card, has reformatted its C: drive.

Another situation in which a package becomes “stray” is when a user removes the media card containing it from one phone and inserts it into another.

When a media card is inserted into a new phone, the packages on the media card will automatically install themselves from the media card onto the new phone - at least, they will if the AllowPackagePropagate setting in the original phone’s SWIPOLICY.INI file is set to true. The automatic process is called “auto-propagation”.

However, auto-propagation can fail, for example, if:

• the package is incompatible with the new phone,

• the package’s certificates have expired,

• data files on the media card have changed. In this case, the software installer compares hashes, and if they differ, will consider the package to have been tampered with and may reject it.

If the propagation process fails for any of these (or any other) reasons, then no entry will be created for the package in the phone’s SWI registry. This means that the new phone’s user will not be able to remove it from the media card. It will be a “stray” package.

To enable a phone’s users to remove “stray” packages (including stub, the binary files and the data files) , SWI provides the API described in this document.

Two classes (UninstalledSisPackages and CUninstalledPackageEntry), which are found in the Swi namespace, provide the functionality for this API. The classes are defined in header pkgremover.h and the library to link to is pkgremover.lib. The header pkgremovererrors.h is needed for the defined error codes.

The following code sample illustrates a typical use of the API for retrieving a list of packages that are on the removable drive but that do not have entries in the registry and removing all of them:

// List the packages present on removable drive E
TDriveNumber drive = EDriveE;
RPointerArray<Swi::CUninstalledPackageEntry> uninstalledPkgList;

// Ensure we delete the entries if there is a leave
CleanupResetAndDestroy<RPointerArray<Swi::CUninstalledPackageEntry> >::PushL(uninstalledPkgList);

// Retrieve the list of packages
TRAPD(err, Swi::UninstalledSisPackages::ListL(drive, uninstalledPkgList));

if (err == KErrNone)
    {
    // List retrieved successfully
    TInt count = uninstalledPkgList.Count();
    if (count > 0)
        {
        for (TInt index = 0; index < count; ++index)
            {
            Swi::CUninstalledPackageEntry* entry = uninstalledPkgList[index];
            // Information about the package can be accessed by calling methods
            // on the returned CUninstalledPackageEntry object:
            //     entry->Uid() returns the package UID
            //     entry->Name() returns the package name
            //     entry->Vendor() returns the package vendor
            //     entry->Version() returns the package version
            //     entry->PackageType() return the package type

            // Remove the package    
            TRAPD(err, Swi::UninstalledSisPackages::RemoveL(*entry));
            if (err == KErrNone)
                {
                // Package successfully removed
                }
            else
                {
                // An error occurred during removal
                }
            }
        }
    else
        {
        // No "uninstalled" packages were found
        }
    }
else if (err == KErrNotRemovable)
    {
    // The drive passed was not removable
    // Handle the error...
    }
 else
    {
    // Other error occurred
    // Can be any of the system-wide errors
    }
// Cleanup the entries
CleanupStack::PopAndDestroy(&uninstalledPkgList);