|
|
<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.AddRegCopyFiles = 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>
|
