This topic has not yet been rated - Rate this topic

SetupCopyError Function

[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

UINT SetupCopyError(
  __in     HWND hwndParent,
  __in     PCTSTR DialogTitle,
  __in     PCTSTR DiskName,
  __in     PCTSTR PathToSource,
  __in     PCTSTR SourceFile,
  __in     PCTSTR TargetPathFile,
  __out    UINT Win32ErrorCode,
  __in     DWORD Style,
  __inout  PTSTR PathBuffer,
  __in     DWORD PathBufferSize,
  __inout  PDWORD PathRequiredSize
);

Parameters

hwndParent [in]

The handle to the parent window for this dialog box.

DialogTitle [in]

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.

DiskName [in]

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.

PathToSource [in]

A pointer to the path component of the source file where an operation fails, for example, F:\x86.

Use a null-terminated string.

SourceFile [in]

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.

TargetPathFile [in]

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.

Win32ErrorCode [out]

If an error occurs, this member is the System Error Code.

If an error does not occur, it is NO_ERROR.

Style [in]

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.

PathBuffer [in, out]

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.

PathBufferSize [in]

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.

PathRequiredSize [in, out]

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.

DPROMPT_SUCCESS

The requested disk/file is present and accessible.

If PathBuffer is specified, it contains the path to the file, not including the filename.

DPROMPT_CANCEL

The user clicks on the Cancel button or an invalid parameter is passed to the function.

DPROMPT_SKIPFILE

The user clicks on the Skip File button.

DPROMPT_BUFFERTOOSMALL

The provided PathBuffer is too small.

Check PathRequiredSize for the actual size needed.

DPROMPT_OUTOFMEMORY

There is not enough memory to process a request.

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.

Requirements

Minimum supported client	Windows 2000 Professional
Minimum supported server	Windows 2000 Server
Header	Setupapi.h
Library	Setupapi.lib
DLL	Setupapi.dll
Unicode and ANSI names	SetupCopyErrorW (Unicode) and SetupCopyErrorA (ANSI)

Community Additions

ADD