It is quite common for commercial software to have a registration or configuration process which must be completed immediately after installation in order for the software to become operational. This blog entry outlines one technique for getting such a process to automatically occur after installation of a Windows Mobile software package.
My solution is largely based upon a sample application provided with the Windows Mobile 5.0 and Windows Mobile 6 SDKs. If you haven’t found these samples yet (installed by default) I encourage you to investigate them further.
Most Windows Mobile Software is installed via CAB files. A CAB file is an archive which installs a number of files and registry settings onto a PDA. A less commonly used feature of a CAB file is that of a setup dll. A setup dll (traditionally named setup.dll) is a DLL which can hook into various steps of the installation/uninstallation process in order to extend or modify the process. The process of using a setup dll is described within MSDN in an article titled “Optional Setup.dll Files for installation“.
When the device processes a CAB file that includes a setup dll, it extracts the DLL and calls specifically named functions within it at the following stages of the installation process:
Since the DLL must export a set of functions it typically must be implemented in a native language such as C or C++. The functions exported by the setup.dll can perform any task they want and can optionally decide to abort the installation process.
So in order to run an application after installation of a CAB file, one approach is to write a setup dll that implements an Install_Exit() function that launches the newly installed executable.
Launching an application on installation
Since we want to perform a custom action in response to the installation process completing the correct place to place our custom code is the Install_Exit entry point.
One of the parameters to this entry point (as described in MSDN) is pszInstallDir which contains the path to the location the user has decided to install the application in (i.e. typically \Storage Card\Program Files\xyz or \Program Files\xyz). This will help us locate the executable that has been installed.
We can start the desired application by using the CreateProcess API. If we fail to launch the application we can return codeINSTALL_EXIT_UNINSTALL which will cause the CAB installation process to rollback any changes made during installation and display an error message to the user.
My sample application launches an application after installation by placing the following code within the Install_Exit function:
// We are provided with the installation folder the
// user has installed the application into. So append
// the name of the application we want to launch.
// Start the application, and don't wait for it to exit
if (!CreateProcess(szPath, NULL, NULL, NULL, NULL, 0, NULL, NULL, NULL, &pi))
// Failed to launch executable so indicate an error
// and cause wceload to rollback the installation
cie = codeINSTALL_EXIT_UNINSTALL;
You will notice that this code sample hardcodes the name of the executable to launch (TestApplication.exe). It does however cope with users deciding to install the application on to an SD Card etc.
Using Visual Studio Smart Device CAB projects
Having developed your custom setup.dll implementation you must package it into the CAB file in a particular way to indicate to the installation process that the file should be treated specially.
If you are using the Smart Device CAB project type within Visual Studio this is a two step process.
The first step is to add the “Primary Output” of your setup.dll project into the application folder of your setup project (use the file system viewer). This ensures that your dll is archived as part of the CAB file.
The second step is to indicate to the CAB building process which dll within your CAB file should be treated as the special “setup.dll”. To indicate which dll you want to use as the setup.dll within Solution Explorer you should select your Smart Device CAB project, and then switch to the Property viewer. You will notice one of the CAB file properties is called “CE Setup DLL”. Using a popup dialog that appears when this property is selected you should be able to navigate to the DLL you included in the first step of the process.
If you are creating your CAB file via a manually written INF file you specify the DLL that should be used by specifying a CESetupDLL parameter in your [DefaultInstall] section (documented within MSDN) as shown below:
CopyFiles = CopyToInstallDir,CopyToWindows
CESetupDLL = MySetup.dll
[Download sample application - 19.3Kb]
I have produced a small sample application which demonstrates this technique. It consists of a solution (SetupDLL.sln) that contains the following projects.
- TestApplication – An application (written in C#) to run after the installation process.
- SetupDLL – The DLL the CAB installation process invokes during installation in order to execute TestApplication.
- SetupDLLCab – The CAB file project that packages everything up into a single CAB file for the end user to install.
If you build the example CAB file and then install it on a device you should notice that at the end of the installation process (just before the “installation has completed” message box appears) the included .NET Compact Framework application will automatically run.
I will end this blog posting with a question. Is anyone interested in being able to write such setup dlls within a managed language such as VB.NET or C#, and if so what kind of custom behaviour/logic would you be interested in implementing?