SetupCopyError

The SetupCopyError function generates a dialog box to notify the user of a copy file error.

UINT SetupCopyError(
  HWND hwndParent,       // parent window for this dialog box
  PCTSTR DialogTitle,    // optional, title for this dialog box
  PCTSTR DiskName,       // optional, name of disk to insert
  PCTSTR PathToSource,   // failed source path
  PCTSTR SourceFile,     // source file of copy error
  PCTSTR TargetPathFile, // optional, target file of copy error
  UINT Win32ErrorCode,   // error information
  DWORD Style,           // dialog box formatting and display
  PTSTR PathBuffer,      // optional, receives new path info
  DWORD PathBufferSize,  // size of supplied buffer
  PDWORD PathRequiredSize  // optional, buffer size needed
);
 

Parameters

hwndParent

Handle to the parent window for this dialog box.

DialogTitle

This optional parameter points to a null-terminated string specifying the dialog box title. If this parameter is NULL, the default title of "Copy Error" (localized to the system language) is used.

DiskName

This optional parameter points to a null-terminated string specifying the name of the disk to insert. If this parameter is NULL, the default name "(Unknown)" (localized to the system language) is used.

PathToSource

Pointer to the path component of the source file on which the operation failed; for example, F:\mips.

SourceFile

Pointer to a null-terminated string specifying the filename part of the file on which the operation failed. This filename is displayed if the user clicks on the Details or Browse buttons. The SetupCopyError function looks for the file using 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.

TargetPathFile

This optional parameter points to a null-terminated string that specifies the full path of the target file for rename and copy operations. If TargetPathFile is not specified, "(Unknown)" (localized to the system language) is used.

Win32ErrorCode

The Win32 error code encountered during the file operation. For information about Win32 error codes, see the WINERROR.H file included with the Platform SDK.

Style

Specifies flags that control display formatting and behavior of the 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 provided by a hardware manufacturer.

IDF_NOBEEP

Prevent the dialog box from beeping to get the user's attention when it first appears.

IDF_NOFOREGROUND

Prevent the dialog box from becoming the foreground window.

IDF_WARNIFSKIP

Warn the user that skipping a file can affect the installation.

PathBuffer

This optional parameter points to a caller-supplied variable in which this function returns the path (not including the filename) of the location specified by the user through the dialog box.

PathBufferSize

Specifies the size of the buffer pointed to by PathBuffer. It should be at least MAX_PATH in length.

PathRequiredSize

This optional parameter points to a caller-supplied variable in which this function returns the required buffer size.

Return Values

The function returns one of the following values:

DPROMPT_SUCCESS

The requested disk/file is present and accessible. If PathBuffer was specified, it contains the path to the file (not including the filename).

DPROMPT_CANCEL

The user clicked on the Cancel button.

DPROMPT_SKIPFILE

The user clicked on the Skip File button.

DPROMPT_BUFFERTOOSMALL

The provided PathBuffer is too small. Check PathRequiredSize for the actual size needed.

DPROMPT_OUTOFMEMORY

There is insufficient memory to process the request.

To get extended error information, call GetLastError.

Remarks

For the Unicode version of this function, the buffer sizes ReturnBufferSize and RequiredSize are specified in number of characters. This number includes the null terminator. For the ANSI version of this function, the sizes are specified in number of bytes.

If this function is called with a ReturnBuffer of NULL and a ReturnBufferSize of zero, the function puts the buffer size needed to hold the specified data into the variable pointed to by RequiredSize. If the function succeeds in this, the return value is NO_ERROR. Otherwise, the return value is one of the values specified preceding.

To avoid insufficient buffer errors, ReturnBuffer should be at least MAX_PATH.

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, SetupDeleteError, SetupPromptForDisk, SetupRenameError