Platform Invoke Technology Sample

  • Article

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:

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

Concepts

Consuming Unmanaged DLL Functions

Platform Invoke Examples

Reference

CharSet

DllImportAttribute

LayoutKind

Marshal

MarshalAsAttribute

StructLayoutAttribute

Other Resources

Default Marshaling Behavior

Marshaling Data with Platform Invoke