Marshaling with C# Pocket Reference

Author | Mohammad Elsheimy
MARSHALING WITH C#
POCKET REFERENCE

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
2

MARSHALING WITH C#
POCKET REFERENCE

Mohammad Elsheimy
A freelance software developer and trainer

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
3

© 2010 Mohammad Elsheimy

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
4
ABOUT THE AUTHOR

Mohammad Elsheimy
Mohammad is a MCP, MCTS, and MCPD independent
consultant, trainer, and author. He was born in 1991 in KB,
Egypt.
Besides self-studying computer science, yet, he is a student in
Al-Azhar Holy Quran Institute. There, he studies Islamic
legislation and sciences related to Islam, The Holy Quran, and
the Arabic language.
Mohammad loves community work. He always works on
helping developers and average users all over the world. He is writing in many
places including his own blog, http://JustLikeAMagic.WordPress.com.
You can reach Mohammad at [email protected]. In addition, you can
reach him directly at +2 018 577 1171.

WHO SHOULD READ THIS BOOK?

This book discusses the marshaling process between managed and unmanaged
code using C#, devoted for developers who know the basics of unmanaged code
(especially Windows API) and platform invocation.
For the sake of simplicity, this book focuses on Windows API as the source for
unmanaged code. However, information in this book can be applied to any of the
unmanaged environments.
In addition, this book assumes a 32-bit version of Windows. All DWORDs,
HANDLEs, etc. are considered 4-bytes. If you want to hand your application to
64-bit machine, consider revising your code to avoid memory layout problems.
For VB.NET developers, it is helpful reading pages in Appendix A.

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
5
CONTENTS AT A GLANCE

About the Author
Who should read this book?
Chapter 1: Introducing Marshaling
Chapter 2: Marshaling Simple Types
Chapter 3: Marshaling Compound Types
Chapter 4: Marshaling Arrays
Chapter 5: Marshaling Callbacks
Chapter 6: Memory Management
Chapter 7: Controlling the Marshaling Process
Appendix A: What about VB.NET
Where to Go Next
References
Figures
Code Listings
Glossary

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
6
TABLE OF CONTENTS

About the Author
Who should read this book?
Chapter 1: Introducing Marshaling
What is Marshaling?
Why Marshaling?
When I Need to Marshal?
Chapter 2: Marshaling Simple Types
Chapter Contents
Overview
Simple and Compound data Types
Blittable and Non-Blittable Data Types
Marshaling Blittable Data Types
Numeric Data Types
Textual Data Types
Examining Type Definition
Variants
Try It Out!
A Rule of Thumb
Marshaling Booleans
The Two Types
Try It Out!
Marshaling Textual Data types
How to Marshal Strings and Buffers
Handling Character Encoding
Try It Out!

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
7
Marshaling Handles
Generic Handles
Safe Handles
Critical Handles
Passing Mechanism
Additional Techniques
Encapsulation
Creating Wrappers
Working with Nullable Arguments
Working out the CLS Problem
Real-World Examples
Programmatically Swapping Mouse Buttons
Programmatically Turning On the Screen Saver
Dragging a Form without a Title Bar
Summary
Chapter 3: Marshaling Compound Types
Chapter Contents
Overview
Introduction
Marshaling Unmanaged Structures
How to Marshal a Structure
Handling Memory Layout Problem
Try It Out!
Marshaling Unions
A Short Speech About Unions
How to Marshal a Union
Unions with Arrays
Try It Out!

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
8
Value-Types and Reference-Types
Passing Mechanism
Real-World Examples
The DEVMODE Structure
Working with Display Settings
Summary
Chapter 4: Marshaling Arrays
Chapter 5: Marshaling Callbacks
Chapter 6: Memory Management
Chapter 7: Controlling the Marshaling Process
Appendix A: What about VB.NET
Where to Go Next
References
Figures
Code Listings
Glossary

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
9

This page intentionally left blank.

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
10
CHAPTER 1
INTRODUCING MARSHALI NG

WHAT IS MARSHALING ?
Marshaling is the process of creating a bridge between managed code and
unmanaged code; it is the homer that carries messages from the managed to the
unmanaged environment and reverse. It is one of the core services offered by the
CLR (Common Language Runtime).
Because much of the types in unmanaged environment do not have counterparts
in managed environment, you need to create conversion routines that convert
the managed types into unmanaged and vice versa; and that is the marshaling
process.
As a refresher, we call .NET code "managed" because it is controlled (managed)
by the CLR. Other code that is not controlled by the CLR is called unmanaged.

WHY MARSHALING ?
You already know that there is no such compatibility between managed and
unmanaged environments. In other words, .NET does not contain such the types
HRESULT, DWORD, and HANDLE that exist in the realm of unmanaged code.
Therefore, you need to find a .NET substitute or create your own if needed. That
is what called marshaling.
An example is the unmanaged DWORD; it is an unsigned 32-bit integer, so we
can marshal it in .NET as System.UInt32. Therefore, System.UInt32 is a substitute
for the unmanaged DWORD. On the other hand, unmanaged compound types
(structures, unions, etc.) do not have counterparts or substitutes in the managed
environment. Thus, you’ll need to create your own managed types
(structures/classes) that will serve as the substitutes for the unmanaged types
you use.

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
11
WHEN I NEED TO MARSH AL?
Marshaling comes handy when you are working with unmanaged code, whether
you are working with Windows API or COM components. It helps you
interoperating (i.e. working) correctly with these environments by providing a
way to share data between the two environments. Figure 1 shows the
marshaling process, where it fall, and how it is required in the communication
process between the two environments.

Figure 1.1 - The Marshaling Process

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
12

This page intentionally left blank.

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
13
CHAPTER 2
MARSHALING SIMPLE TY PES

CHAPTER CONTENTS
Contents of this chapter:
 Chapter Contents
 Overview
 Simple and Compound data Types
 Blittable and Non-Blittable Data Types
 Marshaling Blittable Data Types
o Numeric Data Types
o Textual Data Types
o Examining Type Definition
o Variants
o Try It Out!
 A Rule of Thumb
 Marshaling Booleans
o The Two Types
o Try It Out!
 Marshaling Textual Data types
o How to Marshal Strings and Buffers
o Handling Character Encoding
o Try It Out!
 Marshaling Handles
o Generic Handles
o Safe Handles

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
14
o Critical Handles
 Passing Mechanism
 Additional Techniques
o Encapsulation
o Creating Wrappers
o Working with Nullable Arguments
o Working out the CLS Problem
 Real-World Examples
o Programmatically Swapping Mouse Buttons
o Programmatically Turning On the Screen Saver
o Dragging a Form without a Title Bar
 Summary

OVERVIEW
This chapter discusses the nitty-gritty part of marshaling process. It is the base
for the rest of discussion about marshaling. It is about marshaling simple data
types.
The first section of this chapter breaks data types into two categories, simple and
compound. Simple types (integers, booleans, etc.) are those that are not made of
other types. On the contrary, compound types (structures and classes) are those
types that require special handling and made of other types.
After that, we will dig into the discussion of simple types and we will break them
into two categories, blittable and non-blittable.
Before we end this chapter, we will discuss the passing mechanism and handles
in .NET Framework.

SIMPLE AND COMPOUND DATA TYPES
There are two kinds of data types:
 Simple (primitive/basic)

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
15
 Compound (complex)
Primitive data types are those that are not defined in terms of other data types.
They are the basis for all other types. Examples of managed primitives are
numbers like System.Byte, System.Int32, System.UInt32, and System.Double,
strings like System.Char and System.String, and handles like System.IntPtr.
Compound data types are those that built up of other data types. For example a
class or a structure that encapsulates simple types and other compound types.
We will use terms simple, primitive, and basic types to refer to base types
like integers, strings, etc. Terms compound, and complex types also will be
used interchangeably to refer to classes and structures.
Some considers that strings are not primitives.

BLITTABLE AND NON -BLITTABLE DATA TYPES
Most data types have common representations in both managed and unmanaged
memory and do not require special handling. These types are called blittable
types because they do not require special handling when passed between
managed and unmanaged code. Other types that require special handling are
called non-blittable types. You can think that most of simple types are blittable
and all of compound types are non-blittable.
The following table lists the blittable data types exist in .NET (their counterparts
in unmanaged code will be covered soon):
Table 2.1 Blittable Types
Description Managed Type
8-bit signed integer. System.SByte
8-bit unsigned integer System.Byte
16-bit signed integer. System.Int16
16-bit unsigned integer System.UInt16
32-bit signed integer System.Int32
32-bit unsigned integer System.UInt32
64-bit signed integer System.Int64
64-bit unsigned integer System.UInt64
Signed pointer System.IntPtr
Unsigned pointer System.UIntPtr

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
16
MARSHALING BLITTABLE DATA TYPES
You can marshal an unmanaged simple data type by tracking its definition then
finding its counterpart (marshaling type) in the managed environment based on
its definition (we will see how soon.)
NUMERIC DATA TYPES
The following table lists some of the unmanaged data types in Windows, their
C/C++ keywords, and their counterparts (marshaling types) in .NET. As you
might guess, by tracking each of these unmanaged types, we were able to find its
managed counterpart. Notice that so
Table 2.2 Numeric Data Types
Description Windows Type C/C++
Keyword
Managed Type C#
Keyword
8-bit signed
integer
CHAR char System.SByte sbyte
8-bit unsigned
integer
BYTE unsigned char System.Byte byte
16-bit signed
integer
SHORT Short System.Int16 short
16-bit unsigned
integer
WORD and USHORT unsigned
short
System.UInt16 ushort
32-bit signed
integer
INT, INT32, LONG,
and LONG32
int, long System.Int32 int
32-bit unsigned
integer
DWORD, DWORD32,
UINT, and UINT32
unsigned int,
unsigned long
System.UInt32 uint
64-bit signed
integer
INT64, LONGLONG,
and LONG64
__int64, long
long
System.Int64 long
64-bit unsigned
integer
DWORDLONG,
DWORD64,
ULONGLONG, and
UINT64
unsigned
__int64,
unsigned long
long
System.UInt64 ulong
Floating-point
integer
FLOAT float System.Double double

Notice that long and int defer from a platform to another and from a
compiler to another. In 32-bit versions of Windows, most compilers refer to
both long and int as 32-bit integers.

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
17
Some types are based on the version of Windows. DWORD, for instance, is 32
bits on 32-bit versions and 64 bits on 64-bit versions of Windows. This
writing assumes that it is a 32-bit version of Windows.
Know that there is no difference between Windows data types and C/C++
data types. Windows data types are just aliases for the actual C types.
Do not be confused with the many types that refer to one thing, they are all
just names (aliases.) INT, INT32, LONG, and LONG32 are all 32-bit integers
for instance.
To keep things simple, we will focus on Windows API in our examples.
Although, some unmanaged types have names similar to names of some
managed types, they have different meanings. An example is LONG, it has similar
name as System.Long. However, LONG is 32-bit and System.Long is 64-bit!
If you need to learn more about these types, check out the article “Windows Data
Types” in MSDN library.
TEXTUAL DATA TYPES
In addition to the numeric data types, you will need to know how to marshal
unmanaged textual data types (a single character or a string.) However, these
types are non-blittable, so they require special handling.
The following table lists briefly unmanaged textual data types.
Table 2.3 Textual Data Types
Description Unmanaged Type(s) Managed Type
8-bit ANSI character CHAR System.Char
16-bit Unicode character WCHAR System.Char
8-bit ANSI string of
characters
LPSTR, LPCSTR, PCSTR, and
PSTR
System.String
16-bit Unicode string of
characters
LPCWSTR, LPWSTR,
PCWSTR, and PWSTR
System.String

Soon we will cover textual data types in details.
EXAMINING TYPE DEFIN ITION
As we have said, for the sake of simplicity, we will use Windows API as the base
for our discussion in this book. Therefore, you need to know that all Windows
Data Types (INT, DWORD, etc.) are just names (technically, typedefs) for the
actual C types. Therefore, many names may refer to one thing just as INT and
LONG.

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
18
Thus, we can say that LONG is defined as C int and DWORD is defined as C
unsigned long.
INT and LONG are easy to marshal. However, there are primitive types that you
will need to track their definitions to know how to marshal it.
Remember that we will use MSDN documentation (specially the article
“Windows Data Types”) when tracking unmanaged data types (Windows data
types specially.)
The next are some of the types defined as another types. You can think of these
types as aliases for the base types. Yet, some are platform-specific, and others
not.
 HRESULT:
As you will see, plenty of functions return a HRESULT to represent the
status of the operation. If HRESULT equals to zero, then the function
succeeded, otherwise it represents the error code or status information
for the operation. HRESULT defined as LONG, and LONG in turn defined as
a 32-bit signed integer. Therefore, you can marshal HRESULT as
System.Int32.
 BOOL and BOOLEAN:
Both are Boolean types, that means that they take either TRUE (non-zero)
or FALSE (zero.) The big difference between BOOL and BOOLEAN is that
BOOL is defined as INT, thus occupies 4 bytes. BOOLEAN on the other
hand is defined as BYTE, thus occupies only 1 byte. Booleans are covered
soon.
 HFILE:
A handle to a file opened using one of the Windows File IO functions like
OpenFile() function. This type is defined as INT, and INT in turn is defined
as a 32-bit signed integer. Therefore, you can marshal HFILE as
System.Int32. Although, HFILE defined as INT, handles should be
marshaled as System.IntPtr, which is internally encapsulates the raw
handle. To be clear, you would better marshal an unmanaged handle as a
System.Runtime.InteropServices.SafeHandle or CriticalHandle, this is the
ideal marshaling type for any handle. Hence, file handles best marshaled
as Microsoft.Win32.SafeHandles.SafeFileHandle that is derived from
SafeHandleZeroOrMinusOneIsInvalid that is in turn derived from the
abstract class System.Runtime.InteropServices.SafeHandle. For more
details about handles, refer to the section "Marshaling Handles" later in
this chapter.

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
19
In addition, there are types that are variable based on the operating system.
Examples are:
 INT_PTR:
A pointer to a signed integer. Defined as INT64 if this is a 64-bit OS, or INT
otherwise.
 LONG_PTR:
A pointer to a signed long. Defined as INT64 if this is a 64-bit OS, or LONG
otherwise.
 UINT_PTR:
A pointer to an unsigned integer. Defined as DWORD64 if this is a 64-bit
OS, or DWORD otherwise.
 ULONG_PTR:
A pointer to an unsigned long. Defined as DWORD64 if this is a 64-bit OS,
or DWORD otherwise.
Keep in mind that there is a big difference between a variable and a pointer to a
variable. A variable refers directly to its value into the memory. However, a
pointer contains an address of another value into the memory. Consider the
following illustration, Figure 2.1:

Figure 2.1 - Pointers into Memory
In the illustration above, the variable i contains the value 320 and you can get the
value from the variable directly. The pointer ptr on the other hand contains the

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
20
address of the variable i. Thus, it indirectly contains the value of the variable i.
That is why we cannot get the value of the pointer directly. We need to
dereference it first before retrieving its value.
More on pointers later in this chapter. Memory management is discussed in
details in chapter 6.

In addition, for textual data types, there are types variable based on Unicode
definition (strings and buffers are covered soon.) Examples are:
 TBYTE and TCHAR:
Defined as WCHAR if UNICODE defined, otherwise CHAR.
 LPCTSTR, LPTSTR, and PCTSTR:
All defined as LPCWSTR if UNICODE defined, otherwise LPCSTR.
 PTSTR:
Defined as PWSTR if UNICODE defined, otherwise PSTR.
More on textual data types and Unicode later in this chapter.
Notice that some types have special characters in their names. For example, A in
textual data types stands for ANSI, and W in stands for Wide, which means
Unicode. In addition, the letter T in textual information too means it varies based
on OS. Another example is the prefix P (lowercase,) it means a pointer, and LP
means a long pointer. LPC stands for long pointer to a constant.
VARIANTS
In addition, Win32 API defines the types VOID, LPVOID, and LPCVOID. VOID
indicates that the function does accept no arguments. Consider the following
function:
DWORD GetVersion(VOID);
It is required to tag the function with VOID if it does not accept any arguments
(that is one of the specifications of C89.) Notice that VOID is defined as void.
LPVOID and LPCVOID are defined as any type (variant). That means that they can
accept any value. They can be marshaled as integers, strings, handles, or even
compound types, anything you want. In addition, you can marshal them as
System.IntPtr, so you can set them to the address of any object in memory. In
addition, you can marshal them as pointers to object. For example, marshaling a
LPCVOID as System.Int32* (a pointer to an integer) in unsafe code. Moreover,
you can use unsafe code and marshal them as void*. Furthermore, you can

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
21
marshal them as System.Object, so you can set them to any type (refer to chapter
6 for more information about memory management and unsafe code.)
It is worth mentioning that when working with VOIDs it is recommended
decorating your variable with MarshalAsAttribute attribute specifying
UnmanagedType.AsAny which tells the compiler to work out the marshaling
process and sets the type of the argument at runtime. Refer to the last chapter:
"Controlling the Marshaling Process" for more information about this attribute.
If you have worked with traditional Visual Basic, thinking about LPVOID
and LOCVOID as a Variant could help too much.
If you are interoperating with the traditional Visual Basic code, you can use
the same way we did on marshaling LPVOID and LPCVOID in marshaling
the type Variant.
TRY IT OUT!
Now, we will try to create the PInvoke method for the MessageBoxEx() function.
The example demonstrates how to control precisely the marshaling process
using the MarshalAsAttribute attribute. We will cover this attribute and more in
the last chapter of this book: "Controlling the Marshaling Process." Handles are
covered in the section: "Marshaling Handles" of this chapter.
The following example creates the PInvoke method for the MessageBoxEx()
function and calls it to display a friendly message to the user.
The definition of the MessageBoxEx() function is as following:
Listing 2.1 MessageBoxEx() Unmanaged Signature
int MessageBoxEx(
HWND hWnd,
LPCTSTR lpText,
LPCTSTR lpCaption,
UINT uType,
WORD wLanguageId
);
And here is the managed signature (the PInvoke method) of this function:
In order for the example to run you must add a using statement to
System.Runtime.InteropServices namespace. Be sure to add it for all
examples throughout this book.
Listing 2.2 MessageBoxEx() Managed Signature
// CharSet.Unicode defines the UNICODE.
// Use either this way to control

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
22
// the whole function, or you can control
// the parameters individually using the
// MarshalAsAttribute attribute
[DllImport("User32.dll", CharSet = CharSet.Unicode)]
[return: MarshalAs(UnmanagedType.I4)]
static extern Int32 MessageBoxEx
(IntPtr hWnd,
// Marshaling as Unicode characters
[param: MarshalAs(UnmanagedType.LPTStr)]
String lpText,
// Marshaling as Unicode characters
[param: MarshalAs(UnmanagedType.LPTStr)]
String lpCaption,
// Marshaling as 4-bytes (32-bit) unsigned integer
[param: MarshalAs(UnmanagedType.U4)]
UInt32 uType,
// Marshaling as 2-bytes (16-bit) unsigned integer
[param: MarshalAs(UnmanagedType.U2)]
UInt16 wLanguageId);
For more information about marshaling strings, see section “Marshaling
Strings and Buffers” later in this chapter.

A RULE OF THUMB
Keep in mind that. .NET Framework allows you to take a granular level of control
over the marshaling process and that would be very complicated. However,
things can be so simple.
You can ignore attributes in most cases and just use the counterparts and CLR
will do its best. Likely, you are not required to use managed signed integers for

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
23
unmanaged equivalents. You can use managed signed integers for unmanaged
unsigned integers and vice versa. You can also marshal a SHORT as System.Char!
The key point is that as long as the managed marshal type occupies the same
memory size as the unmanaged type, you are in safe. However, keeping things in
its right position helps avoiding undesirable errors that maybe very difficult to
know and handle.
Another thing that you should keep in mind that the information in this book can
be applied to any unmanaged environment. You can apply this information when
interoperating with Windows API, C/C++ libraries, Visual Basic, COM, OLE,
ActiveX, etc. However, for the sake of simplicity, we will talk about the Windows
API as the source of the unmanaged code.
Another thing, this writing assumes a 32-bit version of Windows. Thus, it
considers that DWORDs, HANDLEs, etc. are all 4 bytes. On 64-bit versions, they
are 8 bytes.

MARSHALING BOOLEANS
THE TWO TYPES
In general, marshaling simple data types is very easy and booleans are no
exception. However, Booleans are non-blittable types. Therefore, they require
some handling.
There are some notes about marshaling booleans in the managed environment.
The first thing to mention about is that Windows defines two types of Boolean
variables:
1. BOOL:
Defined as INT, therefore, it is 4-bytes wide.
2. BOOLEAN:
Defined as BYTE, therefore it is only 1-byte.
Both can be set to non-zero to indicate a true (TRUE) value, and zero otherwise
(FALSE.)
Again, the two types exist only in the Windows SDK. Other environments
may define other types with similar names.
While it is true that BOOL and BOOLEAN are best marshaled as System.Boolean,
BOOL can be marshaled as System.Int32 too, because it is defined as a 32-bit
integer. On the other hand, BOOLEAN can be marshaled as System.Byte or
System.U1, because it is defined as 8-bits integer. Do you remember our rule of
thumb?

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
24
Take into consideration that whether you are marshaling your Boolean type to
System.Boolean, System.Int32, or System.Byte, it is recommended that you apply
MarshalAsAttribute attribute to the variable to specify the underlying
unmanaged type. For example, to specify that the underlying type is BOOL,
specify UnmanagedType.Bool (recommended) or UnmanagedType.I4 in the
MarshalAsAttribute constructor. On the other hand, BOOLEAN can be specified
as UnmanagedType.U1. If you omit MarshalAsAttribute, CLR assumes the default
behavior for System.Boolean, which is 2 bytes wide. For more information about
MarshalAsAttribute attribute, see the last chapter: "Controlling the Marshaling
Process."
TRY IT OUT!
Fortunately, plenty of functions return BOOL indicating whether the function
succeeded (TRUE) or failed (FALSE.)
The following is the definition of the famous CloseHandle() function:
Listing 2.3 CloseHandle() Unmanaged Signature
BOOL CloseHandle(HANDLE hObject);
The managed version of CloseHandle() is as following:
Listing 2.4 CloseHandle() Managed Signature
[DllImport("Kernel32.dll")]
[return: MarshalAs(UnmanagedType.Bool)]
// In addition, you can marshal it as:
// [return: MarshalAs(Unmanag edType.I4)]
// Moreover, You can change System.Boolean to System.Int32
static extern Boolean CloseHandle(IntPtr hObject);
Handles covered soon. For now, it is OK to know that all handles marshaled
to System.IntPtr.

MARSHALING TEXTUAL DATA TYPES
HOW TO MARSHAL STRIN GS AND BUFFERS
This section discusses how to marshal strings and buffers. We will use the terms
string and buffer interchangeably to refer to a sequence of characters.
Two types exist in the managed environment for marshaling unmanaged string
buffers. They are System.String and System.Text.StringBuilder. Of course, they

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
25
both hold character sequences. However, StringBuilder is more advantageous
because it is very efficient working with mutable strings than System.String.
Every time you use one of the methods of System.String class or you pass a
System.String to a function, normally, you create a new string object in memory,
which requires a new allocation of memory space for the new object. In addition,
if the function changes the string you will not get the results back. That is why
System.String is called immutable. On the other hand, StringBuilder does not
require re-allocating of space unless you exceed its capacity. Besides the talk
about marshaling, you should use StringBuilder to accommodate performance
issues if you often change the same string many times.
To keep System.String immutable, the marshaler copies the contents of the string
to another buffer before calling the function, and then it passes that buffer to the
function. If you were passing the string by reference, the marshaler copies the
contents of the buffer into the original string when returning from the function.
Conversely, when using StringBuilder, it passes a reference to the internal buffer
of StringBuilder if passed by value. Passing a StringBuilder by reference actually
passes a pointer to the StringBuilder object into memory to the function not a
pointer to the buffer itself.
Read more about passing a type by value or by reference in the section
"Passing Mechanism" later in this chapter.
Another feature of StringBuilder is its ability to specify buffer capacity. As we will
see, this can be very helpful in plenty of cases.
To summarize, System.String is preferable when working with immutable
strings, especially for input (In) arguments. On the other hand,
System.Text.StringBuilder is preferable with changeable strings especially
output (Out) arguments.
Noteworthy to say that StringBuilder cannot be used inside compound types.
Therefore, you will need to use String instead.
Another point to mention is that you can pass array of System.Char in place of a
System.String or System.Text.StringBuilder. In other words, you can marshal
unmanaged strings as managed arrays of System.Char (or System.Int16, do you
remember?)
Compound types discussed in the next chapter.
HANDLING CHARACTER E NCODING
Encoding of a character is very important because it determines the value that
the character can hold and the size it occupies into memory. For example, if the
character is ANSI-encoded it can be one of only 256 characters. Likewise, if it is

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
26
Unicode-encoded, it can hold one of 65536 characters, which is very good for
most languages.
If you need more information about Unicode, you can check the official site
of Unicode, www.Unicode.org. In addition, Programming Windows 5
th by
Charles Petzold includes a must-read introduction of Unicode and
character sets.
For controlling character encoding when marshaling unmanaged types, you may
take one of two approaches or you can combine them as needed. You can control
the encoding of the overall function (i.e. at the function level,) or you can drill
down and control the encoding process at a granular level by controlling every
argument separately (the second approach is required in certain cases e.g.
MultiByteToWideChar() function.)

For changing the encoding of the overall function, DllImportAttribute offers the
property CharSet that indicates the encoding (character set) for the strings and
arguments of the function. This property can take one of several values:
 CharSet.Auto (CLR Default):
Strings encoding varies based on operating system; it is Unicode-encoded
on Windows NT and ANSI-encoded on other versions of Windows.
 CharSet.Ansi (C# Default):
Strings are always 8-bit ANSI-encoded.
 CharSet.Unicode:
Strings are always 16-bit Unicode-encoded.
 CharSet.None:
Obsolete. Has the same behavior as CharSet.Ansi.
Take into consideration that if you have not set the CharSet property, CLR
automatically sets it to CharSet.Auto. However, some languages override the
default behavior. For example, C# defaults to CharSet.Ansi.
It is worth mentioning that plenty of functions that accept strings and buffers are
just names (technically typedefs)! They are not real functions, they are entry-
points (aliases) for the real functions. For example, ReadConsole() function is
nothing except an entry point redirects the call to the right function, either
ReadConsoleA() if ANSI is defined, or ReadConsoleW() if Unicode is defined (A
stands for ANSI, and W stands for Wide which means Unicode.) Therefore, you
can actually bypass this entry-point by changing the PInvoke method name to
match the right function or by changing DllImportAttribute.EntryPoint to the
name of the required function. In both cases, setting DllImportAttribute.CharSet
along with is no use.

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
27
If you want to control the encoding at a granular level, you can apply the
MarshalAsAttribute attribute to the argument specifying the underlying
unmanaged type.
Usually, you will need to unify the character encoding of all your native functions
and types. This is, all the functions should be either Unicode or ANSI. Under rare
occasions, some functions would be different in character encoding.
It is worth mentioning that, for fixed-length strings you will need to set the
SizeConst property of MarshalAsAttribute to the buffer length.
These techniques are not limited to arguments only! You can use them with
variables of compound types too. We will look at compound types in the
following chapter.
TRY IT OUT!
Now we will look on both ReadConsole() and FormatConsole() unmanaged
functions and how to call them from your managed environment. Next is the
definition of both functions and other functions required for the example:
Listing 2.5 GetStdHandle(), ReadConsole(), GetLastError(), and FormatMessage()
Unmanaged Signature
HANDLE GetStdHandle(
DWORD nStdHandle
);

BOOL ReadConsole(
HANDLE hConsoleInput,
[out] LPVOID lpBuffer,
DWORD nNumberOfCharsToRead,
[out] LPDWORD lpNumberOfCharsRead,
LPVOID lpReserved
);

DWORD GetLastError(void);

DWORD FormatMessage(
DWORD dwFlags,
LPCVOID lpSource,
DWORD dwMessageId,

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
28
DWORD dwLanguageId,
[out] LPTSTR lpBuffer,
DWORD nSize,
va_list* Arguments
);
And this is the managed version along with the driver code.
Listing 2.6 Reading from the Console Screen Buffer Example
// For retrieving a handle to a specific console device
[DllImport("Kernel32.dll")]
static extern IntPtr GetStdHandle(
[param: MarshalAs(UnmanagedType.U4)]
int nStdHandle);

// Used with GetStdHandle() for retrieving console input buffer
const int STD_INPUT_HANDLE = -10;

// Specifying the DLL along with the character set
[DllImport("Kernel32.dll", CharSet = CharSet.Unicode)]
[return: MarshalAs(UnmanagedType.Bool)]
static extern bool ReadConsole(
// Handle to the input device
IntPtr hConsoleInput,
// The buffer of which to write input to
[param: MarshalAs(UnmanagedType.LPTStr), Out()]
// [param: MarshalAs(UnmanagedType.AsAny)]
StringBuilder lpBuffer,
// Number of characters to read
[param: MarshalAs(UnmanagedType.U4)]
uint nNumberOfCharsToRead,
// Outputs the number of characters read
[param: MarshalAs(UnmanagedType.U4), Out()]
out uint lpNumberOfCharsRead,
// Reserved = Always set to NULL

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
29
[param: MarshalAs(UnmanagedType.AsAny)]
uint lpReserved);

// For getting the code for the last error occurred
[DllImport("Kernel32.dll")]
[return: MarshalAs(UnmanagedType.U4)]
static extern uint GetLastError();

// Retrieves error messag es
[DllImport("Kernel32.dll", CharSet = CharSet.Unicode)]
[return: MarshalAs(UnmanagedType.U4)]
static extern uint FormatMessage(
// Options
[param: MarshalAs(UnmanagedType.U4)]
uint dwFlags,
// Source to get the message from
// [param: MarshalAs(UnmanagedType.AsAny)]
[param: MarshalAs(UnmanagedType.U4)]
uint lpSource,
// Message code = error code
[param: MarshalAs(UnmanagedType.U4)]
uint dwMessageId,
// Language ID (Reserved)
[param: MarshalAs(UnmanagedType.U4)]
uint dwLanguageId,
// Outputs the error message
[param: MarshalAs(UnmanagedType.LPTStr), Out()]
out string lpBuffer,
// Size of error message
[param: MarshalAs(UnmanagedType.U4)]
uint nSize,
// Additional options

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
30
[param: MarshalAs(UnmanagedType.U4)]
uint Arguments);

// Message Options
const uint FORMAT_MESSAGE_ALLOCATE_BUFFER = 0x0100;
const uint FORMAT_MESSAGE_IGNORE_INSERTS = 0x0200;
const uint FORMAT_MESSAGE_FROM_SYSTEM = 0x1000;
const uint FORMAT_MESSAGE_FLAGS =
FORMAT_MESSAGE_ALLOCATE_BUFFER |
FORMAT_MESSAGE_IGNORE_INSERTS |
FORMAT_MESSAGE_FROM_SYSTEM;

// Message Source
public const int FORMAT_MESSAGE_FROM_HMODULE = 0x0800;

static void Main()
{
// Handle to input buffer
IntPtr handle = GetStdHandle(STD_INPUT_HANDLE);

const int maxCount = 256;

uint noCharacters;
StringBuilder builder = new StringBuilder(maxCount);

if (ReadConsole(handle, builder, (uint)maxCount,
out noCharacters, 0) == false) // false = non-zero = failed
{
string errMsg;
FormatMessage(FORMAT_MESSAGE_FLAGS,
FORMAT_MESSAGE_FROM_HMODULE,
GetLastError(),

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
31
0, // Means NULL
out errMsg,
0, // Maximum length
0); // Means NULL

Console.WriteLine("ERROR:\n{0}", errMsg);
}
else // true = zero = succeeded
// Writing user input withour the newline
Console.WriteLine("User wroted: = " +
builder.ToString().Substring(0,
builder.Length - Environment.NewLine.Length));

Console.WriteLine(new string('-', 25));

builder = new StringBuilder(maxCount);

// Invalid handle
handle = GetStdHandle(12345);

if (ReadConsole(handle, builder, ( uint)maxCount,
out noCharacters, 0) == false) // false = non-zero = failed
{
string errMsg;
FormatMessage(FORMAT_MESSAGE_FLAGS,
FORMAT_MESSAGE_FROM_HMODULE,
GetLastError(),
0, // Means NULL
out errMsg,
0, // Maximum length
0); // Means NULL

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
32
Console.WriteLine("ERROR: {0}", errMsg);
}
else // true = zero = succeeded
// Exculding the newline characters
Console.WriteLine("User wroted: = " +
builder.ToString().Substring(0,
builder.Length - Environment.NewLine.Length));
The last code demonstrates other useful techniques:
 Until now, handles should be marshaled as System.IntPtr. The following
section talks in details about handles.
 Because LPVOID and LPCVOID are both defined as a pointer to a variant
(i.e. any type,) you can set them to any type you want. They are very
similar to System.Object in the .NET methodology or Variant for people
who are familiar with the traditional Visual Basic. In our example, we
have marshaled LPVOID as System.UInt32 and set it to zero. Again, you
are free to play with the marshaling types. LPVOID and LPCVOID are both
32-bit integer. Why not just marshaling them as any of the 32-bit
managed types and forgetting about them? In addition, you can marshal it
as System.IntPtr, and pass it System.IntPtr.Zero to indicate a NULL value.
Moreover, you can marshal it as System.Object, and set it to any value,
even null to indicate the NULL value. Variant has been discussed in details
previously in the section “Marshaling Blittable Data Types.”
 va_list* is a pointer to an array of specific arguments. You can marshal it
as an array, or System.IntPtr. System.IntPtr is preferred if you intend to
pass it a NULL value.
 If the function requires a parameter passed by value or by reference you
can add the required modifiers like ref and out to the parameter, and
decorate the parameter with either InAttribute or OutAttribute, or both.
The section “Passing an Argument by Value or by Reference” later in this
chapter discusses by-value and by-reference parameters.
 While DWORD is defined as unsigned 32-bit integer and it should be
marshaled as System.UInt32, we find that the GetStdHandle() can take
one of three values: -10 for the input device, -11 for the output device, and
-12 for the error device (usually is the output device.) Although
System.UInt32 does not support negative values, Windows handles this
for you. It converts the signed value to its equivalent unsigned value.
Therefore, you should not worry about the value passed. However, keep
in mind that the unsigned values are too different (from the perspective of
most developers.) For example, the unsigned value of -11 is 0xFFFFFFF5!

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
33
Does this seem strange for you? Start by consulting the documentation
about binary notation.

MARSHALING HANDLES
GENERIC HANDLES
What is a handle? A handle is a pointer to some resource loaded in memory, such
as handles to the console standard input, output, and error devices, the handle
for the window, and the handle to a device context (DC.)
There are plenty of type handles in unmanaged code, here is some of them:
 HANDLE:
This is the most widely used handle type in the unmanaged environment.
It represents a generic handle.
 HWND:
Most widely used with Windows application. It is a handle to a window or
a control.
 HDC, HGDIOBJ, HBITMAP, HICON, HBRUSH, HPE N, and HFONT:
If you have worked with GDI, you will be familiar with these handles. HDC
is a handle to a device context (DC) object that will be used for drawing.
HGDIOBJ is a handle for any GDI object. HBITMAP is a handle to a bitmap,
while HICON is a handle to an icon. HBRUSH is a handle to a brush, HPEN
is a handle to pen, and HFONT is a handle to a font.
 HFILE:
A handle to a file opened by any of Windows File IO functions like
OpenFile() function.
 HMENU:
A handle to a menu or menu item.
Again, from all you have seen, you may have noticed that most types
identified by a prefix or a suffix. For example, handles prefixed with the
letter H, while some pointers have the suffix _PTR, or the prefix P or LP.
While strings with letter W are Unicode-encoded, and strings with letter T
are OS-based.
Handles can be marshaled as the managed type System.IntPtr that represents a
pointer to an object into memory. It is worth mentioning that because
System.IntPtr represents a pointer to an object no matter what the object is, you
can use System.IntPtr for marshaling any type not handles only, but that is not
recommended because it is more difficult to work with, and it is not very flexible,

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
34
but it provides more control over the object in memory. For more information
about memory management, see chapter 6: “Memory Management.”
In addition, starting from version 2.0, new managed types for working with
unmanaged handles added to the .NET Framework. A new namespace
Microsoft.Win32.SafeHandles that contains most of the new types has been
added too. Other types exist in System.Runtime.InteropServices. These types
called managed handles.
Managed handles allow you to pass, to unmanaged code, a handle to an
unmanaged resource (such as DC) wrapped by managed class.
There are two kinds of managed handles safe and critical handles.
SAFE HANDLES
Safe handles represented by the abstract
System.Runtime.InteropServices.SafeHandle. Safe handles provide protection
from recycling security attacks by perform reference counting (and that makes
safe handles slower.) In addition, it provides critical finalization for handle
resources. As a refresher, finalization means releasing the object and its
resources from the memory, and critical finalization ensures object finalization
under any circumstances. Figure 2.2 shows the definition of SafeHandle and its
descendants.

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
35
Figure 2.2 SafeFileHandle and Descendants Class Definitions
As the diagram illustrates, SafeHandle is the base class that represents any safe
handle. It inherits from
System.Runtime.ConstrainedExecution.CriticalFinalizerObject that ensures the
finalization process. The following are the most common members of
SafeHandle:
 IsClosed:
Returns a value indicates whether the handle is closed.
 IsInvalid:
Abstract. If overridden, returns a value indicates whether the handle is
invalid or not.
 Close() and Dispose():
Both close the handle and dispose its resources. Internally, they rely on
the abstract method ReleaseHandle() for releasing the handle. Therefore,

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
36
classes inherit from SafeHandle must implement this member. Be aware
that Dispose() is inherited from System.IDispose interface that is
implemented by SafeHandle, and Close() does not do anything except
calling the Dispose() method. Therefore, you strictly should dispose
(close) the handle as soon as you finish your work with it.
 ReleaseHandle():
Protected Abstract. Use to provide handle clean-up code. This function
should returns true if successfully released, or false otherwise. In the case
of false, it generates a ReleaseHandleFailed Managed Debugging Assistant
(MDA) exception that will not interrupt your code but provides you with a
bad sign about it. Keep in mind that ReleaseHandle() called internally by
Dispose().
 SetHandle():
Protected. Sets the handle to the specified pre-existing handle.
 SetHandleAsInvalid():
Sets the handle as invalid so it is no longer used.
 DangerousGetHandle():
Returns System.IntPtr that represents the handle. Beware that if you have
called SetHandleAsInvalid() before calling DangerousGetHandle(), it
returns the original handle not the invalid one.
 DangerousRelease():
Manually releasing the handle in unsafe manner. It is recommended using
Close() or Dispose() methods instead.
 DangerousAddRef():
Increments the reference count of the handle. It is not recommended
using neither DangerousRelease() nor DangerousAddRef(), use safe
methods instead. However, when working with COM, you will find
yourself using these functions
Do not use unsafe methods unless you really need to use it because they pass
the protection level offered by safe handles.
Because SafeHandle is abstract, you must either implement it or use one of its
implementation classes. Only two classes from the new namespace
Microsoft.Win32.SafeHandles implement SafeHandle, both are abstract too:
 SafeHandleMinusOneIsInvalid:
Represents a safe handle of which a value of -1 indicates that the handle is
invalid. Therefore, IsInvalid returns true only if the handle equals to -1.
 SafeHandleZeroOrMinusOneIsInvalid:
Represents a safe handle of which a value of 0 or -1 indicates that the
handle is invalid. So, IsInvalid returns true only if the handle equals to 0
or -1.

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
37
Notice that, choosing between the two implementations is up to the type of the
underlying handle. If it considered invalid if set to -1, use
SafeHandleMinusOneIsInvalid. If it considered invalid if set to 0 or -1, use
SafeHandleZeroOrMinusOneIsInvalid. Using the right class for the handle
ensures that methods like IsInvalid() returns correct results. It also ensures that
CLR will mark the handle as garbage only if it is invalid.
If you need to provide a safe handle for your object, you will need to inherit from
SafeHandleMinusOneIsInvalid, SafeHandleZeroOrMinusOneIsInvalid, or even
from SafeHandle. Be aware that, you will always need to override the
ReleaseHandle() method because neither SafeHandleMinusOneIsInvalid nor
SafeHandleZeroOrMinusOneIsInvalid does override it.
As the diagram illustrates, two concrete classes inherit from
SafeHandleZeroOrMinusOneIsInvalid:
 SafeFileHandle:
A wrapper class for an IO device handle (e.g. HFILE.) This class internally
overrides the ReleaseHandle() and calls the unmanaged CloseHandle()
function to close the handle. Use when working with HFILE handles in
Windows File IO functions like OpenFile() and CreateFile(). Internally,
System.FileStream uses a HFILE as SafeFileHandle, and it exposes a
constructor that accepts SafeFileHandle.
 SafeWaitHandle:
If you are working with unmanaged thread synchronization objects like a
Mutex or an Event, then this should be the desired marshaling type for
synchronization objects' handles.
Now, we are going to create a file using CreateFile() function with SafeFileHandle
for the marshaling process. The definition of CreateFile() is as following:
Listing 2.7 CreateFile() Unmanaged Signature
HANDLE CreateFile(
LPCTSTR lpFileName,
DWORD dwDesiredAccess,
DWORD dwShareMode,
LPSECURITY_ATTRIBUTES lpSecurityAttributes,
DWORD dwCreationDisposition,
DWORD dwFlagsAndAttributes,
HANDLE hTemplateFile
);

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
38
In addition, here is the .NET code:
Listing 2.8 Create File Example
[DllImport("Kernel32.dll", CharSet = CharSet.Auto, SetLastError = true)]
static extern SafeFileHandle CreateFile(
string lpFileName,
uint dwDesiredAccess,
uint dwShareMode,
// Because we are going to set the argument
// to NULL we marshaled it as IntPtr
// so we can set it to IntPtr.Zero
// to represent a NULL value
IntPtr lpSecurityAttributes,
uint dwCreationDisposition,
uint dwFlagsAndAttributes,
// A handle for a template file
// we are going to set it to NULL
// so e can marshal it as System.IntPtr
// and pass IntPtr.Zero for the NULL value
// But, this is another way
SafeFileHandle hTemplateFile);

// Accessing the file for writing
const uint GENERIC_WRITE = 0x40000000;
// Do now allow file sharing
const uint FILE_SHARE_NONE = 0x0;
// Create the file and overwrites it if exists
const uint CREATE_ALWAYS = 0x2;
// Normal file, no attribute set
const uint FILE_ATTRIBUTE_NORMAL = 0x80;

static void Main()
{
SafeFileHandle handle =
CreateFile("C:\\MyFile.txt",

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
39
GENERIC_WRITE,
FILE_SHARE_NONE,
IntPtr.Zero, // NULL
CREATE_ALWAYS,
FILE_ATTRIBUTE_NORMAL,
new SafeFileHandle(IntPtr.Zero, true));

// Because SafeFileHandle inherits
// SafeHandleZeroOrMinusOneIsInvalid
// IsInvalid returns true onl y if
// the handle equals to 0 or -1
if (handle.IsInvalid) // 0 or -1
{
Console.WriteLine("ERROR: {0}", Marshal.GetLastWin32Error());
return;
// Marshal.GetLastWin32Error() returns the last error only
// if DllImportAttribute.SetLastError is set to true
}

FileStream stream = new FileStream(handle, FileAccess.Write);
StreamWriter writer = new StreamWriter(stream);
writer.WriteLine("Hello, World!");
writer.Close();

/*
* Order of methods called by
* StreamWriter by this example:
*
* StreamWriter.Close()
* - StreamWriter.BaseStream.Close()
* - - FileStream.SafeFileHandle.Close()
* - - - SafeHandleZeroOrMinusOneIsInvalid
* .Close()

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
40
* - - - - SafeHandle.Close()
* - - - - - SafeHandle.ReleaseHandle()
*/
}
Although, you can use IntPtr instead of SafeFileHandle, the FileStream
constructor that accepts the IntPtr is considered obsolete (.NET 2.0 and
higher) and you should use the constructor that accepts the SafeFileHandle.
The next example demonstrates how to create your custom safe handle. This
custom safe handle represents a handle invalid only if equals to zero. Although,
you can extend the functionality of either SafeHandleMinusOneIsInvalid or
SafeHandleZeroOrMinusOneIsInvalid, we have inherited SafeHandle directly.
Code is very simple:
Listing 2.9 Custom Safe Handle Example
public sealed class SafeHandleZeroIsInvalid : SafeHandle
{
[DllImport("Kernel32.dll")]
[return: MarshalAs(UnmanagedType.Bool)]
private static extern bool CloseHandle(IntPtr hObject);

// If ownsHandle equals true handle will
// be automatically released during the
// finalization process, otherwise, you
// will have the responsibility to
// release it outside the class.
// Automatic releasing means calling
// the ReleaseHandle() method.
public SafeHandleZeroIsInvalid
(IntPtr preexistingHandle, bool ownsHandle)
: base(IntPtr.Zero, ownsHandle)
{
this.SetHandle(preexistingHandle);
}

public override bool IsInvalid
{

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
41
get
{
// this.handle.ToInt32() == 0
// this.handle == new IntPtr(0)
return this.handle == IntPtr.Zero;
}
}

protected override bool ReleaseHandle()
{
return CloseHandle(this.handle);
}
}
Until now, I do not have an answer for why a handle could be invalid only if
it is set to zero! Maybe you will need this for your custom handles. However,
this is just an illustration.
CRITICAL HANDLES
Critical handles are the same as safe handles, except that they do not perform
reference counting, so they do not provide protection from recycling security
attacks.
Use critical handles instead of safe handles to address performance
considerations, but you will be required to provide necessary synchronization
for reference counting yourself.
Critical handles represented by the abstract
System.Runtime.InteropServices.CriticalHandle. Figure 2.3 shows the definition
of CriticalHandle and its descendants.

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
42
Figure 2.3 CriticalHandle and descendants Class Definitions
As the diagram illustrates, CriticalHandle is the base class that represents any
critical handle. It inherits from
System.Runtime.ConstrainedExecution.CriticalFinalizerObject that ensures the
finalization process. The members of CriticalHandle are the same as SafeHandle,
except that it does not include the Dangerous-prefixed methods because critical
handles themselves are dangerous because they do not provide the necessary
protection. For more information about CriticalHandle members, refer to
members of SafeHandle discussed previously.
Because CriticalHandle is abstract, you must either implement it or use one of its
implementation classes. Only two classes from the new namespace
Microsoft.Win32.SafeHandles implement CriticalHandle, both are abstract too:
 CriticalHandleMinusOneIsInvalid:
Represents a critical handle of which a value of -1 indicates that the
handle is invalid. Therefore, IsInvalid returns true only if the handle
equals to -1.

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
43
 CriticalHandleZeroOrMinusOneIsInvalid:
Represents a critical handle of which a value of 0 or -1 indicates that the
handle is invalid. So, IsInvalid returns true only if the handle equals to 0
or -1.
Examples are the same as SafeHandle, only to change the type name.

PASSING MECHANISM
When passing an argument to a function, the function may require either passing
the argument by value or by reference. If the function intends to change
argument value, it requires it to be passed by reference, otherwise, by value. This
is what called passing mechanism.
Value arguments (i.e. input/In arguments,) when passed to a function, a copy of
the argument is sent to the function. Therefore, any changes to the argument do
not affect the original copy. On the other hand, reference arguments, when
passed to a function, the argument itself is passed to the function. Therefore, the
caller sees any changes happen inside the function.
Arguments passed by reference can be either In/Out (Input/Output) or only Out
(Output.) In/Out arguments are used for passing input to the function and
returning output. On the other hand, Out arguments used for returning output
only. Therefore, In/Out arguments must be initialized before they are passed to
the function. Conversely, Out arguments do not require pre-initialization.
When passing an argument by value, no changes to the PInvoke method are
required. Conversely, passing an argument by reference requires two additional
changes. The first is adding the ref modifier to the argument if it is In/Out
argument, or the out modifier if it is Out argument. The second is decorating your
argument with both InAttribute and OutAttribute attributes if it is In/Out
argument or only OutAttribute if it is Out argument. To be honest, applying those
attributes is not required, the modifiers are adequate in most cases. However,
applying them gives the CLR a notation about the passing mechanism.
As you have seen, when marshaling a string, you can marshal it as a
System.String or as a System.Text.StringBuilder. By default, StringBuilder is
passed by reference (you do not need to apply any changes.) System.String on
the other hand is passed by value.
It is worth mentioning that Windows API does not support reference arguments.
Instead, if a function requires an argument to be passed by reference, it declares
it as a pointer so that caller can see the applied changes. Other code such as COM
libraries can require either a pointer or a reference argument. In either cases,
you can safely apply the changes required. You can also marshal a pointer
argument as System.IntPtr or as the unsafe void* for example.

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
44
Many of the previous examples demonstrated only functions those require
arguments to be passed by value. Some functions require one or more arguments
to be passed by reference. A good example of a function requires In/Out
argument is GetVersionEx() which returns version information of the current
system. It requires a single reference (In/Out) argument. The argument is of the
structure OSVERSIONINFOEX. For our discussion, we will leave this function to
the next chapter in the discussion of compound types.
A great deal of functions require Out arguments specially for returning results or
status information. Good examples are ReadConsole() and WriteConsole() that
require by-reference Out arguments for returning the characters read/written.
The following is the unmanaged signature for the WriteConsole() function.
Listing 2.10 WriteConsole() Unmanaged Signature
BOOL WriteConsole(
HANDLE hConsoleOutput,
VOID lpBuffer,
DWORD nNumberOfCharsToWrite,
LPDWORD lpNumberOfCharsWritten,
LPVOID lpReserved
);
And this is the managed version along with the driver code:
Listing 2.11 Writing to Console Screen Example
[DllImport("Kernel32.dll", CharSet = CharSet.Unicode)]
[return: MarshalAs(UnmanagedType.Bool)]
static extern bool WriteConsole(
IntPtr hConsoleOutput,
String lpBuffer,
[param: MarshalAs(UnmanagedType.U4)]
UInt32 nNumberOfCharsToWrite,
[param: MarshalAs(UnmanagedType.U4)]
out UInt32 lpNumberOfCharsWritten,
[param: MarshalAs(UnmanagedType.AsAny)]
object lpReserved);

[DllImport("Kernel32.dll")]
static extern IntPtr GetStdHandle(
[param: MarshalAs(UnmanagedType.U4)]

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
45
Int32 nStdHandle);

const int STD_OUTPUT_HANDLE = -11;

static void Main()
{
IntPtr handle = GetStdHandle(STD_OUTPUT_HANDLE);

String textToWrite = "Hello, World!" + Environment.NewLine;
uint noCharactersWritten;

WriteConsole(handle,
textToWrite,
(uint)textToWrite.Length,
out noCharactersWritten,
null);

Console.WriteLine("No. Characters written = {0}" ,
noCharactersWritten);
}
Finally yet importantly, chapter 6 provides you with more granular and down-
level details about the memory management and the passing mechanism.

ADDITIONAL TECHNIQUE S
Here we will talk about techniques that should be taken into consideration when
working with unmanaged code, they are encapsulation, creating wrappers,
working with nullable arguments, and working out CLS problem.
ENCAPSULATION
If the function requires an argument that can be set to a value or more, you can
define these values (constants or typedefs) in an enumeration so you can easily
access every set of values separately; that technique called encapsulation

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
46
(grouping.) The following example shows the MessageBoxEx() example, the most
suitable function for the example:
Listing 2.12 Message Box Example
[DllImport("User32.dll", CharSet = CharSet.Unicode)]
[return: MarshalAs(UnmanagedType.I4)]
static extern UInt32 MessageBoxEx
(IntPtr hWnd,
[param: MarshalAs(UnmanagedType.LPTStr)]
String lpText,
[param: MarshalAs(UnmanagedType.LPTStr)]
String lpCaption,
[param: MarshalAs(UnmanagedType.U4)]
UInt32 uType,
[param: MarshalAs(UnmanagedType.U2)]
UInt16 wLanguageId);

public enum MB_BUTTON : uint
{
MB_OK = 0x0,
MB_OKCANCEL = 0x1,
MB_ABORTRETRYIGNORE = 0x2,
MB_YESNOCANCEL = 0x3,
MB_YESNO = 0x4,
MB_RETRYCANCEL = 0x5,
MB_HELP = 0x4000,
}
public enum MB_ICON : uint
{
MB_ICONHAND = 0x10,
MB_ICONQUESTION = 0x20,
MB_ICONEXCLAMATION = 0x30,
MB_ICONASTERISK = 0x40,
MB_ICONERROR = MB_ICONHAND,
MB_ICONSTOP = MB_ICONHAND,

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
47
MB_ICONWARNING = MB_ICONEXCLAMATION,
MB_ICONINFORMATION = MB_ICONASTERISK,
}
public enum MB_DEF_BUTTON : uint
{
MB_DEFBUTTON1 = 0x0,
MB_DEFBUTTON2 = 0x100,
MB_DEFBUTTON3 = 0x200,
MB_DEFBUTTON4 = 0x300,
}
public enum MB_MODAL : uint
{
MB_APPLMODAL = 0x0,
MB_SYSTEMMODAL = 0x10 00,
MB_TASKMODAL = 0x2000,
}
public enum MB_SPECIAL : uint
{
MB_SETFOREGROUND = 0x10000,
MB_DEFAULT_DESKTOP_ONLY = 0x20000,
MB_SERVICE_NOTIFICATION_NT3X = 0x40000,
MB_TOPMOST = 0x40000,
MB_RIGHT = 0x80000,
MB_RTLREADING = 0x100000,
MB_SERVICE_NOTIFICATION = 0x200000,
}
public enum MB_RETURN : uint
{
IDOK = 1,
IDCANCEL = 2,
IDABORT = 3,
IDRETRY = 4,
IDIGNORE = 5,

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
48
IDYES = 6,
IDNO = 7,
IDCLOSE = 8,
IDHELP = 9,
IDTRYAGAIN = 10,
IDCONTINUE = 11,
}

static void Main()
{
UInt32 result = MessageBoxEx( IntPtr.Zero, // NULL
"Do you want to save changes before closi ng?",
"MyApplication",
(UInt32)MB_BUTTON.MB_YESNOCANCEL |
(UInt32)MB_ICON.MB_ICONQUESTION |
(UInt32)MB_DEF_BUTTON.MB_DEFBUTTON3 |
(UInt32)MB_SPECIAL.MB_TOPMOST,
0);// Reserved

if (result == 0) // error occurred
Console.WriteLine("ERROR");
else
{
MB_RETURN ret = (MB_RETURN)result;

if (ret == MB_RETURN.IDYES)
Console.WriteLine("User clicked Yes!");
else if (ret == MB_RETURN.IDNO)
Console.WriteLine("User clicked No!");
else if (ret == MB_RETURN.IDCANCEL)
Console.WriteLine("User clicked Cancel!" );
}
}

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
49
You could also change the names of the constants to friendly names.
Figure 2.4 shows the message box resulted from running of the last code.

Figure 2.4 Message Box Example Result
In addition, you can marshal an argument as an enumeration which of the
argument type of course. The following example demonstrates this:
Listing 2.13 Console Standard Devices Example
[DllImport("Kernel32.dll")]
static extern IntPtr GetStdHandle(
[param: MarshalAs(UnmanagedType.U4)]
CONSOLE_STD_HANDLE nStdHandle);

public enum CONSOLE_STD_HANDLE
{
STD_INPUT_HANDLE = -10,
STD_OUTPUT_HANDLE = -11,
STD_ERROR_HANDLE = -12
}

static void Main()
{
IntPtr handle;
handle =
GetStdHandle(CONSOLE_STD_HANDLE.STD_INPUT_HANDLE);
if (handle == IntPtr.Zero)
Console.WriteLine("Failed!");
else
Console.WriteLine("Succeeded!");
}

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
50
CREATING WRAPPERS
Exposing PInvoke methods to the outside the assembly is not a good practice. It
is always recommended that you group your PInvoke methods into an internal
class, and that class should be named as NativeMethods, SafeNativeMethods or
UnsafeNativeMethods. For more information about this, check Code Analyzing
Rules in MSDN documentation. Read “Move PInvokes to Native Methods Class”
article.
The following code segment illustrates the wrapper method for our
MessageBoxEx() function:
Listing 2.14 Message Box Example Revised
public static MB_RETURN MessageBox
(IntPtr handle, string text, string title,
MB_BUTTON buttons, MB_ICON icon, MB_DEF_BUTTON defaultButton,
MB_MODAL modality, MB_SPECIAL options)
{
UInt32 result = MessageBoxEx(handle,
"Do you want to save changes before closing?" ,
"MyApplication",
(UInt32)buttons |
(UInt32)icon |
(UInt32)defaultButton |
(UInt32)modality |
(UInt32)options,
0);

if (result == 0)
// Not recommended throwing System.Exception
// throw a derived exception instead
throw new Exception("FAILED");
return (MB_RETURN)result;
}
In addition, it is recommended changing the type of enumerations to any CLS-
compliant type like System.Int32. Check the last technique in this section.

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
51
WORKING WITH NULLABL E ARGUMENTS
Some function arguments are nullable. Means that they can take a NULL (null in
C#) value. To pass a NULL value to an argument, you can marshal this argument
as System.IntPtr, so you can set it to System.IntPtr.Zero to represent a NULL
value. Another trick here is creating an overload for the function, in which the
first is marshaled as the argument type, and the other is marshaled as
System.IntPtr. Thus, if you pass a System.IntPtr.Zero, CLR directs the call to the
function with System.IntPtr. Conversely, passing a value to the argument, directs
the call to the function with the correct type. The following code segment
demonstrates this technique:
Code abbreviated for clarity.
Listing 2.15 ScrollConsoleScreenBuffer() Managed Signature
[DllImport("Kernel32.dll", CharSet = CharSet.Auto)]
[return: MarshalAs(UnmanagedType.Bool)]
static extern bool ScrollConsoleScreenBuffer(
IntPtr hConsoleOutput,
SMALL_RECT lpScrollRectangle,
SMALL_RECT lpClipRectangle,
COORD dwDestinationOrigin,
CHAR_INFO lpFill);

[DllImport("Kernel32.dll", CharSet = CharSet.Auto)]
[return: MarshalAs(UnmanagedType.Bool)]
static extern bool ScrollConsoleScreenBuffer(
IntPtr hConsoleOutput,
SMALL_RECT lpScrollRectangle,
IntPtr lpClipRectangle,
COORD dwDestinationOrigin,
CHAR_INFO lpFill);
...
WORKING OUT THE CLS PROBLEM
You should know that some types are non-CLS-compliant and you should avoid
exposing them outside the assembly. For example, the famous System.UInt32 is
non-CLS-compliant, and you strictly should not expose it.

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
52
Being non-CLS-compliant means that the type violates with CLS (Common
Language Specifications) specifications. Following CLS specifications helps the
interoperation of .NET languages. It helps avoiding some actions like declaring
specific types or following uncommon naming conventions.
Why to avoid such these acts? This helps the big goal of .NET Framework, the
interoperation of .NET languages. Some languages for example does not support
variable names beginning with an underscore (_) others do. Therefore, following
the CLS specifications allows your assembly to be callable from any other
assembly build with any language easily.
To force the check of CLS specification, you can decorate the assembly with
System.CLSCompliantAttribute attribute -specifying true,- and that would result
in compiler warnings whenever you try to expose non-CLS-compliant type out.
To work out this CLS dilemma, for functions require UInt32 as an argument, you
can create a wrapper that behaves as an entry-point to the private non-CLS-
compliant method. That wrapper method accepts, for instance, System.Int32 and
converts it internally to System.UInt32.
For structures, you can declare the structure as internal and continue using it the
normal way.
Again, you could replace all non-CLS-compliant types like System.UInt32 with
CLS-compliant equivalents like System.Int32 and take advantage of easily
distributing your types and assembly. However, that would not be easy in all
cases.
It is very helpful consulting the documentation about
System.CLSCompliantAttribute attribute.

REAL-WORLD EXAMPLES
In this chapter, we have covered many aspects of marshaling in many examples.
However, most of all were just for illustration.
The following are some real-world examples that solve problems that you might
face while developing your application. Those problems can be solved only via
interoperability with unmanaged code.
PROGRAMMA TICALLY SWAPPING MOU SE BUTTONS
The following code swaps mouse buttons programmatically. It makes the left
button acts like the right button (e.g. opens the context menu) and vice versa.

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
53
Listing 2.16 Swapping Mouse Buttons Sample
[DllImport("user32.dll")]
[return: MarshalAs(UnmanagedType.Bool)]
public static extern bool SwapMouseButton
([param: MarshalAs(UnmanagedType.Bool)] bool fSwap);

public void MakeRightButtonPrimary()
{
SwapMouseButton(true);
}

public void MakeLeftButtonPrimary()
{
SwapMouseButton(false);
}
PROGRAMMATICALLY TUR NING ON THE SCREEN SAVER
The following code shows how to turn on the screen saver programmatically.
Listing 2.19 Dragging a Form without a Title Bar Sample
[DllImport("User32.dll")]
public static extern int SendMessage
(IntPtr hWnd,
uint Msg,
uint wParam,
uint lParam);

public const uint WM_SYSCOMMAND = 0x112;
public const uint SC_SCREENSAVE = 0xF140;

public enum SpecialHandles
{
HWND_DESKTOP = 0x0,
HWND_BROADCAST = 0xFFFF

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
54
}

public static void TurnOnScreenSaver()
{
SendMessage(
new IntPtr((int)SpecialHandles.HWND_BROADCAST),
WM_SYSCOMMAND,
SC_SCREENSAVE,
0);
}
DRAGGING A FORM WITH OUT A TITLE BAR
The following code allows the form to be dragged from its body. This code is a
good example for the wrapper creating technique discussed earlier.
Listing 2.18 Dragging a Form without a Title Bar Sample
SafeNativeMethods.cs

internal static class SafeNativeMethods
{
[DllImport("user32.dll")]
[return: MarshalAs(UnmanagedType.I4)]
public static extern int SendMessage(
IntPtr hWnd,
[param: MarshalAs(UnmanagedType.U4)]
uint Msg,
[param: MarshalAs(UnmanagedType.U4)]
uint wParam,
[param: MarshalAs(UnmanagedType.I 4)]
int lParam);

[DllImport("user32.dll")]
[return: MarshalAs(UnmanagedType.Bool)]
public static extern bool ReleaseCapture();

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
55
public const uint WM_NCLBUTTONDOWN = 0xA1; // 161
public const uint HTCAPTION = 2;
}

HelperMethods.cs

internal static class HelperMethods
{
public static void MoveObject(IntPtr hWnd)
{
SafeNativeMethods.ReleaseCapture();
SafeNativeMethods.SendMessage
(hWnd, SafeNativeMethods.WM_NCLBUTTONDOWN,
SafeNativeMethods.HTCAPTION, 0);
}
}

MainForm.cs

// In the form, write the following code
// in the handler of the MouseDown event

private void MainForm_MouseDown(object sender, MouseEventArgs e)
{
HelperMethods.MoveObject( this.Handle);
}

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
56
SUMMARY
The last word to say is that MarshalAsAttribute is not required all the time.
Sometimes it is optional, and other times it is required.
For example, if you marshal blittable data types like DWORD, you can safely
ignore MarshalAsAttribute. Conversely, if you are marshaling non-blittable data
types like booleans and strings, you will need to use the MarshalAsAttribute to
ensure correct marshaling process. However, it is always better giving the CLR
and other developers a notation about the underlying data type by apply the
MarshalAsAttribute attribute to blittable data types too.
Finally yet importantly, this chapter was the key for the gate to the
interoperation with unmanaged environments. It discussed the most important
part of the marshaling process, marshaling the simple types, which you will
always need to keep it into your mind.
Next, you will learn how to work with compound types and marshal them in your
managed environment.

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
57

This page intentionally left blank.

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
58
CHAPTER 3
MARSHALING COMPOUND TYPES

CHAPTER CONTENTS
Contents of this chapter:
 Chapter Contents
 Overview
 Introduction
 Marshaling Unmanaged Structures
o How to Marshal a Structure
o Handling Memory Layout Problem
o Try It Out!
 Marshaling Unions
o A Short Speech About Unions
o How to Marshal a Union
o Unions with Arrays
o Try It Out!
 Value-Types and Reference-Types
 Passing Mechanism
 Real-World Examples
o The DEVMODE Structure
o Working with Display Settings
 Summary

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
59
OVERVIEW
This chapter demonstrates how to marshal compound types. Compound types
are those build of other types, for example structures and classes.
Like the previous chapter. This chapter breaks unmanaged compound types into
two categories, structures and unions. We first discuss structures and then we
will dive into unions and how to marshal them.
You might ask, why you have divided compound types into just two categories,
structures and unions, I can create classes too? The answer is easy. For its
simplicity, this book will focus primarily on Windows API. Therefore, you will
find much of our talking about Win32 functions and structures. However, the
same rules apply to classes and other unmanaged types.

INTRODUCTION
A compound type encapsulates related data together; it provides an organized
and arranged container for transmitting a group of variables between the client
application and the unmanaged server. It consists (usually) of variables of simple
types and (optionally) other compound types. In addition, it could define other
compound types inside.
Compound types come in two kinds:
 Unmanaged Structures
 Unmanaged Unions
An example of a structure is OSVERSIONINFOEX structure that encapsulates
operating system version information together. For those who are somewhat
familiar with DirectX, they may find that DirectX API relies heavily on structures.
As you know, because there is no compatibility between .NET and unmanaged
code, data must undergo some conversion routines for transmitting from the
managed code to the unmanaged server and vice versa, and compound types are
no exception.
In the next section, we will focus of the first kind, structures.

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
60
MARSHALING UNMANAGED STRUCTURES
HOW TO MARSHAL A STR UCTURE
Unmanaged structures can be marshaled as managed structures or even classes.
Choosing between a managed structure and a class is up to you, there are no
rules to follow. However, when marshaling as managed classes, there are some
limitations with the passing mechanism as we will see later in this chapter.
When marshaling structures in the managed environment, you must take into
consideration that while you access a variable into your by its name, Windows
accesses it via its address (i.e. position) inside the memory, it does not care about
field name, but it cares about its location and size. Therefore, the memory layout
and size of the type are very crucial.
You can marshal an unmanaged structure in few steps:
1. Create the marshaling type either a managed structure or a class.
2. Add the type fields (variables) only. Again, layout and size of the type are
very crucial. Therefore, fields must be ordered as they are defined, so that
the Windows can access them correctly.
3. Decorate your type with StructLayoutAttribute attribute specifying the
memory layout kind.
HANDLING MEMORY LAYO UT PROBLEM
When marshaling an unmanaged structure, you must take care of how that type
is laid-out into memory.
Actually, application memory is divided into blocks (in a 4-bytes base,) and every
block has its own address. When you declare a variable or a type in your
program it is stored inside the memory and got its memory address.
Consequently, all data members inside a structure have their own addresses that
are relative to the address of the beginning of the structure.
Consider the following structures:
Listing 3.1 SMALL_RECT and COORD Unmanaged Signature
typedef struct SMALL_RECT {
SHORT Left;
SHORT Top;
SHORT Right;
SHORT Bottom;
};

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
61

typedef struct COORD {
SHORT X;
SHORT Y;
};
When we declare those structures in our code they are laid-out into memory and
got addresses like that:

Figure 3.1 How Memory is Laid-Out
Thus, you should keep in mind that the size and location of each of type members
is very crucial and you strictly should take care of how this type is laid-out into
the memory.
For now, you do not have to think about the last illustration. We will cover
memory management in details in chapter 6.
For handling the memory layout problem, you must apply the
StructLayoutAttribute attribute to your marshaling type specifying the layout
kind using the LayoutKind property.

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
62
This property can take one of three values:
 LayoutKind.Auto (Default):
Lets the CLR chooses how the type is laid-out into memory. Setting this
value prevents interoperation with this type, that means that you will not
be able to marshal the unmanaged structure with this type, and if you
tried, an exception will be thrown.
 LayoutKind.Sequential:
Variables of the type are laid-out sequentially. When setting this value
ensure that all variables are on the right order as they are defined in the
unmanaged structure.
 LayoutKind.Explicit:
Lets you control precisely each variable’s location inside the type. When
setting this value, you must apply the FieldOffsetAttribute attribute to
every variable in your type specifying the relative position in bytes of the
variable to the start of the type. Note that when setting this value, order of
variables becomes unimportant.
For the sake of simplicity, you should lay-out all of your types sequentially.
However, when working with unions, you are required to explicitly control every
variable’s location. Unions are covered in the next section.
We have said that you should add only the type members into the
marshaling type, however, this is not always true. In structures where there
is a member that you can set to determine the structure size (like the
OPENFILENAME structure,) you can add your own members to the end of
the structure. However, you should set the size member to the size of the
entire structure minus the new members that you have added. This
technique is discussed in details in chapter 6.
TRY IT OUT!
The following example demonstrates how to marshal the famous structures
SMALL_RECT and COORD. Both used earlier with the
ScrollConsoleScreenBuffer() function in the last chapter. You can check code
listing 3.1 earlier in this chapter for the definition of the structures.
Next is the managed signature for both the structures. Note that you can marshal
them as managed classes too.
Listing 3.2 SMALL_RECT and COORD Managed Signature
// Laying-out the structure sequentially
[StructLayout(LayoutKind.Sequential)]
//public class SMALL_RECT
public struct SMALL_RECT

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
63
{
// Because we are laying the structure sequentially,
// we preserve field order as they are defined.

public UInt16 Left;
public UInt16 Top;
public UInt16 Right;
public UInt16 Bottom;
}

// The same as SMALL_RECT applies to COORD
[StructLayout(LayoutKind.Sequential)]
//public struct COORD
public struct COORD
{
public UInt16 X;
public UInt16 Y;
}

MARSHALING UNIONS
A SHORT SPEECH ABOUT UNIONS
A union is a memory location that is shared by two or more different types of
variables. A union provides a way for interpreting the same bit pattern in two or
more different ways (or forms.)
In fact, unions share structures lots of characteristics, like the way they defined
and marshaled. It might be helpful to know that, like structures, unions can be
defined inside a structure or even as a single entity. In addition, unions can
define compound types inside, like structures too.
To understand unions, we will take a simple example. Consider the following
union:

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
64
Listing 3.3 SOME_CHARACTER Unmanaged Signature
typedef union SOME_CHARACTER {
int i;
char c;
};
This was a simple union defines a character. It declared two members, i and c, it
defined them in the same memory location. Thus, it provides two ways for
accessing the character, by its code (int) and by its value (char). For this to work
it allocates enough memory storage for holding the largest member of the union
and that member is called container. Other members will overlap with the
container. In our case, the container is i because it is 4 bytes (on Win32, 16 on
Win16), while c is only 1 byte. Figure 3.2 shows how the memory is allocated for
the union.

Figure 3.2 SOME_CHARACTER Union
Because the two members are sharing the same memory location, when you
change one member the other is changed too. Consider the following C example:
Listing 3.4 Unions Example 1
int main()
{
union CHARACTER ch;

ch.i = 65; // 65 for A
printf("c = %c", ch.c); // prints 'A'
printf("\n");

ch.c += 32; // 97 for a
printf("i = %d", ch.i); // prints '97'
printf("\n");

return 0;
}

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
65
When you change any of the members of the union, other members change too
because they are all share the same memory address.
Now consider the same example but with values that won’t fit into the char
member:
Listing 3.5 Unions Example 2
int main()
{
union CHARACTER ch;

ch.i = 330;
printf("c = %c", ch.c); // prints 'J'
printf("\n"); // Ops!

ch.c += 32;
printf("i = %d", ch.i); // prints '362'
printf("\n");

return 0;
}
What happened? Because char is 1 bye wide, it interprets only the first 8 bits of
the union that are equal to 32.
The same rule applies if you add another member to the union. See the following
example. Notice that order of member declarations doesn’t matter.
Listing 3.6 Unions Example 3
int main()
{
union {
int i;
char c;
short n;
} ch;

ch.i = 2774186;

printf("i = %d", ch.i);

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
66
printf("\n");
printf("c = %i", (unsigned char)ch.c);
printf("\n");
printf("n = %d", ch.n);
printf("\n");

return 0;
}
Now, member i, the container, interprets the 32 bits. Member c, interprets the
first 8 bits (notice that we converted it to unsigned char to not to show the
negative value.) Member n, interprets the first high word (16 bits.)
You might ask: Why I need unions at all? I could easily use the cast operator to
convert between data types!
The answer is very easy. Unions come very efficient when casting between types
require much overhead. Consider the following example: You are about to write
an integer to a file. Unfortunately, there are no functions in the C standard library
that allow you to write an int to a file, and using fwrite() function requires
excessive overhead. The perfect solution is to define a union that contains an
integer and a character array to allow it to be interpreted as an integer and as a
character array when you need to pass it to fwrite() for example. See the
following code snippet:
Listing 3.7 Unions Example 4
typedef union myval{
int i;
char str[4];
};
In addition, unions offer you more performance than casts. Moreover, your code
will be more readable and efficient when you use unions.
More on how the unions are laid-out into memory in chapter 6.
HOW TO MARSHAL A UNI ON
You can marshal a union the same way as you marshal structures, except that
because of the way that unions laid-out into memory, you will need to explicitly
set variable positions inside the type.
Follow these steps to marshal a union:

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
67
1. Create your marshaling type, no matter whether your marshaling type is a
managed structure or class. Again, classes require special handling when
passed as function arguments. Passing mechanism is covered soon.
2. Decorate the type with the StructLayoutAttribute attribute specifying
LayoutKind.Explicit for the explicit layout kind.
3. Add the type fields. Do not add fields other than those defined in the
unmanaged signature. Because we are controlling the type layout
explicitly, order of fields is not important.
4. Decorate every field with the FieldOffsetAttribute attribute specifying the
absolute position in bytes of the member from the start of the type.
The following example demonstrates how to marshal our SOME_CHARACTER
union.
Listing 3.8 SOME_CHARACTER Managed Signature
// Unions require explicit memory layout
[StructLayout(LayoutKind.Explicit)]
//public class SOME_CHARACTER
public struct SOME_CHARACTER
{
// Both members located on the sam e
// position in the beginning of the union

// This is the continer it is 4 bytes
[FieldOffset(0)]
[MarshalAs(UnmanagedType.U4)]
public int i;
// This is only 1 byte. Therefore, it is contained
[FieldOffset(0)]
public char c;
}

public static void Main()
{
SOME_CHARACTER character = new SOME_CHARACTER();

// The code for letter 'A'

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
68
character.i = 65;
// Should prints 'A'
Console.WriteLine("c = {0}", character.c);

character.c = 'B';
// Should prints 66
Console.WriteLine("i = {0}", character.i);
}
From the last code, we learn that…
 Unions are marshaled like structures, they can be marshaled as either
managed structures or classes.
 Setting StructLayoutAttribute.LayoutKind to LayoutKind.Explicit allows
us to exactly control the memory location of our members.
 We use the FieldOffsetAttribute to specify the starting location in bytes of
the field into the type in memory.
 To create the union between the fields, we set both the fields to the same
memory location.
 In the example, member i occupies byte 0 through byte 4, and member c
occupies byte 0 through byte 1.
 If we do not need the benefits of unions, we can omit member c because it
is contained inside the range of member i. However, we cannot omit
member c because it is the container.
 When we change either one of the union variables, the other variable
changes too because they share the same memory address.
UNIONS WITH ARRAYS
Another example of a union is as following:
Listing 3.9 UNION_WITH_ARRAY Unmanaged Signature
typedef union UNION_WITH_ARRAY
{
INT number;
CHAR charArray[128];
};

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
69
This union must be marshaled in a special way because managed code does not
permit value types and reference types to overlap.
As a refresher, a value-type is the type stored in the memory stack; it inherits
from System.ValueType. All primitive data types, structures, and enumerations
are considered value-types. On the other hand, reference-types are those types
stored in the memory heap; they inherit from System.Object. Most types in .NET
are reference-types (except System.ValueType and its descendents of course.)
That is, all value-types inherit -directly or indirectly- from
System.ValueType.
As a result, we cannot union both members of our example, because whether
marshaling the second variable charArray as an array, a System.String, or as a
System.Text.StringBuilder, it is still a reference-type. Therefore, we have to leave
the benefits of unions and marshal only a single member. For our example, we
will create two marshaling types for our union, one with the first member
marshaled, and the other with the other member.
As we know, the layout and size of the type inside the memory is the most
crucial. Therefore, we must preserve the layout and size of our union. This union
has a 128 bytes array as a container and only one member contained, and this
member is only 2-bytes. Therefore, we have two choices, to marshal the union
with the container member, or to marshal it with the contained member but to
extend it enough to be as large as the container. In this example, we will take the
two approaches.
TRY IT OUT!
The following are two code segments. The first demonstrates how to marshal
only the second member which is the container, while the second demonstrates
how to marshal the first member.
Listing 3.10 UNION_WITH_ARRAY Union Managed Signature
// Setting StructLayoutAttribute.CharSet
// ensures the correct encoding for all
// string members of the union in our example
[StructLayout(LayoutKind.Sequential, CharSet = CharSet.Ansi)]
//public struct UNION_WITH_ARRAY_1
public struct UNION_WITH_ARRAY_1
{
// As we know, character arrays can be marshaled
// as either an array or as a string

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
70
// Setting MarshalAsAttribute is required
// for the array and the string

//[MarshalAs(UnmanagedType.ByValArray, SizeConst = 128)]
//public char[] charArray;

[MarshalAs(UnmanagedType.ByValTStr, SizeConst = 128)]
public string charArray;
}

// StructLayoutAttribute.Size determines
// the size -in bytes- of the type.
// If the size specified is larger than
// members’ size, the last member will be ext ended
// Because this is only a single
// member, we laid it out sequentially.
[StructLayout(LayoutKind.Sequential, Size = 128)]
//public class UNION_WITH_ARRAY_2
public struct UNION_WITH_ARRAY_2
{
[MarshalAs(UnmanagedType.I2)]
public short number;
}
For more information about marshaling arrays, refer to the next chapter.

VALUE-TYPES AND REFERENCE -TYPES
In the realm of .NET, types are broken into two categories:
 Value-Types:
These types are stored in the memory stack. They are destroyed when
their scope ends, therefore, they are short-lived. Types of this category
are all types inherit from System.ValueType (like all primitive data types,
structures, and enumerations.)

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
71
 Reference-Types:
These types are stored in the memory heap. They are controlled by the
Garbage Collector (GC,) therefore, they may retain in memory for a long
while. Reference-types are all types -directly or indirectly- inherit from
System.Object (except System.ValueType and descendants of course.) All
.NET classes fall in this category.
Stack and heap! Confused? Check chapter 6 for more details.
Talking about value-types and reference-types leads us to talk about the passing
mechanism. And that is what the next section is devoted for.

PASSING MECHANISM
In the last chapter, we have talked about the passing mechanism with simple
types and how it affects the call. Actually, all we have learnt is applied to the
compound types too.
As a refresher, when a type passed by value, a copy of type passed to the
function, not the value itself. Therefore, any changes to the type inside the
function do not affect the original copy. On the other hand, passing a type by
reference passes a pointer to the value to the function. In other words, the value
itself is passed. Therefore, any changes to the type inside the function are seen by
the caller.
Functions require the type passed to be passed either by value or by reference.
Plus, they require the argument to be passed by reference only if the argument
will be changed inside.
Moreover, an argument passed by reference can be passed either as
Input/Output (In/Out) or Output (Out). In/Out arguments used by the function
for receiving the input from the caller and posting the changes back to him.
Therefore, In/Out arguments must be initialized before handing them to the
function. On the other hand, output (Out) arguments are only used for returning
output to the caller. Therefore, they do not require pre-initialization because the
function will initialize them.
All of the information learnt from the last chapter is applied to this chapter too.
Compound types also can be passed by value or by reference. When passing by
value, no changes need to be applied. On the other hand passing a type by
reference requires some changes to the PInvoke method and the call itself.
If you are marshaling as a structure, you may add the ref modifier to the
parameter. However, classes are -by default- reference-types. Thus, they are
normally passed by reference and they cannot be passed by value. Therefore,
they do not need the ref modifier.

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
72
On the other hand, if you are passing the type as output (Out,) you will need to
add the out modifier whether it is a structure or a class.
As you know, you can decorate In/Out arguments with both InAttribute and
OutAttribute attributes. For Out arguments, specify OutAttribute attribute only.
Notice that there is a big difference between managed and unmanaged
classes. Unmanaged classes are -by default- value-types. Manager classes
are reference-types.
The following example demonstrates the PInvoke method for the function
GetVersionEx(). This function requires a single In/Out argument. That argument
is of the type OSVERSIONINFO.
The function uses OSVERSIONINFO’s dwOSVersionInfoSize field as input from
the caller for determining the type size, and it uses the remaining arguments as
output for sending the version information back. Therefore, the function requires
the argument to be passed by reference as In/Out.
Next is the definition of the function along with the structure:
Listing 3.11 GetVersionEx() Unmanaged Signature
BOOL GetVersionEx(
OSVERSIONINFO lpVersionInfo
);
typedef struct OSVERSIONINFO{
DWORD dwOSVersionInfoSize ;
DWORD dwMajorVersion;
DWORD dwMinorVersion;
DWORD dwBuildNumber;
DWORD dwPlatformId;
TCHAR szCSDVersion[128];
}
In addition, this is the managed version with the text code:
Listing 3.12 Retrieving System Version Information Sample
[DllImport("Kernel32.dll")]
[return: MarshalAs(UnmanagedType.Bool)]
static extern bool GetVersionEx
([param: In, Out]
// If a class remove the "ref" keyword
ref OSVERSIONINFO lpVersionInfo);

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
73

[StructLayout(LayoutKind.Sequential)]
//public class OSVERSIONINFO
public struct OSVERSIONINFO
{
[MarshalAs(UnmanagedType.U4)]
public UInt32 dwOSVersionInfoSize;
[MarshalAs(UnmanagedType.U4)]
public UInt32 dwMajorVersion;
[MarshalAs(UnmanagedType.U4)]
public UInt32 dwMinorVersion;
[MarshalAs(UnmanagedType.U4)]
public UInt32 dwBuildNumber;
[MarshalAs(UnmanagedType.U4)]
public UInt32 dwPlatformId;

// Can be marshaled as an array too
[MarshalAs(UnmanagedType.ByValTStr, SizeConst = 128)]
public string szCSDVersion;
}

static void Main()
{
OSVERSIONINFO info = new OSVERSIONINFO();
info.dwOSVersionInfoSize = ( uint)Marshal.SizeOf(info);

//GetVersionEx(info);
GetVersionEx(ref info);

Console.WriteLine("System Version: {0}.{1}",
info.dwMajorVersion, info.dwMinorVersion);
}

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
74
COMPOUND TYPES AND C HARACTER ENCODING
As you know, the size and layout of the marshaling type is the most important. If
the compound type contains a textual data, sure special handling should be taken
to ensure correct marshaling of the data.
You already know that the character encoding can be either ANSI or Unicode.
When a string is ANSI-encoded, every character reserves only a single byte of
application memory. On the other hand, every character in a Unicode-encoded
string reserves two bytes of the memory. Therefore, a string like “C-Sharp” with
7 characters reserves 7 bytes if ANSI-encoded and 14 bytes if Unicode-encoded.
You can determine the character encoding of the compound type by specifying
the CharSet property of the StructLayoutAttribute attribute. This property can
take one of several values:
 CharSet.Auto (CLR Default):
Strings encoding varies based on operating system; it is Unicode-encoded
on Windows NT and ANSI-encoded on other versions of Windows.
 CharSet.Ansi (C# Default):
Strings are always 8-bit ANSI-encoded.
 CharSet.Unicode:
Strings are always 16-bit Unicode-encoded.
 CharSet.None:
Obsolete. Has the same behavior as CharSet.Ansi.
Take into consideration that if you have not set the CharSet property, CLR
automatically sets it to CharSet.Auto. However, some languages override the
default behavior. For example, C# defaults to CharSet.Ansi.
In addition, you can determine the character encoding at a granular level by
specifying the CharSet property of the MarshalAsAttribute attribute applied to
the member.

REAL-WORLD EXAMPLE S
THE DEVMODE STRUCTUR E
Now, we are going to dig into real-world examples. In the first example, we are
going to marshal one of the most complex compound structures in the Windows
API, it is the DEVMODE structure.

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
75
If you have worked with GDI, you will be somewhat familiar with this structure.
It encapsulates information about initialization and environment of a printer or a
display device. It is required by many functions like EnumDisplaySettings(),
ChangeDisplaySettings() and OpenPrinter().
The complexity of this structure comes because of few factors. Firstly, there are
unions defined inside the structure. In addition, the definition of this structure
defers from a platform to another. As we will see, the structure defines some
members based on the operating system.
Here is the definition of DEVMODE structure along with the POINTL structure
that is referenced by DEVMODE.
Listing 3.13 DEVMODE and POINTL Unmanaged Signature
typedef struct DEVMODE {
BCHAR dmDeviceName[CCHDEVICENAME];
WORD dmSpecVersion;
WORD dmDriverVersion;
WORD dmSize;
WORD dmDriverExtra;
DWORD dmFields;
union {
struct {
short dmOrientation;
short dmPaperSize;
short dmPaperLength;
short dmPaperWidth;
short dmScale;
short dmCopies;
short dmDefaultSource;
short dmPrintQuality;
};
POINTL dmPosition;
DWORD dmDisplayOrientation;
DWORD dmDisplayFixedOutput;
};
short dmColor;
short dmDuplex;

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
76
short dmYResolution;
short dmTTOption;
short dmCollate;
BYTE dmFormName[CCHFORMNAME];
WORD dmLogPixels;
DWORD dmBitsPerPel;
DWORD dmPelsWidth;
DWORD dmPelsHeight;
union {
DWORD dmDisplayFlags;
DWORD dmNup;
}
DWORD dmDisplayFrequency;
#if(WINVER >= 0x0400)
DWORD dmICMMethod;
DWORD dmICMIntent;
DWORD dmMediaType;
DWORD dmDitherType;
DWORD dmReserved1;
DWORD dmReserved2;
#if (WINVER >= 0x0500) || (_WIN32_WINNT >= 0x0400)
DWORD dmPanningWidth;
DWORD dmPanningHeight;
#endif
#endif /* WINVER >= 0x0400 */
};
typedef struct POINTL {
LONG x;
LONG y;
};
You might have noticed that two unions are defined inside the structure. In
addition, a structure is defined inside the first union! Moreover, the last 8
members are not supported in Windows NT. Plus, the very last two members,

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
77
dmPanningWidth and dmPanningHeight, are not supported in Windows 9x
(95/98/ME.)
When working with Windows API, you should take care of operating system
compatibility. Some functions, for instance, are not supported on certain
operating systems (e.g. most Unicode versions are not supported on Win9x.)
Other functions take arguments that vary based on the OS (i.e.
EnumPrinters() function.) If your application tried to call a function, for
instance, that is not supported by the current operating system, the call
would fail.
If you need your application to be portable to every platform, you will need to
create three versions of the structure, one for Windows ME and its ascendants,
one for Windows NT, and the last for Windows 2000 and higher versions. In
addition, you will need to create three overloads of every function require
DEVMODE structure; three overloads for the three structures. For the sake of
simplicity, we will assume that you are working with Windows 2000 or a higher
version. Thus, we will marshal all members of the structure.
The following is the managed version of both DEVMODE and POINTL structures:
Listing 3.14 DEVMODE and POINTL Managed Signature
// Setting StructLayout.LayoutKind to LeyoutKind.Explicit to allow
// precisely choosing of member position. It is required for unions
// This structure is 156 -bytes
[StructLayout(LayoutKind.Explicit, CharSet = CharSet.Ansi)]
//public class DEVMODE
public struct DEVMODE
{
// You can define the following constant
// BUT OUTSIDE THE STRUCTURE
// because you know that size and layout of the structure
// is very important
// CCHDEVICENAME = 32 = 0x50
[FieldOffset(0)]
[MarshalAs(UnmanagedType.ByValArray, SizeConst = 32)]
public Char[] dmDeviceName;
// In addition you can define the last character array
// as following:
//MarshalAs(UnmanagedType.ByValTStr, SizeConst = 32 ])
//public string dmDeviceName;

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
78

// After the 32-bytes array
[FieldOffset(32)]
[MarshalAs(UnmanagedType.U2)]
public UInt16 dmSpecVersion;

[FieldOffset(34)]
[MarshalAs(UnmanagedType.U2)]
public UInt16 dmDriverVersion;

[FieldOffset(36)]
[MarshalAs(UnmanagedType.U2)]
public UInt16 dmSize;

[FieldOffset(38)]
[MarshalAs(UnmanagedType.U2)]
public UInt16 dmDriverExtra;

[FieldOffset(40)]
[MarshalAs(UnmanagedType.U4)]
public UInt32 dmFields;

// ************ Union Start ************
// Because DEVMODE_PRINT_SETTINGS is the hugest member and it is
// 16-bytes, it is the container for other members
// Remeber, you cannot emit the container
[FieldOffset(44)]
public DEVMODE_PRINT_SETTINGS dmSettings;

// Positioned within DEVMODE_PRINT_SETTINGS
// It is 8-bytes only
[FieldOffset(44)]
public POINTL dmPosition;

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
79

// Positioned within DEVMODE_PRINT_SETTINGS
[FieldOffset(44)]
[MarshalAs(UnmanagedType.U4)]
public UInt32 dmDisplayOrientation;

// Positioned within DEVMODE_PRINT_SETTINGS
[FieldOffset(44)]
[MarshalAs(UnmanagedType.U4)]
public UInt32 dmDisplayFixedOutput;
// ************* Union End *************

// Because DEVMODE_PRINT_SETTINGS structure
// is 16-bytes, dmColor is positioned on byte 60
[FieldOffset(60)]
[MarshalAs(UnmanagedType.I2)]
public Int16 dmColor;

[FieldOffset(62)]
[MarshalAs(UnmanagedType.I2)]
public Int16 dmDuplex;

[FieldOffset(64)]
[MarshalAs(UnmanagedType.I2)]
public Int16 dmYResolution;

[FieldOffset(66)]
[MarshalAs(UnmanagedType.I2)]
public Int16 dmTTOption;

[FieldOffset(70)]
[MarshalAs(UnmanagedType.I2)]
public Int16 dmCollate;

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
80

// CCHDEVICENAME = 32 = 0x50
[FieldOffset(72)]
[MarshalAs(UnmanagedType.ByValArray,
SizeConst = 32,
ArraySubType = UnmanagedType.U1)]
public Byte[] dmFormName;

// After the 32-bytes array
[FieldOffset(102)]
[MarshalAs(UnmanagedType.U2)]
public UInt16 dmLogPixels;

[FieldOffset(104)]
[MarshalAs(UnmanagedType.U4)]
public UInt32 dmBitsPerPel;

[FieldOffset(108)]
[MarshalAs(UnmanagedType.U4)]
public UInt32 dmPelsWidth;

[FieldOffset(112)]
[MarshalAs(UnmanagedType.U4)]
public UInt32 dmPelsHeight;

// ************ Union Start ************
// Because both members are 4 -bytes, the union is 4-bytes
// and its members are overlapped
// Again, you cannot emit the container
// Except if both are equal, you can emit anyone of them
[FieldOffset(116)]
[MarshalAs(UnmanagedType.U4)]
public UInt32 dmDisplayFlags;

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
81

[FieldOffset(116)]
[MarshalAs(UnmanagedType.U4)]
public UInt32 dmNup;
// ************* Union End *************

[FieldOffset(120)]
[MarshalAs(UnmanagedType.U4)]
public UInt32 dmDisplayFrequency;

[FieldOffset(124)]
[MarshalAs(UnmanagedType.U4)]
public UInt32 dmICMMethod;

[FieldOffset(128)]
[MarshalAs(UnmanagedType.U4)]
public UInt32 dmICMIntent;

[FieldOffset(132)]
[MarshalAs(UnmanagedType.U4)]
public UInt32 dmMediaType;

[FieldOffset(136)]
[MarshalAs(UnmanagedType.U4)]
public UInt32 dmDitherType;

[FieldOffset(140)]
[MarshalAs(UnmanagedType.U4)]
public UInt32 dmReserved1;

[FieldOffset(144)]
[MarshalAs(UnmanagedType.U4)]
public UInt32 dmReserved2;

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
82
[FieldOffset(148)]
[MarshalAs(UnmanagedType.U4)]
public UInt32 dmPanningWidth;

[FieldOffset(152)]
[MarshalAs(UnmanagedType.U4)]
public UInt32 dmPanningHeight;
}

// 16-bytes structure
[StructLayout(LayoutKind.Sequential)]
//public class DEVMODE_PRINT_SETTINGS
public struct DEVMODE_PRINT_SETTINGS
{
public short dmOrientation;
public short dmPaperSize;
public short dmPaperLength;
public short dmPaperWidth;
public short dmScale;
public short dmCopies;
public short dmDefaultSource;
public short dmPrintQuality;

}

// 8-bytes structure
[StructLayout(LayoutKind.Sequential)]
//public class POINTL
public struct POINTL
{
public Int32 x;
public Int32 y;
}

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
83
As we have said earlier in the previous chapter, this writing assumes 32-bit
versions of Windows. For instance, in the DEVMODE example, we have
assumed that DWORDs are 4 bytes. If you want to port your application to a
64-bit machine, DWORDs should be considered as 8 bytes.
Lengthy, isn't it? DEVMODE is one of the lengthy and compound GDI structures.
If you want to learn more about laying out structure into memory, refer to
chapter 6 “Memory Management.”
From the last code we learn that…
 Whether the union defined as a single entity or inside a structure, you will
need to lay-out the type explicitly into memory to allow defining two or
more variables at the same memory location.
 When setting the memory layout explicitly, we apply the
FieldOffsetAttribute attribute to the variable specifying the location -in
bytes- of the variable from the start of the type.
 In the union that defines a structure inside, we marshaled the structure
outside the union and referred it to be the container of other members.
Chapter 6 demonstrates other techniques for laying-out structures into
memory.
WORKING WITH DISPLAY SETTINGS
The follows example shows how you can access and modify display settings
programmatically using C# and Windows API. In this example we will create four
functions, one retrieves current display settings, another enumerates available
display modes, the third changes current display settings, and the last changes
screen orientation (i.e. rotates the screen.)
For our example, we will use the DEVMODE and POINTL structures that we have
marshaled previously. In addition, we will make use of two new Windows API
functions, EnumDisplaySettings and ChangeDisplaySettings. The following is the
unmanaged signature of both functions:
Listing 3.15 EnumDisplaySettings() and ChangeDisplaySettings() Unmanaged Signature
BOOL EnumDisplaySettings(
LPCTSTR lpszDeviceNa me, // display device
DWORD iModeNum, // graphics mode
[In, Out] LPDEVMODE lpDevMode // graphics mode settings
);

LONG ChangeDisplaySettings(
LPDEVMODE lpDevMode, // graphics mode

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
84
DWORD dwflags // graphics mode options
);
For more information about these functions, refer to the MSDN
documentation.
The next is the managed version of the functions:
Listing 3.16 EnumDisplaySettings() and ChangeDisplaySettings() Managed Signature
[DllImport("User32.dll")]
[return: MarshalAs(UnmanagedType.Bool)]
public static extern Boolean EnumDisplaySettings(
[param: MarshalAs(UnmanagedType.LPTStr)]
string lpszDeviceName,
[param: MarshalAs(UnmanagedType.U4)]
int iModeNum,
[In, Out]
ref DEVMODE lpDevMode);

[DllImport("User32.dll")]
[return: MarshalAs(UnmanagedType.I4)]
public static extern int ChangeDisplaySettings(
[In, Out]
ref DEVMODE lpDevMode,
[param: MarshalAs(UnmanagedType.U4)]
uint dwflags);
Finally, those are our four functions that utilize the native functions:
Listing 3.17 Accessing/Modifying Display Settings Sample
public static void GetCurrentSettings()
{
DEVMODE mode = new DEVMODE();
mode.dmSize = (ushort)Marshal.SizeOf(mode);

if (EnumDisplaySettings( null,
ENUM_CURRENT_SETTINGS, ref mode) == true) // Succeeded
{
Console.WriteLine("Current Mode:\n\t" +

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
85
"{0} by {1}, {2} bit, {3} degrees, {4} hertz" ,
mode.dmPelsWidth, mode.dmPelsHeight,
mode.dmBitsPerPel, mode.dmDisplayOrientation * 90,
mode.dmDisplayFrequency);
}
}

public static void EnumerateSupportedModes()
{
DEVMODE mode = new DEVMODE();
mode.dmSize = (ushort)Marshal.SizeOf(mode);

int modeIndex = 0; // 0 = The first mode

Console.WriteLine("Supported Modes:");

while (EnumDisplaySettings( null,
modeIndex, ref mode) == true) // Mode found
{
Console.WriteLine("\t{0} by {1}, {2} bit, " +
"{3} degrees, " +
"{4} hertz",
mode.dmPelsWidth, mode.dmPelsHeight,
mode.dmBitsPerPel, mode.dmDisplayOrientation * 90,
mode.dmDisplayFrequency);

modeIndex++; // The next mode
}
}

public static void ChangeDisplaySettings
(int width, int height, int bitCount)
{
DEVMODE originalMode = new DEVMODE();

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
86
originalMode.dmSize = ( ushort)Marshal.SizeOf(originalMode);

// Retrieving current settings to edit them
EnumDisplaySettings( null, ENUM_CURRENT_SETTINGS, ref originalMode);

// Making a copy of the current settings
// to allow reseting to the original mode
DEVMODE newMode = originalMode;

// Changing the settings
newMode.dmPelsWidth = ( uint)width;
newMode.dmPelsHeight = ( uint)height;
newMode.dmBitsPerPel = (uint)bitCount;

// Capturing the operation result
int result = ChangeDisplaySettings( ref newMode, 0);

if (result == DISP_CHANGE_SUCCESSFUL)
{
Console.WriteLine("Succeeded.\n");

// Inspecting the new mode
GetCurrentSettings();

Console.WriteLine();

// Waiting for seeing the results
Console.ReadKey(true);

ChangeDisplaySettings( ref originalMode, 0);
}
else if (result == DISP_CHANGE_BADMODE)
Console.WriteLine("Mode not supported." );

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
87
else if (result == DISP_CHANGE_RESTART)
Console.WriteLine("Restart required.");
else
Console.WriteLine("Failed. Error code = {0}" , result);
}

public static void RotateScreen(bool clockwise)
{
// Retrieving current settings
// ...

// Rotating the screen
if (clockwise)
if (newMode.dmDisplayOrientation < DMDO_270)
newMode.dmDisplayOrientation++;
else
newMode.dmDisplayOrientation = DMDO_DEFAULT;
else
if (newMode.dmDisplayOrientation > DMDO_DEFAULT)
newMode.dmDisplayOrientation --;
else
newMode.dmDisplayOrientation = DMDO_270;

// Swapping width and height;
uint temp = newMode.dmPelsWidth;
newMode.dmPelsWidth = newMode.dmPelsHeight;
newMode.dmPelsHeight = temp;

// Capturing the operation r esult
// ...
}
THE CONSOLE LIBRARY

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
88
There are functionalities of console applications that are not accessible from the
.NET Framework like clearing the console screen and moving a text around.
The following sample shows a tiny library for console applications. It contains
some of the common functionalities of the console (like writing and reading
data) along with new functionalities added.
Listing 3.18 The Console Library Sample
SafeNativeMethods.cs

using System;
using System.Runtime.InteropS ervices;
using System.Text;

/// <summary>
/// Safe native functions
/// </summary>
internal static class SafeNativeMethods
{
/// <summary>
/// Standard input device.
/// </summary>
public const int STD_INPUT_HANDLE = -10;
/// <summary>
/// Standard output device.
/// </summary>
public const int STD_OUTPUT_HANDLE = -11;
/// <summary>
/// Standard error device (usually the output device.)
/// </summary>
public const int STD_ERROR_HANDLE = -12;

/// <summary>
/// White space character for clearing the screen.
/// </summary>

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
89
public const char WHITE_SPACE = ' ';

/// <summary>
/// Retrieves a handle for the console standard input, output, or error
device.
/// </summary>
/// <param name="nStdHandle">The standard device of which to retrieve
handle for.</param>
/// <returns>The handle for the standard device selected. Or an invalid
handle if the function failed. </returns>
[DllImport("Kernel32.dll")]
public static extern IntPtr GetStdHandle([param:
MarshalAs(UnmanagedType.I4)] int nStdHandle);

/// <summary>
/// Writes a character string to the console buffer starting from the
current cursor position.
/// </summary>
/// <param name="hConsoleOutput"> A handle for the opened output
device.</param>
/// <param name="lpBuffer"> The string of which to write. </param>
/// <param name="nNumberOfCharsToWrite"> Number of characters to
write.</param>
/// <param name="lpNumberOfCharsWritten"> Outputs the number of
characters written.</param>
/// <param name="lpReserved"> Reserved.</param>
/// <returns>True if succeeded, otherwise False. </returns>
[DllImport("kernel32.dll", CharSet = CharSet.Unicode)]
[return: MarshalAs(UnmanagedType.Bool)]
public static extern bool WriteConsole
(IntPtr hConsoleOutput,
string lpBuffer,
[param: MarshalAs(UnmanagedType.U4)] uint nNumberOfCharsToWrite,
[param: MarshalAs(UnmanagedType.U4)] [Out] out uint
lpNumberOfCharsWritten,
[param: MarshalAs(UnmanagedType.U4)]
uint lpReserved);

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
90

/// <summary>
/// Read a character string from the console buffer starting from the
current cursor position.
/// </summary>
/// <param name="hConsoleInput"> A handle for the opened input
device.</param>
/// <param name="lpBuffer"> The string read from the buffer. </param>
/// <param name="nNumberOfCharsToRead"> The number of characters to
read.</param>
/// <param name="lpNumberOfCharsRead"> Outputs the number of characters
read.</param>
/// <param name="lpReserved"> Reserved.</param>
/// <returns>True if succeeded, otherwise False. </returns>
[DllImport("kernel32.dll", CharSet = CharSet.Unicode)]
[return: MarshalAs(UnmanagedType.Bool)]
public static extern bool ReadConsole(
IntPtr hConsoleInput,
StringBuilder lpBuffer,
[param: MarshalAs(UnmanagedType.U4)] uint nNumberOfCharsToRead,
[param: MarshalAs(UnmanagedType.U4)] [Out] out uint
lpNumberOfCharsRead,
[param: MarshalAs(UnmanagedType.U4)] uint lpReserved);

/// <summary>
/// Retrieves information about the console cursor such as the size and
visibility.
/// </summary>
/// <param name="hConsoleOutput"> A handle for the opened output
device.</param>
/// <param name="lpConsoleCursorInfo"> The cursor info.</param>
/// <returns>True if succeeded, otherwise False. </returns>
[DllImport("kernel32.dll")]
[return: MarshalAs(UnmanagedType.Bool)]
public static extern bool GetConsoleCursorInfo(
IntPtr hConsoleOutput,

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
91
[Out] out CONSOLE_CURSOR_INFO lpConsoleCursorInfo);

/// <summary>
/// Sets the console cursor properties as the size and visibility.
/// </summary>
/// <param name="hConsoleOutput"> A handle for the opened output
device.</param>
/// <param name="lpConsoleCursorInfo"> The cursor info.</param>
/// <returns>True if succeeded, otherwise False. </returns>
[DllImport("kernel32.dll")]
[return: MarshalAs(UnmanagedType.Bool)]
public static extern bool SetConsoleCursorInfo(
IntPtr hConsoleOutput,
ref CONSOLE_CURSOR_INFO lpConsoleCursorInfo);

/// <summary>
/// Moves a block of data in a screen buffer.
/// </summary>
/// <param name="hConsoleOutput"> A handle for the opened output
device.</param>
/// <param name="lpScrollRectangle"> The coordinates of the block to
move.</param>
/// <param name="lpClipRectangle"> The coordinates affected by the
scrolling.</param>
/// <param name="dwDestinationOrigin"> The coordinates represents the new
location of the block. </param>
/// <param name="lpFill"> Specifies the character and color info for the
cells left empty after the move. </param>
/// <returns>True if succeeded, otherwise False. </returns>
/// <remarks>
/// Because we are going to set the <paramref name="lpClipRectangle"/>
to NULL, we marshaled it as IntPtr so we can set it to null using
IntPtr.Zero.
/// If you do need to set its value, you can marshal it as SMALL_RECT.
/// </remarks>
[DllImport("kernel32.dll")]

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
92
[return: MarshalAs(UnmanagedType.Bool)]
public static extern bool ScrollConsoleScreenBuffer(
IntPtr hConsoleOutput,
ref SMALL_RECT lpScrollRectangle,
IntPtr lpClipRectangle,
COORD dwDestinationOrigin,
ref CHAR_INFO lpFill);

/// <summary>
/// Retrieves information about the specified console screen buffer.
/// </summary>
/// <param name="hConsoleOutput"> A handle for the device of which to get
its information.</param>
/// <param name="lpConsoleScreenBufferInfo"> Outputs the information of
the specified screen buffer. </param>
/// <returns>True if succeeded, otherwise False. </returns>
[DllImport("Kernel32.dll")]
[return: MarshalAs(UnmanagedType.Bool)]
public static extern bool GetConsoleScreenBufferInfo
(IntPtr hConsoleOutput,
[Out] out CONSOLE_SCREEN_BUFFER_INFO lpConsoleScreenBufferInfo);

/// <summary>
/// Fills the console buffer with a specific character.
/// </summary>
/// <param name="hConsoleOutput"> A handle for the opened output
device.</param>
/// <param name="cCharacter"> The character of which to fill the buffer
width. Setting this character to a white space means clearing the
cells.</param>
/// <param name="nLength">The number of cells to fill. </param>
/// <param name="dwWriteCoord"> The location of which to start
filling.</param>
/// <param name="lpNumberOfCharsWritten"> Outputs the number of
characters written.</param>
/// <returns>True if succeeded, otherwise False.</returns>

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
93
[DllImport("Kernel32.dll")]
[return: MarshalAs(UnmanagedType.Bool)]
public static extern bool FillConsoleOutputCharacter
(IntPtr hConsoleOutput,
char cCharacter,
[param: MarshalAs(UnmanagedT ype.U4)] uint nLength,
COORD dwWriteCoord,
[param: MarshalAs(UnmanagedType.U4)][Out] out uint
lpNumberOfCharsWritten);

/// <summary>
/// Sets the console cursor to a specific position.
/// </summary>
/// <param name="hConsoleOutput">A handle for the opened output
device.</param>
/// <param name="dwCursorPosition"> The new cursor position inside the
console buffer.</param>
/// <returns>True if succeeded, otherwise False. </returns>
[DllImport("Kernel32.dll")]
[return: MarshalAs(UnmanagedType.Bool)]
public static extern bool SetConsoleCursorPosition
(IntPtr hConsoleOutput, COORD dwCursorPosition);
}

/// <summary>
/// Information about the screen buffer.
/// </summary>
[StructLayout(LayoutKind.Sequenti al)]
public struct CONSOLE_SCREEN_BUFFER_INFO
{
/// <summary>
/// The size of the buffer.
/// </summary>
public COORD dwSize;
/// <summary>

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
94
/// The location of the cursor inside the buffer.
/// </summary>
public COORD dwCursorPosition;
/// <summary>
/// Additional attributes about the buffer write the fore color and back
color.
/// </summary>
[MarshalAs(UnmanagedType.U2)]
public ushort wAttributes;
/// <summary>
/// The location and bounds of the w indow.
/// </summary>
public SMALL_RECT srWindow;
/// <summary>
/// The maximum size of the window.
/// </summary>
public COORD dwMaximumWindowSize;
}

/// <summary>
/// Coordinates (X, Y).
/// </summary>
[StructLayout(LayoutKind.Se quential)]
public struct COORD
{
/// <summary>
/// The location from the left (X).
/// </summary>
[MarshalAs(UnmanagedType.I2)]
public short X;
/// <summary>
/// The location from the top (Y).
/// </summary>
[MarshalAs(UnmanagedType.I2)]

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
95
public short Y;
}

/// <summary>
/// Defines the coordinates of the upper left and right bottom coordinates
of a rectangle.
/// </summary>
[StructLayout(LayoutKind.Sequential)]
public struct SMALL_RECT
{
/// <summary>
/// The X-coordinate of the upper left corner of the rectangle.
/// </summary>
[MarshalAs(UnmanagedType.I2)]
public short Left;
/// <summary>
/// The Y-coordinate of the upper left corner of the rectangle.
/// </summary>
[MarshalAs(UnmanagedType.I2)]
public short Top;
/// <summary>
/// The X-coordinate of the lower right corner of the rectangle.
/// </summary>
[MarshalAs(UnmanagedType.I2)]
public short Right;
/// <summary>
/// The Y-coordinate of the lower right corner of the rectangle.
/// </summary>
[MarshalAs(UnmanagedType.I2)]
public short Bottom;
}

/// <summary>
/// Defines the console cursor info.

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
96
/// </summary>
[StructLayout(LayoutKind.Sequential)]
public struct CONSOLE_CURSOR_INFO
{
/// <summary>
/// The size of the cursor. Usually 0.25 of the cell.
/// </summary>
[MarshalAs(UnmanagedType.U4)]
public uint dwSize;
/// <summary>
/// If cursor is visible or not.
/// </summary>
[MarshalAs(UnmanagedType.Boo l)]
public bool bVisible;
}

/// <summary>
/// Defines a character information.
/// </summary>
[StructLayout(LayoutKind.Sequential)]
public struct CHAR_INFO
{
/// <summary>
/// The character.
/// </summary>
public char Char;
/// <summary>
/// Additional attributes of the character like fore color and back
color.
/// </summary>
[MarshalAs(UnmanagedType.U2)]
public ushort Attributes;
}

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
97

ConsoleLib.cs

using System;
using System.Runtime.InteropServices;
using System.Text;

// Console horizontal text alignment.
public enum ConsoleTextAlignment
{
/// <summary>
/// Text is left aligned.
/// </summary>
Left,
/// <summary>
/// Text is right aligned.
/// </summary>
Right,
/// <summary>
/// Text is centered.
/// </summary>
Center
}

/// <summary>
/// Console standard devices.
/// </summary>
public enum ConsoleStandardDevice
{

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
98
/// <summary>
/// The input device.
/// </summary>
Input = SafeNativeMethods.STD_INPUT_HANDLE,
/// <summary>
/// The output device.
/// </summary>
Output = SafeNativeMethods.STD_OUTPUT_HANDLE,
/// <summary>
/// The error device (usually the output device.)
/// </summary>
Error = SafeNativeMethods.STD_ERROR_HANDLE
}

/// <summary>
/// Extension methods for the console.
/// </summary>
public static class ConsoleExtensions
{
/// <summary>
/// Clears the screen buffer.
/// </summary>
public static void ClearScreen()
{
// Clearing the screen starting from the first cell
COORD location = new COORD();
location.X = 0;
location.Y = 0;

ClearScreen(location);
}
/// <summary>
/// Clears the screen buffer starting from a specific location.
/// </summary>

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
99
/// <param name="location"> The location of which to start clearing the
screen buffer.</param>
public static void ClearScreen(COORD location)
{
// Clearing the screen starting from the specified location
// Setting the character to a white space means clearing it
// Setting the count to 0 means clearing to the end, not a specific
length
FillConsoleBuffer(location, 0, SafeNativeMethods.WHITE_SPACE);
}

/// <summary>
/// Fills a specific cells with a specific character starting from a
specific location.
/// </summary>
/// <param name="location"> The location of which to start
filling.</param>
/// <param name="count"> The number of cells starting from the location
to fill.</param>
/// <param name="character"> The character to fill with. </param>
public static void FillConsoleBuffer(COORD location, uint count, char
character)
{
// Getting the console output device handle
IntPtr handle = GetStandardDevice( ConsoleStandardDevice.Output);

uint length;

// If count equals 0 then user require clearing all the screen
if (count == 0)
{
// Getting console screen buffer info
CONSOLE_SCREEN_BUFFER_INFO info =
GetBufferInfo(ConsoleStandardDevice .Output);
// All the screen
length = (uint)(info.dwSize.X * info.dwSize.Y);
}

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
100
else
length = count;

// The number of written characters
uint numChars;

// Calling the Win32 API function
SafeNativeMethods.FillConsoleOutputCharacter(handle, character,
length, location, out numChars);

// Setting the console cursor position
SetCursorPosition(location);
}
/// <summary>
/// Rettrieves a handle for a specific device.
/// </summary>
/// <param name="device"> The device of which to retrieve the handle
for.</param>
/// <returns>The handle for the specified device. </returns>
public static IntPtr GetStandardDevice( ConsoleStandardDevice device)
{
// Calling the Win32 API function
return SafeNativeMethods.GetStdHandle((int)device);
}
/// <summary>
/// Writes an empty line to the console buffer on the current position
of the cursor.
/// </summary>
public static void WriteLine()
{
WriteLine(string.Empty);
}
/// <summary>
/// Writes specific text followed by a line terminator to the console
buffer on the current position of the cursor.

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
101
/// </summary>
/// <param name="txt">The text to write.</param>
public static void WriteLine(string txt)
{
WriteLine(txt, ConsoleTextAlignment .Left);
}
/// <summary>
/// Writes specific text followed by a line terminator to the console
buffer on the current position of the cursor with the specified line
alignemnt.
/// </summary>
/// <param name="txt">The text to write.</param>
/// <param name="alignment"> The horizontal alignment of the
text.</param>
public static void WriteLine(string txt, ConsoleTextAlignment alignment)
{
Write(txt + Environment.NewLine, alignment);
}
/// <summary>
/// Writes specific text to the console buffer on the current position
of the cursor.
/// </summary>
/// <param name="txt">The text to write.</param>
public static void Write(string txt)
{
Write(txt, ConsoleTextAlignment .Left);
}
/// <summary>
/// Writes specific text to the console buffer on the current position
of the cursor with the specified lin e alignment.
/// </summary>
/// <param name="txt">The text to write.</param>
/// <param name="alignment"> The horizontal alignment of the
text.</param>
public static void Write(string txt, ConsoleTextAlignment alignment)
{

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
102
if (alignment == ConsoleTextAlignment .Left)
InternalWrite(txt);
else
{
// Determining the location of which to begin writing
CONSOLE_SCREEN_BUFFER_INFO info =
GetBufferInfo(ConsoleStandardDevice .Output);

COORD pos = new COORD();

if (alignment == ConsoleTextAlignment .Right)
pos.X = (short)(info.dwSize.X - txt.Length);
else // Center
pos.X = (short)((info.dwSize.X - txt.Length) / 2);

pos.Y = info.dwCursorPosition.Y;

// Changing the cursor position
SetCursorPosition(pos);

// Now writing on the current position
InternalWrite(txt);
}
}
/// <summary>
/// Writing a specific text to the console output buffer starting from
the current cursor position.
/// </summary>
/// <param name="txt">The text to write.</param>
private static void InternalWrite(string txt)
{
// Required for the WriteConsole() fun ction
// It is the number of characters written
uint count;

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
103
// Getting the output handle
IntPtr handle = GetStandardDevice( ConsoleStandardDevice .Output);
// Calling the Win32 API function
SafeNativeMethods.WriteConsole(handle, txt, ( uint)txt.Length, out
count, 0);
}

/// <summary>
/// Shows or hides the cursor.
/// </summary>
/// <param name="show">Specifies whether to show the cursor or
not.</param>
public static void ShowCursor(bool show)
{
CONSOLE_CURSOR_INFO info;
// Getting the output device
IntPtr handle = GetStandardDevice( ConsoleStandardDevice .Output);

// Getting the cursor info
SafeNativeMethods.GetConsoleCursorInfo(handle, out info);

// Determining the visibility of the cursor
info.bVisible = show;

// Setting the cursor info
SafeNativeMethods.SetConsoleCursorInfo(handle, ref info);
}

/// <summary>
/// Read the next line from the input dev ice.
/// </summary>
/// <returns></returns>
public static string ReadText()
{

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
104
// The buffer
// Maximum number of characters is 256
StringBuilder buffer = new StringBuilder(256);
// Required for the function c all
uint count;
// Getting the input device that's used for receiving user input

SafeNativeMethods.ReadConsole(GetStandardDevice( ConsoleStandardDevice .Input)
, buffer,
(uint)buffer.Capacity, out count, 0);
// Returning the user input cutting up the line terminator
return buffer.ToString().Substring(0, ( int)(count -
Environment.NewLine.Length));
}

/// <summary>
/// Retrieves the buffer info of the specified device.
/// </summary>
/// <param name="device">The device of which to retrieve its
information.</param>
/// <returns>The buffer info of the specified device. </returns>
public static CONSOLE_SCREEN_BUFFER_INFO
GetBufferInfo(ConsoleStandardDevice device)
{
// Returning the handle for the selected device
IntPtr handle = GetStandardDevice(device);

// Getting console screen buffer information
CONSOLE_SCREEN_BUFFER_INFO info;
SafeNativeMethods.GetConsoleScreenBufferInfo(handle, out info);

return info;
}

/// <summary>
/// Sets the cursor position in the buffer.

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
105
/// </summary>
/// <param name="pos">The coordinates of which to move the cursor
to.</param>
public static void SetCursorPosition(COORD pos)
{
// Getting the console output device handle
IntPtr handle =
SafeNativeMethods.GetStdHandle(SafeNativeMethods.STD_OUTPUT_HANDLE);

// Moving the cursor to the new location
SafeNativeMethods.SetConsoleCursorPosition(handle, pos) ;
}

/// <summary>
/// Writes the buffer information to the screen.
/// </summary>
/// <param name="info">The information of which to write. </param>
public static void WriteBufferInfo(CONSOLE_SCREEN_BUFFER_INFO info)
{
// Discovering console screen buffer information
WriteLine("Console Buffer Info:" );
WriteLine("-------------------- ");

WriteLine("Cursor Position:");

WriteLine(string.Format(System.Globalization. CultureInfo.InvariantCulture,
"\t{0}, {1}",
info.dwCursorPosition.X, info.dwCursorPosition.Y));

// Is this information right?
WriteLine("Maximum Window Size:" );

WriteLine(string.Format(System.Globalization. CultureInfo.InvariantCulture,
"\t{0}, {1}",
info.dwMaximumWindowSize.X,
info.dwMaximumWindowSize.Y));

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
106

// Is this information right?
WriteLine("Screen Buffer Size:" );

WriteLine(string.Format(System.Globalization. CultureInfo.InvariantCulture,
"\t{0}, {1}",
info.dwSize.X, info.dwSize.Y));

WriteLine("Screen Buffer Bounds:" );

WriteLine(string.Format(System.Globalization. CultureInfo.InvariantCulture,
"\t{0}, {1}, {2}, {3}" ,
info.srWindow.Left, info.srWindow.Top,
info.srWindow.Right, info.srWindow.Bottom));

WriteLine("-------------------- ");
}

/// <summary>
/// Writes the specific text followed by a line terminator to the left
and moves it to the far right.
/// </summary>
/// <param name="txt">The text of which to write. </param>
public static void MoveText(string txt)
{
// First, writing the text
WriteLine(txt);

// Getting the handle for the output device
IntPtr handle = GetStandardDevic e(ConsoleStandardDevice .Output);

// Getting the screen buffer info for the output device
CONSOLE_SCREEN_BUFFER_INFO screenInfo =
GetBufferInfo(ConsoleStandardDevice .Output);

// Selecting the text to be moved

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
107
SMALL_RECT rect = new SMALL_RECT();
rect.Left = 0; // The 1st cell
rect.Top = (short)(screenInfo.dwCursorPosition.Y - 1); // The row of
the text
rect.Bottom = (short)(rect.Top); // Only a single line

while (true)
{
// Moving to the right
rect.Right = (short)(rect.Left + (txt.Length - 1));

// Do not move it nore if we are in the far right of the buffer
if (rect.Right == (screenInfo.dwSize.X - 1))
break;

// The character to fill the empty cells created after the move
with
CHAR_INFO charInfo = new CHAR_INFO();
charInfo.Char = SafeNativeMethods.WHITE_SPACE; // For clearing
the cells

// Calling the API function
SafeNativeMethods.ScrollConsoleScreenBuffer(handle, ref rect,
IntPtr.Zero, new COORD() { X = (short)(rect.Left + 1), Y = rect.Top }, ref
charInfo);

// Blocking the thread for the user to see the effect
System.Threading.Thread.Sleep(100);

// Moving the rectangle
rect.Left++;
}
}
}
SUMMARY

MARSHALING WITH C# POCKET REFERENCE
© 2010 MOHAMMAD ELSH EIMY
108
After all, you learned that compound types are unmanaged structures and
unions, and they called compound because they consisted of other types.
You learned that compound types could be marshaled as either a managed
structure or a class. In addition, you learned how to lay-out the type into
memory.
Again and again, the memory layout and size of the type is very crucial.
After that, you have worked with unions and learned that unions are simply a
group of multiple variables share the same memory. In fact, the same memory
location is shared by one or more variables. Therefore, bits are represents in
several ways.
Now it is the time for arrays. The next chapter discusses what arrays are and
how to marshal them.

Marshaling with C# Pocket Reference

About This Presentation

Slide Content

Tags

Categories

Download

Quick Actions

Statistics

Related Slideshows

Marshaling with C# Pocket Reference

About This Presentation

Slide Content

Slide 1

Slide 2

Slide 3

Slide 4

Slide 5

Slide 6

Slide 7

Slide 8

Slide 9

Slide 10

Slide 11

Slide 12

Slide 13

Slide 14

Slide 15

Slide 16

Slide 17

Slide 18

Slide 19

Slide 20

Slide 21

Slide 22

Slide 23

Slide 24

Slide 25

Slide 26

Slide 27

Slide 28

Slide 29

Slide 30

Slide 31

Slide 32

Slide 33

Slide 34

Slide 35

Slide 36

Slide 37

Slide 38

Slide 39

Slide 40

Slide 41

Slide 42

Slide 43

Slide 44

Slide 45

Slide 46

Slide 47

Slide 48

Slide 49

Slide 50

Slide 51

Slide 52

Slide 53

Slide 54

Slide 55

Slide 56

Slide 57

Slide 58

Slide 59

Slide 60

Slide 61

Slide 62

Slide 63

Slide 64

Slide 65

Slide 66

Slide 67

Slide 68

Slide 69

Slide 70

Slide 71

Slide 72

Slide 73

Slide 74

Slide 75

Slide 76

Slide 77