Out Of Band Component Installer

SUMMARY

A component INF must have the following entries in it's Version section:

[Version]
signature = "$Windows NT$"
Class = %ExceptionClassDesc% ; Short descriptive name of exception pack (no more than 63 chars)
ClassGUID = {F5776D81-AE53-4935-8E84-B0B283D8BCEF} ; Indicates exception pack
Provider = %Msft%
CatalogFile = delta.cat ; substitute name of catalog file
ComponentId = {E34D1BDE-2AEB-4bc1-94F7-9D4D8387F1EE} ; your component ID
DriverVer = 12/17/2001,5.1.2.0 ; Not required by spec, but used by msoobci.dll - date & version of exception pack
 

A component INF must use [DefaultInstall] as it's installation section, and must be completely installable by right-clicking on the INF (this means you need to be aware of the differences between SetupAPI syntax and AdvPack extended syntax).

The ComponentId and descriptive names should be chosen when an exception pack is first created. You may use uuidgen or guidgen to obtain a ComponentId. The ComponentId must remain the same in future exception packs.

Files specified in [SourceDisksFiles] in this exception pack must not appear in any other exception packs.

Exception pack changes must be cumulative and the version must increase. For example, an exception pack created today cannot be targeted at just Win2k, it must also work on WinXP. It must contain all the files and fixes of previous versions of the same exception pack.

The catalog must be signed with the explicit operating systems it is targeted at. For example, an exception pack created today may contain both 5.0+5.1 version tags, or just 5.1 version tag. It cannot contain 5.x version tag.

MSOOBCI.DLL does not do OS relevance checks. That must be done by the caller or by using OS version decorations for driver INF's.

RunDll32 Invocation

rundll32 <path>\msoobci.dll,DoInstall <path>\comp.INF;<flags>;<compId>;<ver>;<name>

Example:

rundll32 Z:\mypath\msoobci.dll,DoInstall Z:\mypath\expacktest.inf;0x22;{E34D1BDE-2AEB-4bc1-94F7-9D4D8387F1EE
};5.1.2;Foo Bar
rundll32 Z:\mypath\msoobci.dll,DoInstall Z:\mypath\expacktest.inf

All but the INF path is optional. No success/failure feedback is given.

Refer to InstallComponent for discussion of flags.

InstallComponent API

HRESULT
WINAPI
InstallComponent(
IN LPCTSTR InfPath,
IN DWORD Flags,
IN const GUID * CompGuid, OPTIONAL
IN INT VerMajor, OPTIONAL
IN INT VerMinor, OPTIONAL
IN INT VerBuild, OPTIONAL
IN INT VerQFE, OPTIONAL
IN LPCTSTR Name OPTIONAL
);

(defined in msoobci.h)

Description

Installs an exception package specified in InfPath. The exception package is verified as valid. Version of this exception pack is checked against any existing exception pack installed for the component. If the install is successful, the exception package will be registered and copied to the registered components directory as well as installed into the final destination.

Return

S_FALSE if same or better exception pack already installed.
S_OK if exception pack installed (no boot required).
INST_S_REBOOT if exception pack installed but a reboot is required.
INST_S_REBOOTING if exception pack installed and machine is rebooting.
various errors may be returned as a HRESULT.

Parameters

InfPath - full path to INF

Flags:

• COMP_FLAGS_NOINSTALL - use if you wish to register an exception pack for installation at a future date. Usually passed in when installing on pre Win2k OS.

• COMP_FLAGS_NOUI - do not show progress UI.

• COMP_FLAGS_NOPROMPTREBOOT - reboot if needed without prompting.

• COMP_FLAGS_PROMPTREBOOT - prompt for reboot if needed.

• COMP_FLAGS_NEEDSREBOOT - force the fact that a reboot is needed (same as Reboot key in INF).

• COMP_FLAGS_FORCE - don't do version checking, overwrite existing exception pack.

CompGuid - if specified (non-NULL) verified against ComponentId entry in INF.

VerMajor/VerMinor/VerBuild/VerQFE - if -1, read the version information from DriverVer entry in INF. If specified and DriverVer entry specified in INF, check against DriverVer. Used along with DriverVer to determine if exception pack is better than whatever is previously installed. Version must either be specified here or in INF.

Name - short name (no more than 64 characters including NULL) describing the package. If specified, overrides "CLASS" entry specified in INF.

InstallInfSection API

HRESULT
WINAPI
InstallInfSection(
IN LPCTSTR InfPath,
IN LPCTSTR SectionName, OPTIONAL
IN DWORD Flags
);

(defined in msoobci.h)

Description

Installs a Section within an INF (cf InstallHinfSection in SetupAPI).

Return

S_OK if section installed (no boot required).
INST_S_REBOOT if section installed but a reboot is required.
INST_S_REBOOTING if section installed and machine is rebooting.
various errors may be returned as a HRESULT.

Parameters

InfPath - full path to INF

SectionName - fully qualified name of section. If SectionName is NULL then [DefaultInstall] or decorated variant will be used.

Flags:

• COMP_FLAGS_NOUI - do not show progress UI.

• COMP_FLAGS_NOPROMPTREBOOT - reboot if needed without prompting.

• COMP_FLAGS_PROMPTREBOOT - prompt for reboot if needed.

• COMP_FLAGS_NEEDSREBOOT - force the fact that a reboot is needed (same as Reboot key in INF).

IsUserAdmin API

BOOL
WINAPI
IsUserAdmin(
VOID
);

(defined in msoobci.h)

Description

Checks if current user has administrator privileges. Caller is NOT expected to be impersonating anyone and IS expected to be able to open their own process and process token.

Return

TRUE if current user has administrator privileges. FALSE otherwise.

IsInteractiveWindowStation API

BOOL
WINAPI
IsInteractiveWindowStation(
VOID
);

(defined in msoobci.h)

Description

Checks if current user is running in an interactive window station (i.e., they can respond to dialogs).

Return

TRUE if running in an interactive window station. FALSE otherwise.

DriverInstallComponents API

DWORD
CALLBACK
DriverInstallComponents (
IN DI_FUNCTION InstallFunction,
IN HDEVINFO DeviceInfoSet,
IN PSP_DEVINFO_DATA DeviceInfoData,
IN OUT PCOINSTALLER_CONTEXT_DATA Context
);

(defined in msoobci.h)

Description

Co-Installer callback entry to handle "Components" keyword in INF.

Return

Refer to co-installers description in DDK.

Parameters

Refer to co-installers description in DDK.

Driver INF Component Installation

A driver INF must register the DriverInstallComponents co-installer callback to be able to use the Components syntax in an INF. The INF must be designed so that the components section is only processed for the relevant target platforms. The co-installer must be given a unique name for the specific version of msoobci.dll.

With this co-installer, one or more

Components=<compsection>[,<compsection>...]

entries can be specified in the [DDInstall] section. The compoent section has the form:

[compsection]
<component>,0x0001xxxx,<componentId>,<version>[,<name>[,<osver>[-<osver]]] ; exception pack
<component>,0x0002xxxx,<osver>,<sp>,<qfe> ; service pack
<component>,<flags>,...
...
; multiple entries allowed, a component must only be listed once

Where:

<component> - full pathname to INF that contains the exception pack or full path to self-extracting executable to install QFE.

<flags>:

• 0x00010000 indicates this is an exception pack.
• 0x00020000 indicates this is a QFE
• + 0x00000001 indicates device needs re-installing if component was installed.
• + 0x00000002 indicates machine needs rebooting if component was installed.

Exception Packs:

<componentId> - value of ComponentId in component INF (for version check).

<version> - version of component in component INF. In Major.Minor.Build.QFE format.

<name> - name of component. If not specified, will be obtained from INF. Also used if media prompt is required.

<osver> - format <major>.<minor>[.<build>]. If single version specified, will only install component on that version of NT. If version-range specified, will only install on that range of versions. Eg 5.0-5.1 will install on Win2k and XP only.

QFEs:

<osver> - version of operating system QFE is for (e.g. 5.1).

<sp> - service pack that QFE will first appear in (e.g. 1).

<qfe> - QFE number starting with "Q" (e.g. Q315000).

An example INF is as follows:

[Version]
Signature="$Windows NT$"
Class=Unknown ; Replace with device class
ClassGuid={4D36E97E-E325-11CE-BFC1-08002BE10318} ; Replace with device class Guid
Provider=%MSFT%

[DestinationDirs]
MSOOBCI.CopyFiles = 11 ; copying MSOOBCI DLL to system32. 

[SourceDisksNames.x86]
1 = %DiskName%,mytag,,\i386

[SourceDisksNames.ia64]
1 = %DiskName%,mytag,,\ia64

[SourceDisksFiles]
msoobci.dll=1 ; Source name

[Manufacturer]
%MSFT% = Microsoft,NT.5.1 ; Install is targeted at NT 5.1 and above

[Microsoft]
; NT4/2k/9x/ME install - probably not supported

[Microsoft.NT.5.1]
; XP install
%DeviceDesc% = Device.Comp,HwId

[Device.Comp.CoInstallers]
AddReg = MSOOBCI.AddReg
CopyFiles = MSOOBCI.CopyFiles

[Device.Comp]
Components = MyComponents
; add other installation steps here