Marshalling data in Compact Framework

In many situations when we create applications for different embedded systems or mobile platforms we can’t develop all parts of the product using managed code only.

For example we need several modules written in native language which perform some low level operations or we already have these libraries written on C++. So we have to use more that one programming language in our product and also use data marshaling in it.

In this article we will review some aspects of using data types and ways of using them during marshalling data to and from unmanaged code.

Making your interop calls more efficient

Marshaling is the act of taking data from one environment to another. In the context of .NET marshalling refers to transferring data from the app-domain you are in to somewhere else, outside.

You should remember that such Platform Invoke calls are slower than direct native calls and than regular managed calls. The speed depends on types marshaled between managed and native code, but nevertheless you should avoid using Platform Invoke calls if you have a chance to do this. Also it is recommended to use calls with some amount of transferred data than several “small” Platform Invoke calls.

Blittable types

It is recommended to use simple data types (int, byte, boolean, characters and strings). It makes the call more efficient and helps to avoid any convertions and copying. These blittable types have identical representation in both managed and unmanaged memory. But you should remember that in Compact Framework during marshaling boolean type is represented as 1-byte integer value (instead of 4-byte integer value in the full .NET Framework), character type (char) is always represented as 2-bytes Unicode character and String type is always treated as a Unicode array (in full .NET Framework it may be treated as a Unicode or ANSI array, or a BSTR).

Method Inlining

The JIT compiler can inline some methods in order to make the calls more efficient. You can not force a method to be inlined by the compiler, but you can make it NOT to be inlined. In order to avoid inlining you can:

• make the method virtual;
• add branching to the method’s body;
• define local variables in the method;
• use 2-bit floating point arguments (or return value).

Disabling method inlining can help to detect a problem during Platform Invoke calls.

Sequential layout

In the Compact Framework all structures and classes always have sequential layout (the managed value type has the same memory layout as the unmanaged structure). This behavior can be specified by setting attribute LayoutKind.Sequential. You don’t need to specify this attribute in Compact Framework, but if you use these pieces of code in both full .NET Framework and Compact Framework you have to set it to avoid different behavior on two platforms.

The following sample shows how to send some pointers from C# code for storing them in the native module.

Code C#:

[StructLayout(LayoutKind.Sequential)]
public class BasePointers // you can use the struct too
{
    public IntPtr pointer1;
    public IntPtr pointer2;
}

[DllImport("NativeDLL.dll", CallingConvention = CallingConvention.Winapi)] 
// Cdecl
public static extern int TransferStruct(BasePointers pointers);

Code C++:

struct BasePointers
    {
       unsigned int pointer1;
       unsigned int pointer2;
    }

     extern "C" __declspec(dllexport) int CDECL TransferArray(BasePointers* 
pointers);	 

One Calling Convention

The Calling Convention determines the order in which parameters are passed to the function, and who is responsible for the stack cleaning. The .NET Compact Framework supports only the Winapi value (Cdecl on this platform) of Calling Convention. It defines the calling convention for C and C++ (instead of the full .NET Framework which supports three different calling conventions). To avoid crashes of your application you should make sure that your calling conventions in both managed and native declarations are same.

If you specify the attribute to preserve signature of functions ([PreserveSig]) then the returned value will contain 32-bit HRESULT value that will give you more data to analyze errors during the native function execution. The Calling Convention can be specified by adding the attribute CallingConvention to the declaration of your function. As it was mentioned the .NET Compact Framework supports only “Winapi” Calling Convention that corresponds to Cdecl:

Code C#:

[UnmanagedFunctionPointer(CallingConvention.Winapi)]
    public delegate int ProgressEventHandler(int progressValue);

Code C++:

typedef void (CDECL *ProgressEventHandler)(int progressValue);

Data Alignment

In some situations we need to transfer data between the managed and unmanaged code in the structures. As it’s written above all structures have sequential layout in the Compact Framework, but you should remember about representation of structs in the managed in unmanaged code. The way of packing structures depends on a platform and on a way how the members of structure are aligned. On ARM platform this value for alignment is four (all values in structures are aligned to 4 bytes).

typedef struct OurStruct
{
      unsigned char valueChar;
      usingned int valueInt;
} ourStruct_;

This structure could be perfectly acceptable in desktop code, but if you use such structure on the Windows Mobile platform then you might receive valueInt at the offset 4. If you use such structures in both desktop and device’s side code you have to use them carefully during marshaling.

During marshaling data you might receive such errors as “Datatype misalignment” (0x80000002) or “Access violation” (0x80000005). It indicates that you are using wrong pointers or try to access to the wrong offset of data. For example, you transfer array of bytes from C# code to the native module and define you functions as:

C# code:

[DllImport("NativeDLL.dll", CallingConvention = CallingConvention.Winapi)]
// Cdecl
public static extern int TransferArray(IntPtr src, int srcSize);

C++ Native Module code:

extern "C" __declspec(dllexport) int CDECL TransferArray(byte* srcArr, 
int srcSize); 

If you try to use the pointer “srcArr” as the pointer on integer (int*) and then try to use the corresponding value you will receive an error :

int value = *(int*)srcArr;  //  Datatype misalignment

The simple way to avoid this problem is to change declaration of C++ function and change the pointer on array of bytes to the pointer on array of integer and use it without any problems:

extern "C" __declspec(dllexport) int CDECL TransferArray(int* srcArr, 
int srcSize);

Marshal class

You can use methods in the class Marshal to manually convert managed objects and perform conversions between IntPtrs. These methods are PtrToStructure, GetComInterfaceForObject, PtrToStringBSTR, GetFunctionPointerForDelegate and others. It allows you to control marshaling. These methods are also useful for debugging issues with marshaling parameters where the runtime is not able to convert a particular argument.

You cannot pass delegate directly to the native module as parameter of you function because the .NET Compact Framework does not support marshaling of delegates. Instead you should use method Marshal.GetFunctionPointerForDelegate for getting function pointer which you can pass to the native code and call it.

Code:

class MainClass
{
   [UnmanagedFunctionPointer(CallingConvention.Winapi)]
   public delegate int ProgressEventHandler(int progressValue);

   ...
    void OnProgressChanged(int progressValue)
    {
        ...
    }
   …
 
   … 

   [DllImport("NativeDLL.dll", CallingConvention = CallingConvention.Winapi)] 
// Cdecl
   public static extern int SetCallbackFunction(IntPtr functionPointer);
}


// Passing  function pointer

Delegate d = new  ProgressEventHandler(OnProgressChanged);

IntPtr progressChanged =  Marshal.GetFunctionPointerForDelegate(d);

int result = SetCallbackFunction(progressChanged);

But you should be aware of Garbage Collector (GC) in such situation. The GC might collect you delegates and your function pointers will become invalid. It may happen when you passed the function pointer to the native code as callback method in order to call it later – GC might think that there are no references to it in the managed code. To avoid this situation you should keep reference to this delegate. For example, you can store it in the classes variable or create some delegates pool, in which you can keep references to the several delegates.

GCHandle

Since we’re passing a pointer to some data we need to allocate memory for that data and make sure that the GC will not remove that memory. One of the possible ways to manage this situation is to use GCHandle.

If you want to pass some class (or array of bytes) to the unmanaged code and you need to pin memory for the proper work with it in the unmanaged code you can write:

class SampleClass
      {
          ...
      }

      SampleClass classSample = new SampleClass();

      GCHandle classHandle = GCHandle.Alloc(classSample, GCHandleType.Pinned);
      IntPtr ptrToClass = classHandle.AddrOfPinnedObject(); 

      int result = PassPtrToUnmanagedCode(ptrToClass);  // our function

You can also make an instance of GCHandle as a member of the class to avoid deleting them by GC. Also you should remember that the structure is value-type. And pinning it to the memory will cause a problem, because structure will be copied and GCHandle will handle a reference to created “boxed” copy of the object. It will be hard to find such problem in the future.

Conclusion

During marshaling data you may face with the problems described above. Very often you may get “NotSupportedException” and other exceptions. To find a problem you can enable logging of setting the registry keys. One of the logging components is “Interop ”. The log provides information about Platform Invoke calls and marshaling. You can read MSDN for more information about Creating Log Files.

With the .NET Compact Framework 2.0 you can use Platform Invoke calls in managed application, even though there are a few limitations. You should remember all differences and limitations between full .NET Framework and the Compact Framework to avoid problems in your applications.

Resources:

.NET Compact Framework blog (Performance and Working Set FAQ)

Interop: Common Issues & Debugging Techniques

The Truth About GCHandles

Structure packing

Creating Log Files:
http://msdn.microsoft.com/en-us/library/ms229650.aspx
http://blogs.msdn.com/netcfteam/archive/2005/07/24/442609.aspx