pinvoke.net: Edit: shlwapi.SHMessageBoxCheck

@msdn=http://search.microsoft.com/search/results.aspx?qu=$$$
@pinvoke=http://pinvoke.net/$$$.htm

Summary: Displays a message box with a "Never show this dialog again" check box.  This dialog is useful for displaying a one-time message to the user where they are likely never to want to see the dialog again.

MSDN: http://msdn.microsoft.com/library/default.asp?url=/library/en-us/shellcc/platform/shell/reference/shlwapi/others/SHMessageBoxCheck.asp

!!!!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.

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:

Blog: This blog (Raymond Chen, Microsoft) contains discussion about SHMessageBoxCheck in the user-added comments.  http://blogs.msdn.com/oldnewthing/archive/2005/04/29/412577.aspx

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.
 }

Documentation: SHMessageBoxCheck@msdn on MSDN