pinvoke.net: Edit: kernel32.FormatMessage

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

Summary: The FormatMessage API

!!!!C# Signature:
 [DllImport("kernel32.dll")]
 static extern uint FormatMessage(uint dwFlags, IntPtr lpSource,
   uint dwMessageId, uint dwLanguageId, [Out] StringBuilder lpBuffer,
   uint nSize, IntPtr Arguments);

// the version, the sample is built upon:
 [DllImport("Kernel32.dll", SetLastError=true)]
 static extern uint FormatMessage( uint dwFlags, IntPtr lpSource, 
   uint dwMessageId, uint dwLanguageId, ref IntPtr lpBuffer, 
   uint nSize, IntPtr pArguments);

// the parameters can also be passed as a string array:
 [DllImport("Kernel32.dll", SetLastError=true)]
 static extern uint FormatMessage( uint dwFlags, IntPtr lpSource, 
   uint dwMessageId, uint dwLanguageId, ref IntPtr lpBuffer, 
   uint nSize, string[] Arguments);

// see the sample code
 [DllImport("kernel32.dll", SetLastError = true)]
 static extern uint FormatMessage(uint dwFlags, IntPtr lpSource, uint dwMessageId, uint dwLanguageId, [Out] StringBuilder lpBuffer, uint nSize, string[] Arguments);

!!!!VB.NET Signature:
 <DllImport("Kernel32.dll", EntryPoint:="FormatMessageW", SetLastError:=True, CharSet:=CharSet.Unicode, CallingConvention:=CallingConvention.StdCall)> _
 Public Shared Function FormatMessage(ByVal dwFlags As Integer, ByRef lpSource As IntPtr, ByVal dwMessageId As Integer, ByVal dwLanguageId As Integer, ByRef lpBuffer As [String], ByVal nSize As Integer, ByRef Arguments As IntPtr) As Integer
 End Function

!!!!VB.NET Signature:
 <DllImport("Kernel32.dll", EntryPoint:="FormatMessageW", SetLastError:=True, CharSet:=CharSet.Unicode, CallingConvention:=CallingConvention.StdCall)> _
 Public Shared Function FormatMessage(ByVal dwFlags As Integer, ByVal lpSource As IntPtr, ByVal dwMessageId As Integer, ByVal dwLanguageId As Integer, <MarshalAs(UnmanageType.LPWStr)> ByRef lpBuffer As String, ByVal nSize As Integer, ByVal Arguments As IntPtr) As Integer
 End Function

!!!!VB.NET Signature:
 <DllImport("Kernel32.dll", EntryPoint:="FormatMessageW", SetLastError:=True, CharSet:=CharSet.Unicode, CallingConvention:=CallingConvention.StdCall)> _
 Public Shared Function FormatMessage(ByVal dwFlags As Integer, ByVal lpSource As IntPtr, ByVal dwMessageId As Integer, ByVal dwLanguageId As Integer, ByRef lpBuffer As StringBuilder, ByVal nSize As Integer, ByVal Arguments As IntPtr) As Integer
 End Function

!!!!User-Defined Types:
None.

!!!!Notes:
To have FormatMessage substitute %1, %2, etc. with arguments you pass it, declare FormatMessage with a string[] for the last parameter and just pass a normal C# string array. You need to include FORMAT_MESSAGE_ARGUMENT_ARRAY in the dwFlags parameter for this to work.

!!!!Tips & Tricks:
If you are trying use FormatMessage to "decode" an error from Marshal.GetLastWin32Error, go take a look at Marshal.ThrowExceptionForHR (http://msdn.microsoft.com/en-us/library/ckxcyk36(v=VS.80).aspx).
ThrowExceptionForHR is for HRESULT values returned directly from NT functions, is it not?
For Win32Errors you most likely want new Win32Exception() (http://msdn.microsoft.com/en-us/library/asy2azk0.aspx) which gives you a ready made message for the error code returned by Marshal.GetLastWin32Error().

!!!!Sample Code:
	// from header files
	const uint FORMAT_MESSAGE_ALLOCATE_BUFFER = 0x00000100;
	const uint FORMAT_MESSAGE_IGNORE_INSERTS  = 0x00000200;
	const uint FORMAT_MESSAGE_FROM_SYSTEM    = 0x00001000;
	const uint FORMAT_MESSAGE_ARGUMENT_ARRAY = 0x00002000;
	const uint FORMAT_MESSAGE_FROM_HMODULE = 0x00000800;
	const uint FORMAT_MESSAGE_FROM_STRING = 0x00000400;

int nLastError= Marshal.GetLastWin32Error();
	
	IntPtr lpMsgBuf= IntPtr.Zero;

uint dwChars= FormatMessage( 
		FORMAT_MESSAGE_ALLOCATE_BUFFER | FORMAT_MESSAGE_FROM_SYSTEM | FORMAT_MESSAGE_IGNORE_INSERTS,
		IntPtr.Zero,
		(uint)nLastError,
		0, // Default language
		ref lpMsgBuf,
		0,
		IntPtr.Zero);
	if (dwChars==0)
	{
		// Handle the error.
		int le= Marshal.GetLastWin32Error();
		return null;
	}
			
	string sRet= Marshal.PtrToStringAnsi(lpMsgBuf);
			
	// Free the buffer.
	lpMsgBuf= LocalFree( lpMsgBuf );
	return sRet;

// add for the forth signature
	try
	{
		StringBuilder msgBuilder = new StringBuilder(101);

string formatExpression = "%1,%2%!";
		string[] formatArgs = new string[] { "Hello", "world" };

IntPtr formatPtr = Marshal.StringToHGlobalAnsi(formatExpression);

//must specify the FORMAT_MESSAGE_ARGUMENT_ARRAY flag when pass an array
		uint length = FormatMessage(FORMAT_MESSAGE_FROM_STRING | FORMAT_MESSAGE_ARGUMENT_ARRAY, formatPtr, 0, 0, msgBuilder, 101, formatArgs);

if (length == 0)
		{
			FormatMessage(FORMAT_MESSAGE_FROM_SYSTEM, IntPtr.Zero, (uint)Marshal.GetLastWin32Error(), 0, msgBuilder, 101, null);

Console.WriteLine("Error:" + msgBuilder.ToString());
		}
		else
		{
			Console.WriteLine("Format result:" + msgBuilder.ToString() + ", length:" + length.ToString());
		}
	}
	catch (Exception ex)
	{
		Console.WriteLine(ex.Message);
	}

!!!!Sample Code:
	<System.Runtime.InteropServices.DllImport("Kernel32.dll", EntryPoint:="FormatMessageW", SetLastError:=True, CharSet:=System.Runtime.InteropServices.CharSet.Unicode)>
	Public Shared Function FormatMessage(ByVal dwFlags As Integer, ByRef lpSource As IntPtr, ByVal dwMessageId As Integer, ByVal dwLanguageId As Integer, ByRef lpBuffer As IntPtr, ByVal nSize As Integer, ByRef Arguments As IntPtr) As Integer
	End Function

<System.Runtime.InteropServices.DllImport("Kernel32.dll", SetLastError:=True)>
	Public Shared Function LocalFree(ByVal hMem As IntPtr) As IntPtr
	End Function

Enum Format_Message
	FORMAT_MESSAGE_ALLOCATE_BUFFER = &H100 'The caller should use the LocalFree function to free the buffer when it is no longer needed
	FORMAT_MESSAGE_IGNORE_INSERTS = &H200
	FORMAT_MESSAGE_FROM_SYSTEM = &H1000
	'FORMAT_MESSAGE_ARGUMENT_ARRAY = &H2000
	'FORMAT_MESSAGE_FROM_HMODULE = &H800
	''FORMAT_MESSAGE_FROM_STRING = &H400
	End Enum

Private Sub Error_Message()
	'DllImport filed SetLastError must be set True
	'so Runtime.InteropServices.Marshal.GetLastWin32Error() returns a valid error
	Dim nLastError As Integer = Runtime.InteropServices.Marshal.GetLastWin32Error

Dim lpMsgBuf As IntPtr = IntPtr.Zero
	
	Dim dwChars As Integer = FormatMessage(Format_Message.FORMAT_MESSAGE_ALLOCATE_BUFFER Or Format_Message.FORMAT_MESSAGE_FROM_SYSTEM Or Format_Message.FORMAT_MESSAGE_IGNORE_INSERTS,
	IntPtr.Zero, nLastError, 0, lpMsgBuf, 0, IntPtr.Zero)
	If dwChars = 0 Then
	Error_Message()
	Else
	Dim sRet As String = Runtime.InteropServices.Marshal.PtrToStringAuto(lpMsgBuf, dwChars)

MessageBox.Show(sRet, "Error_Message()", MessageBoxButtons.OK, MessageBoxIcon.Error)
	End If

'Format_Message.FORMAT_MESSAGE_ALLOCATE_BUFFER
	'The caller should use the LocalFree function to free the buffer when it is no longer needed
	If LocalFree(lpMsgBuf) <> 0 Then
	Error_Message()
	End If
	End Sub

!!!!Alternative Managed API:
This functionality is also given by System.ComponentModel.Win32Exception:
 string errorMessage = new Win32Exception(Marshal.GetLastWin32Error()).Message;
 Console.WriteLine(errorMessage);

Yet the sample might still be useful for messages not provided by the system.

Documentation: FormatMessage@msdn on MSDN