SetupInstallFile

The SetupInstallFile function installs a file as specified either by an INFCONTEXT returned by SetupFindXXXLine or explicitly by the filename and path information.

BOOL SetupInstallFile(
  HINF InfHandle,         // optional, handle to the INF file
  PINFCONTEXT InfContext,  // optional, context for a INF file line
  PCTSTR SourceFile,      // optional, name of file to copy
  PCTSTR SourcePathRoot,  // optional, root path to source
  PCTSTR DestinationName,  // optional, filename after copy
  DWORD CopyStyle,        // specifies copy behavior
  PSP_FILE_CALLBACK CopyMsgHandler, 
                          // optional, callback routine to use
  PVOID Context           // optional, callback routine context
);
 

Parameters

InfHandle

This optional parameter points to the handle of an INF file that contains SourceDisksNames and SourceDisksFiles sections. If platform-specific sections exist for the user's system (for example, SourceDisksNames.mips and SourceDisksFiles.mips), the platform-specific section will be used. If InfContext is NULL and CopySyle includes SP_COPY_SOURCE_ABSOLUTE or SP_COPY_SOURCEPATH_ABSOLUTE, InfHandle is ignored.

InfContext

This optional parameter points to the context of a line in a Copy Files section in an INF file. The routine looks this file up in the SourceDisksFiles section of InfHandle to get file copy information. If InfContext is not specified, SourceFile must be.

SourceFile

This optional parameter supplies the filename (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, and is ignored if InfContext is specified.

SourcePathRoot

This optional parameter supplies 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.

DestinationName

This optional parameter supplies the filename 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 target path and filename for the target.

CopyStyle

Flags that control the behavior of the file copy operation. These flags may be a combination of the following values:

SP_COPY_DELETESOURCE

Delete the source file upon successful copy. The caller is not notified if the delete fails.

SP_COPY_REPLACEONLY

Copy the file only if doing so would overwrite a file at the destination path. If the target doesn't exist, the function returns FALSE and GetLastError returns NO_ERROR.

SP_COPY_NEWER

Examine each file being copied to see if its version resources indicate that it is 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 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.

If the source file is not newer, and CopyMsgHandler is specified, the caller is notified and may cancel the copy. If CopyMsgHandler is not specified, the file is not copied.

SP_COPY_NOOVERWRITE

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.

SP_COPY_NODECOMP

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:\mips\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 filename part of DestinationName, if specified, is stripped and replaced with the filename of the source file. When SP_COPY_NODECOMP is specified, SP_COPY_LANGUAGEAWARE and SP_COPY_NEWER are ignored.

SP_COPY_LANGUAGEAWARE

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.

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 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

If the target exists, behave as if it is in use and queue the file for copying on the next system reboot.

SP_COPY_FORCE_NOOVERWRITE

Check whether the target file exists, and, if so, the file is not overwritten. The caller is not notified.

SP_COPY_FORCE_NEWER

Examine each file being copied to see if its version resources (or timestamps 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.

CopyMsgHandler

This optional parameter points to a callback function to be notified of various conditions that may arise during the file copy.

Context

This optional parameter points to a caller-defined value that is passed as the first parameter of the callback function.

Return Values

If the function succeeds, the return value is a non-zero 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 because the 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 and do not create UNC directories. If the target UNC directory does not exist, the file installation will fail.

QuickInfo

  Windows NT: Use version 4.0 and later.
  Windows: Use Windows 95 and later.
  Windows CE: Unsupported.
  Header: Declared in setupapi.h.
  Import Library: Link with setupapi.lib.

See Also

Overview, Functions, SetupCloseFileQueue, SetupCommitFileQueue, SetupOpenFileQueue, SetupQueueCopy