SetupPromptForDiskW 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 SetupPromptForDisk function displays a dialog box that prompts the user for a disk.
WINSETUPAPI UINT SetupPromptForDiskW( HWND hwndParent, PCWSTR DialogTitle, PCWSTR DiskName, PCWSTR PathToSource, PCWSTR FileSought, PCWSTR TagFile, DWORD DiskPromptStyle, PWSTR PathBuffer, DWORD PathBufferSize, PDWORD PathRequiredSize );
Handle to the parent window for this dialog box.
Optional pointer to a null-terminated string specifying the dialog title. If this parameter is NULL, the default of ""%s--Files Needed"" (localized) is used. The "%s" is replaced with the text retrieved from the parent window. If no text is retrieved from the parent window, the title is "Files Needed".
Optional pointer to a null-terminated string specifying the name of the disk to insert. If this parameter is NULL, the default "(Unknown)" (localized) is used.
Optional pointer to a null-terminated string specifying the path part of the expected location of the file, for example, F:\x86. If not specified, the path where SetupPromptForDisk most recently located a file is used. If that list is empty, a system default is used.
Pointer to a null-terminated string specifying the name of the file needed (filename part only). The filename is displayed if the user clicks on the Browse button. This routine 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.
Optional pointer to a null-terminated string specifying a tag file (filename part only) that identifies the presence of a particular removable media volume. If the currently selected path would place the file on removable media and a tag file is specified, SetupPromptForDisk looks for the tag file at the root of the drive to determine whether to continue.
For example, if PathToSource is A:\x86, the tagfile is disk1.tag, and the user types B:\x86 into the edit control of the prompt dialog box, the routine looks for B:\disk1.tag to determine whether to continue. If the tag file is not found, the function looks for the tagfile using PathToSource.
If a tag file is not specified, removable media works just like non-removable media and FileSought is looked for before continuing.
Specifies the behavior of the dialog box. This parameter can be a combination of the following flags.
Check for the file/disk before displaying the prompt dialog box, and, if present, return DPROMPT_SUCCESS immediately.
Prevent the dialog box from beeping to get the user's attention when it first appears.
Do not display the browse option.
Do not check for compressed versions of the source file.
Do not display detail information.
Prevent the dialog box from becoming the foreground window.
Do not display the skip option.
Prompt for a disk supplied by a hardware manufacturer.
Warn the user that skipping a file may affect the installation.
Optional pointer to a buffer that, upon return, receives the path (no filename) of the location specified by the user through the dialog box. You should use a null-terminated string. The null-terminated string should not exceed the size of the destination buffer. You can call the function once to get the required buffer size, allocate the necessary memory, and then call the function a second time to retrieve the data. Using this technique, you can avoid errors due to an insufficient buffer size. See the Remarks section.
Size of the buffer pointed to by PathBuffer, in characters. It should be at least MAX_PATH long. This includes the null terminator.
Optional pointer to a variable that receives the required size for PathBuffer, in characters. This includes the null terminator.
The function returns one of the following values.
To get extended error information, call GetLastError.
If this function is called with a PathBuffer of NULL and a PathBufferSize of zero, the function puts the buffer size needed to hold the specified data into the variable pointed to by PathRequiredSize. If the function succeeds in this, the return value is NO_ERROR. Otherwise, the return value is one of the values described in the Return Values section.
The setupapi.h header defines SetupPromptForDisk as an alias which 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 not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.
|Minimum supported client||Windows XP [desktop apps only]|
|Minimum supported server||Windows Server 2003 [desktop apps only]|