Although managed classes are normally composed of other managed types, it is possible to mix managed and unmanaged types as members of classes under some circumstances. It is also possible to have a pointer to an unmanaged object as a member of a managed class, as in this example:

ref class ManagedClass
{
    UnmanagedClass *puc;
    ...
};

Notice the use of the asterisk (*) rather than the caret (^): this is a pointer to an unmanaged type, not a handle.

Because the member is unmanaged, it’s up to you to manage the lifetime of the object at the other end of the pointer. You should handle this carefully: unmanaged objects sometimes need explicit deletion at a particular point in the code, and this might not fit well with the .NET garbage collection model. However, you can declare destructors for managed classes and use delete on objects of managed types, so it’s possible to arrange for correct object deallocation in most circumstances.

You can’t have an unmanaged object as a member of a managed class, such as is illustrated in the following:

ref class ManagedClass
{
    UnmanagedClass obj;    // C4368: mixed types are not supported
    ...
};

An unmanaged object will only work as a class member if the host object is explicitly deleted at some point: at the end of the enclosing block for an automatic variable, at the end of the process for a global variable, or when delete is called on a pointer. Managed objects don’t work in this way, and the garbage collector can’t collect an unmanaged object.

It’s impossible to have a handle to a managed type as part of an unmanaged class, as shown here:

class UnmanagedClass
{
    ManagedClass ^obj;    // C3265: cannot declare a managed 'obj'
                          // in an unmanaged 'UnmanagedClass'
    ...
};

Because the unmanaged object doesn’t exist in the .NET world, the handle to the contained object is invisible to the garbage collector. Thus, the garbage collector doesn’t know who has a reference to the object or when it can be collected.

There is a way to use a managed type as part of an unmanaged class by using the GCHandle type provided in the System::Runtime::InteropServices namespace. GCHandle asks the runtime to give you a “handle” to refer to a managed object from unmanaged code. You use the GCHandle::Alloc static method to create the handle, and the handle’s Free method to release it again. Here’s how you’d use GCHandle if you wanted to pass a pointer to a managed object to unmanaged code:

To help you use GCHandles within unmanaged code without your having to get into the details of using Alloc and Free, Microsoft provides a helper template class called gcroot. The following exercise shows you how to use gcroot to include a pointer to a managed type as part of an unmanaged class:

Before getting to pinning, let’s briefly discuss interior pointers. We will do this by looking at a scenario in which you have a managed object, and you want to pass it to an unmanaged function that requires a pointer.

You probably know that the garbage collector can (and does) move objects around on the managed heap to maximize free space. This means that you can’t use an unmanaged pointer to refer to a managed object, because the address held in the pointer could end up pointing to the wrong place if the garbage collector moves the object. In fact, the compiler will give you an error if you try to use an ordinary pointer with a managed object.

An interior pointer is a pointer whose address will be updated if the object to which it refers is moved. They are called “interior” pointers because you use them to point to a member within a managed object.

The CLR assumes that it can move objects around in the managed heap whenever it wants. At times, however, you might need to tell the CLR to leave objects where they are. For example, if you want to pass a pointer to a managed object to an unmanaged function, you don’t want the CLR to move the object around in memory while the object is being used by the unmanaged code.

A pinning pointer is a pointer to a managed object, but the value of the pointer cannot be changed, which means that the garbage collector cannot move it around in memory. Thus, creating a pinning pointer to an object gives you a pointer that can safely be passed out to unmanaged code because you can be sure that the address is going to remain valid.

You can use pinning on all or part of a managed object, and pinning a member of a managed object results in the entire object being pinned. For example, pinning the first element of an array will result in the entire array being pinned. The object will remain pinned until there are no references left to the pinning pointer.

The code fragment that follows shows the creation and use of a pinning pointer. First, assume that we have an unmanaged function that takes a pointer to an integer.

void someFunc(int *p)
{
    // Do something with the integer value...
    int n = *p;
}

Here is how we could use this with a managed array:

// Create a managed array of int
array<int> ^arr = gcnew array<int>(5);

// Create a pinning pointer to the first element
// Note there is no '^', and that '&' is used to take the address of the object
pin_ptr<MyClass> pin = &arr[0];

// Pass the integer member to an unmanaged function
someFunc(pin);

// Zero out the pinning pointer
// The array is not pinned any more
pin = nullptr;

After the array element has been pinned, you can pass its address to the unmanaged function, confident that the int won’t be moved around in memory. Observe how there is an implicit conversion between pin_ptr<int> and int*, so you don’t need to convert it yourself. When you’re finished, assigning nullptr to the pinning pointer frees the array object so that it can be moved.

Boxing and unboxing, which will be discussed in a moment, make it possible for value types to be treated as objects. Chapter 9, covers value types in detail and teaches that they are fundamentally different from reference types. To recap, value types have three particular properties:

Anything that wraps a simple value, such as a Boolean or an integer, and that is less than about 16 bytes in size is a good candidate for making a value type. Because value types aren’t accessed via references, they can be far more efficient than the equivalent reference types but can’t be regarded as objects in the same way that reference types can. This becomes a problem when you want to use a value type in a context where an object reference is needed. For example, consider the overload of the Console::WriteLine function that performs formatted output, whose prototype is shown here:

static void WriteLine(String^, Object^);

The first String^ parameter is the format string, and the second is a handle to any .NET reference type. Because value types aren’t accessed by references, you can’t directly specify a value type. But, you will find that the following works, even though “12” is not an instance of a reference type:

int foo = 12;
Console::WriteLine("foo is {0}", foo);

Boxing wraps a value type in an object “box” so that it can be used where an object reference is needed. In C++/CLI, this wrapping is done automatically.

The following three things happen when an object is boxed:

Be aware that the managed object contains a copy of the value type. This means that any modifications you might make to the managed wrapper don’t propagate back to the original value. You can see this happening if you look at the generated code the IL disassembler tool (ISDASM). The IL generated for the preceding two lines of C++/CLI code look something like this:

IL_0002:  ldc.i4.s   12
IL_0004:  stloc.1
IL_0005:  ldstr "Value is {0}"
IL_000a:  ldloc.1
IL_000b:  box        [mscorlib]System.Int32
IL_0010:  call       void [mscorlib]System.Console::WriteLine(string, object)

The first line pushes a literal 12 onto the stack, and the second line stores it (stloc) into a local variable. After the string literal is pushed onto the stack, the ldloc instruction takes the local variable and pushes it back onto the stack. You can see that the next line is a box instruction, which generates an object to hold the integer before calling WriteLine.

What if you want to retrieve the value from a boxed object? The following brief exercise shows you how to get the value back out of a boxed object by using a cast.

You used the DllImportAttribute class in the previous exercise to provide a prototype for an unmanaged function. This class has a number of fields (data members) that can be used when constructing the prototype, and they’re listed in the following table:

Let’s look at the more common fields in detail. CallingConvention defines how arguments are passed between the managed and unmanaged code, and will take one of the values in the Calling Convention enumeration. Different languages use different ways of passing arguments, so Windows supports a number of different calling conventions. C and C++ normally use the C calling convention, often known as Cdecl, whereas many other Windows languages use the standard calling convention, often abbreviated to StdCall. You call Windows API functions by using StdCall, which is the default, unless you use the CallingConvention field to choose another.

With CharSet, you can specify how characters and strings are to be marshaled. It takes one of the values from the CharSet enumeration. You can specify CharSet::Ansi, in which case all characters and strings are converted to one-byte ANSI characters and an “A” is appended to the name of the DLL entry point. Choosing CharSet::Unicode converts characters and strings to use two-byte Unicode characters and appends a “W” to the entry point name. However, it’s usually sufficient to specify CharSet::Auto, which chooses the best option for the host system.

Using the EntryPoint field, you can specify the name or ordinal number of the entry point in the DLL. If you don’t specify this field, as in the preceding exercise, the entry point name is taken to be the function name given in the prototype. A name given using the EntryPoint field takes precedence over the prototype name, so this gives you the ability to provide synonyms for unmanaged functions if you want to refer to them by another name when calling them in your code. The following code fragment shows how you could define a synonym for the MessageBox function:

[DllImport("User32.dll", EntryPoint="MessageBox",
               CharSet=CharSet::Auto)]
int WindowsMessageBox(IntPtr hwnd, String ^text,
                      String ^caption, unsigned int type);

You call the function as WindowsMessageBox, and the call is mapped onto the appropriate MessageBox entry point in User32.dll.

You’ll often need to pass structured data to arguments to unmanaged functions, and you must do this carefully. In particular, you need to specify the way structures are laid out in memory to be sure that they are passed around correctly. You specify the layout of structures and classes by using the StructLayoutAttribute and FieldOffsetAttribute classes.

You add StructLayoutAttribute to managed types to define a formatted type with a particular layout. There are three possible layout types that you can specify for a formatted type:

The following exercise shows how to call an unmanaged Windows API function that needs to be passed a structure. The function is GetSystemPowerStatus, which reports on the AC and battery status of the system. The Windows API defines a structure SYSTEM_POWER_STATUS, which contains the status information. The definition of this unmanaged structure is shown here:

typedef struct _SYSTEM_POWER_STATUS {
    BYTE ACLineStatus;
    BYTE  BatteryFlag;
    BYTE  BatteryLifePercent;
    BYTE  Reserved1;
    DWORD  BatteryLifeTime;
    DWORD  BatteryFullLifeTime;
} SYSTEM_POWER_STATUS, *LPSYSTEM_POWER_STATUS;

The prototype for the GetSystemPowerStatus function in the API documentation is this:

BOOL GetSystemPowerStatus(
  LPSYSTEM_POWER_STATUS lpSystemPowerStatus  // status
);

The function takes a pointer to a SYSTEM_POWER_STATUS structure, fills it in, and hands back the filled structure, returning a Boolean value to let you know whether it worked. Your task is to call this function, passing over a structure, and then display the results.