You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
14 KiB
14 KiB
<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>