INF CopyFiles Directive
A CopyFiles directive can do either of the following:
- Cause a single file to be copied from the source media to the default destination directory.
- Reference one or more INF-writer-defined sections in the INF that each specifies a list of files to be copied from the source media to the destination.
[DDInstall] | [DDInstall.CoInstallers] | [ClassInstall32] | [ClassInstall32.ntx86] | [ClassInstall32.ntia64] | (Windows XP and later versions of Windows) [ClassInstall32.ntamd64] (Windows XP and later versions of Windows) CopyFiles=@filename | file-list-section[, file-list-section]...
A CopyFiles directive can be specified within any of the sections shown in the formal syntax statement. This directive can also be specified within any of the following INF sections:
- An add-interface-section referenced by the INF AddInterface directive in a DDInstall.Interfaces section.
- An install-interface-section referenced in an INF InterfaceInstall32 section
Each named section referenced by a CopyFiles directive has one or more entries of the following form:
[file-list-section] destination-file-name[,[source-file-name][,[unused][,flag]]] ...
An INF-writer-defined file-list-section can have any number of entries, each on a separate line.
Each file-list-section can have an optional, associated file-list-section.security section of the following form:
These optional flags, expressed in hexadecimal notation or as a decimal value in a section entry, can be used to control how (or whether) a particular source file is copied to the destination. One or more (ORed) values for the following system-defined flags can be specified. However, some of these flags are mutually exclusive:
Do not allow the user to skip copying a file. This flag is implied if the driver package is signed.
Ignore file versions and write over existing files in the destination directory. This flag and the next two are mutually exclusive. This flag is irrelevant to digitally signed INF files.
Force file-in-use behavior: do not copy over an existing file of the same name if it is currently open. Instead, copy the given source file with a temporary name so that it can be renamed and used when the next restart occurs.
Beginning with Windows Vista and later operating systems, Windows respects this flag for all INF files, including digitally signed INF files.
Prior to Windows Vista this flag is irrelevant to digitally signed INF files. If a driver package is digitally signed, Windows installs the package as a whole and does not selectively omit files in the package based on other versions already present on the computer.
Copy the source file to the destination directory only if the file on the destination is superseded by a newer version. This flag is irrelevant to digitally signed INF files.
For example, Windows might determine that the file copy operation is not necessary because the file already exists. However, the writer of the INF knows that the operation is required and directs Windows to override its optimization and perform the file operation.
If the source file cannot be copied because the destination file is being used, rename the destination file, then copy the source file to the destination file, and delete the renamed destination file. If the destination file cannot be renamed, complete the copy operation during the next system restart. If the renamed destination file cannot be deleted, delete the renamed destination file during the next system restart.
Specifies a security descriptor, to be applied to all files copied by the named file-list-section. The security-descriptor-string is a string with tokens to indicate the DACL (D:) security component.
For information about security descriptor strings, see Security Descriptor Definition Language (Windows). For information about the format of security descriptor strings, see Security Descriptor Definition Language (Windows).
If an file-list-section.security section is not specified, files inherit the security characteristics of the directory into which the files are copied.
If an file-list-section.security section is specified, the following ACE's must be included so that installations and upgrades of devices and system service packs can occur:
- (A;;GA;;;SY) − Grants all access to the local system.
- (A;;GA;;;BA) − Grants all access to built-in administrators.
Do not specify ACE strings that grant write access to nonprivileged users.
For more information about how to specify security descriptors, see Creating Secure Device Installations.
Windows only copies a driver package to its destination location as part of a driver installation if the file has an INF CopyFiles directive. When it copies files, the operating system automatically generates temporary file names, when necessary, and renames the copied source files the next time that the operating system is started.
The INF file writer must also supply path specifications for files that are copied from source media by using the INF SourceDisksNames section and the INF SourceDisksFiles section to explicitly specify the path of each source file relative to the INF file in the source media.
The destination of copy operations is controlled by the INF DestinationDirs section. This section controls the destination for all file-copy operations, as follows:
- If a named section referenced by a CopyFiles directive has a corresponding entry in the DestinationDirs section of the same INF, that entry explicitly specifies the target destination directory into which all files that are listed in the named section are copied. If the named section is not listed in the DestinationDirs section, Windows uses the DefaultDestDir entry in the DestinationDirs section of the INF file.
- If a CopyFiles directive uses the @filename syntax, Windows uses the DefaultDestDir entry in the DestinationDirs section of the INF file.
The following points apply to the INF CopyFiles directive:
- Every file-list-section name must be unique to the INF file, but it can be referenced by CopyFiles, DelFiles, or RenFiles directives elsewhere in the same INF file. The section name must follow the general rules that are described in General Syntax Rules for INF Files.
- File names that are specified in either the @filename or file-list-section entries must be the exact name of a file on the source media. You cannot use a %strkey% token to specify the file name. For more information about %strkey% tokens, see INF Strings Section.
- The CopyFiles directive does not support decorating a file-list-section name with a system-defined platform extension (.nt, .ntx86, .ntia64, or .ntamd64).
- Do not use CopyFiles directives to copy INF files. For more information, see Copying INF Files.
Starting with Windows Vista, the following points also apply to the INF CopyFiles directive:
- When the DIFx tools preinstall a driver package in the driver store, they only copy a file from the driver package source to the driver store if the file has a corresponding INF CopyFiles directive.
- As part of a Windows upgrade, Windows only copies a driver package file to the driver store as part of a driver migration if the file has an INF CopyFiles directive.
This example shows how the SourceDisksNames, SourceDisksFiles, and DestinationDirs sections specify the paths for copy-file (and delete-file) operations that occur in processing a simple device-driver INF. (The same INF was also used previously as examples of Version, SourceDisksNames, and SourceDisksFiles sections.)
[SourceDisksNames] 1 = %Floppy_Description%,,,\WinNT [SourceDisksFiles.x86] aha154x.sys = 2,\x86 ; on distribution disk 2, in subdir \WinNT\x86 [DestinationDirs] DefaultDestDir = 12 ; DIRID_DRIVERS ; == \System32\Drivers on Windows platforms ; ... Manufacturer and Models sections omitted here DelFiles= AHA154X.DelFiles ; defines a delete-files section not shown here ; ... some other directives and sections omitted here [AHA154X.NTx86] CopyFiles=@AHA154x.SYS ; ... some other directives and sections omitted here ; ...
This example shows how a CopyFiles directive can be used in a DDInstall.CoInstallers section of an INF for a device driver that provides two device-specific co-installers to supplement the INF processing of the system device-type-specific class installer.
[DestinationDirs] XxDev_Coinstallers_CopyFiles = 11 ; DIRID_SYSTEM ; ... other file-list entries and DefaultDestDirs omitted here ; ... Manufacturer, Models, and DDInstall sections omitted here [XxDev_Install.CoInstallers] CopyFiles=XxDev_Coinstallers_CopyFiles ; ... AddReg omitted here [XxDev_Coinstallers_CopyFiles] XxPreInst.dll ; dev-specific co-installer run before class installer XxPostInst.dll ; run after class installer (post processing)
As the preceding example suggests, the names of new device-specific co-installers can be constructed from the name of the provider (shown here as Xx) and the intended use for each such co-installer DLL (shown here as PreInst and PostInst).
For additional examples of how to use the INF CopyFiles directive, see the INF files for the device driver samples that are included in the src directory of the Windows Driver Kit (WDK).