About INF File Architecture

  • Article

An INF file consists of a set of named sections, each containing one or more line items. Each section begins with the name of the section enclosed in square brackets. Sections have a particular purpose (for example, to copy files or add entries to the registry). Each of the line items in a section contributes to the purpose of the section. This article presents the syntax, structure, and processing of INF files.

  • INF File Syntax
  • Main Sections of an INF File
  • Valid Keys
  • Hook Syntax
  • Win32 INF Syntax and Variable Substitutions
  • Sample INF File
  • Order of Processing and Execution of INF Files

INF File Syntax

To be understood by Internet Component Download, INF files must obey the following syntax rules.

  • All URLs in the INF file must be encoded for handling of special characters—for example, a space must be encoded as %20, as in this example.

    "http://example.microsoft.com/sample%20control.ocx"

  • Friendly file names are created using the decoded base names of these URLs. URLs, if relative, are based on the context of the main CODEBASE attribute, unless redirected by the object index, in which case the context is set to that of the redirected URL.

Main Sections of an INF File

Internet Component Download looks for and understands the [Add.Code] and [Setup Hooks] sections in the INF file. If both of these sections are missing, the INF file is assumed to be a standard Microsoft Win32 INF file without code downloader extensions, and a hook is created to have the system process the INF file's [DefaultInstall] section.

The [Add.Code] section lists all the files to be installed, including optional files.

[Add.Code]
filename1=section-name1
filename2=section-name2

The [Setup Hooks] section lists all the hooks to be executed before setting up files in the [Add.Code] section.

[Setup Hooks]
hookname1=section-name4
hookname2=section-name5

Like the [Add.Code] section, the [Setup Hooks] section also lists files to be installed. The hook= key is used in the [Setup Hooks] section to execute conditional hooks. You can also list a set of unconditional hooks that will always be executed before setup of files in the [Add.Code] section. This is done by listing all the hooks in order of preferred execution in the [Setup Hooks] section.

Note  When using hooks, it is important to add the following lines to your INF file for compatibility.

 

[Version]
Signature="$CHICAGO$"
AdvancedINF=2.0

Valid Keys

Each section in an INF file is identified by the section name in brackets, followed by all the key values, as in an .ini file.

[section-name1]
key1=value1
key2=value2

The following keys are valid in an INF file section.

  • File-%opersys%-%cpu%=[url | ignore | thiscab]

    Currently, %opersys% can only be win32, and %cpu% can be one of the following three values: [x86 | ia64 | amd64]. A URL can indicate the correct file for the target operating system and CPU, or the special value "ignore", which indicates the file is not required for the specified platform. Windows Internet Explorer always looks for this key before the platform-independent description key File=, as described below.

  • File=[url | thiscab]

    The value of the File key indicates where the file can be downloaded from. It can be a URL or the special value "thiscab", which indicates that the file is located in the cabinet (.cab) file where the INF file came from. If no value is specified, component download fails if the file is not already installed on the user's computer. If this URL points to a non-HTTP protocol or to an HTTP server that does not support/understand the special Accept Types sent out by the code downloader as discussed in Platform Independence and HTTP, you must use the File-%opersys%-%cpu%= key described in the previous paragraph.

  • FileVersion=a,b,c,d

    The FileVersion key specifies the minimum required version of the file specified by the File key. If no value is specified, any version is acceptable.

  • Clsid={nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn}

    The value of the Clsid key is the string representation of the component CLSID, enclosed in braces {}.

  • DestDir=[10 | 11]

    DestDir can be set to 10 to place the file into the \Windows directory or to 11 to place the file into the \Windows\System directory. If no value is specified, the file is placed into the \Cache directory.

  • RegisterServer=[yes | no]

    This key provides a way to override the self-registration policy. When the value of this key is set to "no", the file will not be registered even if it is marked "OleSelfRegister". For more information on the registration policy, see Registry Details.

Hook Syntax

A hook is a way to override or customize the installation process of one or more pieces required for a component. There are two types of hooks—unconditional and conditional. Unconditional hooks are hooks that always get executed. Conditional hooks are run only when a certain condition evaluates as TRUE.

This is the way to specify conditional hooks:

hook=section-name3

If the version of the class identifier (CLSID) specified in this section is lower than the minimum required version, and there are no values specified in the File= or File-%opersys%-%cpu%= key, the component downloader looks for a custom setup hook to install the required file or component.

The hooks section looks like this:

[section-name3]
key1=value1
key2=value2

It is valid for several different [Add.Code] section hooks to point to the same [Setup Hooks] section. This is a way to have one hook install one or more components/files. The hook is executed only once if one or more files are missing.

The following keys are valid in a hooks section.

  • File-%opersys%-%cpu%=[url | ignore]

    Currently, %opersys% can only be win32, and %cpu% can be one of the following three values: [x86 | ia64 | amd64]. A URL can be specified to indicate the correct file for the target operating system and CPU, or the special value "ignore", which indicates the file is not required for the specified platform. This is identical to the way you would specify the location of a file name in a section describing the piece in [Add.Code] except that this has to point to a .cab file, and the keyword 'thiscab' is not applicable with this key. This value, if absent, would cause Internet Explorer to set its context to the .cab file that this INF file was located in. This key is always looked for before the platform-independent description key File= as described below.

  • File=[url]

    This is a URL to a .cab file that contains one or more files that are needed for the hook. The component download downloads the .cab file and expands it into a unique temporary directory and then executes the hook. This is identical to the way you would specify the location of a file name in a section describing the piece in [Add.Code], except that this has to point to a .cab file, and the keyword 'thiscab' is not applicable with this key. This value, if absent, would cause Internet Explorer to set its context to the .cab file that this INF file was located in.

  • Run=[cmd-line]

    This is the command line to be run in the temporary directory with the extracted files in the .cab file pointed to by the above File= key. The command line can contain some component downloader variables that are expanded before execution. It can also contain translations of Win32 INF syntax based on registry key values on the client. If this key is absent, the component downloader looks for InfFile= and InfSection= keys to run a Win32 INF hook.

  • InfFile=[name of Win32 INF file inside the .cab file]

    If no value is specified for this key, the value is set to the current INF (the main INF pointed to or found in the .cab file pointed to by the CODEBASE attribute). This is a way to use standard Win32 INF syntax for installation of a file or component.

  • InfSection=[section name in the InfFile mentioned in the above key]

    If no value is specified for this key, the value is set to the [DefaultInstall] section of the INF file specified in the InfFile= key above.

For more information about hooks, see Using Hooks.

Win32 INF Syntax and Variable Substitutions

If both [Add.Code] and [Setup Hooks] sections are missing from the INF file, the INF file is assumed to be a standard Win32 INF file without code downloader extensions, and a hook is created to have the system process the INF file's [DefaultInstall] section.

The following component downloader variables are valid in a command line.

  • EXTRACT_DIR

    This variable can be used as a parameter in a command line to specify the directory in which files are extracted. For example, the following line runs the command Mysetup.exe in the extracted directory.

    run=%EXTRACT_DIR%\mysetup.exe

  • OBJECT_DIR

    Expands to the default destination directory for controls. In Microsoft Internet Explorer 4.0 and later, this is the Downloaded Program Files folder under the Windows directory. If there is a file name conflict with a previously existing file in this directory, CONFLICT.<n> folders are created under the default destination directory, where n is a monotonically increasing number. OBJECT_DIR reflects the final destination directory including such name conflict resolutions.

Sample INF File

The following is a sample INF file that demonstrates the syntax understood by the Internet Component Download service.

;Sample INF file for CIRC3.OCX
[Add.Code]
circ3.ocx=circ3.ocx
random.dll=random.dll
mfc40.dll=mfc40.dll
example.ocx=example.ocx

[circ3.ocx]
; Lines below specify that the specified circ3.ocx (clsid, version)
; needs to be installed on the system. If it doesn't exist already, 
; it can be downloaded from the given location (a .cab file).
; Note: if "thiscab" is specified instead of the file location, 
; it is assumed that the desired file is present in the same .cab 
; cabinet that the INF originated from. Otherwise, if the location 
; pointed to is a different .cab, the new cabinet is also downloaded
; and unpacked in order to extract the desired file.
file=http://www.code.com/circ3/circ3.cab
clsid={9DBAFCCF-592F-101B-85CE-00608CEC297B}
; Note that the {}s are required when entering a <tla rid="tla_clsid"/> in the INF file.
; This is slightly different from the HTML syntax for inserting CLSIDs 
; in an <OBJECT> tag.
FileVersion=1,0,0,143

[random.dll]
; Lines below specify that the random.dll needs to be installed in 
; the system.
; If this doesn't exist already, it can be downloaded from the given 
; location.
file=http:// www.code.com/circ3/random.dll
; Note that the FileVersion is optional, and it can also be left 
; empty, meaning that any version is ok.
FileVersion=
DestDir=10

; DestDir can be set to 10 or 11 ( LDID_WIN or LDID_SYS by INF 
; convention). 
; This places files in \Windows or \Windows\System, respectively.
; If no dest dir is specified (typical case), code is installed in 
; the occache directory.

[mfc40.dll]
; Leaving the file location empty specifies that the installation
; needs mfc40 (version 4,0,0,5), but it should not be downloaded.
; If this file is not already present on the client machine, component 
; download fails.
file=
FileVersion=4,0,0,5

[example.ocx]
; Leaving the file location empty specifies that the installation
; needs the specified example.ocx (clsid, version), but it should not 
; be downloaded.
; If this file is not already present on the client machine, component 
; download fails.
file=clsid={DEADBEEF-592F-101B-85CE-00608CEC297B}
FileVersion=1,0,0,143

Order of Processing and Execution of INF Files

The [Add.Code] section is processed in the order listed, but the files are installed and set up in reverse order. This means that typically you would list the main OCX file first in the INF file, followed by dependent DLLs. The dependent DLLs are guaranteed to be installed and available at registration time of the main OCX.

Unconditional hooks, those hooks in the [Setup Hooks] section in the INF file, are executed in the order listed in that section (Hook1 executes before Hook2). Conditional hooks, those hooks in the file sections referenced by file names in the [Add.Code] section, are executed in the order of the [Add.Code] section. Between conditional hooks and file section installation/setup, conditional hooks always get executed before file section installations/setups in the same .cab file. Between two file section installations/setups, the order of file installation and setup is the reverse of the listing in the [Add.Code] section. Between two conditional hooks, the order is the same as that listed in the [Add.Code] section. Note this different ordering rule between conditional hooks and file section installation and setup.