SetupInstallFileEx
[New
- Windows NT]
The SetupInstallFileEx
function installs a file as specified either by an INFCONTEXT
returned by SetupFindXXXLine or explicitly by the filename and path
information. This function is the same as SetupInstallFile, except that a BOOL
is returned indicating whether or not the file was in use.
BOOL SetupInstallFileEx(
|
HINF InfHandle, |
// optional,
handle to the INF file |
|
PINFCONTEXT InfContext, |
// optional,
context of an INF file |
|
PCTSTR SourceFile, |
// optional,
filename of the source |
|
PCTSTR SourcePathRoot, |
// optional,
root path to the 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 |
|
PBOOL FileWasInUse |
// receives the
file in use information |
|
); |
|
Parameters
InfHandle
This optional
parameter points to the handle of an INF file that contains the 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 not
specified and CopySyle includes SP_COPY_SOURCE_ABSOLUTE or SP_COPY_SOURCEPATH_ABSOLUTE,
InfHandle is ignored.
InfContext
This optional
parameter supplies context for 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. However, SourceFile
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 can be used to specify a new name for the copied file. If InfContext
is specified, DestinationName 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.
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_IN_USE_NEEDS_REBOOT
If the file
was in use during the copy operation, alert the user that the system needs to
be rebooted.
SP_COPY_NO_SKIP
Do not give
the user the option to skip a file.
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.
SP_COPY_WARNIFSKIP
If the user
tries to skip a file, warn them that skipping a file may affect the
installation. (Used for system-critical files.)
CopyMsgHandler
This optional
parameter points to a callback function to be notified of various conditions that
may arise during the file copy.
Context
Pointer to a
caller-defined value that is passed as the first parameter of the callback
function.
FileWasInUse
This optional
parameter points to a caller-supplied variable in which this function returns a
flag indicating whether the file was in use.
Return Values
If the
function succeeds, the return value is TRUE.
If the
function fails, the return value is FALSE. 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
This API is
typically used when installing new versions of system files that are likely to
be in use. It updates a BOOL value that indicates whether the file was in use.
If the file was in use, then the file copy operation is post-poned until the
system is rebooted.
If a UNC
directory is specified as the target directory of a file installation, you must
ensure it exists before you call SetupInstallFileEx. 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.
See Also