325 lines
14 KiB
HTML
325 lines
14 KiB
HTML
|
<HTML>
|
||
|
|
<HEAD>
|
||
|
|
<TITLE>Out Of Band Component Installer</TITLE>
|
||
|
|
<META content="text/html; charset=windows-1252" http-equiv=Content-Type>
|
||
|
|
<META content="Microsoft FrontPage 5.0" name=GENERATOR>
|
||
|
|
<style>
|
||
|
|
<!--
|
||
|
|
DIV.Section1 {
|
||
|
|
page: Section1
|
||
|
|
}
|
||
|
|
-->
|
||
|
|
</style>
|
||
|
|
</HEAD>
|
||
|
|
|
||
|
|
<BODY link=#0000ff><FONT face=Verdana size=5>
|
||
|
|
<H2>Out Of Band Component Installer</H2></FONT>
|
||
|
|
<FONT face=Arial size=2 color="#FF0000">
|
||
|
|
<P>(</FONT><FONT face=Verdana size=2><SPAN style="COLOR: #ff0000; FONT-FAMILY: Arial; FONT-SIZE: 10pt">Microsoft
|
||
|
|
Confidential)</SPAN></P>
|
||
|
|
|
||
|
|
<H3>SUMMARY</H3>
|
||
|
|
This document describes how to use "MSOOBCI.DLL" for exception pack
|
||
|
|
installation. MSOOBCI.DLL has been designed for use on Windows 2000 and XP. It
|
||
|
|
will also run on NT4 with reduced functionality <font color="#FF0000"><i>
|
||
|
|
Untested</i></font>.<p>MSOOBCI.DLL will simplify installation of exception
|
||
|
|
packages to ensure that the correct registration occurs as outlined in
|
||
|
|
</FONT><a href="http://wfp/excp.doc">System Components Redistribution
|
||
|
|
Specification</a> (<a href="http://wfp/excp.doc">http://wfp/excp.doc</a>). In
|
||
|
|
particular it ensures that a package does version checking correctly, is copied
|
||
|
|
to the registered component directory correctly and is registered correctly.<p>
|
||
|
|
MSOOBCI.DLL also works as a device co-installer to ensure that one or more
|
||
|
|
components are installed when a device dependent upon them is installed. In this
|
||
|
|
mode, it may install exception packages or QFE's.<FONT face=Verdana size=2><H3>
|
||
|
|
General</H3>
|
||
|
|
|
||
|
|
<p>A component INF must have the following entries in it's Version section:</p>
|
||
|
|
|
||
|
|
<p><b>[Version]<br>
|
||
|
|
</b>signature = "$Windows NT$"<br>
|
||
|
|
Class = %ExceptionClassDesc% ; <font color="#FF0000">Short descriptive name of
|
||
|
|
exception pack (no more than 63 chars)</font><br>
|
||
|
|
ClassGUID = {F5776D81-AE53-4935-8E84-B0B283D8BCEF} ; <font color="#FF0000">
|
||
|
|
Indicates exception pack</font><br>
|
||
|
|
Provider = %Msft%<br>
|
||
|
|
CatalogFile = delta.cat ; <font color="#FF0000">substitute name of catalog file</font><br>
|
||
|
|
ComponentId = {E34D1BDE-2AEB-4bc1-94F7-9D4D8387F1EE} ; <font color="#FF0000">
|
||
|
|
your component ID</font><br>
|
||
|
|
DriverVer = 12/17/2001,5.1.2.0 ; <font color="#FF0000">Not required by spec, but
|
||
|
|
used by msoobci.dll - date & version of exception pack</font><br>
|
||
|
|
</p>
|
||
|
|
|
||
|
|
<p>A component INF must use <b>[DefaultInstall]</b> 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).</p>
|
||
|
|
|
||
|
|
<p>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.</p>
|
||
|
|
|
||
|
|
<p>Files specified in <b>[SourceDisksFiles] </b>in this exception pack must not
|
||
|
|
appear in any other exception packs.</p>
|
||
|
|
|
||
|
|
<p>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.</p>
|
||
|
|
|
||
|
|
<p>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.</p>
|
||
|
|
|
||
|
|
<p>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.</p>
|
||
|
|
|
||
|
|
<H3>RunDll32 Invocation</H3>
|
||
|
|
|
||
|
|
<p><b>rundll32 </b><path><b>\msoobci.dll,DoInstall</b> <path><b>\</b>comp<b>.INF</b>;<flags>;<compId>;<ver>;<name><p>
|
||
|
|
Example:<p>rundll32 Z:\mypath\msoobci.dll,DoInstall Z:\mypath\expacktest.inf;0x22;{E34D1BDE-2AEB-4bc1-94F7-9D4D8387F1EE<br>
|
||
|
|
};5.1.2;Foo Bar<br>
|
||
|
|
rundll32 Z:\mypath\msoobci.dll,DoInstall Z:\mypath\expacktest.inf<p>All but the
|
||
|
|
INF path is optional. No success/failure feedback is given.<p>Refer to <b>
|
||
|
|
InstallComponent</b> for discussion of flags.<p> <h3>InstallComponent API</h3>
|
||
|
|
|
||
|
|
<p>HRESULT<br>
|
||
|
|
WINAPI<br>
|
||
|
|
InstallComponent(<br>
|
||
|
|
IN LPCTSTR InfPath,<br>
|
||
|
|
IN DWORD Flags,<br>
|
||
|
|
IN const GUID * CompGuid, OPTIONAL<br>
|
||
|
|
IN INT VerMajor, OPTIONAL<br>
|
||
|
|
IN INT VerMinor, OPTIONAL<br>
|
||
|
|
IN INT VerBuild, OPTIONAL<br>
|
||
|
|
IN INT VerQFE, OPTIONAL<br>
|
||
|
|
IN LPCTSTR Name OPTIONAL<br>
|
||
|
|
);<p>(defined in msoobci.h)<h4 dir="ltr">Description</h4>
|
||
|
|
|
||
|
|
<p dir="ltr">Installs an exception package specified in <i>InfPath</i>. 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.<h4 dir="ltr">Return</h4>
|
||
|
|
|
||
|
|
<p dir="ltr">S_FALSE if same or better exception pack already installed.<br>
|
||
|
|
S_OK if exception pack installed (no boot required).<br>
|
||
|
|
INST_S_REBOOT if exception pack installed but a reboot is required.<br>
|
||
|
|
INST_S_REBOOTING if exception pack installed and machine is rebooting.<br>
|
||
|
|
various errors may be returned as a HRESULT.<h4 dir="ltr">Parameters</h4>
|
||
|
|
|
||
|
|
<p dir="ltr">InfPath - full path to INF<p dir="ltr">Flags:<ul>
|
||
|
|
<li dir="ltr">
|
||
|
|
|
||
|
|
<p dir="ltr">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.</li>
|
||
|
|
<li dir="ltr">
|
||
|
|
|
||
|
|
<p dir="ltr">COMP_FLAGS_NOUI - do not show progress UI.</li>
|
||
|
|
<li dir="ltr">
|
||
|
|
|
||
|
|
<p dir="ltr">COMP_FLAGS_NOPROMPTREBOOT - reboot if needed without prompting.</li>
|
||
|
|
<li dir="ltr">
|
||
|
|
|
||
|
|
<p dir="ltr">COMP_FLAGS_PROMPTREBOOT - prompt for reboot if needed.</li>
|
||
|
|
<li dir="ltr">
|
||
|
|
|
||
|
|
<p dir="ltr">COMP_FLAGS_NEEDSREBOOT - force the fact that a reboot is needed
|
||
|
|
(same as Reboot key in INF).</li>
|
||
|
|
<li dir="ltr">
|
||
|
|
|
||
|
|
<p dir="ltr">COMP_FLAGS_FORCE - don't do version checking, overwrite existing
|
||
|
|
exception pack.</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p dir="ltr">CompGuid - if specified (non-NULL) verified against ComponentId
|
||
|
|
entry in INF.<p dir="ltr">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.<p dir="ltr">Name - short name (no more than 64 characters including NULL)
|
||
|
|
describing the package. If specified, overrides "CLASS" entry specified in INF.<p dir="ltr"> <h3 dir="ltr">
|
||
|
|
InstallInfSection API</h3>
|
||
|
|
|
||
|
|
<p dir="ltr">HRESULT<br>
|
||
|
|
WINAPI<br>
|
||
|
|
InstallInfSection(<br>
|
||
|
|
IN LPCTSTR InfPath,<br>
|
||
|
|
IN LPCTSTR SectionName, OPTIONAL<br>
|
||
|
|
IN DWORD Flags<br>
|
||
|
|
);<p>(defined in msoobci.h)<h4 dir="ltr">Description</h4>
|
||
|
|
|
||
|
|
<p dir="ltr">Installs a Section within an INF (cf InstallHinfSection in SetupAPI).<h4 dir="ltr">
|
||
|
|
Return</h4>
|
||
|
|
|
||
|
|
<p dir="ltr">S_OK if section installed (no boot required).<br>
|
||
|
|
INST_S_REBOOT if section installed but a reboot is required.<br>
|
||
|
|
INST_S_REBOOTING if section installed and machine is rebooting.<br>
|
||
|
|
various errors may be returned as a HRESULT.<h4 dir="ltr">Parameters</h4>
|
||
|
|
|
||
|
|
<p dir="ltr">InfPath - full path to INF<p dir="ltr">SectionName - fully
|
||
|
|
qualified name of section. If <i>SectionName</i> is NULL then [DefaultInstall]
|
||
|
|
or decorated variant will be used.<p dir="ltr">Flags:<ul>
|
||
|
|
<li dir="ltr">
|
||
|
|
|
||
|
|
<p dir="ltr">COMP_FLAGS_NOUI - do not show progress UI.</li>
|
||
|
|
<li dir="ltr">
|
||
|
|
|
||
|
|
<p dir="ltr">COMP_FLAGS_NOPROMPTREBOOT - reboot if needed without prompting.</li>
|
||
|
|
<li dir="ltr">
|
||
|
|
|
||
|
|
<p dir="ltr">COMP_FLAGS_PROMPTREBOOT - prompt for reboot if needed.</li>
|
||
|
|
<li dir="ltr">
|
||
|
|
|
||
|
|
<p dir="ltr">COMP_FLAGS_NEEDSREBOOT - force the fact that a reboot is needed
|
||
|
|
(same as Reboot key in INF).</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p dir="ltr"> <h3 dir="ltr">IsUserAdmin API</h3>
|
||
|
|
|
||
|
|
<p>BOOL<br>
|
||
|
|
WINAPI<br>
|
||
|
|
IsUserAdmin(<br>
|
||
|
|
VOID<br>
|
||
|
|
);<p>(defined in msoobci.h)<h4 dir="ltr">Description</h4>
|
||
|
|
|
||
|
|
<p dir="ltr">Checks if current user has administrator privileges. Caller is <b>
|
||
|
|
NOT</b> expected to be impersonating anyone and <b>IS</b> expected to be able to
|
||
|
|
open their own process and process token.<h4 dir="ltr">Return</h4>
|
||
|
|
|
||
|
|
<p dir="ltr">TRUE if current user has administrator privileges. FALSE otherwise.<p dir="ltr"> <h3 dir="ltr">
|
||
|
|
IsInteractiveWindowStation API</h3>
|
||
|
|
|
||
|
|
<p>BOOL<br>
|
||
|
|
WINAPI<br>
|
||
|
|
IsInteractiveWindowStation(<br>
|
||
|
|
VOID<br>
|
||
|
|
);<p>(defined in msoobci.h)<h4 dir="ltr">Description</h4>
|
||
|
|
|
||
|
|
<p dir="ltr">Checks if current user is running in an interactive window station
|
||
|
|
(i.e., they can respond to dialogs).<h4 dir="ltr">Return</h4>
|
||
|
|
|
||
|
|
<p dir="ltr">TRUE if running in an interactive window station. FALSE otherwise.<p dir="ltr"> <h3 dir="ltr">
|
||
|
|
DriverInstallComponents API</h3>
|
||
|
|
|
||
|
|
<p dir="ltr">DWORD<br>
|
||
|
|
CALLBACK<br>
|
||
|
|
DriverInstallComponents (<br>
|
||
|
|
IN DI_FUNCTION InstallFunction,<br>
|
||
|
|
IN HDEVINFO DeviceInfoSet,<br>
|
||
|
|
IN PSP_DEVINFO_DATA DeviceInfoData,<br>
|
||
|
|
IN OUT PCOINSTALLER_CONTEXT_DATA Context<br>
|
||
|
|
);<p>(defined in msoobci.h)<h4 dir="ltr">Description</h4>
|
||
|
|
|
||
|
|
<p dir="ltr">Co-Installer callback entry to handle "Components" keyword in INF.<h4 dir="ltr">
|
||
|
|
Return</h4>
|
||
|
|
|
||
|
|
<p dir="ltr">Refer to co-installers description in DDK.<h4 dir="ltr">Parameters</h4>
|
||
|
|
<p>Refer to co-installers description in DDK.</p>
|
||
|
|
<p> </p>
|
||
|
|
<h3>Driver INF Component Installation</h3>
|
||
|
|
<p>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.</p>
|
||
|
|
<p>With this co-installer, one or more</p>
|
||
|
|
<p><b>Components=</b><compsection>[,<compsection>...]</p>
|
||
|
|
<p>entries can be specified in the [DDInstall] section. The compoent section has
|
||
|
|
the form:</p>
|
||
|
|
<p>[compsection]<br>
|
||
|
|
<component>,0x0001xxxx,<componentId>,<version>[,<name>[,<osver>[<b>-</b><osver]]]<font color="#FF0000">
|
||
|
|
; exception pack</font><br>
|
||
|
|
<component>,0x0002xxxx,<osver>,<sp>,<qfe><font color="#FF0000">
|
||
|
|
; service pack<br>
|
||
|
|
</font><component>,<flags>,...<br>
|
||
|
|
...<br>
|
||
|
|
; <font color="#FF0000">multiple entries allowed, a component must only be
|
||
|
|
listed once</font></p>
|
||
|
|
<p>Where:</p>
|
||
|
|
<p><component> - full pathname to INF that contains the exception pack or full
|
||
|
|
path to self-extracting executable to install QFE.</p>
|
||
|
|
<p><flags>:</p>
|
||
|
|
<ul>
|
||
|
|
<li>0x00010000 indicates this is an exception pack.</li>
|
||
|
|
<li>0x00020000 indicates this is a QFE</li>
|
||
|
|
<li>+ 0x00000001 indicates device needs re-installing if component was
|
||
|
|
installed.</li>
|
||
|
|
<li>+ 0x00000002 indicates machine needs rebooting if component was
|
||
|
|
installed.</li>
|
||
|
|
</ul>
|
||
|
|
<h4>Exception Packs:</h4>
|
||
|
|
<p><componentId> - value of ComponentId in component INF (for version check).</p>
|
||
|
|
<p><version> - version of component in component INF. In Major.Minor.Build.QFE
|
||
|
|
format.</p>
|
||
|
|
<p><name> - name of component. If not specified, will be obtained from INF. Also
|
||
|
|
used if media prompt is required.</p>
|
||
|
|
<p><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.</p>
|
||
|
|
<h4>QFEs:</h4>
|
||
|
|
<p><osver> - version of operating system QFE is for (e.g. 5.1).</p>
|
||
|
|
<p><sp> - service pack that QFE will first appear in (e.g. 1).</p>
|
||
|
|
<p><qfe> - QFE number starting with "Q" (e.g. Q315000).</p>
|
||
|
|
<p> </p>
|
||
|
|
<p>An example INF is as follows:</p>
|
||
|
|
<pre><font face="Verdana">[Version]
|
||
|
|
Signature="$Windows NT$"
|
||
|
|
</font>Class=Unknown ; <font color="#FF0000">Replace with device class</font>
|
||
|
|
ClassGuid={4D36E97E-E325-11CE-BFC1-08002BE10318} ; <font color="#FF0000">Replace with device class Guid</font>
|
||
|
|
Provider=%MSFT%</pre>
|
||
|
|
<pre>[DestinationDirs]
|
||
|
|
MSOOBCI.CopyFiles = 11 ; <font color="#FF0000">copying MSOOBCI DLL to system32. </font>
|
||
|
|
|
||
|
|
[SourceDisksNames.x86]
|
||
|
|
1 = %DiskName%,mytag,,\i386</pre>
|
||
|
|
<pre>[SourceDisksNames.ia64]
|
||
|
|
1 = %DiskName%,mytag,,\ia64
|
||
|
|
|
||
|
|
[SourceDisksFiles]
|
||
|
|
msoobci.dll=1 ; <font color="#FF0000">Source name</font>
|
||
|
|
|
||
|
|
[Manufacturer]
|
||
|
|
%MSFT% = Microsoft,NT.5.1 ; <font color="#FF0000">Install is targeted at NT 5.1 and above</font>
|
||
|
|
|
||
|
|
[Microsoft]
|
||
|
|
; <font color="#FF0000">NT4/2k/9x/ME install - probably not supported
|
||
|
|
|
||
|
|
</font>[Microsoft.NT.5.1]
|
||
|
|
; <font color="#FF0000">XP install
|
||
|
|
</font>%DeviceDesc% = Device.Comp,HwId
|
||
|
|
|
||
|
|
[Device.Comp.CoInstallers]
|
||
|
|
AddReg = MSOOBCI.AddReg
|
||
|
|
CopyFiles = MSOOBCI.CopyFiles
|
||
|
|
|
||
|
|
[Device.Comp]
|
||
|
|
Components = MyComponents
|
||
|
|
; <font color="#FF0000">add other installation steps here</font></pre>
|
||
|
|
<pre>[Device.Comp.Services]
|
||
|
|
AddService = ,2 ; <font color="#FF0000">or other service entries</font>
|
||
|
|
|
||
|
|
|
||
|
|
[MyComponents]
|
||
|
|
;<font color="#FF0000"> actual component reference</font>
|
||
|
|
%1%\pack\expacktest.inf,0x10001,"{E34D1BDE-2AEB-4bc1-94F7-9D4D8387F1EE}",5.1.2.0,"ExPack Test",5.1
|
||
|
|
</FONT>%1%\qfe\Q315000_WXP_SP1_x86_ENU.exe,5.1,1,Q315000
|
||
|
|
<FONT face=Verdana size=2>
|
||
|
|
[MSOOBCI.AddReg]
|
||
|
|
; <font color="#FF0000">same name as used in MSOOBCI.CopyFiles</font>
|
||
|
|
HKR,,CoInstallers32,0x10000,"msoobci01.DLL,DriverInstallComponents"
|
||
|
|
|
||
|
|
[MSOOBCI.CopyFiles]
|
||
|
|
; <font color="#FF0000">copy to a name apropriate for this version of co-installer</font>
|
||
|
|
msoobci01.dll,msoobci.dll,,0x10</pre>
|
||
|
|
|
||
|
|
<p dir="ltr"> </FONT><P align=center><FONT face=Verdana size=2><A href="#top">Top of page</A></P></FONT>
|
||
|
|
<TABLE border=0" cellSpacing="0" width="624">
|
||
|
|
<TR>
|
||
|
|
<TD bgColor="#00ffff" height="2" vAlign="middle"></TD></TR></TABLE>
|
||
|
|
<FONT face="MS Sans Serif" size=1>
|
||
|
|
<P>© Microsoft Corporation 2001</FONT><FONT face=Verdana size=2> (Internal)</P></FONT>
|
||
|
|
</BODY>
|