SHMessageBoxCheckA-Funktion (shlwapi.h)

[SHMessageBoxCheck steht für die Verwendung in den im Abschnitt "Anforderungen" angegebenen Betriebssystemen zur Verfügung. Sie kann in nachfolgenden Versionen geändert oder nicht verfügbar sein.]

Zeigt ein Meldungsfeld an, das dem Benutzer die Möglichkeit gibt, weitere Vorkommen zu unterdrücken. Wenn sich der Benutzer bereits für die Unterdrückung des Meldungsfelds entschieden hat, zeigt die Funktion kein Dialogfeld an und gibt stattdessen einfach den Standardwert zurück.

Syntax

int SHMessageBoxCheckA(
  [in, optional] HWND   hwnd,
  [in]           LPCSTR pszText,
  [in]           LPCSTR pszCaption,
                 UINT   uType,
                 int    iDefault,
  [in]           LPCSTR pszRegVal
);

Parameter

[in, optional] hwnd

Typ: HWND-

Das Fensterhandle für den Besitzer des Meldungsfelds. Dieser Wert kann NULL-sein.

[in] pszText

Typ: LPCTSTR-

Ein Zeiger auf eine mit Null beendete Zeichenfolge, die die anzuzeigende Nachricht enthält.

[in] pszCaption

Typ: LPCTSTR-

Ein Zeiger auf eine mit Null beendete Zeichenfolge, die den Titel des Meldungsfelds enthält. Wenn dieser Parameter auf NULL-festgelegt ist, wird der Titel auf Fehler festgelegt!.

uType

Typ: UINT-

Die Flags, die den Inhalt und das Verhalten des Meldungsfelds angeben. Diese Funktion unterstützt nur eine Teilmenge der Flags, die von MessageBox-unterstützt werden. Wenn Sie Flags verwenden, die unten nicht aufgeführt sind, ist das Verhalten der Funktion nicht definiert.

Sie müssen die Schaltflächen angeben, die angezeigt werden sollen, indem Sie eins und nur eines der folgenden Flags festlegen.

MB_OKCANCEL

Anzeigen eines Meldungsfelds mit den Schaltflächen OK und Abbrechen.

MB_YESNO

Anzeigen eines Meldungsfelds mit den Schaltflächen Ja und Nein.

MB_OK

Zeigt ein Meldungsfeld mit einer Schaltfläche OK an.

Sie können ein optionales Symbol anzeigen, indem Sie eins und nur eines der folgenden Flags festlegen.

MB_ICONHAND

Zeigt ein Stoppzeichensymbol an.

MB_ICONQUESTION

Zeigt ein Fragezeichensymbol an.

MB_ICONEXCLAMATION

Zeigt ein Ausrufezeichensymbol an.

MB_ICONINFORMATION

Zeigt ein Symbol mit einem Kleinbuchstaben "i" in einem Kreis an.

iDefault

Typ: int

Der Wert, den die Funktion zurückgibt, wenn der Benutzer sich entschieden hat, das Meldungsfeld nicht erneut angezeigt zu lassen. Wenn sich der Benutzer nicht für die Unterdrückung des Meldungsfelds entschieden hat, wird das Meldungsfeld angezeigt, und die Funktion ignoriert iDefault-.

[in] pszRegVal

Typ: LPCTSTR-

Ein Zeiger auf eine mit Null beendete Zeichenfolge, die einen eindeutigen Zeichenfolgenwert enthält, der dieser Nachricht zugeordnet werden soll. Um Konflikte mit von Microsoft verwendeten Werten zu vermeiden, sollte diese Zeichenfolge eine GUID enthalten. Diese Zeichenfolge darf REGSTR_MAX_VALUE_LENGTH Zeichen nicht überschreiten, einschließlich des endenden Nullzeichens.

Rückgabewert

Typ: int

Wenn der Benutzer bereits das Meldungsfeld unterdrückt hat, gibt die Funktion sofort den Wert zurück, der iDefaultzugewiesen ist.

Wenn der Benutzer auf die Schaltfläche OK, Abbrechen, Jaoder Schaltfläche "Nein" klickt, gibt die Funktion IDOK, IDCANCEL, IDYES oder IDNO zurück.

Wenn der Benutzer das Meldungsfeld schließt, indem er in der Beschriftung auf die Schaltfläche X klickt, gibt die Funktion IDCANCEL zurück. Dieser Wert wird in diesem Fall zurückgegeben, auch wenn das MB_OKCANCEL Flag nicht festgelegt wurde.

Wenn ein Fehler auftritt, ist der Rückgabewert normalerweise –1. Unter bestimmten Bedingungen mit geringem Arbeitsspeicher kann die Funktion jedoch iDefault-zurückgeben.

Bemerkungen

Sicherheitswarnung: Ergreifen Sie keine gefährlichen Aktionen, wenn die Funktion entweder –1 oder iDefault-zurückgibt. Wenn beim Versuch, das Meldungsfeld anzuzeigen, ein Fehler auftritt, gibt SHMessageBoxCheck- -1 zurück oder in einigen Fällen iDefault-zurück. Solche Fehler können durch unzureichenden Arbeitsspeicher oder Ressourcen verursacht werden. Wenn Sie einen dieser Rückgabewerte erhalten, sollten Sie sich bewusst sein, dass der Benutzer das Dialogfeld nicht unbedingt angezeigt hat und folglich keiner Aktion positiv zugestimmt hat.

Verwechseln Sie "Dieses Dialogfeld nicht anzeigen" mit "Diese Antwort speichern". SHMessageBoxCheck- stellt keine Funktionalität "Diese Antwort speichern" bereit. Wenn der Benutzer das Meldungsfeld erneut unterdrücken möchte, behält die Funktion nicht bei, auf welche Schaltfläche sie geklickt hat. Stattdessen geben nachfolgende Aufrufe von SHMessageBoxCheck einfach den durch iDefaultangegebenen Wert zurück. Betrachten Sie das folgende Beispiel.

int iResult = SHMessageBoxCheck(hwnd, 
                                TEXT("Do you want to exit without saving?"),
                                TEXT("Warning"), 
                                MB_YESNO, 
                                IDNO,
                                TEXT("{d9108ba3-9a61-4398-bfbc-b02102c77e8a}");

Wenn der Benutzer in Zukunft auswählt, zeigen Sie mir dieses Dialogfeld nicht an, und klicken Sie auf die Schaltfläche Ja, SHMessageBoxCheck- gibt IDYES zurück. Wenn dieser Code das nächste Mal ausgeführt wird, gibt SHMessageBoxCheck idYES nicht zurück, obwohl der Benutzer Ja ausgewählt hat. Stattdessen wird IDNO zurückgegeben, da dies der durch iDefaultangegebene Wert ist.

Die standardschaltfläche, die im Meldungsfeld angezeigt wird, sollte ihrem iDefault- Wert zustimmen. Die fehlende Unterstützung für das MB_DEFBUTTON2 Flag bedeutet, dass iDefault- auf IDOK festgelegt werden sollte, wenn Sie das MB_OK- oder MB_OKCANCEL-Flag angegeben haben. Der iDefault--Wert sollte auf IDYES festgelegt werden, wenn Sie das MB_YESNO Flag festgelegt haben.

SHMessageBoxCheck zeichnet die Meldungsfelder auf, die der Benutzer unter dem folgenden Registrierungsschlüssel unterdrückt hat:

HKEY_CURRENT_USER
   Software
      Microsoft
         Windows
            CurrentVersion
               Explorer
                  DontShowMeThisDialogAgain

Anmerkung

Der Header "shlwapi.h" definiert SHMessageBoxCheck 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 Code, der nicht codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Windows XP [nur Desktop-Apps]
mindestens unterstützte Server-	Windows Server 2003 [Nur Desktop-Apps]
Zielplattform-	Fenster
Header-	shlwapi.h
DLL-	Shlwapi.dll (Version 5.0 oder höher)