C# Signature:

/* The SHMessageBoxCheck() function is a Windows Shell API function that displays a custom messagebox with a "never ask me again" check box.  When the user checks the checkbox, the dialog never shows up again.  The shell API .dll exports this function by ordinal only.  The entrypoint  is ordinal 185 for ASCII and 191 for unicode. */

[DllImport("shlwapi.dll", EntryPoint="#185", ExactSpelling=true, PreserveSig=false)]
public static extern int SHMessageBoxCheck(
    [In] IntPtr hwnd,
    [In] String pszText,
    [In] String pszTitle,
    [In] MessageBoxCheckFlags uType,
    [In] int iDefault,
    [In] string pszRegVal
    );

VB Signature:

Declare Function SHMessageBoxCheck Lib "shlwapi.dll" (TODO) As TODO

User-Defined Types:

None.

Alternative Managed API:

I had to set PreserveSig=true in order to get this to work. Without it, I would receive a PInvokeStackImbalance exception from MDA.

Notes:

/* We use the Windows Shell function SHMessageBoxCheck, so we have to define this parallel enum of the definitions in winuser.h. */

public enum MessageBoxCheckFlags : uint
{
    MB_OK             = 0x00000000,
    MB_OKCANCEL           = 0x00000001,
    MB_YESNO          = 0x00000004,
    MB_ICONHAND           = 0x00000010,
    MB_ICONQUESTION       = 0x00000020,
    MB_ICONEXCLAMATION    = 0x00000030,
    MB_ICONINFORMATION    = 0x00000040
}

The Windows Shell (Explorer) stores your preference in the following registry key:

HKEY_CURRENT_USER
        Software
            Microsoft
                Windows
                    CurrentVersion
                        Explorer
                            DontShowMeThisDialogAgain

The problem of leaving behind the registry keys: Since the registry key gets stored in HKEY_CURRENT_USER, every different user on a system will have their own preference saved. If you uninstall the program for one user, you'll leave behind the registry keys for the other users. For example, suppose users X and Y have checked the "Do not show me this dialog again" checkbox, and therefore each have the registry key in their HKEY_CURRENT_USER area. Now user X uninstalls the program. The uninstaller must leave behind the registry key for user Y because that user is not logged in.

One problem: If you have an application that you must uninstall, how do you remove this key for all users? For example, suppose users X and Y have checked the "Do not show me this dialog again" checkbox. Now user X uninstalls the program. The installer would need to be able to go into user Y's registry settings to remove the registry key, which may not be possible depending on system permissions. I don't know how to solve this problem.

Raymond Chen, a popular Microsoft blogger, recommends that you not worry about leaving keys because it's per-user data anyway and in many environments it's preferable to leave it behind. Definitely do not try to enumerate all user profiles to remove the keys for the other users because in the case of roaming profiles you'll likely corrupt a lot of stuff. If you want to remove all traces of your program, one alternative is to write your own SHMessageBoxCheck dialog and store the preference wherever you want. Source: http://blogs.msdn.com/oldnewthing/archive/2007/09/17/4948130.aspx

Tips & Tricks:

Note the discussion on what to do when you have multiple dialog options, like YES/NO and OK/CANCEL.

Sample Code:

/* This code displays a dialog box with a "Don't show me this dialog again" checkbox and an OK button.  In normal circumstances, result will always be 0 on return. */

int result;

try
{
    result = SHMessageBoxCheck(
        this.Handle,
        "This text fills the dialog",
        "This text is in the title bar",
        MessageBoxCheckFlags.MB_OK | MessageBoxCheckFlags.MB_ICONINFORMATION,
        0,
        "MyApplicationName.exe" // This last argument is the value of the registry key
        );
}
catch( Exception e )
{
// Note that the only exceptions we can get here are inter-op exceptions, I think.
    result = -1;
}

if( result == -1 )
{
// The dialog didn't show up, so do some alternate action here.
}

Please edit this page!

Do you have...

• helpful tips or sample code to share for using this API in managed code?
• corrections to the existing content?
• variations of the signature you want to share?
• additional languages you want to include?

Select "Edit This Page" on the right hand toolbar and edit it! Or add new pages containing supporting types needed for this API (structures, delegates, and more).