Platform Invocation Services

From Wikipedia, the free encyclopedia

Jump to: navigation, search

Platform Invocation Services, commonly referred to as P/Invoke, is a feature of Common Language Infrastructure implementations, like Microsoft's Common Language Runtime, that enables managed code to call native code.

Contents

[edit] Architecture

[edit] Overview

Two variants of P/Invoke in use currently are;

Explicit

  • Native code is imported via dynamic-linked libraries (DLLs)
  • Metadata embedded in the callers 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)
  • This definition is the "Explicit" part

Implicit

  • By using C++/CLI, 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.

[edit] Details

When using P/Invoke, the CLR handles DLL loading and conversion of the unmanaged legacy types to CTS types (also referred to as parameter marshalling)[1]. To perform this, the CLR:

  • Locates the DLL containing the function.
  • Loads the DLL into memory.
  • Locates the address of the function in memory and pushes its arguments onto the stack, marshaling data as required.

P/Invoke is useful for using legacy C or C++ DLLs. It can be used when a programmer needs to have access to the extensive Windows API, as there are no available wrappers for a lot of functions provided by the Windows libraries. When a Win32 API is not exposed by the .NET framework the wrapper to this API must be written manually.

[edit] 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 and garbage collection as is usually provided in the .NET environment. When they are used improperly this may cause problems such as segmentation faults or memory leaks. Getting the exact signatures of the legacy functions for use in the .NET 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. [1]

Other pitfalls include:

  • Incorrect data alignment of user-defined types 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 how to align data for non-blittable types. A common example of this is when trying to define a data type in .NET to represent a union in C. 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 IL 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 not without new challenges:

  • Code is prone to Double Thunking[2] if not specifically addressed
  • The Loader Lock issue [3]

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.

[edit] Examples

[edit] Basic examples

This first simple example shows how to get the version of a particular DLL:

DllGetVersion function signature in the Windows API:

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:

HICON ExtractIcon
(      
    HINSTANCE hInst,
    LPCTSTR lpszExeFileName,
    UINT nIconIndex
);

P/Invoke C# code to invoke the ExtractIcon function:

[DllImport("shell32.dll")]
static extern IntPtr ExtractIcon(
    IntPtr hInst, 
    [MarshalAs(UnmanagedType.LPStr)] string lpszExeFileName, 
    uint nIconIndex);

This next complex example shows how to share an Event between two processes in the Windows platform:

CreateEvent function signature:

 HANDLE CreateEvent(
     LPSECURITY_ATTRIBUTES lpEventAttributes,
     BOOL bManualReset,
     BOOL bInitialState,
     LPCTSTR lpName
 );

P/Invoke C# code to invoke the CreateEvent function:

[DllImport("kernel32.dll", SetLastError=true)]
static extern IntPtr CreateEvent(
    IntPtr lpEventAttributes, 
    bool bManualReset,
    bool bInitialState, 
    [MarshalAs(UnmanagedType.LPStr)] string lpName);

[edit] A more complex example

// native declaration

typedef struct _PAIR 
{ 
	DWORD Val1; 
	DWORD Val2; 
} PAIR, *PPAIR;

// 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<CLR_PAIR^, PAIR> (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;
};

CLR_PAIR^ mgd_pair1;
CLR_PAIR^ mgd_pair2;
PAIR native0,*native1=&native0;
 
native0 = NativeCallGetRefToMemory();
 
// using marshal_as, makes seance for large or frequently used types
mgd_pair1 = marshal_as<CLR_PAIR^>(*native1);
 
// direct field use
mgd_pair2->Val1 = native0.Val1;
mgd_pair2->val2 = native0.val2;
 
return(mgd_pair1); // return to C#

[edit] References

  1. ^ Parameter marshaling is not to be confused with the general term marshalling, meaning Serialization. Marshaled parameters are copied in the CLR stack after their conversion to CTS types, but are not serialized.
  2. ^ http://msdn.microsoft.com/en-us/library/ms235292(VS.80).aspx
  3. ^ http://msdn.microsoft.com/en-us/library/ms173266(vs.80).aspx

[edit] See also

[edit] External links

Retrieved from "http://en.wikipedia.org/wiki/Platform_Invocation_Services"
Personal tools