SetupCopyErrorA 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 SetupCopyError function generates a dialog box to notify a user of a copy file error.
Syntax
WINSETUPAPI UINT SetupCopyErrorA(
[in] HWND hwndParent,
[in] PCSTR DialogTitle,
[in] PCSTR DiskName,
[in] PCSTR PathToSource,
[in] PCSTR SourceFile,
[in] PCSTR TargetPathFile,
[out] UINT Win32ErrorCode,
[in] DWORD Style,
[in, out] PSTR PathBuffer,
[in] DWORD PathBufferSize,
[in, out] PDWORD PathRequiredSize
);
Parameters
[in] hwndParent
The handle to the parent window for this dialog box.
[in] DialogTitle
An optional pointer to a null-terminated string that specifies the dialog box title.
This parameter can be NULL. If this parameter is NULL, the default title of "Copy Error" (localized to the system language) is used.
[in] DiskName
An optional pointer to a null-terminated string that specifies the name of the disk to insert.
This parameter can be NULL. If this parameter is NULL, the default name "(Unknown)" (localized to the system language) is used.
[in] PathToSource
A pointer to the path component of the source file where an operation fails, for example, F:\x86.
Use a null-terminated string.
[in] SourceFile
A pointer to a null-terminated string that specifies the filename part of the file where an operation fails.
Use a null-terminated string. This filename is displayed if the user clicks on the Details or Browse buttons. The SetupCopyError function looks for the file that uses its compressed form names. Therefore, you can pass cmd.exe and not worry that the file actually exists as cmd.ex_ on the source media.
[in] TargetPathFile
An optional pointer to a null-terminated string that specifies the full path of the target file for rename and copy operations.
Use a null-terminated string. This parameter can be NULL. If TargetPathFile is not specified, "(Unknown)" (localized to the system language) is used.
[out] Win32ErrorCode
If an error occurs, this member is the System Error Code.
If an error does not occur, it is NO_ERROR.
[in] Style
The flags that control display formatting and behavior of a dialog box.
This parameter can be one of the following flags.
IDF_NOBROWSE
Do not display the browse option.
IDF_NOSKIP
Do not display the skip file option.
IDF_NODETAILS
Do not display the details option.
If this flag is set, the TargetPathFile and Win32ErrorCode parameters can be omitted.
IDF_NOCOMPRESSED
Do not check for compressed versions of the source file.
IDF_OEMDISK
The operation source is a disk that a hardware manufacturer provides.
IDF_NOBEEP
Prevents the dialog box from beeping to get the user's attention when it first appears.
IDF_NOFOREGROUND
Prevents the dialog box from becoming the foreground window.
IDF_WARNIFSKIP
Warns the user that skipping a file can affect the installation.
[in, out] PathBuffer
An optional pointer to a variable in which this function returns the path (not including the filename) of the location that a user specifies in the dialog box. You should use a null-terminated string.
The null-terminated string should not exceed the size of the destination buffer. To avoid insufficient buffer errors, PathBuffer should be at least MAX_PATH. For more information, see the Remarks section of this topic.
[in] PathBufferSize
The size of the buffer that PathBuffer points to, in characters.
The buffer size should be at least MAX_PATH characters, including the null terminator.
[in, out] PathRequiredSize
An optional pointer to a variable in which this function returns the required buffer size, in characters, including the null terminator.
Return value
The function returns one of the following values.
To get extended error information, call GetLastError.
Remarks
If this function is called with a PathBuffer of NULL and a PathBufferSize of 0 (zero), the function puts the buffer size that is needed to hold the specified data into the variable pointed to by PathRequiredSize.
If the function succeeds, the return value is NO_ERROR. Otherwise, the return value is one of the specified values.
To avoid insufficient buffer errors, ReturnBuffer should be at least MAX_PATH.
Note
The setupapi.h header defines SetupCopyError as an alias that 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 is 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 |