Appendix E. PInvoke Definitions for Win32 Functions

In This Appendix

• GDI32.DLL

• KERNEL32.DLL

• OLE32.DLL

• SHELL32.DLL

• USER32.DLL

The biggest hassle of using Platform Invocation Services (PInvoke) is correctly defining the signatures of functions you wish to call. This appendix provides a PInvoke signature for just about every function exposed by five Windows DLLs so you don’t have to come up with these definitions yourself. The function definitions are listed alphabetically with respect to other functions in the same DLL. The five DLLs covered are:

• GDI32.DLL

• KERNEL32.DLL

• OLE32.DLL

• SHELL32.DLL

• USER32.DLL

To get a better understanding of how to use these signatures, tweak them, or translate them to other .NET languages, consult Part VI, “Platform Invocation Services (PInvoke).” Here are a few notes about the following lists of signatures:

• The definitions are given in C# syntax, but in a way that can easily be translated to other .NET languages. If you rewrite any of these signatures in VB .NET syntax, you’ll want to change unsigned types to signed types (such as changing ushort, uint, and UIntPtr to Short, Integer, and IntPtr, respectively). Also, the signatures assume that DllImportAttribute is used with no named parameters set (unless shown otherwise). Therefore, the C# default of CharSet.Ansi is assumed. The easiest way to reproduce the same behavior in VB .NET is to use DllImportAttribute with CharSet.Ansi rather than Declare, because Declare turns on the ExactSpelling setting. ExactSpelling doesn’t work for many of these definitions as-is, because they depend on an “A” or “W” suffix being appended to their names.

• The definitions use types in the System namespace (IntPtr and UIntPtr), the System.Text namespace (StringBuilder), and custom attributes in the System.Runtime.InteropServices namespace (DllImportAttribute, MarshalAsAttribute, InAttribute, and OutAttribute).

• Several signatures use structures, interfaces, or delegates (ending with a Delegate suffix) that need to be defined in order to compile and use them. For the sake of space, these additional type definitions are not given.

• All structures are assumed to be defined as value types rather than formatted classes. If a function expects a pointer to a structure that could be null, the parameter is defined with the IntPtr type.

• Several of the signatures have customizations to make them more user-friendly than straightforward definitions, but you may have to tweak the signatures for usability and/or performance, depending on your specific scenario.

• Most of these signatures have not been tested, so it’s possible that some have errors. Check this book’s Web site for any corrections.

GDI32.DLL

All of these functions should be preceded with the following line when used in source code:

[DllImport("gdi32.dll")]

Here are signatures from GDI32.DLL:

KERNEL32.DLL

All of these functions should be preceded with the following line when used in source code:

[DllImport("kernel32.dll")]

Here are signatures from KERNEL32.DLL:

OLE32.DLL

All of these functions should be preceded with the following line when used in source code:

[DllImport("ole32.dll")]

Most of these methods return an HRESULT. Therefore, rather than using an int return value to represent the HRESULT, you could change it to void and add PreserveSig=false to the DllImportAttribute for functions that don’t return multiple success HRESULT values. For example:

[DllImport("ole32.dll", PreserveSig=true)]

This way, failure HRESULTs cause exceptions to be thrown, which is usually more convenient but at the sake of performance. In the signatures listed, PreserveSig=true is not used, so methods that return an HRESULT are listed as returning int.

Notice that the PInvoke signatures for functions in OLE32.DLL are generally longer than the previous signatures, because they use common COM types that the Interop Marshaler doesn’t handle by default for PInvoke (such as IUnknown and Unicode strings). The MarshalAsAttribute pseudo-custom attribute is required to use these COM types with PInvoke marshaling. Here are signatures from OLE32.DLL:

SHELL32.DLL

All of these functions should be preceded with the following line when used in source code:

[DllImport("shell32.dll")]

Here are signatures from SHELL32.DLL:

USER32.DLL

All of these functions should be preceded with the following line when used in source code, unless specified otherwise:

[DllImport("user32.dll")]

Here are signatures from USER32.DLL: