interop - DllImport - PreserverSig and SetLastError attributes

Question

On the MSDN I've found the following description for the two attributes:

PreserveSig Set the PreserveSig field to true to directly translate unmanaged signatures with HRESULT or retval values; set it to false to automatically convert HRESULT or retval values to exceptions. By default, the PreserveSig field is true.

SetLastError Enables the caller to use the Marshal.GetLastWin32Error API function to determine whether an error occurred while executing the method. In Visual Basic, the default is true (which adds some overhead); in C# and C++, the default is false.

My question is: How these two relate to each other? Suppose I have PreserveSig set to 'false' - it means that I should have HRESULT converted to exception - if unmanaged function returns integer indicating that error or no error occured, how could this be translated to exception?

Also why do I need to call GetLastWin32Error method if I somehow managed to extract the exception using PreserveSig?

Kind regards PK

Answer 1

Win32 functions almost never return a HRESULT. Instead they return a BOOL or use special values to indicate error (e.g. CreateFile returns INVALID_HANDLE_VALUE). They store the error code in a per-thread variable, which you can read with GetLastError(). SetLastError=true instructs the marshaler to read this variable after the native function returns, and stash the error code where you can later read it with Marshal.GetLastWin32Error(). The idea is that the .NET runtime may call other Win32 functions behind the scenes which mess up the error code from your p/invoke call before you get a chance to inspect it.

Functions which return a HRESULT (or equivalent, e.g. NTSTATUS) belong to a different level of abstraction than Win32 functions. Generally these functions are COM-related (above Win32) or from ntdll (below Win32), so they don't use the Win32 last-error code (they might call Win32 functions internally, though).

PreserveSig=false instructs the marshaler to check the return HRESULT and if it's not a success code, to create and throw an exception containing the HRESULT. The managed declaration of your DllImported function then has void as its return type.

Remember, the C# or VB compiler cannot check the DllImported function's unmanaged signature, so it has to trust whatever you tell it. If you put PreserveSig=false on a function which returns something other than a HRESULT, you will get strange results (e.g. random exceptions). If you put SetLastError=true on a function which does not set the last Win32 error code, you will get garbage instead of a useful error code.