Función SHMessageBoxCheckA (shlwapi.h)

[ SHMessageBoxCheck está disponible para su uso en los sistemas operativos especificados en la sección Requisitos. Puede modificarse o no estar disponible en versiones posteriores.]

Muestra un cuadro de mensaje que proporciona al usuario la opción de suprimir más repeticiones. Si el usuario ya ha optado por suprimir el cuadro de mensaje, la función no muestra un cuadro de diálogo y, en su lugar, simplemente devuelve el valor predeterminado.

Sintaxis

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

Parámetros

[in, optional] hwnd

Tipo: HWND

Identificador de ventana para el propietario del cuadro de mensaje. Este valor puede ser null.

[in] pszText

Tipo: LPCTSTR de

Puntero a una cadena terminada en NULL que contiene el mensaje que se va a mostrar.

[in] pszCaption

Tipo: LPCTSTR de

Puntero a una cadena terminada en null que contiene el título del cuadro de mensaje. Si este parámetro se establece en NULL, el título se establece en Error!.

uType

Tipo: UINT

Marcas que especifican el contenido y el comportamiento del cuadro de mensaje. Esta función solo admite un subconjunto de las marcas admitidas por Cuadro de mensajes. Si usa marcas que no se enumeran a continuación, el comportamiento de la función no está definido.

Debe especificar los botones que se van a mostrar estableciendo una y solo una de las marcas siguientes.

MB_OKCANCEL

Muestra un cuadro de mensaje con Aceptar y botones Cancelar.

MB_YESNO

Muestra un cuadro de mensaje con botones Sí y No.

MB_OK

Muestra un cuadro de mensaje con un botón Aceptar.

Puede mostrar un icono opcional estableciendo una y solo una de las marcas siguientes.

MB_ICONHAND

Muestra un icono de inicio de sesión.

MB_ICONQUESTION

Muestra un icono de signo de interrogación.

MB_ICONEXCLAMATION

Muestra un icono de signo de exclamación.

MB_ICONINFORMATION

Muestra un icono con una "i" minúscula en un círculo.

iDefault

Tipo: int

Valor que devuelve la función cuando el usuario ha optado por no volver a mostrar el cuadro de mensaje. Si el usuario no ha optado por suprimir el cuadro de mensaje, se muestra el cuadro de mensaje y la función omite iDefault.

[in] pszRegVal

Tipo: LPCTSTR de

Puntero a una cadena terminada en null que contiene un valor de cadena único que se va a asociar a este mensaje. Para evitar colisiones con valores usados por Microsoft, esta cadena debe incluir un GUID. Esta cadena no debe superar REGSTR_MAX_VALUE_LENGTH caracteres de longitud, incluido el carácter nulo de terminación.

Valor devuelto

Tipo: int

Si el usuario ya ha elegido suprimir el cuadro de mensaje, la función devuelve inmediatamente el valor asignado a iDefault.

Si el usuario hace clic en el botón Aceptar, Cancelar, Sío No, la función devuelve IDOK, IDCANCEL, IDYES o IDNO, respectivamente.

Si el usuario cierra el cuadro de mensaje haciendo clic en el botón X del título, la función devuelve IDCANCEL. Este valor se devuelve en este caso incluso si no se ha establecido la marca MB_OKCANCEL.

Si se produce un error, el valor devuelto suele ser –1. Sin embargo, en determinadas condiciones de memoria baja, la función podría devolver iDefault.

Observaciones

advertencia de seguridad: No realizar acciones peligrosas si la función devuelve –1 o iDefault. Si se produce un error al intentar mostrar el cuadro de mensaje, SHMessageBoxCheck devuelve –1 o, en algunos casos, iDefault. Estos errores pueden deberse a una memoria o recursos insuficientes. Si obtiene uno de estos valores devueltos, debe tener en cuenta que el usuario no vio necesariamente el cuadro de diálogo y, por lo tanto, no aceptó positivamente ninguna acción.

No confunda "No mostrar este cuadro de diálogo" con "Recordar esta respuesta". SHMessageBoxCheck no proporciona la funcionalidad "Recordar esta respuesta". Si el usuario decide suprimir de nuevo el cuadro de mensaje, la función no conserva el botón en el que ha clic. En su lugar, las invocaciones posteriores de SHMessageBoxCheck simplemente devuelven el valor especificado por iDefault. Considere el ejemplo siguiente.

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

Si el usuario selecciona En el futuro, no me muestre este cuadro de diálogo de y haga clic en el botón Sí , SHMessageBoxCheck devuelve IDYES. Sin embargo, la próxima vez que se ejecute este código, SHMessageBoxCheck no devuelve IDYES, aunque el usuario seleccionado Sí originalmente. En su lugar, devuelve IDNO, porque es el valor especificado por iDefault.

El botón predeterminado que muestra el cuadro de mensaje debe estar de acuerdo con el valor de iDefault. La falta de compatibilidad con la marca MB_DEFBUTTON2 significa que iDefault debe establecerse en IDOK si ha especificado la marca MB_OK o MB_OKCANCEL. El valor de iDefault debe establecerse en IDYES si ha establecido la marca MB_YESNO.

SHMessageBoxCheck registra los cuadros de mensaje que el usuario ha elegido suprimir en la siguiente clave del Registro:

HKEY_CURRENT_USER
   Software
      Microsoft
         Windows
            CurrentVersion
               Explorer
                  DontShowMeThisDialogAgain

Nota

El encabezado shlwapi.h define SHMessageBoxCheck como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Conventions for Function Prototypes.

Requisitos

Requisito	Valor
cliente mínimo admitido	Windows XP [solo aplicaciones de escritorio]
servidor mínimo admitido	Windows Server 2003 [solo aplicaciones de escritorio]
de la plataforma de destino de	Windows
encabezado de	shlwapi.h
DLL de	Shlwapi.dll (versión 5.0 o posterior)