What is wrong with the following code?

int[] numbers = { 1,2,3,4,5,6 };
int* pI = numbers; // compiler error

The problem is that the numbers variable is an array, which is a reference type. The code will not compile because the array is assigned to a pointer. References are movable types and cannot be implicitly converted to pointers. However, structures are value types and are placed on the stack and outside of the control of the Garbage Collector. Struct values have a fixed address and are easily converted into pointers. In the preceding code, if the type were changed from an array to a structure, it would compile successfully. With the fixed statement, you pin the location of a movable type—at least temporarily. Be careful, though. Pinning memory for an extended period of time can interfere with efficient garbage collection.

Here is the code revised with the fixed statement. This code compiles successfully:

int[] numbers = { 1,2,3,4,5,6 };
fixed (int* pI = numbers) {
    // do something
}

The fixed statement pins memory for the span of a fixed block. In the block, the memory is unmovable and is exempt from garbage collection. You can access the pinned memory using the pointer from the fixed statement, which is a read-only pointer. When the fixed block exits, the memory is unpinned. Multiple pointers can be declared in the fixed statement. The pointers are delimited with commas, and only the first pointer is prefixed with the asterisk (*):

int[] n1 = { 1,2,3,4 };
int[] n2 = { 5,6,7,8 };
int[] n3 = { 9,10,11,12 };
fixed (int* p1 = n1, p2 = n2, p3 = n3) {
}

Here is a more complete example of using the fixed statement:

using System;

namespace Donis.CSharpBook {
    public class Starter {

        private static int[] numbers = { 5,10,15,20,25,30 };

        public unsafe static void Main() {
           int count = 0;
           Console.WriteLine(" Pointer   Value
");
           fixed (int* pI = numbers) {
               foreach (int a in numbers) {
                   Console.WriteLine("{0} : {1}",
                       (int)(pI+count), *((int*)pI + count));
                   ++count;
               }
           }
        }
    }
}

In the following code, ZClass is a class and a movable type. The fixed statement makes the ZClass object fixed in memory. A pointer to the integer member then is obtained:

public class Starter {
    public unsafe static void Main() {
        ZClass obj = new ZClass();
        fixed (int* pA = &obj.fielda) {
        }
    }
}

public class ZClass {
    public int fielda = 5;
}

The stackalloc command allocates memory dynamically on the stack instead of the heap, which provides another option for allocating memory at run time. The lifetime of the allocation is the duration of the current function. The stackalloc command must be used within an unsafe context. It can be used to initialize only local pointers. The CLR will detect buffer overruns caused by the stackalloc command.

Here is the syntax for stackalloc:

type* stackalloc type[expression]

These are the particulars of the stackalloc command. It returns an unmanaged type. The expression should evaluate to an integral value, which is the number of elements to be allocated. The resulting pointer points to the base of the memory allocation. This memory is fixed and not available for garbage collection. It is automatically released at the end of the function.

The following code allocates 26 characters on the stack. The subsequent for loop assigns alphabetic characters to each element. The final loop displays each character:

using System;

namespace Donis.CSharpBook {
    public unsafe class Starter {
        public static void Main() {
            char* pChar = stackalloc char[26];
            char* _pChar = pChar;
            for (int count = 0; count < 26; ++count) {
                (*_pChar) = (char)(((int)('A')) + count);
                ++_pChar;
            }
            for (int count = 0; count < 26; ++count) {
                Console.Write(pChar[count]);
            }
        }
    }
}

The Interop marshaler is responsible for transferring data between managed and unmanaged memory. It automatically transfers data that is similarly represented in managed and unmanaged environments. For example, integers are identically formatted in both environments and automatically marshaled between managed and unmanaged environments. Types that are the same in both environments are called blittable types. Nonblittable types, such as strings, are managed types without an equivalent unmanaged type and must be marshaled. The Interop marshaler assigns a default unmanaged type for many nonblittable types. Developers can also explicitly marshal nonblittable types to specific unmanaged types with the MarshalAsAttribute type.

DllImportAttribute imports a function exported from an unmanaged library, where the library must export the function. DllImportAttribute is in the System.Runtime.InteropServices name space. DllImportAttribute has several options that configure the managed environment for importing the named function. The library is dynamically loaded with the LoadLibrary native API, and the underlying function pointer is initialized at run time. Because the attribute is evaluated at run time, most configuration errors are not found at compile time; they are found later. Because many errors related to DllImportAttribute do not occur at compile time, you should be careful when using this attribute.

Here is the syntax of DllImportAttribute:

[DllImport(options)] accessibility static extern returntype functionname(parameters)

Options are used to configure the import of the external function. The name of the library is the only required option. If it is not found in a directory within the environment path variable, the name of the library should include the fully qualified path. Accessibility is the visibility of the function, such as public or protected. Imported functions must be static and extern. The remainder of the statement is the managed signature of the function.

The following code imports three functions to display the vertical and horizontal size of the screen. GetDC, GetDeviceCaps, and ReleaseHandle are Microsoft Win32 APIs. The imported functions are configured and exposed in the API class, which is a static class. The functions then are called from managed code. In the code, the IntPtr type is used. IntPtr is an abstraction of an integer pointer, where IntPtr.Zero is a null integer pointer:

using System;
using System.Runtime.InteropServices;

namespace Donis.CSharpBook {
    public class Starter {
        public static void Main() {
            IntPtr hDC = API.GetDC(IntPtr.Zero);
            int v = API.GetDeviceCaps(hDC, API.VERTRES);
            Console.WriteLine("Vertical size of window {0}mm.", v);
            int h = API.GetDeviceCaps(hDC, API.HORZRES);
            Console.WriteLine("Horizontal size of window {0}mm.", h);
            int resp = API.ReleaseDC(IntPtr.Zero, hDC);
            if (resp != 1) {
                Console.WriteLine("Error releasing hdc");
            }
        }
    }

    public static class API {
       [DllImport("user32.dll")] public static extern
        IntPtr GetDC(IntPtr hWnd);

       [DllImport("user32.dll")] public static extern
        int ReleaseDC(IntPtr hWnd, IntPtr hDC);

       [DllImport("gdi32.dll")]public static extern
        int GetDeviceCaps(IntPtr hDC, int nIndex);

        public const int HORZSIZE = 4;  // horizontal size in pixels
        public const int VERTSIZE = 6;  // vertical size in pixels
        public const int HORZRES = 8;   // horizontal size in millimeters
        public const int VERTRES = 10;  // vertical size in millimeters
    }
}

In the preceding code, the only option used with DllImportAttribute is the library name. There are several other options, which are described in the following sections.

using System;
using System.Runtime.InteropServices;

namespace Donis.CSharpBook {
    public class Starter {
        public static void Main() {
            string caption = "Visual C# 2008";
            string text = "Hello, world!";
            API.ShowMessage(0, text, caption, 0);
        }
    }

    public class API {
        [DllImport("user32.dll", EntryPoint="MessageBox")]
        public static extern int ShowMessage(int hWnd,
            string text, string caption, uint type);
    }
}

using System;
using System.Runtime.InteropServices;

namespace Donis.CSharpBook {
    public class Starter {
        public static void Main() {
            int val1 = 5, val2 = 10;
            API.printf("%d+%d=%d", val1, val2, val1 + val2);
        }
    }

    public class API {
        [DllImport("msvcrt.dll", CharSet=CharSet.Ansi,
            CallingConvention=CallingConvention.Cdecl)]
        public static extern int printf(string formatspecifier,
            int lhs, int rhs, int total);
    }
}

using System;
using System.Runtime.InteropServices;

namespace Donis.CSharpBook {
    public class Starter {
        public static void Main() {
            int hProcess = API.GetModuleHandleW(null);
        }
    }
    public class API {
        [DllImport("kernel32.dll", ExactSpelling=true)]
        public static extern int GetModuleHandleW(string filename);
    }
}

public class API {
    [DllImport("ole32.dll", PreserveSig=false)]
    public static extern int SomeFunction();
}

HRESULT SomeFunction([out, retval] int param)

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

namespace Donis.CSharpBook {
    public class Starter {
        public static void Main() {
            bool resp = API.CreateDirectory(@"c*:file.txt",
                IntPtr.Zero);
            if (resp == false) {
                StringBuilder message;
                int errorcode = Marshal.GetLastWin32Error();
                API.FormatMessage(
                    API.FORMAT_MESSAGE_ALLOCATE_BUFFER |
                    API.FORMAT_MESSAGE_FROM_SYSTEM |
                    API.FORMAT_MESSAGE_IGNORE_INSERTS,
                    IntPtr.Zero, errorcode,
                    0, out message, 0, IntPtr.Zero);
                Console.WriteLine(message);
            }
        }
    }

    public class API {
        [DllImport("kernel32.dll", SetLastError=true)]
        public static extern bool CreateDirectory(
            string lpPathName, IntPtr lpSecurityAttributes);

        [DllImport("kernel32.dll", SetLastError=false)]
        public static extern System.Int32 FormatMessage(
            System.Int32 dwFlags,
            IntPtr lpSource,
            System.Int32 dwMessageId,
            System.Int32 dwLanguageId,
            out StringBuilder lpBuffer,
            System.Int32 nSize,
            IntPtr va_list);

        public const int FORMAT_MESSAGE_ALLOCATE_BUFFER = 256;
        public const int FORMAT_MESSAGE_IGNORE_INSERTS = 512;
        public const int FORMAT_MESSAGE_FROM_STRING = 1024;
        public const int FORMAT_MESSAGE_FROM_HMODULE = 2048;
        public const int FORMAT_MESSAGE_FROM_SYSTEM = 4096;
        public const int FORMAT_MESSAGE_ARGUMENT_ARRAY = 8192;
        public const int FORMAT_MESSAGE_MAX_WIDTH_MASK = 255;
    }
}

using System;
using System.Runtime.InteropServices;

namespace Donis.CSharpBook {
    public class Starter {
        public static void Main() {
            int hProcess = API.GetModuleHandle(null);
        }
    }

    public class API {
        [DllImport("kernel32.dll", CharSet=CharSet.Ansi)]
        public static extern int GetModuleHandle(string filename);
    }
}

Blittable types are represented similarly in managed and unmanaged memory. Therefore, no conversion is necessary from the Interop marshaler when marshaling between managed and unmanaged environments. Because conversion can be expensive, blittable types are more efficient than nonblittable types. For this reason, when possible, parameters and return types should be blittable types, which include System.Byte, System.SByte, System.Int16, System.UInt16, System.Int32, System.UInt32, System.Int64, System.IntPtr, System.UIntPtr, System.Single, and System.Double. Arrays of blittable types and formatted value types that contain only blittable types also are considered blittable. (Formatted types are explained in the next section.)

Nonblittable types have different representations in managed and unmanaged memory. Some nonblittable types are converted automatically by the Interop marshaler, whereas others require explicit marshaling. Strings and user-defined classes are examples of nonblittable types. A managed string can be marshaled as a variety of unmanaged string types: LPSTR, LPTSTR, LPWSTR, and so on. Classes are nonblittable unless they are formatted. In addition, a formatted class marshaled as a formatted value type is blittable.

A formatted type is a user-defined type in which the memory layout of the members is explicitly specified. Formatted types are prefixed with the StructLayoutAttribute, which sets the layout of the members as described in the LayoutKind enumeration. Table 18-4 lists the members of the LayoutKind enumeration.

In the following code, the API class imports the GetWindowRect unmanaged API. This function returns the location of the client area in the screen. The parameters of GetWindowRect are a window handle and a pointer to a Rect structure, which also is defined in the API class. The Rect structure, which is initialized inside the function, is a formatted value type and is blittable. By default, value types are passed by value. To pass a value type by reference, the out modifier is assigned to the Rect parameter:

public class API
{
    [DllImport("user32.dll")]
    public static extern bool GetWindowRect(
        IntPtr hWnd,
        out Rect windowRect);

    [StructLayout(LayoutKind.Sequential)]
    public struct Rect
    {
        public int left;
        public int top;
        public int right;
        public int bottom;
    }
}

Here is the code that uses the GetWindowRect API and the Rect structure:

API.Rect client = new API.Rect();
API.GetWindowRect(this.Handle, out client);
string temp = string.Format("Left {0} : Top {1} : "+
    "Right {2} : Bottom {3}", client.left,
    client.top, client.right, client.bottom);
MessageBox.Show(temp);

The following code is a version of the API class that defines a Rect class instead of a structure. Because the Rect class has the StructLayout attribute, it is a formatted type. Classes are passed by reference or by pointer by default, depending on the signature of the native API. The out modifier required for a structure (shown in the previous example code) is not necessary for a class:

class API2
{
    [DllImport("user32.dll")]
    public static extern bool GetWindowRect(
        IntPtr hWnd,
        Rect windowRect);

    [StructLayout(LayoutKind.Sequential)]
    public class Rect
    {
        public int left;
        public int top;
        public int right;
        public int bottom;
    }
}

Here is the code to call the GetWindowRect API using the Rect class:

API2.Rect client = new API2.Rect();
API2.GetWindowRect(this.Handle, client);
string temp = string.Format("Left {0} : Top {1} : " +
    "Right {2} : Bottom {3}", client.left,
    client.top, client.right, client.bottom);
MessageBox.Show(temp);

Unions are fairly common in C and C++ code. A union is a type in which the members share the same memory location. This conserves memory by overlaying mutually exclusive data in shared memory. C# does not offer a union type. In managed code, emulate a union in unmanaged memory with the LayoutKind.Explicit option of StructLayoutAttribute. Set each field of the union to the same offset, as shown in the following code:

[StructLayout(LayoutKind.Explicit)]
struct ZStruct {
   [FieldOffset(0)] int fielda;
   [FieldOffset(0)] short fieldb;
   [FieldOffset(0)] bool fieldc;
}

Directional attributes explicitly control the direction of marshaling. Parameters can be assigned InAttribute, OutAttribute, or both attributes to affect marshaling. This is equivalent to [in], [out], and [in, out] of the IDL. InAttribute and OutAttribute are also represented by keywords in C#. Table 18-5 lists the attributes and related keywords.

The default directional attribute depends on the type of parameter and any modifiers.

Strings are immutable and dynamically sized. An unmanaged API might require a fixed-length and modifiable string. In addition, some unmanaged APIs initialize the string with memory allocated at run time. The string type should not be used in these circumstances. Instead, use the StringBuilder class, which is found in the System.Text name space. StringBuilders are fixed-length and not immutable. Furthermore, you can initialize the StringBuilder with memory created in the unmanaged API.

In the following code, the GetWindowText unmanaged API is imported twice. GetWindowText retrieves the text from the specified window. For an overlapped window, this is text from the title bar. The second parameter of GetWindowText is a string, which is initialized with the window text during the function call. The first version of GetWindowText in the API class has a string parameter, whereas the version in the API2 class has a StringBuilder parameter. The GetWindowText application is a Windows Forms application that has two buttons. The first button calls API.GetWindowText and the second button calls API2.GetWindowText. Click the first button. Because of the string parameter in API.GetWindowText, an exception is raised because the API attempts to change that parameter. The second button invokes API2.GetWindowText, which uses the StringBuilder type, and the function runs successfully:

public class API
{
    [DllImport("user32.dll")]
    public static extern int GetWindowText(
        IntPtr hWnd, ref string lpString, int nMaxCount);
}

public class API2
{
    [DllImport("user32.dll")]
    public static extern int GetWindowText(
        IntPtr hWnd, StringBuilder lpString, int nMaxCount);
}

Here is the code from the button-click handlers of the form:

private void btnGetText_Click(object sender, EventArgs e)
{
    string windowtext=null;
    API.GetWindowText(this.Handle, ref windowtext, 25);
    MessageBox.Show(windowtext);
}

private void btnGetText2_Click(object sender, EventArgs e)
{
    StringBuilder windowtext = new StringBuilder();
    API2.GetWindowText(this.Handle, windowtext, 25);
    MessageBox.Show(windowtext.ToString());
}

Some unmanaged functions accept a callback as a parameter, which is a function pointer. The unmanaged function then invokes the function pointer to call a function in the managed caller. Callbacks typically are used for iteration. For example, the EnumWindows unmanaged API uses a callback to iterate handles of top-level windows.

.NET abstracts function pointers with delegates, which are type-safe and have a specific signature. In the managed signature, substitute a delegate for the callback parameter of the unmanaged signature.

These are the steps to implement a callback for an unmanaged function:

The following code imports the EnumWindows unmanaged API. The first parameter of EnumWindows is a callback. EnumWindows enumerates top-level windows. The callback function is called at each iteration and is given the current window handle as a parameter. In this code, APICallback is a delegate and is compatible with the unmanaged signature of the callback:

class API
{
    [DllImport("user32.dll")]
    public static extern bool EnumWindows(
        APICallback lpEnumFunc,
        System.Int32 lParam);

    public delegate bool APICallback(int hWnd, int lParam);
}

EnumWindows is called in the click handler of a Windows Forms application. GetWindowHandle is passed as the callback function in the second parameter via an APICallback delegate. GetWindowHandle is called for each handle that is enumerated. During the enumeration, the managed function adds each handle to a list box:

private void btnHandle_Click(object sender, EventArgs e)
{
    API.EnumWindows(new API.APICallback(GetWindowHandle), 0);
}

bool GetWindowHandle(int hWnd, int lParam)
{
    string temp = string.Format("{0:0000000}", hWnd);
    listBox1.Items.Add(temp);
    return true;
}

Explicit marshaling sometimes is required to convert nonblittable parameters, fields, or return types to proper unmanaged types. Marshaling is invaluable for strings, which have several possible representations in unmanaged memory. Strings default to LPSTR. Use MarshalAsAttribute to marshal a managed type explicitly as a specific unmanaged type. The UnmanagedType enumeration defines the unmanaged types available for marshaling. Table 18-6 lists the members of the UnmanagedType enumeration.

GetVersionEx is imported in the following code. The function is called in Main to obtain information on the current operating system. GetVersionEx has a single parameter, which is a pointer to an OSVERSIONINFO structure. The last field in the structure is szCSDVersion, which is a universally unique identifier (UUID). A UUID is a 128-byte array. In the sample code, the MarshalAs attribute marshals the field as a 128-character array. Each character is one byte long:

using System;
using System.Runtime.InteropServices;

namespace Donis.CSharpBook {
    public class Starter {
        public static void Main() {
            API.OSVERSIONINFO info = new API.OSVERSIONINFO();
            info.dwOSVersionInfoSize = Marshal.SizeOf(info);
            bool resp = API.GetVersionEx(ref info);
            if (resp == false) {
                Console.WriteLine("GetVersion failed");
            }
            Console.WriteLine("{0}.{1}.{2}",
                info.dwMajorVersion,
                info.dwMinorVersion,
                info.dwBuildNumber);
        }
    }


    public class API {

        [DllImport("kernel32.dll")] public static extern
        bool GetVersionEx(ref OSVERSIONINFO lpVersionInfo);

      [StructLayout(LayoutKind.Sequential)]
        public struct OSVERSIONINFO {
            public System.Int32 dwOSVersionInfoSize;
            public System.Int32 dwMajorVersion;
            public System.Int32 dwMinorVersion;
            public System.Int32 dwBuildNumber;
            public System.Int32 dwPlatformId;
            [MarshalAs( UnmanagedType.ByValTStr, SizeConst=128 )]
                public String szCSDVersion;
        }
    }
}

In the previous code, the MarshalAs attribute defined a fixed-size field of 128 characters or bytes. As an alternative to the MarshalAs attribute, C# provides fixed-size buffers using the fixed keyword. The primary purpose of this keyword is to embed aggregate types, such as an array, in a structure. Fixed-size buffers are allowed in structures but not in classes.

There are several rules for using fixed-size buffers:

Here is the syntax of the fixed-sized buffer:

attributes accessibility modifier fixed type identifier[expression]

The following code is another version of the OSVERSIONINFO structure. This version uses the MarshalAs attribute and uses the fixed keyword for the szCSDVersion field:

public class API {
[StructLayout(LayoutKind.Sequential)]
    unsafe public struct OSVERSIONINFO {
        public System.Int32 dwOSVersionInfoSize;
        public System.Int32 dwMajorVersion;
        public System.Int32 dwMinorVersion;
        public System.Int32 dwBuildNumber;
        public System.Int32 dwPlatformId;
        public fixed char szCSDVersion[128];
  }
}