SetupInstallFileA 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 SetupInstallFile function installs a file as specified either by an INFCONTEXT returned by SetupFindXXXLine or explicitly by the file name and path.
If a file is copied, the caller of this function must have write privileges into the target directory.
Syntax
WINSETUPAPI BOOL SetupInstallFileA(
[in] HINF InfHandle,
[in] PINFCONTEXT InfContext,
[in] PCSTR SourceFile,
[in] PCSTR SourcePathRoot,
[in] PCSTR DestinationName,
[in] DWORD CopyStyle,
[in] PSP_FILE_CALLBACK_A CopyMsgHandler,
[in] PVOID Context
);
Parameters
[in] InfHandle
Optional pointer to the handle to an INF file that contains SourceDisksNames and SourceDisksFiles sections. If platform-specific sections exist for the user's system (for example, SourceDisksNames.x86 and SourceDisksFiles.x86), the platform-specific section will be used. If InfContext is null and CopyStyle includes SP_COPY_SOURCE_ABSOLUTE or SP_COPY_SOURCEPATH_ABSOLUTE, InfHandle is ignored.
[in] InfContext
Optional pointer to the context of a line in a Copy Files section in an INF file. The routine looks up this file in the SourceDisksFiles section of InfHandle to get file copy information. If InfHandle is not specified, SourceFile must be.
[in] SourceFile
Optional pointer to the file name (no path) of the file to copy. The file is looked up in the SourceDisksFiles section. The SourceFile parameter must be specified if InfContext is not. SourceFile is ignored if InfContext is specified.
[in] SourcePathRoot
Optional pointer to the root path for the file to be copied (for example, A:\ or F:). Paths in the SourceDisksNames section are appended to this path. The SourcePathRoot parameter is ignored if CopyStyle includes the SP_COPY_SOURCE_ABSOLUTE flag.
[in] DestinationName
Optional pointer to the file name only (no path) of the target file. This parameter can be null to indicate that the target file should have the same name as the source file. If InfContext is not specified, DestinationName supplies the full path and file name for the target.
[in] CopyStyle
Flags that control the behavior of the file copy operation. These flags may be a combination of the following values.
| Value | Meaning |
|---|---|
|
Deletes the source file upon successful copy. The caller is not notified if the delete operation fails. |
|
Copies the file only if doing so would overwrite a file at the destination path. If the target does not exist, the function returns FALSE and GetLastError returns NO_ERROR. |
|
Examines each file being copied to see if its version resources indicate that it is either the same version or not newer than an existing copy on the target.
The file version information used during version checks is that specified in the dwFileVersionMS and dwFileVersionLS members of a VS_FIXEDFILEINFO structure, as filled in by the 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. If the source file is not newer or equal in version, and CopyMsgHandler is specified, the caller is notified and may cancel the copy operation. If CopyMsgHandler is not specified, the file is not copied. |
|
Examine each file being copied to see if 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. |
|
Check whether the target file exists, and, if so, notify the caller who may veto the copy. If CopyMsgHandler is not specified, the file is not overwritten. |
|
Do not decompress the file. When this flag is set, the target file is not given the uncompressed form of the source name (if appropriate). For example, copying F:\x86\cmd.ex_ to \\install\temp results in a target file of \\install\temp\cmd.ex_. If the SP_COPY_NODECOMP flag was not specified, the file would be decompressed and the target would be called \\install\temp\cmd.exe. The file name part of DestinationName, if specified, is stripped and replaced with the file name of the source file. When SP_COPY_NODECOMP is specified, no language or version information can be checked. |
|
Examine each file being copied to see if its language differs from the language of any existing file already on the target. If so, and CopyMsgHandler is specified, the caller is notified and may cancel the copy. If CopyMsgHandler is not specified, the file is not copied. |
|
SourceFile is a full source path. Do not look it up in the SourceDisksNames section of the INF file. |
|
SourcePathRoot is the full path part of the source file. Ignore the relative source 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. |
|
If the target exists, behaves as if it is in use and queues the file for copying on the next system restart. |
|
Checks whether the target file exists, and, if so, the file is not overwritten. The caller is not notified. |
|
Examines each file being copied to see if 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 being copied is not newer, the file is not copied. The caller is not notified. The function returns FALSE, and GetLastError returns NO_ERROR. |
[in] CopyMsgHandler
Optional pointer to a callback function to be notified of various conditions that may arise during the file copy operation.
[in] Context
Optional pointer to a caller-defined value that is passed as the first parameter of the callback function.
Return value
If the function succeeds, the return value is a nonzero value.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
If GetLastError returns NO_ERROR, the file copy operation was not completed. The file may not have been copied because the file copy operation was unnecessary or because the file callback function returned FALSE.
Remarks
If a UNC directory is specified as the target directory of a file installation, you must ensure it exists before you call SetupInstallFile. The setup functions do not check for the existence of nor create UNC directories. If the target UNC directory does not exist, the file installation will fail.
Note
The setupapi.h header defines SetupInstallFile 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 |
See also
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for