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.

Requirements

See also

Functions

Overview

SetupInstallFromInfSection

SetupInstallServicesFromInfSection