1. P/Invoke Made Easy
Wei-Chen Wang

2. Interop Marshaling
Marshaling governs how data is passed between managed and unmanaged memory during platform invoke.
Managed
Client
Out Parameters
Unmanaged Library
Function Call
In Parameters

3. Pass Parameters
3 ways to transfer parameters between managed code and unmanaged code
Marshaling the data by Marshaler
Allocating an unmanaged memory block, populating the data, and passing the address of the memory block
Just passing the address of the managed object without marshaling the object

4. The unsafe Way /* C# Wrapper */ struct MyStruct { Int32 num;
IntPtr str1; }
[DllImport("dll.dll")]
void func(IntPtr ms);
/* C Declarations */
struct MyStruct {
DWORD num;
LPWSTR str1; }
void func(struct MyStruct *ms);
unsafe {
IntPtr ms = Marshal.AllocHGlobal(sizeof(MyStruct));
MyStruct *pms = (MyStruct*)ms;
ms->a = MAGIC_NUMBER;
ms->str1 = Marshal.AllocHGlobal(MAGIC_STRING.length*2);
strcpy( ms->str1, MAGIC_STRING);
func( ms ); }
directly operate the object via pointer
pass the address, IntPtr, of the struct

5. A Better Way /* C# Wrapper */ struct MyStruct { Int32 num;
IntPtr str1; }
[DllImport("dll.dll")]
void func(IntPtr ms);
/* C Declarations */
struct MyStruct {
DWORD num;
LPWSTR str1; }
void func(struct MyStruct *ms); {
IntPtr pms = Marshal.AllocHGlobal(sizeof(MyStruct));
MyStruct ms;
ms.num = MAGIC_NUMBER;
ms.str1 = Marshal.StringToHGlobalUni(MAGIC_STRING);
Marshal.StructureToPtr(ms, pms, false);
func(ms); }
operate the managed object
allocate memory and copy string by Mashaler utility

6. Summary, So Far...
unsafe code is hard to write (in C#), hard to debug, and lack of compiling-time and runtime checking. In most case, we don't have to use unsafe pointers.
We should operate everything on managed objects, and convert them to unmanaged objects only when we want to perform platform invoke.
It is free to encapsulate the converting code as methods of the object. Methods won't change the memory layout of the object.
Using AllocHGlobal to manually allocate an unmanaged memory block is necessary, if we want to pass the object for an asynchronous call.

7. Marshaling by Marshaler (the best way)
/* C# Wrapper */
struct MyStruct {
Int32 num;
[MarshalAs(UnmanagedType.LPWStr)]
String str1; }
[DllImport("dll.dll")]
void func(ref MyStruct ms);
/* C Declarations */
struct MyStruct {
DWORD num;
LPWSTR str1; }
void func(struct MyStruct *ms);
indicate the string should be converted to a pointer, which points to a string buffer {
MyStruct ms;
ms.num = MAGIC_NUMBER;
ms.str = MAGIC_STRING;
func(ref ms); }
num
operate on managed object
str1
string
the Marsahler will convert it to unmanaged object for you

8. Marshaling Internals Managed Memory Stack Stack Parameters Heap Heap
Unmanaged Memory
2. Marshal managed In-parameters to native
Stack
Stack
Parameters
6. Clean up managed Out-parameters
4. native code operate on unmanaged object
Heap
Heap
Object
Object
8. Clean up native data
Object
7. Marshal native Out-parameters to managed
Code
Code
1. Call C# wrapper
3. Call native code
C# Wrapper()
Function()
9. Return from C# wrapper
5. Return from native code

9. Default Marshaling for Blittable Types
struct MyStruct
{ Int32 a;
Int32 b;
public MyStruct(Int32 _a,
Int32 _b) {
a = _a;
b = _b;
} }
[DllImport("dll.dll")]
void CFunction(ref MyStruct ms);
MyStruct ms = new MyStruct(MAGIC_A, MAGIC_B);
CFunction(ref ms);
struct MyStruct
{ DWORD a;
DWORD b; };
void f(struct MyStruct *ms);

10. Default Marshaling for Blittable Types
Managed Memory
Unmanaged Memory
3. Pass the address (call-by-reference)
Stack
Stack
Parameters
5. native code operate on managed object
Heap
Heap
2. Pin the object
Object
7. Un-Pin the object
Code
Code
1. Call C# wrapper
4. Call native code
C# Wrapper()
Function()
8. Return from C# wrapper
6. Return from native code

11. Write Your Own Marshaler
class MyClass
{ /* ... */ }
class MyClassMarshaler: ICustomMarshaler
{ public void CleanUpManagedData(object ManagedObj);
public void CleanUpNativeData(IntPtr pNativeData);
public IntPtr MarshalManagedToNative(object ManagedObj);
public object MarshalNativeToManaged(IntPtr pNativeData); }
[DllImport("dll.dll")]
static extern void Function(
[MarshalAs(UnmanagedType.CustomMarshaler,
MarshalTypeRef=typeof(MyClassMarshaler))]
MyClass mc );
Custom marshaler used For marshaling MyClass
Use MyClassMarshaler to marshal MyClass

12. ICustomMarshaler in Action
Managed Memory
Unmanaged Memory
Stack
2. MarshalManaged ToNative()
Stack
Parameters
3. CleanUp ManagedData()
Heap
Heap
Object
Object
5. CleanUp
NativeData()
Object
4. MarshalNative
ToManaged()
1. GetInstance()
to get a instance of the marshaler
Code
Code
3. Call/Return from native code
C# Wrapper()
Function()

13. Delegate/Callback Managed Memory Stack Stack Parameters Heap delegate
2. pass delegate marshaled as a function pointer
Unmanaged Memory
Stack
Stack
Parameters
Heap
delegate
marshaling parameters
Code
Code
5. return from callback
delegate()
callback()
1. Call C# wrapper
4. invoke callback
3. Call native code
C# Wrapper()
Function()
7. Return from C# wrapper
6. Return from native code

14. Windows String at A Glance
ANSI String=char array=user locale encoding
Unicode String=wchar array=UTF-16 Little-Endian (Unicode is not necessary UTF-16LE, but in Windows, it is)
T-String=TCHAR array, char or wchar depends on compiling configuration
WINUSERAPI int WINAPI MessageBoxA( __in_opt HWND hWnd, __in_opt LPCSTR lpText, __in_opt LPCSTR lpCaption, __in UINT uType);
WINUSERAPI int WINAPI MessageBoxW( __in_opt HWND hWnd, __in_opt LPCWSTR lpText, __in_opt LPCWSTR lpCaption, __in UINT uType);
#ifdef UNICODE
#define MessageBox MessageBoxW
#else
#define MessageBox MessageBoxA
#endif // !UNICODE

15. More on Marshaling String
[StructLayout(LayoutKind.Sequential,
CharSet=CharSet.Unicode)]
struct MyStruct
{ [MarshalAs(UnmanagedType.LPStr)]
string str1; [MarshalAs(UnmanagedType.LPWStr)]
string str2; [MarshalAs(UnmanagedType.ByValTStr, SizeConst = N)]
string str3; }
struct MyStruct {
LPSTR str1;
LPWSTR str2;
WCHAR str3[N]; };
Just pass the struct. The marshaler will do the rest for you
MyStruct ms;
ms.str1 = "Hello";
ms.str2 = "world";
ms.str3 = "!!!";
function( ref ms);

16. Get a String Out void GetString( LPWSTR *text, int nMaxCount ); 1
[DllImport("dll.dll")]
static extern void
GetString(out String text, int nMaxCount);
The memory allocated on text in GetString() will leak.
Don't Do It! 2
[DllImport("dll.dll")]
static extern void
GetString(ref String text, int nMaxCount);
You cannot specify the size of the output buffer.
Don't Do It Too
void GetString( LPWSTR text, int nMaxCount ); 3
[DllImport("dll.dll")]
static extern void
GetString(StringBuilder text, int nMaxCount);
Just Do It ü
StringBuilder sbtext = new Stringbuilder(STR_LENGTH);
GetString( sbtext, sbtext.Capacity );

17. InAttribute and OutAttribute
InAttribute indicates that data should be marshaled from the caller to the callee, but not back to the caller
OutAttribute indicates that data should be marshaled from callee back to caller
Use the proper attributes to reduce unnecessary data copy
/* Example */
[DllImport("mydll.dll")]
static extern void func([in] ref MyStruct);
// pass the reference(pointer) of the structure
// parameter will be copied in, but not out

18. Keep Objects in Memory
Local variable can be garbage collected as it reach a point where it appears no longer being referenced {
MyFile file = new MyFile("file.txt");
IntPtr h = file.Handle;
// file is eligible for finalization after push the parameter
WriteFile( file.Handle ); }
Suppose that MyFile will close the file handle when finalizing, hence the file handle will be invalid.

19. Solutions 1 { MyFile file = new MyFile("file.txt");
IntPtr h = file.Handle;
DoSomething(h);
GC.KeepAlive(file); }
The purpose of KeepAlive is to keep a reference the object. Besides that, KeepAlive have no side-effect. 2 {
MyFile file = new MyFile("file.txt");
IntPtr h = file.Handle;
GCHandle gh = GCHnalde.Alloc(file);
DoSomething(h);
gh.Free(); }
Allocating a GCHandle prevents the object from being collected. 3 {
MyFile file = new MyFile("file.txt");
IntPtr h = file.Handle;
PInvoke(new HandleRef(file, h)); }
HandleRef guarantees that the object is not collected until the p/invoke completes

20. GCHandle GCHandle can be used to
prevent an objects being garbage collected
pin an object in memory, so it won't be relocated by GC (the object has to be of a value-type)
get the address of a pinned object

21. Pin an Object Only blittable object can be pinned.
struct PinMe {
int a;
int b; }
void PinYou()
{ struct PinMe pm;
pm.a = MAGIC_NUM1;
pm.b = MAGIC_NUM2;
GCHandle gh = GCHandle.Alloc(pm, GCHandleType.Pinned);
CFunction(gh.AddrOfPinnedObject());
gh.Free(); }
Only blittable object can be pinned.
The only reason to pin an blittable object it that you want to pass it to unmanaged code for an asynchronous operation, hence you don't want GC relocate it.
manipulate the managed object in un managed code, CFunction()

22. Get the Handle of an Object
We can't manipulate a managed object in unmanaged code, but we can pass the handle of it between managed and unmanaged code as callback data.
void function() {
Object obj = new Object();
GCHandle gh = GCHandle.Alloc(obj);
CFunction( GCHandle.ToIntPtr(gh), Callback ); }
void Callback(IntPtr p)
GCHandle gh = GCHandle.FromIntPtr(p); Object obj = gh.Target;
gh.Free(); }

23. References
Interop Marshaling
Marshaling Data with Platform Invoke
Blittable and Non-Blittable Types
HandleRef Structure
SafeHandles: the best V2.0 feature of the .NET Framework
SafeHandle: A Reliability Case Study
The Truth About GCHandles
GCHandle.ToIntPtr vs. GCHandle.AddrOfPinnedObject
GCHandles, Boxing and Heap Corruption
SafeHandle: A Reliability Case Study [Brian Grunkemeyer]