Libraries and binary components provide a common way to reuse software; even the simplest C program is linked to the standard C runtime to benefit from core functions such as memory management and I/O. Modern programs depend on a large number of libraries that are shipped in binary form, and only some of them are written in the same language as the program. Libraries can be linked statically during compilation into the executable or can be loaded dynamically during program execution. Dynamic linking has become significantly common to help share code (dynamic libraries can be linked by different programs and shared among them) and adapt program behavior while executing.

Interoperability among binaries compiled by different compilers, even of the same language, can be a nightmare. One of the goals of the .NET initiative was to ease this issue by introducing the Common Language Runtime (CLR), which is targeted by different compilers and different languages to help interoperability among software developed in those languages.

The CLR is a runtime designed to run programs compiled for the .NET platform. The binary format of these programs differs from the traditional one adopted by executables; Microsoft terminology uses managed for the first class of programs and unmanaged otherwise (see Figure 17-1).

Figure 17.1. Compilation scheme for managed and unmanaged code

A Deeper Look Inside .NET Executables

Programs for the .NET platform are distributed in a form that is executed by the CLR. Binaries are expressed in an intermediate language that is compiled incrementally by the Just-In-Time (JIT) compiler during program execution. A .NET assembly, in the form of a .dll or an .exe file, contains the definition of a set of types and the definition of the method bodies, and the additional data describing the structure of the code in the intermediate language form is known as metadata. The intermediate language is used to define method bodies based on a stack-based machine, where operations are performed by loading values on a stack of operands and then invoking methods or operators.

Consider the following simple F# program in the Program.fs source file:

open System
let i = 2
Console.WriteLine("Input a number:")
let v = Int32.Parse(Console.ReadLine())
Console.WriteLine(i * v)

The F# compiler generates an executable that can be disassembled using the ildasm.exe tool distributed with the .NET Framework. The following screenshot shows the structure of the generated assembly. Because everything in the CLR is defined in terms of types, the F# compiler must introduce the class $Program$ Main in the <StartupCode$applicationname> namespace. In this class, the definition of the main@ static method is the entry point for the execution of the program. This method contains the intermediate language corresponding to the example F# program. The F# compiler generates several elements that aren't defined in the program, whose goal is to preserve the semantics of the F# program in the intermediate language.

If you open the main@ method, you find the following code, which is annotated here with the corresponding F# statements:

.method public static void  main@() cil managed
{
  .entrypoint
  // Code size       38 (0x26)
  .maxstack  4

   // Console.WriteLine("Input a number:")
  IL_0000:  ldstr      "Input a number:"
  IL_0005:  call       void [mscorlib]System.Console::WriteLine(string)

  // let v = Int32.Parse(Console.ReadLine())
  IL_000a:  call       string [mscorlib]System.Console::ReadLine()
  IL_000f:  call       int32 [mscorlib]System.Int32::Parse(string)
  IL_0014:  stsfld     int32 '<StartupCode$ConsoleApplication1>'.$Program::v@4

  // Console.WriteLine(i * v) // Note that i is constant and its value has been inlined
  IL_0019:  ldc.i4.2
  IL_001a:  call       int32 Program::get_v()
  IL_001f:  mul
  IL_0020:  call       void [mscorlib]System.Console::WriteLine(int32)

// Exits
  IL_0025:  ret
} // end of method $Program$Main::main@

The ldxxx instructions are used to load values onto the operand stack of the abstract machine, and the stxxx instructions store values from that stack in locations (locals, arguments, or class fields). In this example, a static field is used for v, and the value of i is inlined using the ldc instruction. For method invocations, arguments are loaded on the stack, and a call operation is used to invoke the method.

The JIT compiler is responsible for generating the binary code that runs on the actual processor. The code generated by the JIT interacts with all the elements of the runtime, including external code loaded dynamically in the form of DLLs or COM components.

Because the F# compiler targets the CLR, its output is managed code, allowing compiled programs to interact directly with other programming languages targeting the .NET platform. Chapter 10 showed how to exploit this form of interoperability, when you saw how to develop a graphic control in F# and use it in a C# application.

Interoperability of F# programs with unmanaged code requires an understanding of the structure of the most important elements of a programming language's runtime. In particular, you must consider how program memory is organized at runtime. Memory used by a program is generally classified in three classes depending on the way it's handled:

As a rule of thumb, top-level variables and static fields belong to the first class, function arguments and local variables belong to the second class, and memory explicitly allocated using the new operator belongs to the last class. The code generated by the JIT compiler uses different data structures to manage memory and automatically interacts with the operating system to request and release memory during program execution.

Each execution thread has a stack where local variables and arguments are allocated when a function or method is invoked (see Figure 17-2). A stack is used because it naturally follows the execution flow of method and function calls. The topmost record contains data about the currently executing function; below that is the record of the caller of the function, which sits on top of another record of its caller, and so on. These activation records are memory blocks used to hold the memory required during the execution of the function and are naturally freed at the end of its execution by popping the record off the stack. The stack data structure is used to implement the automatic memory of the program; and because different threads execute different functions at the same time, a separate stack is assigned to each of them.

Figure 17.2. Memory organization of a running CLR program

Dynamic memory is allocated in the heap, which is a data structure where data resides for an amount of time not directly related to the events of program execution. The memory is explicitly allocated by the program, and it's deallocated either explicitly or automatically depending on the strategy adopted by the runtime to manage the heap. In the CLR, the heap is managed by a garbage collector, which is a program that tracks memory usage and reclaims memory that is no longer used by the program. Data in the heap is always referenced from the stack—or other known areas such as static memory—either directly or indirectly. The garbage collector can deduce the memory potentially reachable by program execution in the future, and the remaining memory can be collected. During garbage collection, the running program may be suspended because the collector may need to manipulate objects needed by its execution. In particular, a garbage collector may adopt a strategy called copy collection that can move objects in memory; during this process, the references may be inconsistent. To avoid dangling references, the memory model adopted by the CLR requires that methods access the heap through object references stored on the stack; objects in the heap are forbidden to reference data on the stack.

Data structures are the essential tool provided by programming languages to group values. A data structure is rendered as a contiguous area of memory in which the constituents are available at a given offset from the beginning of the memory. The actual layout of an object is determined by the compiler (or by the interpreter for interpreted languages) and is usually irrelevant to the program because the programming language provides operators to access fields without having to explicitly access the memory. System programming, however, often requires explicit manipulation of memory, and programming languages such as C let you control the in-memory layout of data structures. The C specification, for instance, defines that fields of a structure are laid out sequentially, although the compiler is allowed to insert extra space between them. Padding is used to align fields at word boundaries of the particular architecture in order to optimize the access to the fields of the structure. Thus, the same data structure in a program may lead to different memory layouts depending on the strategy of the compiler or the runtime, even in a language such as C where field ordering is well defined. By default, the CLR lays out structures in memory without any constraint, which gives you the freedom of optimizing memory usage on a particular architecture, although it may introduce interoperability issues if a portion of memory must be shared among the runtimes of different languages.^[4]

Interoperability among different programming languages revolves mostly around memory layouts, because the execution of a compiled routine is a jump to a memory address. But routines access memory explicitly, expecting that data is organized in a certain way. The rest of this chapter discusses the mechanisms used by the CLR to interoperate with external code in the form of DLLs or COM components.

Component Object Model (COM) is a technology that Microsoft introduced in the 1990s to support interoperability among different programs possibly developed by different vendors. The Object Linking and Embedding (OLE) technology that lets you embed arbitrary content in a Microsoft Word document, for instance, relies on this infrastructure. COM is a binary standard that allows code written in different languages to interoperate, assuming that the programming language supports this infrastructure. Most of the Windows operating system and its applications are based on COM components.

The CLR was initially conceived as an essential tool to develop COM components, because COM was the key technology at the end of 1990s. It's no surprise that the Microsoft implementation of CLR interoperates easily and efficiently with the COM infrastructure.

This section briefly reviews the main concepts of the COM infrastructure and its goals in order to show you how COM components can be consumed from F# (and vice versa) and how F# components can be exposed as COM components.

A COM component is a binary module with a well-defined interface that can be dynamically loaded at runtime by a running program. The COM design was influenced by CORBA and the Interface Definition Language (IDL) to describe a component as a set of interfaces. In the case of COM, however, components are always loaded inside the process using the dynamic loading of DLLs. Even when a component runs in a different process, a stub is loaded as a DLL, and it's responsible for interprocess communication.

When you create an instance of a COM component, you obtain a pointer to an IUnknown interface that acts as the entry point to all interfaces implemented by the component. The QueryInterface method of this interface allows you to get pointers to additional interfaces.

Interface pointers in COM are pointers to tables of pointers defining the method's location. The program must know the layout of the table in order to read the desired pointer and invoke the corresponding method. This knowledge can be compiled into the program (interfaces must be known at compile time) or acquired at runtime by accessing component metadata in the form of an interface named IDispatch or a database called type library.

Because COM components can be compiled by any compiler supporting the generation of memory layouts compatible with the standard, it's necessary for the client to share the same layout for data structures that must be passed or returned by the component methods. The standard type system for COM, defined in ole.dll, defines a simple and restricted set of types. COM types correspond to the Variant type of Visual Basic and provide only basic types and arrays. For structured types, COM requires a custom marshaller to be developed, but this has been rarely used in components that are widely available.

The COM infrastructure provides a memory manager that uses reference counting to automatically free components when they aren't used anymore. Whenever a copy of a pointer to an interface is copied, you must invoke the AddRef method of the IUnknown interface (every interface inherits from IUnknown); and when the pointer is no longer required, you should call the Release method to decrement the counter inside the component. When the counter reaches zero, the component is automatically freed. This strategy of memory management, although more automatic than the traditional malloc/free handling of the heap, has proven to be error prone, because programmers often forget to increment the counter when pointers are copied (risk of dangling pointers) or decrement when a pointer is no longer needed (risk of memory wasted in the garbage).

When Microsoft started developing the runtime that has become the CLR, which was destined to replace the COM infrastructure, several design goals addressed common issues of COM development:

The need for a better component infrastructure led Microsoft to create the CLR, but the following concepts from COM proved so successful that they motivated several aspects of the CLR:

COM Metadata and the Windows Registry

COM components are compiled modules that conform to well-defined protocols designed to allow binary interoperability among different languages. An essential trait of component architectures is the ability to dynamically create components at runtime. It's necessary for an infrastructure to locate and inspect components in order to find and load them. The Windows registry holds this information, which is why it's such an important structure in the operating system.

The HKEY_CLASSES_ROOT registry key holds the definition of all the components installed on the local computer. It's helpful to understand the basic layout of the registry in this respect when you're dealing with COM components. The following is a simple script in JScript, executed^[5] by the Windows Scripting Host, which is an interpreter used to execute Visual Basic and JScript scripts on Windows:

w = WScript.CreateObject("Word.Application");
w.Visible = true;
WScript.Echo("Press OK to close Word");
w.Quit();

This simple script creates an instance of a Microsoft Word application and shows its window programmatically by setting the Visible property to true. Assuming that the script is executed using the wscript command (the default), its execution is stopped until the message box displayed by the Echo method is closed, and then Word is closed.

How can the COM infrastructure dynamically locate the Word component and load it without prior knowledge about it? The COM infrastructure is accessed through the ubiquitous CreateObject method, which accepts as input a string containing the program ID of the COM component to be loaded. This is the human-readable name of the component; but the COM infrastructure was conceived as a foundation of a potentially large number of components and therefore adopted globally unique identifier (GUID) strings to define components. GUIDs are often displayed during software installation and are familiar for their mysterious syntax of a sequence of hexadecimal digits enclosed in curly braces. GUIDs are also used to identify COM classes; these IDs are known as CLSIDs and are stored in the Windows registry as subkeys containing further metadata about the COM object. When CreateObject is invoked, the code infrastructure looks for the key:

HKEY_CLASSES_ROOTWord.ApplicationCLSID

The default value for the key in this example (on one of our computers) is as follows:

{000209FF-0000-0000-C000-000000000046}

Now, you can access the registry key defining the COM component and find all the information relative to the component. The following screenshot shows the content of the LocalServer32 subkey, which says that winword.exe is the container of the Word.Application component. If a COM component should be executed in a process different from that of the creator, LocalServer32 contains the location of the executable. Components are often loaded in-process in the form of a DLL; in this case, the InprocServer32 key indicates the location of the library.

To get a feel for the number of COM components installed on a Windows system, you can use a few lines of F# using fsi.exe as a shell:

> open Microsoft.Win32;;
> let k = Registry.ClassesRoot.OpenSubKey("CLSID");;
val k : RegistryKey
> k.GetSubKeyNames().Length;;
val it : int = 9237
> k.Close();;
val it : unit = ()

The registry is also responsible for storing information (that is, the metadata associated with COM components that describes their interfaces) about type libraries. Type libraries are also described using registry entries and identified by GUIDs available under the registry key:

HKEY_CLASSES_ROOTTypeLib

COM components can be easily consumed from F# programs, and the opposite is also possible by exposing .NET objects as COM components. The following example is similar to the one discussed in the "COM Metadata and the Windows Registry" sidebar; it's based on the Windows Scripting Host but uses F# and fsi.exe:

> open System;;
> let o = Activator.CreateInstance(Type.GetTypeFromProgID("Word.Application"));;
val o : obj
> let t = o.GetType();;
val t : Type = System.__ComObject
> t.GetProperty("Visible").SetValue(o, (true :> Object), null);;
val it : unit  = ()
> let m = t.GetMethod("Quit");;
val m : Reflection.MethodInfo
> m.GetParameters().Length;;
val it : int = 3
> m.GetParameters();;
val it : ParameterInfo []
       = [|System.Object& SaveChanges
             {Attributes = In, Optional, HasFieldMarshal;
              DefaultValue = System.Reflection.Missing;
              IsIn = true;
              IsLcid = false;
              IsOptional = true;
              IsOut = false;
              IsRetval = false;
              Member =
                Void Quit(System.Object ByRef,
                            System.Object ByRef, System.Object ByRef);
              MetadataToken = 134223449;
              Name = "SaveChanges";
              ParameterType = System.Object&;
              Position = 0;
              RawDefaultValue = System.Reflection.Missing;};
           ... more ... |]
> m.Invoke(o, [| null; null; null |]);;
val it : obj = null

Because F# imposes type inference, you can't use the simple syntax provided by an interpreter. The compiler should know in advance the number and type of arguments of a method and the methods exposed by an object. Remember that even though fsi.exe allows you to interactively execute F# statements, it's still subject to the constraints of a compiled language. Because you're creating an instance of a COM component dynamically in this example, the compiler doesn't know anything about this component. Thus, it can be typed as System.Object. To obtain the same behavior as an interpreted language, you must resort to .NET runtime's reflection support. Using the GetType method, you can obtain an object describing the type of the object o. Then, you can obtain a PropertyInfo object describing the Visible property, and you can invoke the SetValue method on it to show the Word main window. The SetValue method is generic; therefore, you have to cast the Boolean value to System.Object to comply with the method signature.

In a similar way, you can obtain an instance of the MethodInfo class describing the Quit method. Because a method has a signature, you ask for the parameters; there are three of them, and they're optional. You can invoke the Quit method by calling the Invoke method and passing the object target of the invocation and an array of arguments that you set to null because arguments are optional.

How can the runtime interact with COM components? The basic approach is based on the COM callable wrapper (CCW) and the runtime callable wrapper (RCW), as shown in Figure 17-3. The former is a chunk of memory dynamically generated with a layout compatible with the one expected from COM components, so that external programs—even legacy Visual Basic 6 applications—can access services implemented as managed components. The latter is more common and creates a .NET type dealing with the COM component, taking care of all the interoperability issues. It's worth noting that although the CCW can always be generated because the .NET runtime has full knowledge about assemblies, the opposite isn't always possible. Without IDispatch or type libraries, there is no description of a COM component at runtime. Moreover, if a component uses custom marshalling, it can't be wrapped by an RCW. Fortunately, for the majority of COM components, it's possible to generate an RCW.

Figure 17.3. The wrappers generated by the CLR to interact with COM components

Programming patterns based on event-driven programming are widely adopted, and COM components have a programming pattern to implement callbacks based on the notion of a sink. The programming pattern is based on the delegate event model, and the sink is where a listener can register a COM interface that should be invoked by a component to notify an event. The Internet Explorer Web Browser COM component (implemented by shdocvw.dll), for instance, provides a number of events to notify its host about various events such as loading a page or clicking a hyperlink. The RCW generated by the runtime exposes these events in the form of delegates and takes care of handling all the details required to perform the communication between managed and unmanaged code.

Although COM components can be accessed dynamically using .NET reflection, explicitly relying on the ability of the CLR to generate CCW and RCW, it's desirable to use a less verbose approach to COM interoperability. The .NET runtime ships with tools that allow you to generate RCW and CCW wrappers offline, which lets you use COM components as .NET classes and vice versa. These tools are as follows:

To better understand how COM components can be accessed from your F# programs and vice versa, let's consider two examples. In the first, you wrap the widely used Flash Player into a form interactively; and in the second, you see how an F# object type can be consumed as if it were a COM component.

The Flash Player you're accustomed to using in everyday browsing is an ActiveX control that is loaded by Internet Explorer using an OBJECT element in the HTML page (it's also a plug-in for other browsers, but here you're interested in the COM component). By using a search engine, you can easily find that an HTML element similar to the following is used to embed the player in Internet Explorer:

<OBJECT
      classid ="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000"
      codebase="http://download.macromedia.com/pub/shockwave/cabs/flash/swflash.cab"
      width   ="640" height="480"
      title   ="My movie">
   <param name="movie"   value="MyMovie.swf" />
   <param name="quality" value="high" />
</OBJECT>

From this tag, you know that the CLSID of the Flash Player ActiveX component is the one specified with the classid parameter of the OBJECT element. You can now look in the Windows registry under HKEY_CLASSES_ROOTCLSID for the subkey corresponding to the CLSID of the Flash ActiveX control. If you look at the subkeys, you notice that the ProgID of the component is ShockwaveFlash.ShockwaveFlash, and InprocServer32 indicates that its location is C:Windowssystem32MacromedFlashFlash10d.ocx. You can also find the GUID relative to the component type library—which, when investigated, shows that the type library is contained in the same OCX file.

Because Flash Player is an ActiveX control with a GUI, you can rely on aximp.exe rather than just tlbimp.exe to generate the RCW for the COM component:

C:> aximp c:WindowsSystem32MacromedFlashFlash10d.ocx
Generated Assembly: C:ShockwaveFlashObjects.dll
Generated Assembly: C:AxShockwaveFlashObjects.dll

If you use ildasm.exe to analyze the structure of the generated assemblies, notice that the wrapper of the COM component is contained in ShockwaveFlashObjects.dll and is generated by the tlbimp.exe tool. The second assembly contains a Windows Forms host for ActiveX components and is configured to host the COM component, exposing the GUI features in terms of the elements of the Windows Forms framework.

You can test the Flash Player embedded in an interactive F# session as follows:

> #I @"c:";;
--> Added 'c: ' to library include path
> #r "AxShockwaveFlashObjects.dll";;
--> Referenced 'c:AxShockwaveFlashObjects.dll'
> open AxShockwaveFlashObjects;;
> open System.Windows.Forms;;
> let f = new Form();;
val f : Form
> let flash = new AxShockwaveFlash();;
val flash : AxShockwaveFlash
Binding session to 'c:AxShockwaveFlashObjects.dll'...
> f.Show();;
val it : unit = ()
> flash.Dock <- DockStyle.Fill;;
val it : unit = ()
> f.Controls.Add(flash);;
val it : unit = ()
> flash.LoadMovie(0, "http://laptop.org/img/meshDemo18.swf");;
val it : unit = ()

You first add to the include path of the fsi.exe directory containing the assemblies generated by aximp.exe using the #I directive, and then you reference the AxShockwaveFlashObjects.dll assembly using the #r directive. The namespace AxShockwaveFlashObjects containing the AxShockwaveFlash class is opened; this is the managed class wrapping the ActiveX control. You create an instance of the Flash Player that is now exposed as a Windows Forms control; then, you set the Dock property to DockStyle.Fill to let the control occupy the entire area of the form. Finally, you add the control to the form.

When you're typing the commands into F# Interactive, it's possible to test the content of the form. When it first appears, a right-click on the client area is ignored. After the ActiveX control is added to the form, the right-click displays the context menu of the Flash Player. You can now programmatically control the player by setting the properties and invoking its methods; the generated wrapper takes care of all the communications with the ActiveX component.

#r "EnvDTE"
open System.Runtime.InteropServices
let appObj =Marshal.GetActiveObject("VisualStudio.DTE") :?> EnvDTE80.DTE2
printfn "%s" appObj.ActiveDocument.FullName

#r "EnvDTE"
open System.Runtime.InteropServices
open System.Runtime.InteropServices.ComTypes

[<DllImport("ole32.dll")>]
extern int internal GetRunningObjectTable(uint32 reserved, IRunningObjectTable& pprot)

[<DllImport("ole32.dll")>]
extern int internal CreateBindCtx(uint32 reserved, IBindCtx& pctx)

let FetchVSDTE (pid:int) =
  let mutable (prot:IRunningObjectTable) = null
  let mutable (pmonkenum:IEnumMoniker) = null
  let (monikers:IMoniker[]) =  Array.create 1 null
  let pfeteched = System.IntPtr.Zero
  let mutable (ret:obj) = null
  let endpid = sprintf ":%d" pid

  try

if (GetRunningObjectTable(0u, &prot) <> 0) || (prot = null) then
        failwith "Error opening the ROT"
    prot.EnumRunning(&pmonkenum)
    pmonkenum.Reset()
    while pmonkenum.Next(1, monikers, pfeteched) = 0 do
      let mutable (insname:string) = null
      let mutable (pctx:IBindCtx) = null
      CreateBindCtx(0u, &pctx) |> ignore
      (monikers.[0]).GetDisplayName(pctx, null, &insname);
      Marshal.ReleaseComObject(pctx) |> ignore
      if insname.StartsWith("!VisualStudio.DTE") && insname.EndsWith(endpid) then
        prot.GetObject(monikers.[0], &ret) |> ignore
  finally
    if prot <> null then Marshal.ReleaseComObject(prot) |> ignore
    if pmonkenum <> null then Marshal.ReleaseComObject(pmonkenum) |> ignore
(ret :?> EnvDTE.DTE)

Next, let's see an example of exposing an F# object type as a COM component. There are several reasons it can be useful to expose a managed class as a COM component, but perhaps the most important is interoperability with legacy systems. COM has been around for a decade and has permeated every aspect of Windows development. Systems have largely used COM infrastructures, and they can be extended using this technology. COM components are heavily used by applications based on the Active Scripting architecture, such as ASP and VBA in Microsoft Office. The ability to expose F# code to existing applications is useful because it allows you to immediately start using this new language and integrate it seamlessly into existing systems.

Suppose you're exposing a simple F# object type as a COM component, and you invoke a method of this object type from a JScript script. You define the following type in the hwfs.fs file:

namespace HelloWorld

open System

type FSCOMComponent() =
    member x.HelloWorld() = "Hello world from F#!"

The assembly that must be exposed as a COM component should be added to the global assembly cache (GAC), which is where shared .NET assemblies are stored. Assemblies present in the GAC must be strongly named, which means a public key cryptographic signature must be used to certify the assembly. To perform the test, you generate a key pair to be used to sign the assembly using the sn.exe command available with the .NET SDK:

C:> sn -k testkey.snk

Microsoft (R) .NET Framework Strong Name Utility  Version 4.0.30319.1
Copyright (c) Microsoft Corporation.  All rights reserved.

Key pair written to testkey.snk

You can compile the program in a DLL called hwfs.dll:

C:> fsc -a --keyfile:testkey.snk hwfs.fs

Note that you use the --keyfile switch to indicate to the compiler that the output should be signed using the specified key pair. Now, you can add the assembly to the GAC (note that under Windows Vista and 7, the shell used should run with administrator privileges):

C: > gacutil /i hwfs.dll
Microsoft (R) .NET Global Assembly Cache Utility.  Version 4.0.30319.1
Copyright (c) Microsoft Corporation.  All rights reserved.

Assembly successfully added to the cache

Use the regasm.exe tool to register the hwfs.dll assembly as a COM component:

C: > regasm hwfs.dll
Microsoft (R) .NET Framework Assembly Registration Utility 4.0.30319.1
Copyright (C) Microsoft Corporation 1998-2004.  All rights reserved.

Types registered successfully

Next, you must write the script using the JScript language to test the component. The script uses the CreateObject method to create an instance of the F# object type, with the CCW generated by the CLR taking care of all the interoperability issues. But what is the ProgID of the COM component? You use regasm.exe with the /regfile switch to generate a registry file containing the keys corresponding to the registration of the COM component instead of performing it. The generated registry file contains the following component registration (we've included only the most relevant entries):

[HKEY_CLASSES_ROOTHelloWorld.FSCOMComponent]
@="HelloWorld.FSCOMComponent"
[HKEY_CLASSES_ROOTHelloWorld.FSCOMComponentCLSID]
@="{30094EBA-CDCB-3C57-9297-49C724421ACB}"
[HKEY_CLASSES_ROOTCLSID{30094EBA-CDCB-3C57-9297-49C724421ACB}]

@="HelloWorld.FSCOMComponent"
[HKEY_CLASSES_ROOTCLSID{30094EBA-CDCB-3C57-9297-49C724421ACB}InprocServer32]
@="mscoree.dll"
"ThreadingModel"="Both"
"Class"="HelloWorld.FSCOMComponent"
"Assembly"="hwfs, Version=0.0.0.0, Culture=neutral, PublicKeyToken=d25287aa2b2b0de6"
"RuntimeVersion"="v4.0.30319"

The InprocServer32 subkey indicates that the COM component is implemented by mscoree.dll, which is the CLR. The additional attributes indicate the assembly that should be run by the runtime.

Note that the ProgID and the class name of the component are HelloWorld.FSCOMComponent. You can now write the following script in the hwfs.js file:

o = WScript.CreateObject("HelloWorld.FSCOMComponent");
WScript.Echo(o.HelloWorld());

If you execute the script (here using the command-based host cscript), you obtain the expected output:

C: > cscript foo.js
Microsoft (R) Windows Script Host Version 5.8
Copyright (C) Microsoft Corporation. All rights reserved.

Hello world from F#!

Using the fully qualified .NET name to name a COM component isn't always a good idea. Names are important, especially in a component infrastructure, because they're used for long time. So far, you've used only the basic features of COM interoperability, but a number of custom attributes can give you finer control over the CCW generation. These attributes are defined in the System.Runtime.InteropServices namespace; and among these classes you find the ProgIdAttribute class, whose name hints that it's related to the ProgID. You can annotate your F# object type using this attribute:

namespace HelloWorld

open System
open System.Runtime.InteropServices

[<ProgId("Hwfs.FSComponent")>]
type FSCOMComponent() =
    member x.HelloWorld() = "Hello world from F#!"

First, unregister the previous component:

C:> regasm hwfs.dll /unregister
Microsoft (R) .NET Framework Assembly Registration Utility 4.0.30319.1
Copyright (C) Microsoft Corporation 1998-2004.  All rights reserved.

Types un-registered successfully
C:> gacutil /u hwfs
Microsoft (R) .NET Global Assembly Cache Utility.  Version 4.0.30319.1

Copyright (c) Microsoft Corporation.  All rights reserved.

Assembly: hwfs, Version=0.0.0.0, Culture=neutral,
    PublicKeyToken=8c1f06f522fc70f8, processorArchitecture=MSIL
Uninstalled: hwfs, Version=0.0.0.0, Culture=neutral,
    PublicKeyToken=8c1f06f522fc70f8, processorArchitecture=MSIL
Number of assemblies uninstalled = 1
Number of failures = 0

Now you can update the script as follows and register everything again after recompiling the F# file:

o = WScript.CreateObject("Hwfs.FSComponent");
WScript.Echo(o.HelloWorld());

Using other attributes, it's possible to specify the GUIDs to be used and several other aspects that are important in some situations. When a system expects a component implementing a given COM interface, the COM component is expected to return the pointer to the interface with the appropriate GUID. In this case, the ability to explicitly indicate a GUID is essential to defining a .NET interface that should be marshalled as the intended COM interface.

Complex COM components can be tricky to wrap using these tools, and official wrappers are maintained by component developers. Microsoft provides the managed version of the Office components, the managed DirectX library, and the Web Browser control to spare programmers from having to build their own wrappers.

In conclusion, it's possible to use COM components from F# and vice versa. You can expose F# libraries as COM components, which allows you to extend existing systems using F# or use legacy code in F# programs.

COM interoperability is an important area in F#, but it's limited to Windows and to the Microsoft implementation of the ECMA and ISO standards of the Common Language Infrastructure (CLI). The CLI standard, however, devises a standard mechanism for interoperability that is called Platform Invoke (PInvoke to friends); it's a core feature of the standard available on all CLI implementations, including Mono.

The basic model underlying PInvoke is based on loading DLLs into the program, which allows managed code to invoke exported functions. DLLs don't provide information other than the entry point location of a function; this isn't enough to perform the invocation unless additional information is made available to the runtime.

The invocation of a function requires the following:

You obtain the address of the entry point using a system call that returns the pointer to the function given a string. You must provide the remaining information to instruct the CLR about how the function pointer should be used.

The additional information required to perform the function call is provided by custom attributes that are used to decorate a function prototype and inform the runtime about the signature of the exported function.

#define CINTEROPDLL_API __declspec(dllexport)
extern "C" {
void CINTEROPDLL_API HelloWorld();
}

void CINTEROPDLL_API HelloWorld()
{
    printf("Hello C world invoked by F#!
");
}

open System.Runtime.InteropServices

module CInterop =
    [<DllImport("CInteropDLL", CallingConvention=CallingConvention.Cdecl)>]
    extern void HelloWorld()

CInterop.HelloWorld()

int CINTEROPDLL_API Sum(int i, int j)
{
    return i + j;
}

module CInterop =
    [<DllImport("CInteropDLL", CallingConvention=CallingConvention.Cdecl)>]
    extern int Sum(int i, int j)

printf "Sum(1, 1) = %d
" (CInterop.Sum(1, 1));

typedef struct _Complex {
    double re;
    double im;
} Complex;

Complex CINTEROPDLL_API SumC(Complex c1, Complex c2)
{
    Complex ret;
    ret.re = c1.re + c2.re;
    ret.im = c1.im + c2.im;
    return ret;
}

module CInterop =
    [<Struct; StructLayout(LayoutKind.Sequential)>]
    type Complex =
        val mutable re:double
        val mutable im:double

        new(r,i) = { re = r; im = i; }

    [<DllImport("CInteropDLL")>]
    extern Complex SumC(Complex c1, Complex c2)

let c1 = CInterop.Complex(1.0, 0.0)
let c2 = CInterop.Complex(0.0, 1.0)

let mutable c3 = CInterop.SumC(c1, c2)
printf "c3 = SumC(c1, c2) = %f + %fi
" c3.re c3.im;

struct Foo {
    int i;
    char c;
    short s;
};

void CINTEROPDLL_API ZeroC(Complex* c)
{
    c->re = 0;
    c->im = 0;
}

[<DllImport("CInteropDLL")>]
extern void ZeroC(Complex* c)

let mutable c4 = CInterop.SumC(c1, c2)
printf "c4 = SumC(c1, c2) = %f + %fi
" c4.re c4.im

CInterop.ZeroC(&&c4)
printf "c4 = %f + %fi
" c4.re c4.im

module CInterop =
    [<StructLayout(LayoutKind.Sequential)>]
    type ObjComplex =
        val mutable re:double
        val mutable im:double

        new() as x = { re = 0.0; im = 0.0 }
        new(r:double, i:double) as x = { re = r; im = i }

     [<DllImport("CInteropDLL", EntryPoint="ZeroC")>]
    extern void ObjZeroC(ObjComplex c)

let oc = CInterop.ObjComplex(2.0, 1.0)
printf "oc = %f + %fi
" oc.re oc.im
CInterop.ObjZeroC(oc)
printf "oc = %f + %fi
" oc.re oc.im

void CINTEROPDLL_API echo(char* str)
{
    puts(str);
}

[<DllImport("CInteropDLL", CallingConvention=CallingConvention.Cdecl)>]
extern void echo(string s);

void CINTEROPDLL_API sayhello(char* str, int sz)
{
    static char* data = "Hello from C code!";
    int len = min(sz, strlen(data));
    strncpy(str, data, len);
    str[len] = 0;
}

[<DllImport("CInteropDLL", CallingConvention=CallingConvention.Cdecl)>]
extern void sayhello(StringBuilder sb, int sz);

let sb = new StringBuilder(50)

CInterop.sayhello(sb, 50)
printf "%s
" (sb.ToString())

void CINTEROPDLL_API sayhellow(wchar_t* str, int sz)
{
    static wchar_t* data = L"Hello from C code Wide!";
    int len = min(sz, wcslen(data));
    wcsncpy(str, data, len);
    str[len] = 0;
}

[<DllImport("CInteropDLL", CallingConvention=CallingConvention.Cdecl)>]
extern void sayhellow([<MarshalAs(UnmanagedType.LPWStr)>]StringBuilder sb, int sz);

typedef int (CALLBACK *TRANSFORM_CALLBACK)(int);

void CINTEROPDLL_API transformArray(int* data, int count, TRANSFORM_CALLBACK fn)
{
    int i;
    for (i = 0; i < count; i++)
        data[i] = fn(data[i]);
}

type Callback = delegate of int -> int

[<DllImport("CInteropDLL", CallingConvention=CallingConvention.Cdecl)>]
extern void transformArray(int[] data, int count, Callback transform);

let data = [| 1; 2; 3 |]
printf "%s
" (string.Join("; ", (Array.map any_to_string data)))

CInterop.transformArray(data, data.Length, new CInterop.Callback(fun x -> x + 1))
printf "%s
" (string.Join("; ", (Array.map any_to_string data)))

module MMap =

    open System
    open System.IO
    open System.Runtime.InteropServices
    open Microsoft.FSharp.NativeInterop
    open Printf

type HANDLE = nativeint
    type ADDR   = nativeint

    [<DllImport("kernel32", SetLastError=true)>]
    extern bool CloseHandle(HANDLE handler)

    [<DllImport("kernel32", SetLastError=true, CharSet=CharSet.Auto)>]
    extern HANDLE CreateFile(string lpFileName,
                             int dwDesiredAccess,
                             int dwShareMode,
                             HANDLE lpSecurityAttributes,
                             int dwCreationDisposition,
                             int dwFlagsAndAttributes,
                             HANDLE hTemplateFile)

    [<DllImport("kernel32", SetLastError=true, CharSet=CharSet.Auto)>]
    extern HANDLE CreateFileMapping(HANDLE hFile,
                                    HANDLE lpAttributes,
                                    int flProtect,
                                    int dwMaximumSizeLow,
                                    int dwMaximumSizeHigh,
                                    string lpName)

    [<DllImport("kernel32", SetLastError=true)>]
    extern ADDR MapViewOfFile(HANDLE hFileMappingObject,
                              int dwDesiredAccess,
                              int dwFileOffsetHigh,
                              int dwFileOffsetLow,
                              int dwNumBytesToMap)

    [<DllImport("kernel32", SetLastError=true, CharSet=CharSet.Auto)>]
    extern HANDLE OpenFileMapping(int dwDesiredAccess,
                                  bool bInheritHandle,
                                  string lpName)

    [<DllImport("kernel32", SetLastError=true)>]
    extern bool UnmapViewOfFile(ADDR lpBaseAddress)

    let INVALID_HANDLE = new IntPtr(−1)
    let MAP_READ    = 0x0004
    let GENERIC_READ = 0x80000000
    let NULL_HANDLE = IntPtr.Zero
    let FILE_SHARE_NONE = 0x0000
    let FILE_SHARE_READ = 0x0001
    let FILE_SHARE_WRITE = 0x0002
    let FILE_SHARE_READ_WRITE = 0x0003
    let CREATE_ALWAYS  = 0x0002
    let OPEN_EXISTING   = 0x0003
    let OPEN_ALWAYS  = 0x0004
    let READONLY = 0x00000002

    type MemMap<'a> (fileName) =

let ok =
            match typeof<'a>) with
            | ty when ty = typeof<int>)     -> true
            | ty when ty = typeof<int32>)   -> true
            | ty when ty = typeof<byte>)    -> true
            | ty when ty = typeof<sbyte>)   -> true
            | ty when ty = typeof<int16>)   -> true
            | ty when ty = typeof<uint16>)  -> true
            | ty when ty = typeof<int64>)   -> true
            | ty when ty = typeof<uint64>)  -> true
            | _ -> false

        do if not ok then failwithf
           "the type %s is not a basic blittable type" ((typeof<'a>).ToString())
        let hFile =
           CreateFile (fileName,
                         GENERIC_READ,
                         FILE_SHARE_READ_WRITE,
                         IntPtr.Zero, OPEN_EXISTING, 0, IntPtr.Zero  )
        do if ( hFile.Equals(INVALID_HANDLE) ) then
            Marshal.ThrowExceptionForHR(Marshal.GetHRForLastWin32Error());
        let hMap = CreateFileMapping (hFile, IntPtr.Zero, READONLY, 0,0, null )
        do CloseHandle(hFile) |> ignore
        do if hMap.Equals(NULL_HANDLE) then
            Marshal.ThrowExceptionForHR(Marshal.GetHRForLastWin32Error());

        let start = MapViewOfFile (hMap, MAP_READ,0,0,0)

        do  if ( start.Equals(IntPtr.Zero) ) then
             Marshal.ThrowExceptionForHR(
                  Marshal.GetHRForLastWin32Error())


        member m.AddressOf(i: int) : 'a nativeptr  =
             NativePtr.of_nativeint(start + (nativeint i))

        member m.GetBaseAddress (i:int) : int -> 'a =
            NativePtr.get (m.AddressOf(i))

        member m.Item
            with get(i : int) : 'a = m.GetBaseAddress 0 i

        member m.Close() =
           UnmapViewOfFile(start) |> ignore;
           CloseHandle(hMap) |> ignore

        interface IDisposable with
          member m.Dispose() =
             m.Close()

let mm = new MMap.MemMap<byte>("somefile.txt")

printf "%A
" (mm.[0])

mm.Close()

struct __db {
        /* ... */
        DB_ENV *dbenv;              /* Backing environment. */
        DBTYPE type;               /* DB access method type. */
        /* ... */
        int  (*close) __P((DB *, u_int32_t));
        int  (*cursor) __P((DB *, DB_TXN *, DBC **, u_int32_t));
        int  (*del) __P((DB *, DB_TXN *, DBT *, u_int32_t));
        // ...
}

DB *db;
// BDB call
db->close(db, 0);
// Wrapper call
db_close(db, 0);

In this chapter, you saw how F# can interoperate with native code in the form of COM components and the standard Platform Invoke interface defined by the ECMA and ISO standards. Neither mechanism is dependent on F#, but the language exposes the appropriate abstractions built into the runtime. You studied how to consume COM components from F# programs and vice versa, and how to access DLLs through PInvoke.