.NET Compact Framework Team : Author: Katie Blanch

Interop: Extending GUI Functionality

NetCFTeam — Sun, 24 Jul 2005 11:26:00 GMT

Interop: Extending GUI Functionality

This post will describe some ways you can use the new interop features present in version 2 of the .Net Compact Framework to extend the framework's GUI functionality present in the System.Windows.Forms namespace. An overview of how GUI works under the hood is also provided to give developers an understanding of the limitations and assumptions that the framework will make when using interop to override or extend the framework.

Under the Hood

The functionality exposed through the System.Windows.Forms namespace is implemented in two parts. There is a native layer, present inside netcfagl2_0.dll, which handles most of the logic required for GUI features and is responsible for interacting with the underlying Windows CE OS. The second part is the managed layer, present inside System.Windows.Forms.dll, which for the most part is actually a relatively thin wrapper that contains very little logic and mostly just exposes functionality to the managed world.
There are a couple of implementation details that you should keep in mind when using interop to extend current functionality.

The runtime will attempt to maintain the managed state of GUI controls and components. For example, if you PInvoke to SHFullScreen to hide the task bar, the runtime may override this behavior at a later time with its understanding of the managed state.
Forms will have logic under the scenes to support features like tabbing, autoscroll, docking and anchoring. The logic for these features often involves examining and manipulating controls parented to the form, and can occur in response to messages received by the form as well as in response to GUI API calls.
All managed controls use the GWL_USERDATA space, and the runtime expects the data stored here to remain valid. This area is considered to be reserved for runtime use only and should not be examined or relied upon.
Managed forms and controls may be recreated as necessary when their attributes are modified. Any modifications that were made to the native control via interop are not guaranteed to be re-applied to the newly created control. Also, the value returned from Control.Handle, associated with the native HWND, will change.
Managed controls are often implemented by wrapping functionality exposed in a similar native control present in the OS.
In some cases, a single managed control may be associated with two native controls (such as the NumericUpDown control). The Control.Handle API will return the handle associated with the major native control of the pair (in the case of NumericUpDown, it will be the Edit control). You can use the remote spy tool to further examine the hierarchy of managed controls.
For performance reasons, not all events are sent up to the managed code layer.

Using Interop Features

A number of interop features have been added to the .Net Compact Framework, making it possible for developers to dramatically extend the framework without writing native code.

Delegate callbacks, which allow you to override the wndproc of native controls and get notified when messages are received by the native control.
Marshaling support for more types, including support for more types of fields in structures.
The InteropServices.Marshal class has been extended, allowing you to access marshaling functionality from managed code and convert between IntPtrs and objects. This is especially useful when the interop functions, such as wndprocs, contain parameters that can be either an int or a pointer to a structure based on what context they are called in. You may find Marshal.PtrToStructure and Marshal.StructureToPtr useful to convert between an IntPtr, representing a native pointer to a structure, and a managed instance of the structure.
COM Interop support, which provides the pluming necessary to host ActiveX controls. An ActiveX container can now be implemented entirely in managed code.

When using interop features to interact with managed controls and components, follow these guidelines:

Whenever possible, you should use managed APIs to modify the state of a control or the system, and rely on interop only as a last resort.
When parenting native controls inside a managed form, provide a level of indirection between the form and the native control by wrapping the native control inside a managed Control or UserControl. This will protect the native control from being frequently examined and manipulated by the runtime; since the runtime will instead reference the parent managed Control.
Be aware that sending a message to a managed control may have side-effects (or may start to have side effects in future versions). The only way to completely prevent runtime logic from executing is to send a message directly to a native control that has been created using interop. In general, sending messages directly to a managed form must be done with care as there may be assumptions about the existence of a managed control or component that would typically send that message.
When spying on messages sent to a managed control by overriding the wndproc, be sure to call the original wndproc (which will often be the runtime). If the original wndproc is not called, there may be undesirable side-effects causing core features such as tabbing, autoscroll, and layout (among other things) to break.
For compatibility against future versions of the framework, it can be safer to wrap a native control from scratch, then to modify the state of a managed control. When using interop to extend the framework, think about how your code will function if the feature you are implementing is eventually added to the framework.
Do not rely on implementation details, as they may change in future versions. Do not attempt to parse or change any runtime owned data structures.
Do not rely on the order, timing or frequency of events.

Resources

The following blog posts describe how to extend the functionality of currently exposed controls. This will show how to use interop to add 'missing' events to managed controls.
Part 1: http://blogs.msdn.com/netcfteam/archive/2005/05/20/420551.aspx
Part 2: http://blogs.msdn.com/netcfteam/archive/2005/05/23/421143.aspx

The following information may be useful when attempting to diagnose and solve issues involving interop.
http://blogs.msdn.com/netcfteam/archive/2005/07/24/442612.aspx

All applications should be tested with Interop Logging turned on, even if there are no known issues. This will produce a log file that should then be searched for 'ERROR' and 'WARNING'. The log file will contain more information about the cause of managed exceptions, subtle errors that do not manifest themselves as managed exceptions, as well as assist in debugging interop issues involving native code for which the source is unavailable.
http://blogs.msdn.com/netcfteam/archive/2005/07/24/442609.aspx

There are interop and GUI related guidelines and tips that can drastically improve your application's performance:
http://blogs.msdn.com/netcfteam/archive/2005/05/04/414820.aspx

Sample Code - Wrapping Native Controls

This sample presents a generic WindowHost class that you can use to host any native control on a managed form. Sample code is shown using this class to host the RichInk control.

using System;
using System.Windows.Forms;
using System.Runtime.InteropServices;
using System.Diagnostics;

namespace GuiInterop
{
/// <summary>
/// This is a generic host that will allow you to create a native
/// control and parent it to your managed form. You will also be
/// able to spy and respond to messsages the native control
/// recieves, and send messages to the native control.
/// </summary>
public class WindowHost : Control
{
private IntPtr m_hwnd; // the window handle of the native
// control

  private IntPtr m_wndprocReal; // the original wndproc of
          // the native control before
          // it is subclassed

  private WindowsAPIs.WindowProcCallback m_delegate; // the
          // delegate used to get
          // message callbacks

  /// <summary>
  /// This event will fire before the message is sent down to
  /// the native control for processing, allowing you to
  /// preview and respond to the message.
  /// </summary>
  public event MessageEventHandler MessageReceived;

  /// <summary>
  /// The HWND associated with the native control being hosted.
  /// </summary>
  public IntPtr NativeHandle
  {
   get
   {
    return m_hwnd;
   }
  }

  /// <summary>
  /// Create a native control and embeds it inside the host.
  /// </summary>
  /// <param name="strClassName">The class name of the native
  /// control to be created. This can be either a system class
  /// or a custom native control that has been registered on
  /// the system through RegisterClassEx. </param>
  /// <param name="wsEx">The extended window style of the native
  /// control to be created. </param>
  /// <param name="ws">The style of the native control to be
  /// created. </param>
  public WindowHost(string strClassName, uint wsEx, uint ws)
  {
#if DESKTOP
   /* Under the desktop framework, ensure this control has been fully
    * created and has a valid hwnd.
    */
   this.CreateHandle();
#endif

Debug.Assert(this.Handle != IntPtr.Zero, "Control should have a handle created by now");

/* Create the native control and parent it to this control. */

   m_hwnd = WindowsAPIs.CreateWindowExW(wsEx, strClassName,
    null, ws | WindowsAPIs.WS_CHILD | WindowsAPIs.WS_VISIBLE,
    0, 0, 0, 0,
    this.Handle, 0, 0, 0);

if (m_hwnd == IntPtr.Zero) {

    /* Class not registered */

    Debug.Assert(false, "Class not registered");
    throw new OutOfMemoryException();
   }

   /* Latch onto windows messages by subclassing the native
    * control
    */

   m_delegate = new WindowsAPIs.WindowProcCallback(this.WnProc);
   m_wndprocReal = WindowsAPIs.SetWindowLong(m_hwnd,
    WindowsAPIs.GWL_WNDPROC,
    Marshal.GetFunctionPointerForDelegate(m_delegate));

}

  /// <summary>
  /// Embeds a native control it inside the host.
  /// </summary>
  public WindowHost(IntPtr hwndNativeControl)
  {
#if DESKTOP
   /* Under the desktop framework, ensure this control has been fully
    * created and has a valid hwnd.
    */
   this.CreateHandle();
#endif
   Debug.Assert(hwndNativeControl != IntPtr.Zero, "Control should have a handle created by now");
   Debug.Assert(this.Handle != IntPtr.Zero, "Control should have a handle created by now");

m_hwnd = hwndNativeControl;

   /* Latch onto windows messages by subclassing the native
    * control
    */

   m_delegate = new WindowsAPIs.WindowProcCallback(this.WnProc);
   m_wndprocReal = WindowsAPIs.SetWindowLong(m_hwnd,
    WindowsAPIs.GWL_WNDPROC,
    Marshal.GetFunctionPointerForDelegate(m_delegate));
  }

  /// <summary>
  /// WnProc called used to monitor all messages the native control
  /// receives.
  /// </summary>
  private int WnProc(IntPtr hwnd, uint msg, uint wParam, uint lParam)
  {
   int ret;
   MessageEventArgs e;

   e = new MessageEventArgs(hwnd, msg, wParam, lParam);

   this.OnMessageReceived(e);

if ((msg == WindowsAPIs.WM_DESTROY) && (!e.Handled))
{

    /* De-subclass the child hwnd */

    WindowsAPIs.SetWindowLong(m_hwnd,
     WindowsAPIs.GWL_WNDPROC, m_wndprocReal);
   }

if (e.Handled)
{

    /* Give the original wnd proc a chance to process the
     * message
     */

    ret = WindowsAPIs.CallWindowProc(m_wndprocReal,
     hwnd, msg, wParam, lParam);
   }
   else
    ret = e.ReturnValue;

   return ret;
  }

  /// <summary>
  /// Used to ensure the native control remains the same size
  /// as the host control.
  /// </summary>
  protected override void OnResize(EventArgs e)
  {
   WindowsAPIs.SetWindowPos(m_hwnd, 0,
    0, 0, this.ClientSize.Width, this.ClientSize.Height,
    WindowsAPIs.SWP_NOZORDER);
  }

  /// <summary>
  /// Applies the window text of the host control to the
  /// native control as well.
  /// </summary>
  protected override void OnTextChanged(EventArgs e)
  {
   WindowsAPIs.SetWindowText(m_hwnd, this.Text);
  }

  /// <summary>
  /// Any time focus is given to the host control, it is passed
  /// down to the hosted native control.
  /// </summary>
  protected override void OnGotFocus(EventArgs e)
  {
   WindowsAPIs.SetFocus(m_hwnd);
  }

  /// <summary>
  /// Called each time a message is received by the native
  /// control, and fires associated event.
  /// </summary>
  protected void OnMessageReceived(MessageEventArgs e)
  {
   if (this.MessageReceived != null)
    this.MessageReceived(this, e);
  }
}

/// <summary>
/// Delegate used to spy and respond to messages received by
/// the hosted native control.
/// </summary>
public delegate void MessageEventHandler(object sender, MessageEventArgs e);

/// <summary>
/// Used to encapsulate the data present in a wndproc message.
/// </summary>
public class MessageEventArgs : EventArgs
{
  private IntPtr m_hwnd;
  private uint m_msg;
  private uint m_wParam;
  private uint m_lParam;
  private bool m_fHandled;
  private int m_ret;

  public MessageEventArgs(IntPtr hwnd, uint msg, uint wParam,
   uint lParam)
  {
   m_fHandled = true;
  }

  /// <summary>
  /// The window handle associated with the message.
  /// </summary>
  public IntPtr Hwnd
  {
   get
   {
    return m_hwnd;
   }

}

  /// <summary>
  /// The ID used to identify the message (WM_*).
  /// </summary>
  public uint Msg
  {
   get
   {
    return m_msg;
   }

}

  /// <summary>
  /// The wParam associated with the message, whose value
  /// depends on the message.
  /// </summary>
  public uint wParam
  {
   get
   {
    return m_wParam;
   }
  }

  /// <summary>
  /// The lParam associated with the message, whose value
  /// depends on the message.
  /// </summary>
  public uint lParam
  {
   get
   {
    return m_lParam;
   }
  }

  /// <summary>
  /// Determines if the message is to be sent to the native
  /// control's wndproc for further processing.
  /// </summary>
  public bool Handled
  {
   get
   {
    return m_fHandled;
   }
   set
   {
    m_fHandled = value;
   }
  }

  /// <summary>
  /// Determines the return value to be returned from the wndproc
  /// to the sender of the message.
  /// </summary>
  public int ReturnValue
  {
   get
   {
    return m_ret;
   }
   set
   {
    m_ret = value;
   }
  }
}

}

using System;
using System.Windows.Forms;
using System.Runtime.InteropServices;
using GuiInterop;

namespace HostDemo
{
public class SampleForm : Form
{
private WindowHost m_ctlRichInk;

  public SampleForm()
  {
   InitInkX();
   m_ctlRichInk = new WindowHost("InkX", 0, 0);
   m_ctlRichInk.Height = 150;
   m_ctlRichInk.Dock = DockStyle.Fill;
   m_ctlRichInk.Parent = this;

   WindowsAPIs.SendMessage(m_ctlRichInk.NativeHandle,
    WindowsAPIs.EM_SETVIEW, WindowsAPIs.VT_DRAWINGVIEW, 0);
   WindowsAPIs.SendMessage(m_ctlRichInk.NativeHandle,
    WindowsAPIs.EM_SETPENMODE, WindowsAPIs.MODE_PEN, 0);
   WindowsAPIs.SendMessage(m_ctlRichInk.NativeHandle,
    WindowsAPIs.EM_SETINKLAYER, WindowsAPIs.VL_DRAWINGINK, 0);
   WindowsAPIs.SendMessage(m_ctlRichInk.NativeHandle,
    WindowsAPIs.EM_SETPAGESTYLE, WindowsAPIs.PS_RULEDLINES, 0);

   this.Text = "Hosting Sample";
   this.MinimizeBox = false;
  }

#if DESKTOP
  [STAThread]
#endif
  static void Main()
  {
   Application.Run(new SampleForm());
  }

[DllImport ("inkx.dll")]
public static extern void InitInkX();
}
}

using System;
using System.Runtime.InteropServices;

namespace GuiInterop
{
/// <summary>
/// Contains managed wrappers of windows APIs necessary for pinvokes
/// and delegate callbacks.
/// </summary>
public sealed class WindowsAPIs
{
public delegate int WindowProcCallback(IntPtr hwnd, uint msg,
uint wParam, uint lParam);

#if DESKTOP
  [DllImport("user32.dll")]
#else
  [DllImport("coredll.dll")]
#endif
  public extern static int DefWindowProc(IntPtr hwnd, uint msg,
   uint wParam, uint lParam);

#if DESKTOP
  [DllImport("user32.dll")]
#else
  [DllImport("coredll.dll")]
#endif
  public extern static int CallWindowProc(
   IntPtr lpPrevWndFunc, IntPtr hwnd, uint msg, uint wParam,
   uint lParam);

#if DESKTOP
  [DllImport("user32.dll")]
#else
  [DllImport("coredll.dll")]
#endif
  public extern static IntPtr SetWindowLong(IntPtr hwnd,
   int nIndex, IntPtr dwNewLong);

#if DESKTOP
  [DllImport("user32.dll")]
#else
  [DllImport("coredll.dll")]
#endif
  public extern static IntPtr CreateWindowExW(uint dwExStyle,
   string lpClassName, string lpWindowName, uint dwStyle,
   int x, int y, int nWidth, int nHeight, IntPtr hwndParent,
   int hMenu, int hInstance, int lpParam);

#if DESKTOP
  [DllImport("user32.dll")]
#else
  [DllImport("coredll.dll")]
#endif
  public extern static int SetWindowPos(IntPtr hwnd,
   int hwndInsertAfter, int x, int y, int cx, int cy,
   uint flags);

#if DESKTOP
  [DllImport("user32.dll")]
#else
  [DllImport("coredll.dll")]
#endif
  public extern static int SetWindowText(IntPtr hwnd,
   string lpString);

#if DESKTOP
  [DllImport("user32.dll")]
#else
  [DllImport("coredll.dll")]
#endif
  public extern static IntPtr SetFocus(IntPtr hwnd);

#if DESKTOP
  [DllImport("user32.dll")]
#else
  [DllImport("coredll.dll")]
#endif
  public extern static int SendMessage(IntPtr hwnd,
   uint msg, uint wParam, uint lParam);

  public const int
   SWP_NOSIZE              = 0x0001,
   SWP_NOMOVE              = 0x0002,
   SWP_NOZORDER            = 0x0004,
   SWP_NOREDRAW            = 0x0008,
   SWP_NOACTIVATE          = 0x0010,
   SWP_FRAMECHANGED        = 0x0020,
   SWP_SHOWWINDOW          = 0x0040,
   SWP_HIDEWINDOW          = 0x0080,
   SWP_NOCOPYBITS          = 0x0100,
   SWP_NOOWNERZORDER       = 0x0200,
   SWP_NOSENDCHANGING      = 0x0400,
   SWP_DRAWFRAME           = 0x0020,
   SWP_NOREPOSITION        = 0x0200,
   SWP_DEFERERASE          = 0x2000,
   SWP_ASYNCWINDOWPOS      = 0x4000,
   HWND_TOP                = 0,
   HWND_BOTTOM             = 1,
   HWND_TOPMOST            = -1,
   HWND_NOTOPMOST          = -2,
   ES_LEFT     = 0x0000,
   ES_CENTER     = 0x0001,
   ES_RIGHT     = 0x0002,
   ES_MULTILINE    = 0x0004,
   ES_UPPERCASE    = 0x0008,
   ES_LOWERCASE    = 0x0010,
   ES_PASSWORD    = 0x0020,
   ES_AUTOVSCROLL    = 0x0040,
   ES_AUTOHSCROLL    = 0x0080,
   ES_NOHIDESEL    = 0x0100,
   ES_OEMCONVERT    = 0x0400,
   ES_READONLY    = 0x0800,
   ES_WANTRETURN    = 0x1000,
   ES_NUMBER     = 0x2000,
   GWL_EXSTYLE    = (-20),
   GWL_STYLE     = (-16),
   GWL_WNDPROC    = (-4),
   GWL_HINSTANCE   = (-6),
   GWL_HWNDPARENT   = (-8),
   GWL_USERDATA   = (-21),
   GWL_ID     = (-12),
   WHEEL_DELTA    = 120,
   WM_NULL = 0x0000,
   WM_CREATE = 0x0001,
   WM_DESTROY = 0x0002,
   WM_MOVE = 0x0003,
   WM_SIZE = 0x0005,
   WM_ACTIVATE = 0x0006,
   WA_INACTIVE = 0,
   WA_ACTIVE = 1,
   WA_CLICKACTIVE = 2,
   WM_SETFOCUS = 0x0007,
   WM_KILLFOCUS = 0x0008,
   WM_ENABLE = 0x000A,
   WM_SETREDRAW = 0x000B,
   WM_SETTEXT = 0x000C,
   WM_GETTEXT = 0x000D,
   WM_GETTEXTLENGTH = 0x000E,
   WM_PAINT = 0x000F,
   WM_CLOSE = 0x0010,
   WM_QUERYENDSESSION = 0x0011,
   WM_QUIT = 0x0012,
   WM_QUERYOPEN = 0x0013,
   WM_ERASEBKGND = 0x0014,
   WM_SYSCOLORCHANGE = 0x0015,
   WM_ENDSESSION = 0x0016,
   WM_SHOWWINDOW = 0x0018,
   WM_WININICHANGE = 0x001A,
   WM_SETTINGCHANGE = 0x001A,
   WM_DEVMODECHANGE = 0x001B,
   WM_ACTIVATEAPP = 0x001C,
   WM_FONTCHANGE = 0x001D,
   WM_TIMECHANGE = 0x001E,
   WM_CANCELMODE = 0x001F,
   WM_SETCURSOR = 0x0020,
   WM_MOUSEACTIVATE = 0x0021,
   WM_CHILDACTIVATE = 0x0022,
   WM_QUEUESYNC = 0x0023,
   WM_GETMINMAXINFO = 0x0024,
   WM_PAINTICON = 0x0026,
   WM_ICONERASEBKGND = 0x0027,
   WM_NEXTDLGCTL = 0x0028,
   WM_SPOOLERSTATUS = 0x002A,
   WM_DRAWITEM = 0x002B,
   WM_MEASUREITEM = 0x002C,
   WM_DELETEITEM = 0x002D,
   WM_VKEYTOITEM = 0x002E,
   WM_CHARTOITEM = 0x002F,
   WM_SETFONT = 0x0030,
   WM_GETFONT = 0x0031,
   WM_SETHOTKEY = 0x0032,
   WM_GETHOTKEY = 0x0033,
   WM_QUERYDRAGICON = 0x0037,
   WM_COMPAREITEM = 0x0039,
   WM_GETOBJECT = 0x003D,
   WM_COMPACTING = 0x0041,
   WM_COMMNOTIFY = 0x0044,
   WM_WINDOWPOSCHANGING = 0x0046,
   WM_WINDOWPOSCHANGED = 0x0047,
   WM_POWER = 0x0048,
   WM_COPYDATA = 0x004A,
   WM_CANCELJOURNAL = 0x004B,
   WM_NOTIFY = 0x004E,
   WM_INPUTLANGCHANGEREQUEST = 0x0050,
   WM_INPUTLANGCHANGE = 0x0051,
   WM_TCARD = 0x0052,
   WM_HELP = 0x0053,
   WM_USERCHANGED = 0x0054,
   WM_NOTIFYFORMAT = 0x0055,
   WM_CONTEXTMENU = 0x007B,
   WM_STYLECHANGING = 0x007C,
   WM_STYLECHANGED = 0x007D,
   WM_DISPLAYCHANGE = 0x007E,
   WM_GETICON = 0x007F,
   WM_SETICON = 0x0080,
   WM_NCCREATE = 0x0081,
   WM_NCDESTROY = 0x0082,
   WM_NCCALCSIZE = 0x0083,
   WM_NCHITTEST = 0x0084,
   WM_NCPAINT = 0x0085,
   WM_NCACTIVATE = 0x0086,
   WM_GETDLGCODE = 0x0087,
   WM_NCMOUSEMOVE = 0x00A0,
   WM_NCLBUTTONDOWN = 0x00A1,
   WM_NCLBUTTONUP = 0x00A2,
   WM_NCLBUTTONDBLCLK = 0x00A3,
   WM_NCRBUTTONDOWN = 0x00A4,
   WM_NCRBUTTONUP = 0x00A5,
   WM_NCRBUTTONDBLCLK = 0x00A6,
   WM_NCMBUTTONDOWN = 0x00A7,
   WM_NCMBUTTONUP = 0x00A8,
   WM_NCMBUTTONDBLCLK = 0x00A9,
   WM_KEYFIRST = 0x0100,
   WM_KEYDOWN = 0x0100,
   WM_KEYUP = 0x0101,
   WM_CHAR = 0x0102,
   WM_DEADCHAR = 0x0103,
   WM_SYSKEYDOWN = 0x0104,
   WM_SYSKEYUP = 0x0105,
   WM_SYSCHAR = 0x0106,
   WM_SYSDEADCHAR = 0x0107,
   WM_KEYLAST = 0x0108,
   WM_IME_STARTCOMPOSITION = 0x010D,
   WM_IME_ENDCOMPOSITION = 0x010E,
   WM_IME_COMPOSITION = 0x010F,
   WM_IME_KEYLAST = 0x010F,
   WM_INITDIALOG = 0x0110,
   WM_COMMAND = 0x0111,
   WM_SYSCOMMAND = 0x0112,
   WM_TIMER = 0x0113,
   WM_HSCROLL = 0x0114,
   WM_VSCROLL = 0x0115,
   WM_INITMENU = 0x0116,
   WM_INITMENUPOPUP = 0x0117,
   WM_MENUSELECT = 0x011F,
   WM_MENUCHAR = 0x0120,
   WM_ENTERIDLE = 0x0121,
   WM_CHANGEUISTATE = 0x0127,
   WM_UPDATEUISTATE = 0x0128,
   WM_QUERYUISTATE = 0x0129,
   WM_CTLCOLORMSGBOX = 0x0132,
   WM_CTLCOLOREDIT = 0x0133,
   WM_CTLCOLORLISTBOX = 0x0134,
   WM_CTLCOLORBTN = 0x0135,
   WM_CTLCOLORDLG = 0x0136,
   WM_CTLCOLORSCROLLBAR = 0x0137,
   WM_CTLCOLORSTATIC = 0x0138,
   WM_MOUSEFIRST = 0x0200,
   WM_MOUSEMOVE = 0x0200,
   WM_LBUTTONDOWN = 0x0201,
   WM_LBUTTONUP = 0x0202,
   WM_LBUTTONDBLCLK = 0x0203,
   WM_RBUTTONDOWN = 0x0204,
   WM_RBUTTONUP = 0x0205,
   WM_RBUTTONDBLCLK = 0x0206,
   WM_MBUTTONDOWN = 0x0207,
   WM_MBUTTONUP = 0x0208,
   WM_MBUTTONDBLCLK = 0x0209,
   WM_NCMOUSEHOVER = 0x02A0,
   WM_NCMOUSELEAVE = 0x02A2,
   WM_MOUSEWHEEL = 0x020A,
   WM_MOUSELAST = 0x020A,
   WM_PARENTNOTIFY = 0x0210,
   WM_ENTERMENULOOP = 0x0211,
   WM_EXITMENULOOP = 0x0212,
   WM_NEXTMENU = 0x0213,
   WM_SIZING = 0x0214,
   WM_CAPTURECHANGED = 0x0215,
   WM_MOVING = 0x0216,
   WM_POWERBROADCAST = 0x0218,
   WM_DEVICECHANGE = 0x0219,
   WM_IME_SETCONTEXT = 0x0281,
   WM_IME_NOTIFY = 0x0282,
   WM_IME_CONTROL = 0x0283,
   WM_IME_COMPOSITIONFULL = 0x0284,
   WM_IME_SELECT = 0x0285,
   WM_IME_CHAR = 0x0286,
   WM_IME_KEYDOWN = 0x0290,
   WM_IME_KEYUP = 0x0291,
   WM_MDICREATE = 0x0220,
   WM_MDIDESTROY = 0x0221,
   WM_MDIACTIVATE = 0x0222,
   WM_MDIRESTORE = 0x0223,
   WM_MDINEXT = 0x0224,
   WM_MDIMAXIMIZE = 0x0225,
   WM_MDITILE = 0x0226,
   WM_MDICASCADE = 0x0227,
   WM_MDIICONARRANGE = 0x0228,
   WM_MDIGETACTIVE = 0x0229,
   WM_MDISETMENU = 0x0230,
   WM_ENTERSIZEMOVE = 0x0231,
   WM_EXITSIZEMOVE = 0x0232,
   WM_DROPFILES = 0x0233,
   WM_MDIREFRESHMENU = 0x0234,
   WM_MOUSEHOVER = 0x02A1,
   WM_MOUSELEAVE = 0x02A3,
   WM_CUT = 0x0300,
   WM_COPY = 0x0301,
   WM_PASTE = 0x0302,
   WM_CLEAR = 0x0303,
   WM_UNDO = 0x0304,
   WM_RENDERFORMAT = 0x0305,
   WM_RENDERALLFORMATS = 0x0306,
   WM_DESTROYCLIPBOARD = 0x0307,
   WM_DRAWCLIPBOARD = 0x0308,
   WM_PAINTCLIPBOARD = 0x0309,
   WM_VSCROLLCLIPBOARD = 0x030A,
   WM_SIZECLIPBOARD = 0x030B,
   WM_ASKCBFORMATNAME = 0x030C,
   WM_CHANGECBCHAIN = 0x030D,
   WM_HSCROLLCLIPBOARD = 0x030E,
   WM_QUERYNEWPALETTE = 0x030F,
   WM_PALETTEISCHANGING = 0x0310,
   WM_PALETTECHANGED = 0x0311,
   WM_HOTKEY = 0x0312,
   WM_PRINT = 0x0317,
   WM_PRINTCLIENT = 0x0318,
   WM_HANDHELDFIRST = 0x0358,
   WM_HANDHELDLAST = 0x035F,
   WM_AFXFIRST = 0x0360,
   WM_AFXLAST = 0x037F,
   WM_PENWINFIRST = 0x0380,
   WM_PENWINLAST = 0x038F,
   WM_APP = unchecked((int)0x8000),
   WM_USER = 0x0400,
   WM_REFLECT          = WM_USER + 0x1C00,
   WMSZ_LEFT    = 1,
   WMSZ_RIGHT    = 2,
   WMSZ_TOP    = 3,
   WMSZ_TOPLEFT   = 4,
   WMSZ_TOPRIGHT   = 5,
   WMSZ_BOTTOM    = 6,
   WMSZ_BOTTOMLEFT   = 7,
   WMSZ_BOTTOMRIGHT  = 8,
   WS_OVERLAPPED   = 0x00000000,
   WS_POPUP    = unchecked((int)0x80000000),
   WS_CHILD    = 0x40000000,
   WS_MINIMIZE    = 0x20000000,
   WS_VISIBLE    = 0x10000000,
   WS_DISABLED    = 0x08000000,
   WS_CLIPSIBLINGS   = 0x04000000,
   WS_CLIPCHILDREN   = 0x02000000,
   WS_MAXIMIZE    = 0x01000000,
   WS_CAPTION    = 0x00C00000,
   WS_BORDER    = 0x00800000,
   WS_DLGFRAME    = 0x00400000,
   WS_VSCROLL    = 0x00200000,
   WS_HSCROLL    = 0x00100000,
   WS_SYSMENU    = 0x00080000,
   WS_THICKFRAME   = 0x00040000,
   WS_GROUP    = 0x00020000,
   WS_TABSTOP    = 0x00010000,
   WS_MINIMIZEBOX   = 0x00020000,
   WS_MAXIMIZEBOX   = 0x00010000,
   WS_TILED    = 0x00000000,
   WS_ICONIC    = 0x20000000,
   WS_SIZEBOX    = 0x00040000,
   WS_OVERLAPPEDWINDOW = (0x00000000|0x00C00000|0x00080000|0x00040000|0x00020000|0x00010000),
   WS_POPUPWINDOW   = (unchecked((int)0x80000000)|0x00800000|0x00080000),
   WS_CHILDWINDOW   = 0x40000000,
   WS_EX_DLGMODALFRAME = 0x00000001,
   WS_EX_NOPARENTNOTIFY = 0x00000004,
   WS_EX_TOPMOST   = 0x00000008,
   WS_EX_ACCEPTFILES  = 0x00000010,
   WS_EX_TRANSPARENT  = 0x00000020,
   WS_EX_MDICHILD   = 0x00000040,
   WS_EX_TOOLWINDOW  = 0x00000080,
   WS_EX_WINDOWEDGE  = 0x00000100,
   WS_EX_CLIENTEDGE  = 0x00000200,
   WS_EX_CONTEXTHELP  = 0x00000400,
   WS_EX_RIGHT    = 0x00001000,
   WS_EX_LEFT    = 0x00000000,
   WS_EX_RTLREADING  = 0x00002000,
   WS_EX_LTRREADING  = 0x00000000,
   WS_EX_LEFTSCROLLBAR = 0x00004000,
   WS_EX_RIGHTSCROLLBAR = 0x00000000,
   WS_EX_CONTROLPARENT = 0x00010000,
   WS_EX_STATICEDGE  = 0x00020000,
   WS_EX_APPWINDOW   = 0x00040000,
   WS_EX_OVERLAPPEDWINDOW = (0x00000100|0x00000200),
   WS_EX_PALETTEWINDOW = (0x00000100|0x00000080|0x00000008),
   WS_EX_LAYERED   = 0x00080000,
   WS_EX_NOINHERITLAYOUT = 0x00100000,
   WS_EX_LAYOUTRTL   = 0x00400000,
   WS_EX_NOACTIVATE  = 0x08000000,
   EM_SETVIEW    = WM_USER + 284,
   EM_CANPASTE    = WM_USER + 50,
   EM_CANREDO    = WM_USER + 246,
   EM_CLEARALL    = WM_USER + 331,
   EM_GETPAGESTYLE   = WM_USER + 323,
   EM_GETPENMODE   = WM_USER + 328,
   EM_GETVIEW    = WM_USER + 254,
   EM_GETWRAPMODE   = WM_USER + 227,
   EM_GETZOOMPERCENT  = WM_USER + 289,
   EM_INSERTLINKS   = WM_USER + 333,
   EM_REDOEVENT   = WM_USER + 235,
   EM_SETINKLAYER   = WM_USER + 288,
   EM_SETPAGESTYLE   = WM_USER + 287,
   EM_SETPENMODE   = WM_USER + 329,
   EM_SETVIEWATTRIBUTES = WM_USER + 332,
   EM_SETWRAPMODE   = WM_USER + 319,
   EM_SETZOOMPERCENT  = WM_USER + 290,
   EM_STREAMIN    = WM_USER + 73,
   EM_STREAMOUT   = WM_USER + 74,
   EM_UNDOEVENT   = WM_USER + 234,
   VT_TYPINGVIEW   = 0,
   VT_WRITINGVIEW   = 2,
   VT_DRAWINGVIEW   = 3,
   VL_SMARTINK    = 0,
   VL_WRITINGINK   = 1,
   VL_DRAWINGINK   = 2,
   VL_LINKS    = 3,
   VL_SMARTLINKS   = 4,
   PS_LEFTMARGIN   = 0x0000,
   PS_TOPMARGIN   = 0x0001,
   PS_RULEDLINES   = 0x0002,
   PS_GRIDLINES   = 0x0004,
   PS_TOPLEFTMARGIN  = 0x0008,
   PS_NONE     = 0x0010,
   PS_DOTTEDLINES   = 0x0020,
   PS_YELLOWBACKGROUND  = 0x0040,
   MODE_PEN    = 0,
   MODE_SELECT    = 1,
   MODE_SPACE    = 2;
}
}

[Author: Katie Blanch]

Disclaimers:
This posting is provided "AS IS" with no warranties, and confers no rights.
Some of the information contained within this post may be in relation to beta software. Any and all details are subject to change.

Interop: Common Issues & Debugging Techniques

NetCFTeam — Sun, 24 Jul 2005 10:48:00 GMT

Interop: Common Issues and Debugging Techniques

This post will describe some of the types of problems that can arise when interoperating between managed and native code using the .Net Compact Framework Version 2. An overview of how the runtime works under the scenes is also given, which may help promote better quality and more efficient code as well as give insight into the cause of problems.

Marshaling

When interoperating with native code, a conversion process is necessary to translate argument data between managed and native code. The .Net Compact Framework supports marshaling many different managed types, both to and from native code. Each managed type that is supported has default marshaling behavior, which may be different depending on the type of call being made (COM interface function call, delegate callback, or PInvoke). You can also override the default marshaling behavior by using the MarshalAs attribute. The runtime will marshal (or convert) data automatically when an interop function call is made, as specified in the managed PInvoke signature, delegate callback signature, or COM interface signature. You can also use the functions in the InteropServices.Marshal class to manually convert data between managed objects and an IntPtr representing the native object. For some examples, see GetIUnknownForObject, GetObjectForIUnknown, PtrToStringBSTR, StringToBSTR, StructureToPtr, or PtrToStructure.

There are a few types of issues that come up when interoperating with native code that involve the marshaling process:

1. A managed NotSupportedException may be thrown, due to an unsupported type being specified as an argument or return value in the managed interop signature.
Although almost all parameter types the desktop framework supports are now supported in the .Net Compact Framework, there are a few situations where there is limited support. These exceptions include fields in structures, elements in arrays, and return types. The workaround for these limitations is to use the functions in the InteropServices.Marshal class to manually do the conversion process, and specify an IntPtr as the type in the signature or structure.
Interoperating using methods, types, or COM interface classes that are generic is also not supported.
The interop log file will specify the particular method causing the issue, which can be especially useful when using COM interfaces. The best way to diagnose this is to isolate the unsupported type by systematically changing parameter types to IntPtr or a known supported type. Once the unsupported type is identified, consider using another similar type or doing the conversion work manually.
If the unsupported type is identified to be a structure, removing the MarshalAs specifier for structure fields may solve the issue (assuming you can specify a field type that has the appropriate default marshaling behavior). .NetCF will allow only a few limited cases of using the MarshalAs attribute to change the default marshaling behavior of a field in a structure. You can also consider using IntPtr marshaling using the various functions in the InteropServices.Marshal class.
See the resources section for more information about how to determine what the default marshaling behavior is for a particular type.

2. The native function call may not produce the expected results or causes a native exception, due to types being marshaled incorrectly and not matching the specifications of the native function signature.
The best way to diagnose these types of issues is to use the signature output in the interop log file and compare how the runtime is marshaling parameters to what is expected by the native function.
You can then change the types used in the managed signature or use the MarshalAs attribute to ensure data is marshaled correctly. Keep in mind the default marshaling behavior of a particular type will sometimes be different depending on the type of interop call (PInvoke, Com, Delegate callback). The ref keyword must also be applied correctly to the parameters in the managed interop signature. In the event the signature takes a structure parameter, you should also make sure the structure alignment is specified correctly using the StructLayout attribute.
Other common marshaling errors include using a managed 'bool' instead of an 'int' to represent a native Win32 BOOL type. Likewise, an managed 'long' is actually 64 bits and is not equalivant to a Win32 LONG, which is 32 bits.

The .Net Compact Framework has two differences from the desktop framework with regard to default marshaling of types for a PInvoke call, for backward compat reasons.

An 'object' in the managed signature will not marshal into a by value variant, but instead will be 'NULL'. You can override this behavior by using MarshalAs(UnmanagedType.Struct) in your PInvoke signature, which will cause the object to be marshaled as a variant under both .NetCF and the desktop.
A class in the managed signature will not marshal into a CCW, but instead will result in a pointer to a structure in native code. You can override this behavior by using MarshalAs(UnmanagedType.Interface) in your PInvoke signature, which will cause the object to be marshaled as a CCW under both .NetCF and the desktop.

3. A native exception occurs after the native function has returned or at inconsistent times, due to improper use of runtime memory by the native code.
During the marshaling process, the runtime will sometimes place the parameter data inside a temporary buffer or temporarily on the stack. For this reason, it is not always safe for native code to hold a reference to the memory containing marshaled data. Although, in some cases this will work with our current implementation depending on the particular types marshaled, it is recommended that native code always copy data into its own buffer when marshaling any complex types.
If you must avoid copying data, use an IntPtr in your managed interop signature. In the event you are passing a pointer associated with managed object data to native code that will live beyond the return of the native function call, be aware that the GC can cause objects to move around. It is recommended that you maintain a pinned reference to the object, by using a GCHandle.
When returning from a native function call, the marshaler will free native memory associated with arguments after the back propagation into the managed object has completed. This includes cases where only out-marshaling has occurred as well as cases where the content pointed to has changed while in the native function. The runtime will use CoTaskMemFree (or SysFreeString in the case of BSTRs), and expects any non-null memory returned to have been allocated with CoTaskMemAlloc. When necessary, the runtime will free both the original data allocated during the in-marshaling process, and the new data allocated inside the native function call. To avoid this behavior, you can use IntPtr in the managed interop signature, in which case you are then responsible for cleaning up the memory yourself. The types that are affected by this include, but are not limited to, Formatted Classes, Strings, StringBuilders, and Arrays.
You must also use IntPtr marshaling when interacting with native APIs that will return data from the middle of an allocated buffer, such as VerQueryValue. You can see more information about cases where IntPtr marshaling may be necessary for certain APIs here:
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpguide/html/cpconmemorymanagement.asp

4. There appears to be a memory leak when using BSTR marshaling, due to a native cache in the Windows CE OS.
The memory used for BSTR allocations is cached, so a BSTR is not always freed completely upon a call to SysFreeString. There is currently no way to turn this cache off under Windows CE, and given the low memory conditions of embedded devices this may present itself as an unacceptable memory leak. To work around this issue, consider using CoTaskMemFree instead of SysFreeString, which prevents any free space in the cache from accumulating.

The runtime will use SysFreeString under two conditions:

During the marshaling process when you specify MarshalAs(UnmanagedType.BSTR) for a parameter, array element, or structure field. You can prevent this from happening by using IntPtr marshaling, and manually converting strings to BSTRs before calling the native function using InteropServices.Marshal.StringToBSTR.
The Marshal.FreeBSTR managed API maps directly to SysFreeString.

The native COM component being used will also need to be screened for SysFreeString use.
You can see some more information about the BSTR cache here:
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/automat/htm/chap7_2xgz.asp

Making Native function calls from Managed code

There are 2 main types of managed to native function calls:

PInvoke - Using the DLLImport attribute, a signature is defined in managed code that corresponds to an exported function in a native .dll.
COM interface method call - a Runtime Callable Wrapper (RCW) object is instantiated in managed code that wraps a native COM object and then cast to a managed interface describing the native COM interface.
- COM VTable call - For interfaces that are declared as Dual or IUnknown, the runtime will call the method directly through the VTable.
- COM Dispatch call - For interfaces that are declared as pure IDispatch, the runtime will call the method through the use of IDispatch->Invoke.

In all three of these cases, there is a stub generated that converts between the managed calling convention and the native calling convention. In order to create this stub, the signature of the PInvoke or COM interface method is processed and any error checking that only requires knowledge of the parameter types and not the actual data occurs.
During runtime when the function is called and this stub is executed, the arguments are in-marshaled as specified, then the native function is called, and finally the out-marshaling occurs along with some runtime post-processing, cleanup, and error handling. If an exception occurs during the in-marshaling process, the native function will not be called.
If a native function call is considered PreserveSig(false), the runtime will assume the native function returns a HResult. In the event that a failure HResult is returned, the runtime will translate this into a managed exception, and managed objects used as parameters will not necessarily be modified or initialized during the out-marshaling process as normal. In this case, you must also keep in mind that the managed signature will not look exactly like the native signature. You can use interop logging to determine the exact native signature the runtime will be expecting. For COM calls PreserveSig defaults to false, where as for PInvoke calls it defaults to true, if not explicitly specified.

Knowledge of this process can help you diagnose and handle a few common issues:

5. A MissingMethodException occurs when trying to call a PInvoke function, due to the .dll not being found by the runtime or because the function requested is not exported as specified in the native .dll.
In this case, the exception occurs at stub generation time rather then at runtime. Normally a PInvoke function is jitted upon its first call, however you can use the Marshal.PreLink function to force the runtime to jit the stub, allowing you to handle these cases smoothly in managed code and present the user with an appropriate message.
If the runtime is failing to find the native .dll, ensure it is present and consider writing a simple native application that calls LoadLibraryW to load the .dll. In some cases under generic windows CE, a native .dll may have a dependency on the components of the image, and may fail to load if the dependencies are not present in the image.
If the runtime is failing to find the particular exported function in the native .dll, ensure the function is present and properly exported using the dumpbin utility as described here: http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnnetcomp/html/netcfdumpbinpinvoke.asp. Keep in mind, you can reference the exported functions either by ordinal or name.

6. A managed exception occurs when calling a native function from managed code, due to a runtime marshaling issue.
In the case a PInvoke function call is being made, it is worthwhile to use Marshal.PreLink and ensure no exceptions are thrown. This will rule out jit-time errors that occur when the stub is generated, such as those resulting from unsupported marshaling types. Some marshaling issues will not occur until the function is called and the actual conversion work happens. These typically happen when trying to convert a native object into a managed object, either during the out-marshaling process of a managed to native function call, or during the in-marshaling process of a native to managed call. Some types have specific ranges in which the data is valid, such as the case with the DateTime type. In the case of VARIANTs, the runtime many not be able to coerce the type specified inside the native variant to the managed type specified in the function signature.
The best practice to diagnose these issues is to use a process of elimination to determine the particular parameter causing the issue. You can use the [in] and [out] attributes to prevent marshaling in a particular direction for each parameter.

7. A native COM function results in an unexpected managed exception or the native function behaves incorrectly, due to the managed COM interface signatures being incorrect with regard to the PreserveSig attribute.
If the PreserveSig attribute is used incorrectly, the runtime will assume an incorrect native signature and may call the function with un-initialized parameters, or interpret the return valid as a failure HResult when the native function does not return a HResult.
The interop log file will reveal the expected native signature, and this should be compared to the documentation associated with the COM interface.

Making Managed function calls from Native code

There are 2 main types of native to managed function calls:

Delegate Callbacks - You can marshal a delegate down to native code as a function pointer
COM interface method call - a Com Callable Wrapper (CCW) is associated with a managed object and used to expose interfaces that object implements to native code.
- COM VTable call - For interfaces that are declared as Dual or IUnknown, native code can directly call managed methods
- COM Dispatch call - For interfaces that are declared as pure IDispatch and Dual, native code can call managed methods through the use of IDispatch->Invoke.

The process for making callbacks from native code into managed code is similar to the other direction. Both stub generation errors and runtime errors are possible. Likewise, based on the PreserveSig attribute, the runtime may translate managed exceptions to HResults. If the managed function call is considered PreserveSig(false) and an uncaught exception occurs while in managed code, the runtime will return a HResult associated with the exception to the native caller. For COM calls PreserveSig defaults to false, where as for delegate callbacks it results to true, if not explicitly specified. If a COM call is marked as PreserveSig(true) and the managed signature returns a 4-byte value such as an int, the runtime will still translate any uncaught exceptions to a HResult.
The .Net Compact Framework does not support hosting the runtime from native code. This means that you will not be able to call CoCreateInstace to instantiate a managed object, or register managed objects as COM objects on the system. You will also not be able to call CorBindToRuntime or ClrCreateManagedInstance. In order to call managed functions from native code, you must first use the runtime to marshal a managed interface or a delegate down to native code. This means you must always start out in managed code (with a .net executable) in order to expose .net components to native code.

8. A native exception occurs when attempting to call a Delegate callbacks from native code, due to the managed delegate being finalized.
When using delegate callbacks, you often first make a PInvoke call to register the callback function pointer which will be used after the original PInvoke call returns. Because the generated stub associated with the callback stub is cleaned up when a delegate is finalized, you must ensure the delegate object stays alive until it will no longer be used by native code. Simply keeping a reference to the delegate in managed code will be enough to keep it alive (there is no need to pin the delegate object).

9. Native code that uses native to managed function calls is behaving unexpectedly because of a managed exception firing or runtime marshaling errors, due to interface signatures being incorrect with regard to the PreserveSig attribute.
When a managed exception occurs inside a managed function call that is not caught before the call returns, operating under PreserveSig(false) is the only way to ensure this exception will be translated to a HResult and properly returned from the managed call so native code can handle the error. If operating under preserveSig(true), it is recommended that you wrap a try/catch around your exposed managed function to ensure there are no uncaught exceptions and handle any errors in managed code since native code will not be able to know there was an error or handle it properly. Also keep in mind, that an exception can also occur due to a runtime marshaling error and cause the managed function to not be called.

10. A CCW function call works when called through the VTable, but not when called through IDispatch->Invoke despite the interface being marked as InterfaceIsDual, due to missing or improper use of attributes.
Individual methods, as well as interfaces, can be marked ComVisible. When a method is marked ComVisible(false), a VTable stub is still generated for it allowing it to be called directly through the VTable, but it is protected from being called through IDispatch->Invoke. In the case of properties, the individual get or set method is checked, as well as the property declaration itself.
If native code calls QueryInterface requesting a pure IDispatch pointer, the runtime will return the interface that it has determined is the 'default interface' that supports IDispatch. Typically, under the desktop framework this resolves to the class interface and exposes all methods to native code. Under .NetCF, since class interfaces are not automatically generated, this will resolve to the first interface present in metadata that the class implements which supports IDispatch. It's recommended that you explicitly declare a default interface using the ComDefaultInterfaceAttribute.
For methods to be exposed through IDispatch, they must be explicitly marked with the DispIdAttribute.
If native code is relying on IDispatch->GetIDsOfNames to resolve methods, there are a couple of limitations. The interop log file will contain more detailed output if unsupported functionallity is being requested or an error is being returned to native code from GetIDsOfNames.

COM Interop

The .Net Compact Framework supports interoperating with native COM objects from managed code as well as allowing native code to interact with managed objects using COM.

Runtime Callable Wrappers (RCWs) - these are used to allow managed code to call native COM object functions.
- There are 3 ways to create an RCW:
  - You can use a tool called tlbimp to import a type library (shipped with the native COM object), and spit out a managed .dll. This managed .dll will contain a bunch of interfaces associated with the native COM interfaces supported by the object. It will also contain a managed class (with a guid and ComImport attribute specified) that is associated with the actual COM object. When this managed class is instantiated, the runtime will make a call to CoCreateInstance and instantiate the native COM object. Using this method requires that the native COM object has been properly registered with the system and the guid is present in the registry for lookup.
  - You can then use the following code to manually instantiate an object
    
    Type t = Type.GetTypeFromCLSID(new Guid("2CD19942-4103-4dcc-A75C-57DF5814C611") ); // This guid is associated with the COM object itself, not the native COM interfaces you'd like to use to interact with the object
    
    Object obj = Activator.CreateInstance(t); // This causes the runtime to call CoCreateInstance
    
    Alternatively, you can use Type.GetTypeFromProgID to use the registry to resolve a string into a GUID associated with a native COM object.
    Using this method requires that the native COM object has been properly registered with the system and the guid and\or progID is present in the registry for lookup.
  - You can also create an RCW object via marshaling when making a managed to native call that causes a COM object to be out-marshaled. For example, a native .dll can have a 'CreateComObject' exported function that returns a native COM object, and therefore doesn't require the native COM object to be registered by the system.
- The runtime will hide many of the rules that are required when using native COM objects. For example, you don't need to manually call QueryInterface in managed code. Simply casting an RCW object to a particular interface causes the runtime to do a QueryInterface under the scenes, and a managed InvalidCast exception is thrown if the native COM object doesn't support the guid associated with the casted interface. The runtime also handles the reference counting details.
Com Callable Wrappers (CCWs) - these are used to allow native code to call managed functions exposed through COM interfaces.
- CCWs are created when an object is marshaled down to native code as an interface. Once in native code, other interfaces can be retrieved using QueryInterface, including a number of runtime implemented interfaces such as IConnectionPointContainer. You can call managed functions directly through the VTable, or through IDispatch->Invoke depending on the type of COM interface as declared in managed code. The native code must abide by normal reference counting and COM rules when interacting with CCWs.

TlbImp is the only tool supported under the .Net Compact Framework. While the use of other tools, such as AxImp, and TlbExp may work in some cases, they are not tested and may not always produce code that will run without modification under the .Net Compact Framework.

11. There appears to be a memory leak when using COM interop features, due to Runtime Callable Wrappers not being freed immediately.
Normally, RCWs are freed upon finalization when the managed object associated with the native COM object is no longer in use and the GC starts collecting object memory. At this point, the original object returned from CoCreateInstance is Released, along with any interface pointers that the runtime called QueryInterface to retrieve.
Marshal.ReleaseComObject and Marshal.FinalReleaseComObject can be used to manage the lifetime of an RCW manually. Keep in mind that once these are used you will not be able to make native COM interface method calls using the object any longer and will receive an exception upon attempting to do so.
There is also a native bug in Windows CE TypeLib support that can cause a memory leak when a native COM object that uses LoadTypeLib or LoadRegTypeLib is freed from a thread other then the one it was created on, including the thread finalizers are run on. In this case, it is highly recommended you use the marshal class functions to manually release the native COM object.

12. A native control doesn't appear properly or doesn't work properly when using COM interop features to host an ActiveX control in a managed Form, due to a bad ActiveX container implementation.
Be sure to review the following references and understand how to write a container in native code.
http://msdn.microsoft.com/library/default.asp?url=/workshop/components/containers/overview/containers.asp
http://msdn.microsoft.com/library/default.asp?url=/workshop/components/activex/intro.asp
It is also recommended that you create a simple native ActiveX control to test your container with (possibly using the Visual Studio MFC wizard), which will allow you to debug into the native source of the control.
When debugging an ActiveX container implementation, it may helpful to examine the interop log file for cases where native code called QueryInterface and received an E_NOINTERFACE return value. This can help you diagnose when a required interface was not implemented by the container.
If the application is running, but the control doesn't appear in the form, use the Remote Spy tool to examine the window hierarchy and position/sizing of the native control and its parents.

13. A native exception or memory leak occurs when using Com Callable Wrappers to provide native code an interface mapping to managed functions, due to improper reference counting logic.
A CCW will be cleaned up upon the last reference count release from native code. Native code is expected to release any interfaces it acquired from a call to QueryInterface, as well as other functions that return an interface (such as IConnectionPointContainer::FindConnectionPoint for example).
If native code wishes to keep a reference to a CCW beyond the return from the PInvoke where a CCW was marshaled down, the particular interface desired should be retrieved through QueryInterface. When the PInvoke returns and the out-marshaling process completes, the CCW will be cleaned up if there are no outstanding references.
When using the runtime implemented connection point interfaces to allow native code to get notified when a managed event fires, the runtime will increment the CCW reference count upon a call to IConnectionPoint::Advise. Native code must call IConnectionPoint::Unadvise when it no longer wishes to be notified of managed events firing or the CCW will not be cleaned up.
You can use the Marshal Class functions to retrieve an IntPtr representing an interface from a managed object (See GetIUnknownForObject), You can also examine the current reference count for an IntPtr representing an interface (including a CCW) by using Marshal.AddRef and Marshal.Release (which both return the current reference count).

14. A managed exception occurs when instantiating or using a Runtime Callable Wrapper or a Com Callable Wrapper despite the same code working on the desktop framework, due to limitations in com interop support under the .Net Compact Framework.
The interop log file will often contain more detailed information about the cause of an exception that occurs due to differences in COM interop support between the desktop framework and the .Net Compact framework.

The .Net Compact Framework does not support class interfaces. Under the desktop, a class interface will be automatically generated for any managed objects exposed as CCWs to native code, allowing you to directly access any field members or functions present in the class. Under the .Net Compact Framework, all functionality you wish to expose must be wrapped in an interface. It is also recommended that you explicitly mark classes as ClassInterfaceType.None using the ClassInterfaceAttribute, when passing classes directly to native code.
The .Net Compact Framework will not automatically generate a guid for interfaces lacking an explicitly defined guid. If an interface is marked ComVisible(true) and is exposed to native code, it must also have a guid specified or an exception will occur.
The .Net Compact Framework does not allow you to inherit from an interop assembly class generated through the use of tlbimp.
The .Net Compact Framework does not support STAThread COM initialization, because Windows Mobile does not allow you to initialize COM in this way.
The .Net Compact Framework has some marshaling support differences from the desktop framework.
The .Net Compact Framework has marked all base class libraries as ComVisible(false) at the assembly level, which requires developers to wrap any BCL functionality they wish to expose to native code.
The .Net Compact Framework has some subtle differences in the logic to determine COM visibility for interfaces.
- Any generic or open type interfaces are automatically not visible to COM.
- Any classes marked as ComImport are visible to COM.
- Any classes without the public access modifier are considered to be not visible to COM.
- Finally the class is checked the ComVisible attribute. If it is not present, the assembly is checked for the ComVisible attribute. If the ComVisible attribute is not declared then the default is ComVisible(true).
- This logic is shared between RCWs and CCWs.
  - For the RCW case, if an interface is not considered to be visible to COM, then you will not be able to cast to it. (The runtime will not attempt to call QueryInterface on the native COM object associated with the RCW object).
  - For the CCW case, if an interface is not considered to be visible to COM, then native code will not be able to successfully call QueryInterface requesting it. Developers will also not be able to marshal an interface not visible to COM down to native code.

15. A managed InvalidComObjectException occurs when using a Runtime Callable Wrapper to call a native COM function, due to the Runtime Callable Wrapper having been freed previously.
If the application has used Marshal.ReleaseComObject or Marshal.FinalReleaseComObject, you will not be able to make native COM interface method calls using the object any longer. If an attempt to do this has been made upon a previously valid RCW object, the interop log file will contain an error message.

16. A managed InvalidComObjectException occurs when attempting to instantiate a Com Callable Wrapper, due to the use of a type that requires an unsupported marshaling feature.
When a CCW is constructed, the object's entire interface hierarchy is walked by the runtime. All interface methods visible to COM that are implemented will have a stub generated for them to allow the managed function call from native code. If the runtime cannot marshal any parameter type for any method, the entire CCW will not be able to be constructed. The interop log file will contain more information specifying the exact method containing the issue.

Resources

With regard to COM interop support, it may be useful to understand both the rules around using and building native COM objects, as well as how COM is integrated and supported in the .Net runtime. I like the following sources:
1) Inside COM, by Dale Rogerson (red book)
2) .Net and COM, by Adam Nathan (blue book)

There are interop related guidelines and tips that can drastically improve your application's performance: http://blogs.msdn.com/netcfteam/archive/2005/05/04/414820.aspx

Default marshaling for various types:
Arrays: http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpguide/html/cpcondefaultmarshalingforarrays.asp
Boolean: http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpguide/html/cpcondefaultmarshalingforbooleans.asp
Classes: http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpguide/html/cpcondefaultmarshalingforclasses.asp
Value Types / Structs: http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpguide/html/cpcondefaultmarshalingforvaluetypes.asp
Strings: http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpguide/html/cpcondefaultmarshalingforstrings.asp
Objects: http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpguide/html/cpcondefaultmarshalingforobjects.asp

[Author: Katie Blanch]

Interop Log File Information

NetCFTeam — Sun, 24 Jul 2005 10:44:00 GMT

This information will be included on MSDN soon...

How to: Create Log Files

Introduction

You can create log files with diagnostic information about interoperability, loading the application, and networking. You can enable logging by setting the registry keys.

By default, log files are written to the same directory containing the application being diagnosed. However, you can you can specify a path and other options with registry keys as follows:

Use an alternate path to write the log files. This requires privileged access to the secure registry.
Include the application name in the log file name.
Include the process ID in the log file name.

A log file has the following parts: "netcf_" + (Application name) + (component) + (Process ID) + ".log".
[component] corresponds to the type of logging information, either Interop, Loader, or Network.
[Application name] is optional and [process ID] are optional and are specified with registry settings.

For example, a Loader log file for "MyApp.exe" with the application name and process ID would be: netcf_MyApp_Loader_2066923010.log

Procedures

To enable logging:
Set the Enabled key value 1: HKLM\Software\Microsoft\.NETCompactFramework\Diagnostics\Logging\Enabled
This key value must be set to enable the three types of logging: Interop, Loader, and Networking. Note that the sub keys under Logging do not exist by default.
You can turn off all logging by setting this value to zero.

To specify a path for the log file (optional):
Set the Path key value to a string: HKLM\Security\.NETCompactFramework\Diagnostics\Logging\Path
This key is only accessible by applications that can write to the secure registry. If a path is not specified, the log file is written to the same directory containing the application.

To include the application in the name (optional):
Set the UseApp key value to 1: HKLM\Software\Microsoft\.NETCompactFramework\Diagnostics\Logging\UseApp
This key is useful if you want to run multiple applications and get separate log files. If there are two applications writing log files to the same directory, the older log file will always get overwritten with the newer log file when the second application is run. This key can be used as a differentiator for the log file.

To include the process ID in the name (optional):
Set the UsePid key value to 1: HKLM\Software\Microsoft\.NETCompactFramework\Diagnostics\Logging\UsePid
This key is useful if you want to run the same application but have separate logs. This adds the process ID to the log file name, so that each run of the same application creates a new log file with a different name.

To log events as they occur (optional):
Set the Flush key value to 1: HKLM\Software\Microsoft\.NETCompactFramework\Diagnostics\Logging\Flush
This value causes the common language runtime to write log events to the log file as they occur instead of keeping them in the buffer and writing then when the buffer is full. Flushing negatively affects performance of the application and might modify timing of the application slightly since every piece of logging information is written out immediately, but it can be useful to diagnose problems related to application crashes or other errors where you might want to get the last few logs that resulted in the crash. If this key is not present or not set, then the default operation is to not flush.

To enable Interop logging:
Set the Enabled key value to 1: HKLM\Software\Microsoft\.NETCompactFramework\Diagnostics\Logging\Interop\Enabled

To enable Loader logging:
Set Enabled value to 1 to enable Loader logging, or set to 2 to enable Loader and GAC related logging: HKLM\Software\Microsoft\.NETCompactFramework\Diagnostics\Logging\Loader\Enabled

To enable Networking logging:
Set the Enabled value to 1: HKLM\Software\Microsoft\.NETCompactFramework\Diagnostics\Logging\Networking\Enabled
The networking log file is binary and cannot be read without the viewer, which is not currently available.

Interop Log Files

The output for interop logging consists of the signatures of interop function calls as they occur at run time, as well as any error messages.

Function Signatures

The signatures for both managed-to-native and native-to-managed calls are logged, and include the following types of calls:

Platform invoke calls.
COM vtable and Dispatch calls.
Delegate callbacks.

These function signatures can help you troubleshoot problems when calling or returning from an interop function call, such as when a parameter is not initialized as expected or when the program terminates unexpectedly.

The output for a function signature entry consists of three lines for each interop call:

Line 1) The first line represents flags identifying the type of function call made, and has one or more of the following elements:

[pinvokeimpl] - A managed-to-native call that uses the System.Runtime.InteropServices.DllImportAttribute attribute.
[Ctor] - A constructor for an interop assembly class, generated by the Type Library Importer (Tlbimp.exe).
[preservesig] - The managed and native functions are assumed to have the same signature, with no translation from HRESULT to exception enforced by the runtime.
[delegate] - Indicates that the function is a native-to-managed delegate callback. The delegate acts as a function pointer in native code.

Line 2) The second line of the interop log file represents the managed signature. For managed-to-native function calls, this line identifies the managed function that describes the PInvoke or com interface method. For native-to-managed function calls, this line identifies the managed function that is being called from native code.

Line 3) The third line represents the native signature, as expected by the runtime. This line identifies data types for each parameter and provides information about how the managed object data is marshaled. The runtime assumes the correct types are specified by the System.Runtime.InteropServices.DllImportAttribute or in the COM interface signature definition. Failure to specify the correct types is a common error that can result in unexpected behavior because the function called is executed with incorrect parameter values.
Every type has a default marshaling type. Note that the marshaling behavior of a managed type can differ between COM calls and System.Runtime.InteropServices.DllImportAttribute calls or delegate callback calls. You can use the System.Runtime.InteropServices.MarshalAsAttribute attribute to specify a marshaling type other then the default. You must also use the ref keyword to identify parameters that are expected to be pointers in native code.

The following example shows a signature entry for a PInvoke call:

1) [pinvokeimpl][preservesig]
2) bool PlatformDetector::SystemParametersInfo(uint , uint , System.Text.StringBuilder , uint );
3) BOOLEAN (I1_WINBOOL_VAL) SystemParametersInfo(unsigned int (U4_VAL) , unsigned int (U4_VAL) , WCHAR * (STRINGBUILDER_LPWSTR) , unsigned int (U4_VAL) );

The following example shows a signature entry for a delegate callback.

1) [preservesig][delegate]
2) int WndProc::Invoke(WndProc , IntPtr , uint , uint , int );
3) int (I4_VAL) (*)(INT_PTR (I_VAL) , unsigned int (U4_VAL) , unsigned int (U4_VAL) , int (I4_VAL) )

The following example shows a signature entry for a native-to-managed COM function call, where the runtime returns a failure HRESULT in the event of a managed exception.

1) [no flags]
2) int N2MDualComponentImp.IN2MDualInterface::GetInt(N2MDualComponentImp.IN2MDualInterface This);
3) HRESULT GetInt(IN2MDualInterface *(INTF_VAL) this, [retval] int (I4_VAL) retval);

Error Messages

You should search the interop log file for the keywords ‘ERROR’ and ‘WARNING’. Some situations can cause error messages to be recorded in the log file, which can be especially useful when investigating issues that involve interoperating with native components and DLLs for which the native source code is not available. You can use error messages to help diagnose the following issues:

Native-to-managed function calls:

Calling runtime COM interfaces. An HRESULT error can be returned to native code when a runtime-implemented COM interface function is called. There are several runtime-implemented interfaces, including IUnknown, IDispatch, IConnectionPointContainer, IEnumConnectionPoints, and IConnectionPoint, that native code can call into by using a managed object marshaled as a COM interface. When an error is returned to native code from a function call into one of these interfaces, the runtime prints out an appropriate error message giving the HRESULT and any additional relevant information.
Native code expecting to use functionality that is unsupported, such as the CCW (COM callable wrapper) implementation of IDispatch::GetTypeInfo.
Unimplemented interfaces. Native code may receive an E_NOINTERFACE error from a CCW implementation of IUnknown::QueryInterface where it expects the managed COM object to have implemented an additional interface. In this case, the GUID of the unimplemented interface is also provided.

Managed exceptions:

Managed exceptions can occur inside the managed function call and cause it to return prematurely. When making a COM call, the runtime converts the exception into a failure HRESULT and returns this back to native code. However, for delegate callbacks and COM calls that do not expect HRESULT return values, there is no way to ensure native code is made aware of the error, and you may see unexpected behavior as a result. The interop log will contain an error message when an exception happens during a native-to-managed interop function call, helping you identify managed functions that need additional error-handling logic to work well with native code. The following factors can cause a managed exception.
Using types in your COM interface definition or System.Runtime.InteropServices.DllImportAttribute signature that are not supported by the .NET Compact Framework will cause an exception to occur during the JIT compilation process. There are often alternative options that are acceptable, such as an System.IntPtr .
When either the actual object cannot be coerced to the type specified in the signature or the object data cannot be converted to the type requested, an exception is thrown at run time when the function is called. This usually occurs when converting a native object into a managed object.
Determining what causes an exception when creating a runtime callable wrapper (RCW) or a COM callable wrapper (CCW) is difficult. The interop log file can help determine the cause of these problems when a detailed error message is not provided with the managed exception.
There are differences between .NET Compact Framework implementation of COM interoperability and that of the full .NET Framework. The following situations will cause a managed exception under the .NET Compact Framework:
- Creating a CCW (COM callable wrapper) containing an interface without a specified GUID.
- Instantiating a class that inherits from an interop assembly class.
- Creating a CCW containing a nongeneric interface with a generic method.
Runtime callable wrappers (RCWs) are usually cleaned up upon finalization, but you can also use the System.Runtime.InteropServices.Marshal.ReleaseComObject(System.Object) or System.Runtime.InteropServices.Marshal.FinalReleaseComObject(System.Object) method to release the RCW associated with an object. If you are using these advanced options to manage the lifetime of your objects and you attempt to use the object after it has been freed to make a native COM call, an exception is thrown and the log file contains an error message about the cause of the exception.

[Author: Katie Blanch]

Disclaimers:
This posting is provided "AS IS" with no warranties, and confers no rights.
Some of the information contained within this post may be in relation to beta software. Any and all details are subject to change.