The Common Language Infrastructure is an open specification developed by Microsoft and standardized by ISO and ECMA that describes the executable code and runtime environment that form the core of the Microsoft .NET Framework and the free and open source implementations Mono and Portable.NET...
Microsoft Corporation is an American public multinational corporation headquartered in Redmond, Washington, USA that develops, manufactures, licenses, and supports a wide range of products and services predominantly related to computing through its various product divisions...
The Common Language Runtime is the virtual machine component of Microsoft's .NET framework and is responsible for managing the execution of .NET programs. In a process known as just-in-time compilation, the CLR compiles the intermediate language code known as CIL into the machine instructions...
Managed code is a term coined by Microsoft to identify computer program code that requires and will only execute under the "management" of a Common Language Runtime virtual machine ....
to call native code.
Explicit
Native code is imported via dynamic-linked libraries (DLLs)
.NET metadata, in the Microsoft .NET framework, refers to certain data structures embedded within the Common Intermediate Language code that describes the high-level structure of the code. Metadata describes all classes and class members that are defined in the assembly, and the classes and class...
embedded in the caller's assembly, defines how the native code is to be called and data accessed (usually requires attributed source specifiers to aid the compiler in generating marshal glue)
C++/CLI is Microsoft's language specification intended to supersede Managed Extensions for C++. It is a complete revision that aims to simplify the older Managed C++ syntax . C++/CLI is standardized by Ecma as ECMA-372...
, an application may simultaneously use the managed heap (by way of tracking pointers) and any native memory region, without the explicit declaration. (Implicit)
A primary benefit in this case being, if underlying native data structures change, so long as the naming is compatible, a breaking change is avoided.
i.e. Adding/removing/re-ordering structures in a native header will be transparently supported so long as the structure member names did not also change.
The Common Language Runtime is the virtual machine component of Microsoft's .NET framework and is responsible for managing the execution of .NET programs. In a process known as just-in-time compilation, the CLR compiles the intermediate language code known as CIL into the machine instructions...
DLL may refer to:* Data link layer, a layer in the OSI network architecture model* Delay-locked loop, a device to reduce clock skew in digital circuits* Doubly linked list, a data structure in computer programming...
Managed code is a term coined by Microsoft to identify computer program code that requires and will only execute under the "management" of a Common Language Runtime virtual machine ....
In Microsoft's .NET Framework, the Common Type System is a standard that specifies how Type definitions and specific values of Types are represented in...
types (also referred to as parameter marshalling). To perform this, the CLR
Common Language Runtime
The Common Language Runtime is the virtual machine component of Microsoft's .NET framework and is responsible for managing the execution of .NET programs. In a process known as just-in-time compilation, the CLR compiles the intermediate language code known as CIL into the machine instructions...
DLL may refer to:* Data link layer, a layer in the OSI network architecture model* Delay-locked loop, a device to reduce clock skew in digital circuits* Doubly linked list, a data structure in computer programming...
DLL may refer to:* Data link layer, a layer in the OSI network architecture model* Delay-locked loop, a device to reduce clock skew in digital circuits* Doubly linked list, a data structure in computer programming...
into memory.
Locates the address of the function in memory and pushes its arguments onto the stack
Call stack
In computer science, a call stack is a stack data structure that stores information about the active subroutines of a computer program. This kind of stack is also known as an execution stack, control stack, run-time stack, or machine stack, and is often shortened to just "the stack"...
, marshaling data as required.
P/Invoke is useful for using standard (unmanaged) C
C (programming language)
C is a general-purpose computer programming language developed between 1969 and 1973 by Dennis Ritchie at the Bell Telephone Laboratories for use with the Unix operating system....
C++ is a statically typed, free-form, multi-paradigm, compiled, general-purpose programming language. It is regarded as an intermediate-level language, as it comprises a combination of both high-level and low-level language features. It was developed by Bjarne Stroustrup starting in 1979 at Bell...
Dynamic-link library , or DLL, is Microsoft's implementation of the shared library concept in the Microsoft Windows and OS/2 operating systems...
. It can be used when a programmer needs to have access to the extensive Windows API
Windows API
The Windows API, informally WinAPI, is Microsoft's core set of application programming interfaces available in the Microsoft Windows operating systems. It was formerly called the Win32 API; however, the name "Windows API" more accurately reflects its roots in 16-bit Windows and its support on...
Like most modern operating systems, Microsoft Windows supports shared libraries, collections of code which can be used by multiple processes while only being loaded once into memory...
lack available wrappers. When a Win32 API is not exposed by the .NET framework
.NET Framework
The .NET Framework is a software framework that runs primarily on Microsoft Windows. It includes a large library and supports several programming languages which allows language interoperability...
the wrapper to this API must be written manually.
Pitfalls
Writing P/Invoke wrappers can be difficult and error prone. Using native DLLs means that the programmer can no longer benefit from type safety
Type safety
In computer science, type safety is the extent to which a programming language discourages or prevents type errors. A type error is erroneous or undesirable program behaviour caused by a discrepancy between differing data types...
In computer science, garbage collection is a form of automatic memory management. The garbage collector, or just collector, attempts to reclaim garbage, or memory occupied by objects that are no longer in use by the program...
as is usually provided in the .NET environment. When they are used improperly this may cause problems such as segmentation fault
Segmentation fault
A segmentation fault , bus error or access violation is generally an attempt to access memory that the CPU cannot physically address. It occurs when the hardware notifies an operating system about a memory access violation. The OS kernel then sends a signal to the process which caused the exception...
A memory leak, in computer science , occurs when a computer program consumes memory but is unable to release it back to the operating system. In object-oriented programming, a memory leak happens when an object is stored in memory but cannot be accessed by the running code...
s. Getting the exact signatures of the legacy functions for use in the .NET
.NET Framework
The .NET Framework is a software framework that runs primarily on Microsoft Windows. It includes a large library and supports several programming languages which allows language interoperability...
environment can be hard, which can result in such problems. For this purpose tools and websites exist to obtain such signatures, helping to prevent signature problems. http://www.pinvoke.net/
Data structure alignment is the way data is arranged and accessed in computer memory. It consists of two separate but related issues: data alignment and data structure padding. When a modern computer reads from or writes to a memory address, it will do this in word sized chunks...
In computer programming, a data type is a classification identifying one of various types of data, such as floating-point, integer, or Boolean, that determines the possible values for that type; the operations that can be done on values of that type; the meaning of the data; and the way values of...
in the managed language: there are different ways data can be aligned depending on compilers or compiler directives in C and care must be taken to explicitly tell the CLR
Common Language Runtime
The Common Language Runtime is the virtual machine component of Microsoft's .NET framework and is responsible for managing the execution of .NET programs. In a process known as just-in-time compilation, the CLR compiles the intermediate language code known as CIL into the machine instructions...
Blittable types are data types in software applications which have a unique characteristic. Data are often represented in memory differently in managed and unmanaged code in the Microsoft .NET framework. However, blittable types are defined as having an identical presentation in memory for both...
. A common example of this is when trying to define a data type in .NET to represent a union
Union (computer science)
In computer science, a union is a value that may have any of several representations or formats; or a data structure that consists of a variable which may hold such a value. Some programming languages support special data types, called union types, to describe such values and variables...
C is a general-purpose computer programming language developed between 1969 and 1973 by Dennis Ritchie at the Bell Telephone Laboratories for use with the Unix operating system....
. Two different variables overlap in memory, and defining these two variables in a type in .NET would cause them to be in different locations in memory, so special attributes must be used to correct the issue.
Interference with the location of data by the managed language's garbage collector: if a reference is local to a method in .NET and is passed to a native function, when the managed method returns, the garbage collector may reclaim that reference. Care should be taken that the object reference is pinned, preventing it from being collected or moved by the garbage collector, which would result in an invalid access by the native module.
When using C++/CLI, emitted CIL is free to interact with objects located on the managed heap and simultaneously any addressable native memory location. A managed heap resident object may be called, modified or constructed, using simple "object->field;" notation to assign values or specify method calls. Significant performance gains result from having eliminated any needless context switching, memory requirements are reduced (shorter stacks).
This magic comes with new challenges:
Code is prone to Double Thunking if not specifically addressed
The Loader Lock issue
These references specify solutions for each of these issue if they are encountered. A primary benefit is the elimination of the structure declaration, the order of field declaration and alignment issues are not present in the context of C++ Interop.
Basic examples
This first simple example shows how to get the version of a particular DLL
DLL
DLL may refer to:* Data link layer, a layer in the OSI network architecture model* Delay-locked loop, a device to reduce clock skew in digital circuits* Doubly linked list, a data structure in computer programming...
:
DllGetVersion function signature in the Windows API
Windows API
The Windows API, informally WinAPI, is Microsoft's core set of application programming interfaces available in the Microsoft Windows operating systems. It was formerly called the Win32 API; however, the name "Windows API" more accurately reflects its roots in 16-bit Windows and its support on...
:
HRESULT DllGetVersion
(
DLLVERSIONINFO* pdvi
)
P/Invoke C# code to invoke the DllGetVersion function:
[DllImport("shell32.dll")]
static extern int DllGetVersion(ref DLLVERSIONINFO pdvi);
The second example shows how to extract an Icon in a File:
ExtractIcon function signature in the Windows API:
This next complex example shows how to share an Event between two processes in the Windows platform
Microsoft Windows
Microsoft Windows is a series of operating systems produced by Microsoft.Microsoft introduced an operating environment named Windows on November 20, 1985 as an add-on to MS-DOS in response to the growing interest in graphical user interfaces . Microsoft Windows came to dominate the world's personal...
// compiled with /clr, use of #pragma managed/unmanaged can lead to double thunking;
// avoid by using a stand-alone .cpp with .h includes
// this would be located in a .h file.
template<>
inline CLR_PAIR^ marshal_as (const PAIR&Src) { // note use of de/referencing, must match your use
CLR_PAIR^ Dest = gcnew CLR_PAIR;
Dest->Val1 = Src.Val1;
Dest->Val2 = Src.Val2;
return Dest;
};
// using marshal_as, makes sense for large or frequently used types
mgd_pair1 = marshal_as(*native1);
// direct field use
mgd_pair2->Val1 = native0.Val1;
mgd_pair2->val2 = native0.val2;
return(mgd_pair1); // return to C#
Tools
There are a number of tools which are designed to aid in the production of p/invoke signatures.
Writing a utility application that would import C++ header files and native DLL
DLL
DLL may refer to:* Data link layer, a layer in the OSI network architecture model* Delay-locked loop, a device to reduce clock skew in digital circuits* Doubly linked list, a data structure in computer programming...
files and produce an interface assembly automatically turns out to be quite difficult. The main problem with producing such an importer/exporter for p/invoke signatures is the ambiguity of some C++ function call parameter types.
What type should we use for the parameter params in our p/invoke signature ? This could be either a C++ null terminated string, or could be a char array or could be an output char parameter. So should we use string, StringBuilder, char [] or ref char ?
Regardless of this issue, there are a few tools available to make the production of p/invoke signatures simpler.
PInvoke.net
PInvoke.net is a wiki containing p/invoke signatures for a large number of standard Windows APIs. It is owned by Redgate software and has around 50000 hits per month.
Microsoft Visual Studio is an integrated development environment from Microsoft. It is used to develop console and graphical user interface applications along with Windows Forms applications, web sites, web applications, and web services in both native code together with managed code for all...
.
PInvoker
PInvoker is an application which imports native DLLs and C++ .h files and exports fully formed and compiled interop DLLs. It overcomes the abiguity problem by wrapping native pointer function parameters in PInvoker specific .NET interface classes. Instead of using standard .NET parameter types in P/Invoke method definitions (char[], string, etc.) it uses these interface classes in the P/Invoke function calls.
For instance, if we consider the above example code, PInvoker would produce a .NET function accepting a .NET interface class wrapping the native char * pointer. The construction of this class could be from a string or from a char [] array. The actual native memory structure for both is the same, but the respective interface class constructors for each type will populate the memory in different ways. The responsibility for deciding what .NET type needs to be passed into the function is therefore passed to the developer.
A converter which takes small sections of native C++ header file code containing struct and method definitions. It then produces C# p/invoke code for you to copy and paste into your applications.
A searchable database of converted Windows API constant, method and struct definitions.
Because this tool produces C# source code rather than a compiled dll the user is free to make any changes necessary to the code before use. So the ambiguity problem is solved by the application picking one particular .NET type to use in the P/Invoke method signature and if necessary the user can change this to the required type.
P/Invoke Wizard
The P/Invoke Wizard uses a similar method to the Microsoft Interop Assistant in that it accepts native C++ .h file code and produces C# (or VB.NET) code for you to paste into your .NET application code.
It also has options for which framework you wish to target: .NET Framework for the desktop or .NET Compact Framework for Windows Mobile smart devices (and Windows CE).
Blittable types are data types in software applications which have a unique characteristic. Data are often represented in memory differently in managed and unmanaged code in the Microsoft .NET framework. However, blittable types are defined as having an identical presentation in memory for both...
The Java Native Interface is a programming framework that enables Java code running in a Java Virtual Machine to call and to be called by native applications and libraries written in other languages such as C, C++ and assembly.-Purpose and features:JNI enables one to write native methods to...
, the standard way for Java programs to access native code
Java Native Access provides Java programs easy access to native shared libraries without using the Java Native Interface. JNA's design aims to provide native access in a natural way with a minimum of effort...
Like most modern operating systems, Microsoft Windows supports shared libraries, collections of code which can be used by multiple processes while only being loaded once into memory...
J/Direct was a technology included in some versions of Microsoft's Java Virtual Machine, which allowed direct calls into the Windows API. J/Direct was specific of Microsoft's Virtual Machine, in replacement of the standard Java Native Interface ....
A Java virtual machine is a virtual machine capable of executing Java bytecode. It is the code execution component of the Java software platform. Sun Microsystems stated that there are over 4.5 billion JVM-enabled devices.-Overview:...
