Platform Invoke Technology Sample

Note
This sample is installed in the \Program Files\Microsoft.NET\SDK\v2.0\LateBreaking\PlatformInvoke or \Program Files\Visual Studio 8\SDK\v2.0\LateBreaking\PlatformInvoke folder.

This sample demonstrates techniques for calling functions exported from an unmanaged library. It shows how to:

• Declare different types

• Use available attributes to modify default behavior

• Use methods of the Marshal type

• Determine which aspects of garbage collection and threading can affect results.

Some of the samples use functions exported from Windows libraries and some use functions exported from a custom library. Certain samples use libraries that are not available on all Windows platforms or use functions in ways that are not supported on all Windows platforms. However, this does not prevent you from understanding specific platform invoke rules that are used in a sample.

These samples contain the following directory structure:

Directory	Contents
WinAPIs	Platform Invoke demonstrated using functions exported from Windows libraries
WinAPIs\CS	Sources written in C#
WinAPIs\VB	Sources written in Visual Basic
Custom	Platform Invoke demonstrated using functions exported from a custom type library.
Custom\CS	Sources written in C#
Custom\LIB	Custom type library source
Custom\VB	Sources written in VB

For information about using the samples, see the following topics:

• How to: View and Download Samples

• How to: Set Sample Settings

To build the samples using the Command Prompt

1. Open a command prompt window and navigate to one of the language-specific subdirectories.

2. Type msbuild [file name].sln at the command line.

   Note
   The Custom platform invoke samples can only be built using Visual Studio.

To build the samples using Visual Studio

1. Open Windows Explorer and navigate to one of the language-specific subdirectories.

2. Double-click the icon for [file name].sln to open the file in Visual Studio.

3. In the Build menu, select Build Solution.

To run the samples

1. Navigate to one of the language-specific directories, under either the WinAPIs or Custom directory, containing built executables.

2. Type the name of the executable file at the command line.

   Note
   This sample builds console applications. You must launch them separately, using the command prompt, in order to view their output.

Requirements

These samples require Windows headers which are available to your project if you build using Microsoft Visual Studio 2005, the Visual Studio 2005 Command Prompt, or if you have the Platform SDK installed and specified in an include path.

Remarks

The following tables summarize the topics demonstrated by these samples, and list the locations of source files for the sample or samples pertaining to that topic.

How to Use Platform Invoke Attributes

Attribute	Description	Sample
EntryPoint	Renames a function for use in managed code.	WinAPIs\CS\MsgBox.cs WinAPIs\VB\MsgBox.vb
CharSet	Chooses how strings are marshaled; also affects the function name search criteria.	WinAPIs\CS\MsgBox.cs WinAPIs\VB\MsgBox.vb
ExactSpelling	Indicates whether the name of the entry point in the unmanaged DLL should be modified to correspond to the CharSet value.	WinAPIs\CS\MsgBox.cs WinAPIs\VB\MsgBox.vb
CallingConvention	Calls functions with varargs.	WinAPIs\CS\Printf.cs WinAPIs\VB\Printf.vb
PreserveSig	Modifies functions that return HRESULTs.	WinAPIs\CS\CreateObject.cs WinAPIs\VB\CreateObject.vb
SetLastError	Guarantees that the error code is saved after a function call.	WinAPIs\CS\Errors.cs WinAPIs\VB\Errors.vb

How to Marshal Structures and Unions

---

Type	Description	Sample
structure ByVal	Passes a structure as an In parameter.	Custom\CS\Structs.cs Custom\VB\Structs.vb
structure ByRef	Passes a structure as an In/Out parameter.	WinAPIs\CS\OSInfo.cs WinAPIs\VB\OSInfo.vb
class ByVal	Passes a class with only integer members as an In/Out parameter.	WinAPIs\CS\SysTime.cs WinAPIs\VB\SysTime.vb
structure with nested structures (flattened)	Produces a class that represents a structure with nested structures on unmanaged side. Structure is flattened in one big structure on managed side.	WinAPIs\CS\FindFile.cs WinAPIs\VB\FindFile.vb
structure with nested structures (not flattened)	Passes a structure with an embedded structure.	Custom\CS\Structs.cs Custom\VB\Structs.vb
structure that contains pointer to another structure	Passes a structure that contains a pointer to another structure as a member.	Custom\CS\Structs.cs Custom\VB\Structs.vb
array of structures that contain only integers ByVal	Passes an array of structures that contain only integers as an In/Out parameter.	Custom\CS\Arrays.cs Custom\VB\Arrays.vb
array of structures that contain integers and strings ByRef	Passes an array of structures that contain integers and strings as the Out parameter. Callee allocates memory for the array.	Custom\CS\OutArrayOfStructs.cs Custom\VB\OutArrayOfStructs.vb
unions with value types	Passes a union with value types (integer and double).	Custom\CS\Unions.cs Custom\VB\Unions.vb
unions with mixed types	Passes a union with mixed types (integer and String).	Custom\CS\Unions.cs Custom\VB\Unions.vb

How to Marshal Arrays

Array	Description	Sample
array of integers ByVal	Passes an array of integers as an In/Out parameter.	Custom\CS\Arrays.cs Custom\VB\Arrays.vb
array of integers ByRef	Passes an array of integers as an In/Out parameter. Array can be resized.	Custom\CS\Arrays.cs Custom\VB\Arrays.vb
2D array of integers ByVal	Passing a matrix of integers as an In/Out parameter.	Custom\CS\Arrays.cs Custom\VB\Arrays.vb

Miscellaneous

---

Type of Item	Description	Sample
HandleRef	Presents a case when HandleRef needs to be used to prevent garbage collection.	WinAPIs\CS\HandleRef.cs WinAPIs\VB\HandleRef.vb
function pointers	Passes a delegate to an unmanaged function that expects a function pointer.	Custom\CS\Callback.cs Custom\VB\Callback.vb
void*	Calls a function that has void* as a parameter.	Custom\CS\Void.cs Custom\VB\Void.vb
LPARAM	Uses GCHandle to pass a managed object to unmanaged function that expects LPARAM.	WinAPIs\CS\GCHandle.cs WinAPIs\VB\GCHandle.vb
Single-Threaded Apartment (STA)/ Multi-Threaded Apartment (MTA)	Changes the default apartment settings when an unmanaged function calls CoInitialize.	WinAPIs\CS\ActiveDir.cs WinAPIs\VB\ActiveDir.vb

Review comments in the source code files for more information on platform invoke.

See Also

Reference

CharSet
DllImportAttribute
LayoutKind
Marshal
MarshalAsAttribute
StructLayoutAttribute

Concepts

Consuming Unmanaged DLL Functions
Platform Invoke Examples

Other Resources

Default Marshaling Behavior
Marshaling Data with Platform Invoke