Andy Rushton Programming

The final tutorial in this series on calling C functions from C# covers the problem of how to pass a C# callback function to a C function. This is needed if you are using a C DLL and there are some exported functions in the C library that require callback functions as parameters.

C# allows you to pass a C# method as a C function. This has the benefit that the C# method has access to its parent object and any data fields or other methods.

As with previous tutorials, the key to this method is to use delgates which have been marshalled to match the parameter profile of the C callback and the C function that uses the callback.

The first step is to look at some C declarations for a function that requires a callback.

typedef int (message_callback*) (char* message);
int register_message_callback(message_callback);

So, there is a type definition that declares the parameter profile of a function that can be used as a message callback. It says that the callback must take a C string (char*) as a parameter and return an int.

The second declaration is of a function that takes such a callback function as a parameter and uses it.

Lets say that the register_message_callback is declared in a C DLL which needs to be loaded into the C# program and then given a C# method as its parameter. How is this done?

The first stage is to declare a delegate that represents the type of a function with each parameter translated into an equivalent C# type:

public delegate int message_callback_delegate(string data);

This is in effect a type definition of a method with this particular parameter profile. However, this does not match the C typedef for the callback. It needs marshalling attributes:

[return: MarshalAs(UnmanagedType.I4)]
public delegate int message_callback_delegate(
   [MarshalAs(UnmanagedType.LPStr)] string data);

The LPStr marshalling attribute maps the C# string onto a char* C parameter.

I can then write a message callback in C# with the same parameter profile as the delegate just declared:

public int message_callback(string message)
{
    ...
}

The next stage is to declare a delegate type for the function that registers the callback:

private delegate int register_message_callback_t(message_callback_delegate callback);

This then also needs to have marshalling attributes added to match up the calling conventions and type profiles of the C function:

[UnmanagedFunctionPointer(CallingConvention.Winapi)]
[return: MarshalAs(UnmanagedType.I4)]
private delegate int register_message_callback_t(
    [MarshalAs(UnmanagedType.FunctionPtr)] message_callback_delegate callback);

Now it is possible to use the dynamic loader written in a previous article to load the C library, load the register function and then call it:

dynaloader loader = new dynaloader("mylibrary.dll");
register_message_callback_t register_message_callback =
    loader.load_function("register_message_callback");
register_message_callback(message_callback);

So, the first line loads the DLL into memory. The second loads the register function into memory and associates the function with the variable register_message_callback. This is of the delegate type register_message_callback_t which is effectively a pointer to the function, with strong typing onto the correct parameter profile. The third line calls this function, passing the name of our C# method message_callback as its parameter. This C# method will then be used by the DLL as its message callback.

A Previous Post explained how to marshall simple parameters so that C# code can call C functions. The marshalling ensures that all the conversions to get from C# to C types on calling the function, then back to C# types on return or out parameters, is done for you.

The next step in complexity is to be able to call C functions that take structs as arguments. In this case, each field in the struct needs to be marshalled in order to map it onto the correct C type and to get the conversions to/from the C type. For example, a char[] C field in the struct can be mapped onto a C# string.

To start off, here’s a C struct:

struct MessageStruct
{
  char[11] MsgID;
  char[501] MsgText;
  char IsAlert;
  char Status;
};

And here’s the function that takes such a struct as an argument:

int GetUsrMsg(int Index, MessageStruct* UserMsg);

In this case, an uninitialised struct is passed into the function, that then fills it in.

To call this function from C#, first we need to define a C# struct that is marshalled to have the same fields and field sizes as the C version. This takes some attention to details because it is very easy to get a size wrong.

First, create a C# struct with fields defined using C# types that are suitable for mapping onto the C types.

public unsafe struct MessageStruct
{
    public string MsgID;
    public string MsgText;
    public char IsAlert;
    public char Status;
}

Note that this is declared unsafe because it is used with an unsafe C function.

So, char arrays are mapped onto strings and char is mapped onto char. However, a char in C# is a Unicode char 16-bits wide whereas in C it is an ASCII char 8-bits wide.

To ensure that the char types are mapped correctly, an attribute is attached to the struct to control the mapping.

[StructLayout(LayoutKind.Sequential, CharSet = CharSet.Ansi, Pack = 1)]
public unsafe struct MessageStruct
{

This attribute declares a number of parameters that control the mapping of C# types onto the bare bytes of the C type.

The Sequential value tells the marshaller that the fields in the C struct are laid out in the same order as the C~ struct. An alternative is to specify the exact byte position of each field.

Then the CharSet value indicates that the underlying C struct uses Ansi characters, so the marshaller must convert from the C# unicode characters to Ansi on in parameters and vice-versa on out parameters.

Finally, the Pack value indicates how the C types are packed into words. Each field is packed to a multiple of this parameter. The deault is 4, so that each field is guaranteed to start on a word boundary. However, in this library, the C structs have been packed down to individual bytes, thus a pack value of 1 is used.

The next stage is to marshall each of the fields by adding a MarshallAs attribute to each one:

    [MarshalAs(UnmanagedType.ByValTStr, SizeConst = 11)]
    public string MsgID;

    [MarshalAs(UnmanagedType.ByValTStr, SizeConst = 501)]
    public string MsgText;

    [MarshalAs(UnmanagedType.U1)]
    public char IsAlert;

    [MarshalAs(UnmanagedType.U1)]
    public char Status;

The marshalling attributes map the field of the C# type onto the corresponding C type. Take the first field. This is a char[11] in the C struct. It has been mapped onto a string and then the string has been marshalled as a ByValTStr with a size of 11. The ByValTStr is a C character array which is embedded in the struct, i.e. a char[11] rather than a char* which points to a separate character buffer.

The char fields have also been marshalled onto a one-byte unsigned type.

The next stage is to marshall the C function that takes this struct as a parameter.

Remember the C function definition:

int GetUsrMsg(int Index, MessageStruct* UserMsg);

So, as with previous tutorials, the first step is to declared a delegate type to represent the function’s type with each parameter marshalled onto the C types.

[UnmanagedFunctionPointer(CallingConvention.Winapi)]
[return: MarshalAs(UnmanagedType.I4)]
private delegate int GetUsrMsg_t(
    [MarshalAs(UnmanagedType.I4)] int index,
    out MessageStruct message);

Note that the message parameter is an out parameter, meaning that there is no need to initialise it and it will be passed by reference.

Then, using the dynamic loader class, the function of this name can be loaded from the DLL and called:

dynaloader loader = new dynaloader("myclib.dll");
GetUsrMsg_t GetUsrMsg = loader.load_function("GetUsrMsg");
MessageStruct message;
int message_status = GetUsrMsg(0, out message);

So, the first two lines use the dynamic DLL loader to load the C DLL. Then the relevant function is loaded from the DLL. The third line declares a bare MessageStruct to use in the function call. The last line calls the function, passing the struct as an out parameter.

The Problem

I am using a DLL provided for me, written in C and I want to call its functions from C#. I have explained in a previous post how to dynamically load a function from a DLL and map it onto a C# delegate so it can be called from C#.

However, this is only part of the problem. The other part is how to map the C types of the function parameters and return value onto C# types so that data can be passed backwards and forwards between the two languages.

The Solution – Marshalling

The solution that Microsoft provide is called Marshalling and is provided by classes in the System.Runtime.InteropServices namespace.

The mashalling mechanism allows the calling conventions and the parameter types of the C function to be specified and, furthermore, to automatically be type converted. So, for example, here’s a C function:

char* ErrorMessage(int id);

In order to dynamically load and call this function from C#, I first declare a delegate with marshalling attributes applied:

[UnmanagedFunctionPointer(CallingConvention.Winapi)]
[return: MarshalAs(UnmanagedType.LPStr)]
private delegate string ErrorMessage_t([MarshalAs(UnmanagedType.I4)] int id);

As explained in the earlier article, this delegate declaration effectively declares a function type. The actual function can then be loaded and converted to this type and then called.

The attributes (i.e. the code in square brackets []) need further explanation.

First, the function itself is declared as an UnmanagedFunctionPointer – this is letting the system know that the function is not managed, so for example it will not be garbage collected. It also says that parameters are to by passed using the WinAPI parameter-passing convention.

The next attribute marshals the return type as unmanaged type “LPStr”. This is a pointer to a C string and corresponds to the char* type in C. The unmanaged part of the marshalling states that the memory associated with the return value will not be garbage collected. In this case the function returns a pointer to an internal buffer and so doesn’t need to be collected anyway.

Note that the return type of the C# delegate is “string”, i.e. a C# string type. The return value from the function will be automatically converted from char* (a byte-wide null-terminated character buffer) to string (a 16-bit wide unicode C# string).

The function parameter itself is of C type int and is marshalled as unmanaged type “I4″. This is unnecessary since the C type int is the same as the C# type int, but I have included it for completeness. Note how the marshalling attribute prefixes the parameter declaration.

Once you have such a delegate declaration, you can now dynamically load a function from a DLL and map it onto the delegate so it can be called from C# as a previous post explained.

Following on from the previous C# article – dynamic loading of a C DLL at run-time, the next step is to make the dynamic loading functions into a class.

The class will be in global scope for this example – in practice I might put it into a namespace.

The class manages the DLL so that it can be unloaded or unloaded at any time. Since the DLL is an unmanaged assembly, the class will need a destructor to unload the DLL as well as a constructor to load it. Also, it is good practice to allow for deferred loading – that is, an instance of the class can be constructed without loading its associated DLL, then the DLL can be loaded on demand later.

So, the outline class looks like this:

class dynaloader
{
    // construct an unloaded object
    public dynaloader()
    {
    }

    // construct a loaded object
    public dynaloader(string dll_name)
    {
    }

    // destructor
    ~dynaloader()
    {
    }

    // test whether this object is unloaded or loaded
    public bool loaded()
    {
    }

    // load the DLL
    public bool load(string name)
    {
    }

    // unload the DLL
    public bool unload()
    {
    }

    // Generic method for loading a function from the DLL
    public T load_function<T>(string name) where T : class
    {
    }

}

So, these functions now need implementing using the external WIN32 functions to load/unload the DLL and to load functions from the DLL.

The class needs to contain a handle that points to the DLL, i.e. contains it’s unmanaged address. This is managed by the constructors/destructor in conjunction with the load/unload methods:

using System;
using System.Runtime.InteropServices;

class dynaloader
{
    private IntPtr m_dll = IntPtr.Zero;

    public dynaloader()
    {
    }

    public dynaloader(string dll_name)
    {
        load(dll_name);
    }

    ~dynaloader()
    {
        if (loaded()) unload();
    }

    public bool loaded()
    {
        return m_dll != IntPtr.Zero;
    }

    [DllImport("kernel32.dll")]
    private static extern IntPtr LoadLibrary(string dllToLoad);

    public bool load(string name)
    {
        if (loaded()) unload();
        m_dll = LoadLibrary(name);
        if (!loaded())
            return false;
        return true;
    }

    [DllImport("kernel32.dll")]
    private static extern bool FreeLibrary(IntPtr hModule);

    public bool unload()
    {
        if (!loaded()) return true;
        if (!FreeLibrary(m_dll))
            return false;
        m_dll = IntPtr.Zero;
        return true;
    }

}

The final stage is to provide the generic method for loading a function from the DLL:

class dynaloader
{
    ...

    [DllImport("kernel32.dll")]
    private static extern IntPtr GetProcAddress(IntPtr hModule, string procedureName);

    public T load_function<T>(string name) where T : class
    {
        IntPtr address = GetProcAddress(m_dll, name);
        if (address == IntPtr.Zero)
            return null;
        System.Delegate fn_ptr = Marshal.GetDelegateForFunctionPointer(address, typeof(T));
        return fn_ptr as T;
    }

}

In this case, the method returns null on failure, but it could instead throw an exception.

The Problem

I am working on a C# project which needs to load one of a set of DLLs at run-time. Indeed, it needs to be able to load and unload them, possibly then loading a different one. The problem is similar to that of supporting plugins.

The DLLs are supplied by another company, so I have no control over them. They are written in C and export a set of C functions.

A Solution

Surprisingly, after a long search I discovered that C# does not seem to support dynamic linking. So in order to solve this problem, I need to use the dynamic linking functions supported by the WIN32 API, a set of low-level C functions.

The first step then was to create bindings to the WIN32 functions so that they are linked into the application. This is done using the Platform Invoke services provided in the namespace System.Runtime.InteropServices, and documented on MSDN.

using System;
using System.Runtime.InteropServices;

static class win32
{

    [DllImport("kernel32.dll")]
    public static extern IntPtr LoadLibrary(string dllToLoad);

    [DllImport("kernel32.dll")]
    public static extern IntPtr GetProcAddress(IntPtr hModule, string procedureName);

    [DllImport("kernel32.dll")]
    public static extern bool FreeLibrary(IntPtr hModule);

}

The DllImport attribute tells the linker which external library to load the functions from.

When mapping from C# to C, it is necessary to “Marshall” the parameters to map C# types onto C types. However, these functions work as they stand since the default marshalling of the parameters is correct. I will revisit the marshalling issue in another article.

These functions perform the following tasks:

LoadLibrary

Loads the DLL into memory and returns a raw address of the DLL’s handle. If the DLL cannot be found, returns IntPtr.Zero.

GetProcAddress

Loads a function by name from the DLL. Returns a raw address of the function. If the function cannot be found, returns IntPtr.Zero.

FreeLibrary

Releases the DLL loaded by the LoadLibrary function.

The LoadLibrary and FreeLibrary functions can now be used directly in C#. However, the GetProcAddress function returns a function pointer and these cannot be called directly from C#. The trick is to convert the function pointer into a delegate using the GetDelegateForFunctionPointer method from the System.Runtime.InteropServices.Marshall class. The code for loading a function and converting it into a delegate is:

using System;
using System.Runtime.InteropServices;
...
IntPtr address = win32.GetProcAddress(m_dll, name);
System.Delegate fn_ptr = Marshal.GetDelegateForFunctionPointer(address, typeof(T));

In this case, the type T is the type of the delegate to convert to. Sadly, the GetDelegateForFunctionPointer method returns a System.Delegate rather than a T. However, this can now be wrapped into a generic method that does return the right type:

class plugins
{
    public T load_function<T>(string name) where T : class
    {
        IntPtr address = win32.GetProcAddress(m_dll, name);
        System.Delegate fn_ptr = Marshal.GetDelegateForFunctionPointer(address, typeof(T));
        return fn_ptr as T;
    }

}

The last line upcasts the System.Delegate onto type T. Of course, the real version has some error checking – for example you could throw an exception if the function wasn’t found.

So what is type T? This is a delegate type declaration for the C function. For example:

[UnmanagedFunctionPointer(CallingConvention.Winapi)]
private delegate int Ready_t();

The attribute tells the compiler that this is an unmanaged function (no garbage collection etc.) and that it uses Windows calling conventions. In this case, the DLL providers have told me in their documentation that their DLLs use Winapi calling conventions.

Note that I have used the delegate keyword to indicate that this is a delegate type. I have used the name Ready_t to indicate that this is the type declaration of the function and not the actual function.

Again, in this case, the return type int already marshalls correctly using the default conversions so there are no marshalling attributes on the function parameters. Marshalling will be dealt with in another article.

The final stage to get a callable C# function is to use this delegate type as the T parameter of the generic load_function method:

Ready_t Ready = load_function<Ready_t>("Ready");
int ready_status = Ready();

The first line loads a function called “Ready” of type Ready_t. The second calls the function as if it were a C# method.