Optional Setup.dll Files for Installation

Article
04/19/2010

A version of this page is also available for

4/19/2010

When you create a cabinet (.cab) file, you can choose to add an optional Setup.dll file. This enables you to perform operations before and after the installation and unistallation of your application on target devices.

Including the Setup dll in your .cab File

If you are using CAB Wizard to create your .cab file, you specify your Setup.dll in the DefaultInstall section of your .inf file. The following example shows how you can use the CESetupDLL directive in the DefaultInstall section of the .inf file to point to a custom Setup.dll file.

[DefaultInstall.SA]
CESetupDLL = custom_setup.dll

For Windows Mobile, if you are generating your .cab file by creating a Smart Device CAB Project in Visual Studio, you can specify your setup DLL in the CE Setup DLL field in the Project Properties window. For more information, see Creating an Installer for Windows Mobile Applications.

Procedure

To create a setup DLL

Make sure that Solution Explorer for your project is visible. On the File menu, point to Add, and then click New Project.
In the project types list, click Visual C++ and then Smart Device. In the template list, click Win32 Smart Device DLL. Enter a name for the new project and click OK.
On the Platforms page of the ATL Smart Device Project Wizard, select the platforms your application will support. On the Application Settings page, under Application Type, choose DLL. Click Finish.
In Solution Explorer, expand your setup DLL project and then the Source Files folder. Right-click the <your project name>.cpp icon and select View Code.
Add the following line after the existing #include statements at the top of the file to include the setup DLL function definitions.
```
#include "ce_setup.h"
```

Add the following lines of code to the end of the file.

codeINSTALL_INIT
Install_Init(
    HWND        hwndParent,
    BOOL        fFirstCall,     // is this the first time this function is being called?
    BOOL        fPreviouslyInstalled,
    LPCTSTR     pszInstallDir
)
{
// TODO: Add custom installation code here

// To continue installation, return codeINSTALL_INIT_CONTINUE
// If you want to cancel installation, 
// return codeINSTALL_EXIT_UNINSTALL
return codeINSTALL_INIT_CONTINUE;

}



codeINSTALL_EXIT
Install_Exit(
    HWND    hwndParent,
    LPCTSTR pszInstallDir,
    WORD    cFailedDirs,
    WORD    cFailedFiles,
    WORD    cFailedRegKeys,
    WORD    cFailedRegVals,
    WORD    cFailedShortcuts
)
{
// TODO: Add custom installation code here

// To exit the installation DLL normally, 
// return codeINSTALL_EXIT_DONE
// To unistall the application after the function exits,
// return codeINSTALL_EXIT_UNINSTALL
return codeINSTALL_EXIT_DONE;
}

codeUNINSTALL_INIT
Uninstall_Init(
    HWND        hwndParent,
    LPCTSTR     pszInstallDir
)
{
// TODO: Add custom uninstallation code here

// To continue uninstallation, return codeUNINSTALL_INIT_CONTINUE
// If you want to cancel installation,
// return codeUNINSTALL_INIT_CANCEL
return codeUNINSTALL_INIT_CONTINUE;
}

codeUNINSTALL_EXIT
Uninstall_Exit(
    HWND    hwndParent
)
{
// TODO: Add custom uninstallation code here

return codeUNINSTALL_EXIT_DONE;
}

Add custom installation and uninstallation code to the methods. If you replace the contents of the Install_Exit method with the following code, the setup DLL will attempt to open a file and write to it. If the file cannot be opened or written to, the method returns codeINSTALL_EXIT_UNINSTALL, and your application will automatically be uninstalled from the device.

HANDLE h=NULL;
h=CreateFile(_T("\\installtest.txt"),GENERIC_WRITE,0,NULL,
               CREATE_NEW,FILE_ATTRIBUTE_NORMAL,NULL);

if(h==NULL || WriteFile(h,_T("tost"),8,NULL,NULL) == false)
{
   // File creation or writing failed, unistall application
CloseHandle(h);
return codeINSTALL_EXIT_UNINSTALL;
}

// File creation and writing succeded
CloseHandle(h);
return codeINSTALL_EXIT_DONE;

To include your setup DLL in a cab file

If you already have a Smart Device CAB Project in your solution, skip to step 4.
Make sure that Solution Explorer for your project is visible. On the File menu, point to Add, and then click New Project.
In the project types list, click Other Project Types and then Setup and Deployment. In the template list, click Smart Device CAB Project. Enter a name for the new project, make sure Add to Existing Solution is selected and click OK.
Add any files and assemblies that should be installed with your application to the CAB file.
In the Properties window for the Smart Device CAB Project, from the CE Setup DLL drop-down list, select Browse….
In the Select Item in Project dialog box, choose either Application Folder or Program Files Folder from the Look-in drop-down list.
Click the Add Output button.
In the Add Project Output Group dialog box, choose your setup DLL project from the Project drop-down list and then select Primary Output.
Hit Ctrl+Shift+B to build the entire solution.

Remarks

To determine the function prototypes and return values that you must use for the functions in your Setup.dll file, examine the Ce_setup.h header file.

Optional Setup.dll Files for Installation

Including the Setup dll in your .cab File

Procedure

Remarks

See Also

Concepts

Additional resources