Symbian OS Platform Security/Appendix C: The Software Install API

Reproduced by kind permission of John Wiley & Sons.

Table of Contents

This section will mainly be of interest to UI developers who are developing an installer application. Some of these APIs might not be fully documented in public SDKs due to the limited audience for them.

The Software Installer Launcher

The basic installer API can be found in the Launcher class in %EPOCROOT%\epoc32\include\swi\launcher.h.

The first method you’ll encounter there is:

  static IMPORT_C TInt Install(MUiHandler& aUiHandler,
     const TFileName& aFileName, const CInstallPrefs& aInstallPrefs);

You’ll notice immediately that a reference to an abstract UI interface is required. This is how the installer communicates back to the UI when questions need to be asked of the user, or certain conditions and events are reported. These call-backs are defined in MUiHandler which itself is an amalgamation of the MCommonDialogs, MInstallerUiHandler, and MUninstallerUIHandler abstract interfaces. These are all declared in the header %EPOCROOT%\epoc32\include\swi\msisuihandlers.h.

Given that the caller provides a concrete implementation of the MUiHandler class, the software installer will call back to this code on the same thread which called the above Install() method.

TrustedUI Capability

Another key point about the installer API is that the caller must have the TrustedUI capability. Being charged with this capability means that the calling code has been deemed responsible enough to accurately broker important information between the user and the installer and not, for example, to subvert the user’s choice not to continue with an installation by itself returning ‘continue’ to the software installer call-back.

If you’re not going to find yourself in a position where you’re writing installer UIs, but you still wish to install a package, then the best way to initiate the process is to use RApaLsSession::StartDocument() to launch whatever application is registered to handle SIS files on your mobile phone.

The SISDataProvider Interface

SIS files might be present in the mobile phone’s file system and, therefore, accessible by filename or file handle. Symbian didn’t want to have to restrict installations to having the entire package present, and recognized that packages might simply be too large to cache locally and leave enough space left for the installation.

By allowing you, the caller, to provide your own data provider implementation, Symbian allows you to provide the support for wherever the SIS file data needs to come from. For example:

• You read the file via the network.
• You compressed a SIS file using a proprietary algorithm.

Note, however, that you will need to provide some form of seek() operation as the installer might wish to move forwards (and backwards) through the SIS file.

SISDataProvider call-backs come from a different thread, but one which is set up to share the same heap as the thread calling the Install() method. If you manage memory within your SISDataProvider object, then please create this object on the install thread so that the object doesn’t end up owning memory in different heaps. A brief synopsis is given below, but full details can be found in the Developer Library or in sisdataprovider.h.

  class MSisDataProvider
  {
  public:
  virtual TInt Read(TDes8& aDes)=0;
  virtual TInt Read(TDes8& aDes, TInt aLength)=0;
  virtual TInt Seek(TSeek aMode, TInt64& aPos)=0;
  virtual ∼MSisDataProvider() {}
  virtual void OpenDrmContentL (ContentAccess::TIntent aIntent);
  virtual TInt ExecuteDrmIntent (ContentAccess::TIntent aIntent);
  };

Install Preferences

You may also have noticed that you can pass preferences into the installer, and this class – CInstallPrefs – is also defined in launcher.h.

These preferences are primarily concerned with run-time configuration issues, such as whether the installer should perform a revocation check on the software being installed, and where it might go to perform this check in default circumstances.

  class CInstallPrefs : public CBase
  {
  public:
  void SetPerformRevocationCheck(TBool aCheck);
  Tbool PerformRevocationCheck() const;
  const TDesC8& RevocationServerUri() const;
  ......

It’s worth pointing out, however, that a ROM-build setting could override any preferences which the caller attempts to set. For example, the manufacturer might have chosen to mandate revocation checks, in which case the caller’s preference will be ignored. Alternatively, the manufacturer might choose to give control of a parameter to the caller.

Note that CInstallPrefs might change over time, so please refer to launcher.h for the options available to you.

Asynchronous Installation

If you would prefer to drive the software installation process via a CActive object running within an active scheduler, then you’ll find that Symbian has provided an alternative installer API that is defined in security\swi\inc\swi\asynclauncher.h.

Copyright © 2006, Symbian Ltd.