SetupInstallFilesFromInfSectionA function (setupapi.h)
[This function is available for use in the operating systems indicated in the Requirements section. It may be altered or unavailable in subsequent versions. SetupAPI should no longer be used for installing applications. Instead, use the Windows Installer for developing application installers. SetupAPI continues to be used for installing device drivers.]
The SetupInstallFilesFromInfSection function queues all the files for an installation that are specified in the Copy Files, Delete Files, and Rename Files sections that are listed by an Install section.
If a file is modified, the caller of this function is required to have privileges to write to the target directory.
Syntax
WINSETUPAPI BOOL SetupInstallFilesFromInfSectionA(
[in] HINF InfHandle,
[in] HINF LayoutInfHandle,
[in] HSPFILEQ FileQueue,
[in] PCSTR SectionName,
[in] PCSTR SourceRootPath,
[in] UINT CopyFlags
);
Parameters
[in] InfHandle
The handle to an INF file that contains the section to be installed.
[in] LayoutInfHandle
An optional pointer to a handle to the INF file that contains the SourceDisksFiles and SourceDisksNames sections.
If LayoutInfHandle is not specified, then the SourceDisksFiles and SourceDisksNames sections from InfHandle are used.
[in] FileQueue
The handle to the queue where installation operations are to be added.
[in] SectionName
The name of the Install section in the InfHandle parameter that lists the Copy Files, Delete Files, and Rename Files sections that contain the files to install.
Use a null-terminated string.
[in] SourceRootPath
An optional pointer to a root path to the source files to copy, for example, A:\ or \pegasus\win\install.
Use a null-terminated string.
[in] CopyFlags
An optional pointer to a set of flags that control the behavior of the file copy operation.
The flags can be a combination of the following values.
SP_COPY_DELETESOURCE
Deletes the source file when the copy task succeeds.
The caller is not notified if a delete task fails.
SP_COPY_REPLACEONLY
Copies a file only to overwrite a file at the destination path.
SP_COPY_NEWER_OR_SAME
Examines each file that is copied to determine whether the version resources indicate that it is the same version, or not newer than an existing copy on the target.
If the source file is not a newer or equal version, the function notifies the caller who can cancel the copy.
The file version information that is used during version checks is specified in the dwFileVersionMS and dwFileVersionLS members of a VS_FIXEDFILEINFO structure, as filled in by the Win32 version functions.
If one of the files does not have version resources, or if they have identical version information, the source file is considered newer.
SP_COPY_NEWER_ONLY
Examines each file that is being copied to determine whether its version resources indicate that it is not newer than an existing copy on the target.
If the source file is newer but not equal in version to the existing target, the file is copied.
SP_COPY_NOOVERWRITE
Checks to determine whether or not the target file exists.
If the target file exists, the function notifies the caller who can cancel the copy.
SP_COPY_NODECOMP
Does not decompress a file.
When this flag is set, the target file is not given the uncompressed form of the source name, for example, if you copy f:\x86\cmd.ex_ to \install\temp the result is the following target file: \install\temp\cmd.ex_.
If the SP_COPY_NODECOMP flag is not specified, the file is decompressed and the target is called \install\temp\cmd.exe.
The filename part of DestinationName, if specified, is deleted and replaced with the filename of the source file. When SP_COPY_NODECOMP is specified, language and version information cannot be checked.
SP_COPY_LANGUAGEAWARE
Examines each file that is being copied to determine whether or not the language is different from the language of any existing file already on the target.
If the language is different, the function notifies the caller who can cancel the copy task.
SP_COPY_SOURCE_ABSOLUTE
SourceFile is a full source path.
Do not look it up in the SourceDisksNames section of the INF file.
SP_COPY_SOURCEPATH_ABSOLUTE
SourcePathRoot is the full path part of the source file.
Ignore the relative source that is specified in the SourceDisksNames section of the INF file for the source media where the file is located. This flag is ignored if SP_COPY_SOURCE_ABSOLUTE is specified.
SP_COPY_FORCE_IN_USE
Queues the file for copying on the next system reboot, if the target exists and is being used.
SP_COPY_IN_USE_NEEDS_REBOOT
Alerts the user that the system needs to be rebooted, if the file is being used during a copy operation.
SP_COPY_NOSKIP
Does not give the user the option to skip a file.
SP_COPY_FORCE_NOOVERWRITE
Checks to determine whether or not the target file exists, and if the target exists, the file is not overwritten and the caller is not notified.
SP_COPY_FORCE_NEWER
Examines each file that is being copied to identify that its version resources (or time stamps for non-image files) indicate that it is not newer than an existing copy on the target.
If the file that is being copied is not newer, the file is not copied, and the caller is not notified.
SP_COPY_WARNIFSKIP
Warns that skipping a file may affect an installation if the user tries to skip a file.
Use this flag for system-critical files.
Return value
If the function succeeds, the return value is a nonzero value.
If the function fails, the return value is 0 (zero). To get extended error information, call GetLastError.
Remarks
SetupInstallFilesFromInfSection can be called multiple times to queue the files that are specified in multiple INF sections. After the queue is committed successfully and the files are copied, renamed, and/or deleted, SetupInstallFromInfSection can be called to perform registry and INI installation operations.
If a UNC directory is specified as the target directory of a file installation, you must ensure that the UNC directory exists before you call SetupInstallFilesFromInfSection. The setup functions do not check for the existence of directories and do not create UNC directories. If the target UNC directory does not exist, the file installation fails.
Note
The setupapi.h header defines SetupInstallFilesFromInfSection as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows XP [desktop apps only] |
| Minimum supported server | Windows Server 2003 [desktop apps only] |
| Target Platform | Windows |
| Header | setupapi.h |
| Library | Setupapi.lib |
| DLL | Setupapi.dll |