SetupPromptForDiskW-Funktion (setupapi.h)

Artikel
08/26/2023

[Diese Funktion ist für die Verwendung in den Betriebssystemen verfügbar, die im Abschnitt "Anforderungen" angegeben sind. Es kann in nachfolgenden Versionen geändert oder entfernt werden. SetupAPI sollte nicht mehr für die Installation von Anwendungen verwendet werden. Verwenden Sie stattdessen den Windows Installer zum Entwickeln von Anwendungsinstallationsprogrammen. SetupAPI wird weiterhin zum Installieren von Gerätetreibern verwendet.]

Die SetupPromptForDisk-Funktion zeigt ein Dialogfeld an, das den Benutzer zur Eingabe eines Datenträgers auffordert.

Syntax

WINSETUPAPI UINT SetupPromptForDiskW(
  [in]      HWND   hwndParent,
  [in]      PCWSTR DialogTitle,
  [in]      PCWSTR DiskName,
  [in]      PCWSTR PathToSource,
  [in]      PCWSTR FileSought,
  [in]      PCWSTR TagFile,
  [in]      DWORD  DiskPromptStyle,
  [in, out] PWSTR  PathBuffer,
  [in]      DWORD  PathBufferSize,
  [in, out] PDWORD PathRequiredSize
);

Parameter

[in] hwndParent

Handle mit dem übergeordneten Fenster für dieses Dialogfeld.

[in] DialogTitle

Optionaler Zeiger auf eine NULL-Zeichenfolge, die den Dialogtitel angibt. Wenn dieser Parameter NULL ist, wird der Standardwert von ""%s--Files Needed"" (lokalisiert) verwendet. "%s" wird durch den Text ersetzt, der aus dem übergeordneten Fenster abgerufen wird. Wenn kein Text aus dem übergeordneten Fenster abgerufen wird, lautet der Titel "Dateien erforderlich".

[in] DiskName

Optionaler Zeiger auf eine NULL-Zeichenfolge, die den Namen des einzufügenden Datenträgers angibt. Wenn dieser Parameter NULL ist, wird die Standardeinstellung "(Unbekannt)" (lokalisiert) verwendet.

[in] PathToSource

Optionaler Zeiger auf eine NULL-Zeichenfolge, die den Pfadteil des erwarteten Speicherorts der Datei angibt, z. B. F:\x86. Falls nicht angegeben, wird der Pfad verwendet, in dem SetupPromptForDisk zuletzt eine Datei gefunden hat. Wenn diese Liste leer ist, wird ein Systemstandard verwendet.

[in] FileSought

Zeiger auf eine NULL-beendete Zeichenfolge, die den Namen der benötigten Datei angibt (nur Dateinameteil). Der Dateiname wird angezeigt, wenn der Benutzer auf die Schaltfläche Durchsuchen klickt. Diese Routine sucht nach der Datei mit ihren komprimierten Formularnamen. Daher können Sie cmd.exe übergeben und sich keine Sorgen machen, dass die Datei tatsächlich als cmd.ex_ auf den Quellmedien vorhanden ist.

[in] TagFile

Optionaler Zeiger auf eine null-beendete Zeichenfolge, die eine Tagdatei (nur Dateiname-Teil) angibt, die das Vorhandensein eines bestimmten Wechselmedienvolumes identifiziert. Wenn der aktuell ausgewählte Pfad die Datei auf Wechselmedien platzieren würde und eine Tagdatei angegeben wird, sucht SetupPromptForDisk nach der Tagdatei im Stammverzeichnis des Laufwerks, um zu bestimmen, ob die Fortsetzung erfolgen soll.

Wenn PathToSource beispielsweise A:\x86 ist, die Tagdatei disk1.tag ist und der Benutzer B:\x86 in das Bearbeitungssteuerelement des Eingabeaufforderungsdialogfelds eingibt, sucht die Routine nach B:\disk1.tag, um zu bestimmen, ob die Fortsetzung ausgeführt werden soll. Wenn die Tagdatei nicht gefunden wird, sucht die Funktion mithilfe von PathToSource nach der Tagdatei.

Wenn keine Tagdatei angegeben ist, funktionieren Wechselmedien genauso wie Nicht-Wechselmedien, und FileSought wird vor dem Fortfahren gesucht.

[in] DiskPromptStyle

Gibt das Verhalten des Dialogfelds an. Dieser Parameter kann eine Kombination der folgenden Flags sein.

IDF_CHECKFIRST

Überprüfen Sie die Datei/den Datenträger, bevor Sie das Eingabeaufforderungsdialogfeld anzeigen, und geben Sie, falls vorhanden, sofort DPROMPT_SUCCESS zurück.

IDF_NOBEEP

Verhindern Sie, dass das Dialogfeld anregt, um die Aufmerksamkeit des Benutzers zu erhalten, wenn es zum ersten Mal angezeigt wird.

IDF_NOBROWSE

Zeigen Sie die Option durchsuchen nicht an.

IDF_NOCOMPRESSED

Suchen Sie nicht nach komprimierten Versionen der Quelldatei.

IDF_NODETAILS

Zeigen Sie keine Detailinformationen an.

IDF_NOFOREGROUND

Verhindern, dass das Dialogfeld zum Vordergrundfenster wird.

IDF_NOSKIP

Zeigen Sie die Option "Überspringen" nicht an.

IDF_OEMDISK

Fordern Sie nach einem Datenträger auf, der von einem Hardwarehersteller bereitgestellt wird.

IDF_WARNIFSKIP

Warnen Sie den Benutzer, dass sich das Überspringen einer Datei auf die Installation auswirken kann.

[in, out] PathBuffer

Optionaler Zeiger auf einen Puffer, der bei der Rückgabe den Pfad (kein Dateiname) des vom Benutzer angegebenen Speicherorts über das Dialogfeld empfängt. Sie sollten eine NULL-Zeichenfolge verwenden. Die NULL-Zeichenfolge sollte die Größe des Zielpuffers nicht überschreiten. Sie können die Funktion einmal aufrufen, um die erforderliche Puffergröße abzurufen, den erforderlichen Arbeitsspeicher zuzuweisen und die Funktion dann ein zweites Mal aufzurufen, um die Daten abzurufen. Mit diesem Verfahren können Sie Fehler aufgrund einer unzureichenden Puffergröße vermeiden. Weitere Informationen finden Sie im Abschnitt mit den Hinweisen.

[in] PathBufferSize

Größe des Puffers, auf den PathBuffer in Zeichen verweist. Es sollte mindestens MAX_PATH lang sein. Dies schließt den NULL-Abschlussator ein.

[in, out] PathRequiredSize

Optionaler Zeiger auf eine Variable, die die erforderliche Größe für PathBuffer in Zeichen empfängt. Dies schließt den NULL-Abschlussator ein.

Rückgabewert

Die Funktion gibt einen der folgenden Werte zurück.

Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

Wenn diese Funktion mit einem PathBuffer von NULL und einer PathBufferSize von null aufgerufen wird, legt die Funktion die Puffergröße, die zum Speichern der angegebenen Daten erforderlich ist, in die Variable ein, auf die pathRequiredSize verweist. Wenn die Funktion dabei erfolgreich ist, wird der Rückgabewert NO_ERROR. Andernfalls ist der Rückgabewert einer der im Abschnitt Rückgabewerte beschriebenen Werte.

Hinweis

Der setupapi.h-Header definiert SetupPromptForDisk als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit nicht codierungsneutralem Code kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen


Unterstützte Mindestversion (Client)	Windows XP [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	setupapi.h
Bibliothek	Setupapi.lib
DLL	Setupapi.dll