Creating a P/Invoke Library

Geoff Schwab
Excell Data Corporation

Contributors:
   Jonathan Wells
   Microsoft Corporation

Registry Sample:
   Dan Elliott
   Microsoft Corporation

Wave Samples:
   Seth Demsey
   Microsoft Corporation

   Jonathan Wells
   Microsoft Corporation

January 2004

Applies to:
   Microsoft® .NET Compact Framework 1.0
   Microsoft Visual Studio® .NET 2003

Summary: This sample demonstrates how to P/Invoke numerous useful native functions that are not directly available through the .NET Compact Framework. A test Form is provided that enumerates all available test procedures and allows the user to select and run them. (18 printed pages)

Download

Contents

Introduction

The intent of this sample is to provide a collection of P/Invokes, as well test procedures that demonstrate their application. This sample provides several of the most commonly requested P/Invoke functions as well as a class that handles the enumeration and invoking of the various test procedures. This class is used by a Form to allow the user to select and run the tests from a selection list.

Note: For the sake of brevity and to facilitate searches, all function parameters and class definitions have been omitted from code blocks. Refer to the sample for full implementations of all code.

The Test Application

The test application is comprised of two components, the test application Form and the MainTest class. The Form provides the user with a list of all available tests and allows the user to select and run one or all of the tests with a press of the "Run Test" button. The results of the tests are displayed on the Form and can be cleared by pressing the "Clear Results" button.

The MainTest class provides the Form with the number and name of all available tests through Reflection. All classes defined in the Assembly are enumerated and searched for a static method named "TestProc." If this method is defined for a class then it is considered to be a P/Invoke test and is therefore added to the list. If the user runs a test then Reflection is again used to determine the MethodInfo for the TestProc and it is invoked.

Results from the tests are displayed via a delegate defined to take a string. This delegate is provided by the Form to the MainTest constructor and is, in turn, provided to each TestProc method as its only parameter.

Figure 1 shows a sample of the MemoryStatus test being run.

Figure 1. P/Invoke Library Test Application.

Input

The Input class provides the ability to override hardware hot keys and detect button presses regardless of which Control has input focus. Figure 2 shows sample output from this test.

Note: Some hardware keys may not be replicated on some emulators, causing this test to wait indefinitely for the proper key to be pressed.

Figure 2. Input Test Results.

The following functions are implemented in the Input class.

// C#
[DllImport("coredll.dll")]
protected static extern uint RegisterHotKey

[DllImport("coredll.dll")]
protected static extern uint UnregisterFunc1

[DllImport("coredll.dll")]
protected static extern short GetAsyncKeyState

'VB
 
Protected Shared Function RegisterHotKey

 
Protected Shared Function UnregisterFunc1

 
Protected Shared Function GetAsyncKeyState

Memory

The Memory class provides methods for allocating, reallocating, and freeing memory from the heap. Figure 3 shows output from a sample test.

Figure 3. Memory Test Results.

The following functions are implemented in the Memory class.

//c#
[DllImport("coredll.dll")]
extern public static IntPtr LocalAlloc

[DllImport("coredll.dll")]
extern public static IntPtr LocalFree

[DllImport("coredll.dll")]
extern public static IntPtr LocalReAlloc

'VB
 
Public Shared Function LocalAlloc 

 
Public Shared Function LocalFree 

 
Public Shared Function LocalReAlloc 

Memory Status

The MemoryStatus class provides methods for determining the status of the device's memory. Figure 4 shows sample output from this test.

Figure 4. Memory Status Test Results.

The MemoryStatus class implements the following classes and functions.

//C#
public class MEMORYSTATUS

[DllImport("CoreDll.dll")]
public static extern void GlobalMemoryStatus

[DllImport("CoreDll.dll")]
public static extern int GetSystemMemoryDivision

'VB
Public Class MEMORYSTATUS

 
Public Shared Sub GlobalMemoryStatus 

 
Public Shared Function GetSystemMemoryDivision 

Performance Counters

The PerfCounter class provides methods for accessing the device's performance counters. For more information on Performance Counters, see . Figure 5 shows sample output from the Performance Counter test.

Figure 5. Performance Counter Test Results.

The following functions are implemented by the PerfCounter class.

C#
[DllImport("CoreDll.dll")]
public static extern int QueryPerformanceFrequency

[DllImport("CoreDll.dll")]
public static extern int QueryPerformanceCounter

'VB
 
Public Shared Function QueryPerformanceFrequency 

 
Public Shared Function QueryPerformanceCounter 

Power Status

The PowerStatus class provides methods for determining the status of the device's power configuration, e.g., batter life, AC line status. For more information on Power Status, see . Figure 6 shows sample output from the Power Status test.

Figure 6. Power Status Test Results.

The PowerStatus class implements the following classes and functions.

C#
public class SYSTEM_POWER_STATUS_EX2

public class SYSTEM_POWER_STATUS_EX

[DllImport("coredll")]
public static extern uint GetSystemPowerStatusEx

[DllImport("coredll")]
public static extern uint GetSystemPowerStatusEx2

'VB
Public Class SYSTEM_POWER_STATUS_EX2

Public Class SYSTEM_POWER_STATUS_EX


Public Shared Function GetSystemPowerStatusEx


Public Shared Function GetSystemPowerStatusEx2

SIP

The SIP class provides methods for controlling the state of the Software Input Panel. During execution of the test, the SIP is temporarily displayed and then removed. Figure 7 shows sample output from the SIP test.

Figure 7. SIP Test Results.

The SIP class implements the following classes and functions.

C#
[DllImport("coredll.dll")]
public extern static void SipShowIM

[DllImport("coredll.dll")]
public extern static uint SipStatus();

public struct RECT

public class SIPINFO

[DllImport("coredll.dll")]
public extern static uint SipGetInfo

[DllImport("coredll.dll")]
public extern static uint SipSetInfo

'VB

Public Shared Sub SipShowIM


Public Shared Function SipStatus() As Integer

Public Structure RECT

Public Class SIPINFO


Public Shared Function SipGetInfo


Public Shared Function SipSetInfo

System Reset

The SystemReset class provides a mechanism for executing kernel IO controls and specifically demonstrates how to soft reset a device. The user is provided with a warning and the chance to back out, as shown in Figure 8.

Figure 8. System Reset Test Warning.

The SystemReset class implements the following function.

C#
[DllImport("Coredll.dll")]
public extern static uint KernelIoControl

'VB

Public Shared Function KernelIoControl

System Time

The SystemTime class provides methods for accessing and setting the system time of the device. The test accesses the time, increments it by one hour, then sets it back to the original. Figure 9 shows sample output from the System Time test.

Figure 9. System Time Test Results.

The SystemTime class implements the following structures and functions.

//C#
public struct SYSTEMTIME 

[DllImport("coredll.dll")]
public extern static void GetSystemTime

[DllImport("coredll.dll")]
public extern static uint SetSystemTime

'VB
Public Structure SYSTEMTIME


Public Shared Sub GetSystemTime


Public Shared Function SetSystemTime

Wave Out

The WaveOut class provides methods and classes for playing a .wav file. Due to the complexity of the Waveform Audio Interface, a WaveFile class is provided which encapsulates all of the functionality required to use the WaveOut P/Invoke functions. This class provides a mechanism for streaming audio via a specified buffer size. For more information on this sample, see the article . Figure 10 shows sample output from the Wave Out test.

Figure 10. Wave Out Test Results.

Note: A helper class named Wave is provided as a common interface to the .wav audio format for both the WaveIn and WaveOut classes.

The following classes and functions are implemented in the WaveOut class.

//C#
[DllImport ("coredll.dll")]
protected static extern int waveOutGetNumDevs();

[DllImport ("coredll.dll")]
private static extern Wave.MMSYSERR waveOutOpen

[DllImport ("coredll.dll")]
protected static extern Wave.MMSYSERR waveOutGetVolume

[DllImport ("coredll.dll")]
protected static extern Wave.MMSYSERR waveOutSetVolume

[DllImport ("coredll.dll")]
private static extern Wave.MMSYSERR waveOutPrepareHeader

[DllImport ("coredll.dll")]
private static extern Wave.MMSYSERR waveOutWrite

[DllImport ("coredll.dll")]
private static extern Wave.MMSYSERR waveOutUnprepareHeader

[DllImport ("coredll.dll")]
protected static extern Wave.MMSYSERR waveOutClose

[DllImport ("coredll.dll")]
protected static extern Wave.MMSYSERR waveOutReset

[DllImport ("coredll.dll")]
protected static extern Wave.MMSYSERR waveOutPause

[DllImport ("coredll.dll")]
protected static extern Wave.MMSYSERR waveOutRestart

protected class MMTIME

[DllImport ("coredll.dll")]
protected static extern Wave.MMSYSERR waveOutGetPosition

protected class WAVEOUTCAPS

[DllImport ("coredll.dll")]
protected static extern Wave.MMSYSERR waveOutGetDevCaps

'VB

Protected Shared Function waveOutGetNumDevs() As Integer


Private Shared Function waveOutOpen


Protected Shared Function waveOutGetVolume


Protected Shared Function waveOutSetVolume


Private Shared Function waveOutPrepareHeader


Private Shared Function waveOutWrite


Private Shared Function waveOutUnprepareHeader


Protected Shared Function waveOutClose


Protected Shared Function waveOutReset


Protected Shared Function waveOutPause


Protected Shared Function waveOutRestart

Protected Class MMTIME


Protected Shared Function waveOutGetPosition

Protected Class WAVEOUTCAPS


Protected Shared Function waveOutGetDevCaps

Wave In

The WaveIn class provides methods and classes for recording a .wav file. Due to the complexity of the Waveform Audio Interface, a WaveFile class is provided which encapsulates all of the functionality required to use the WaveIn P/Invoke functions. For more information on this sample, see the article . Figure 11 shows sample output from the Wave In test.

Figure 11. Wave In Test Results.

Note: A helper class named Wave is provided as a common interface to the .wav audio format for both the WaveIn and WaveOut classes.

The following classes and functions are implemented in the WaveIn class.

C#
[DllImport ("coredll.dll")]
protected static extern int waveInGetNumDevs();

[DllImport ("coredll.dll")]
private static extern Wave.MMSYSERR waveInOpen

[DllImport ("coredll.dll")]
private static extern Wave.MMSYSERR waveInPrepareHeader

[DllImport ("coredll.dll")]
private static extern Wave.MMSYSERR waveInUnprepareHeader

[DllImport ("coredll.dll")]
protected static extern Wave.MMSYSERR waveInClose

[DllImport ("coredll.dll")]
protected static extern Wave.MMSYSERR waveInReset

[DllImport ("coredll.dll")]
protected static extern Wave.MMSYSERR waveInStart

[DllImport ("coredll.dll")]
protected static extern Wave.MMSYSERR waveInStop

[DllImport ("coredll.dll")]
private static extern Wave.MMSYSERR waveInAddBuffer

protected class WAVEINCAPS

[DllImport ("coredll.dll")]
protected static extern Wave.MMSYSERR waveInGetDevCaps

'VB

Protected Shared Function waveInGetNumDevs() As Integer
End Function


Private Shared Function waveInOpen


Private Shared Function waveInPrepareHeader


Private Shared Function waveInUnprepareHeader


Protected Shared Function waveInClose


Protected Shared Function waveInReset


Protected Shared Function waveInStart


Protected Shared Function waveInStop


Private Shared Function waveInAddBuffer

Protected Class WAVEINCAPS


Protected Shared Function waveInGetDevCaps

Windows

The Windows class provides methods for accessing the handle of a window, as well as controlling the state of the window. The test sample creates an invisible Form and then accesses its handle via the various methods. Figure 12 shows sample output from the Windows test.

Figure 12. Windows Test Results

The following functions are implemented by the Windows class.

//C#
[DllImport("coredll.dll")]
public static extern IntPtr GetCapture();

[DllImport("CoreDll")]
public static extern IntPtr FindWindow

[DllImport("CoreDll")]
public static extern bool ShowWindow

'VB

Public Shared Function GetCapture() As IntPtr


Public Shared Function FindWindow


Public Shared Function ShowWindow

Registry

The Registry class provides methods for accessing the registry on the device. The test sample creates a key and two values, retrieves the values, deletes the values, and then deletes the key. Figure 13 shows sample output from the Registry test.

Figure 13. Registry test results.

The following functions are implemented by the Registry class

//C#
[DllImport("coredll.dll", SetLastError=true)]
public static extern int RegCreateKeyEx

[DllImport("coredll.dll", SetLastError=true)]
public static extern int RegDeleteKey

[DllImport("coredll.dll", SetLastError=true)]
public static extern int RegOpenKeyEx

[DllImport("coredll.dll", SetLastError=true)]
public static extern int RegQueryValueEx

[DllImport("coredll.dll", SetLastError=true)]
public static extern int RegSetValueEx

[DllImport("coredll.dll", SetLastError=true)]
public static extern int RegDeleteValue

[DllImport("coredll.dll", SetLastError=true)]
public static extern int RegCloseKey

'VB
 _
Public Shared Function RegCreateKeyEx

 _
Public Shared Function RegDeleteKey

 _
Public Shared Function RegOpenKeyEx

 _
Public Shared Function RegQueryValueEx

 _
Public Shared Function RegSetValueEx

 _
Public Shared Function RegDeleteValue

 _
Public Shared Function RegCloseKey

Phone

The Phone class provides methods for accessing the Phone API on Pocket PC Phone Edition devices. The test sample accesses the call log and attempts to call the number 555-5555. Figure 14 shows sample output from the Phone test.

Figure 14. Phone test results.

The following functions are implemented by the Phone class

//C#
[DllImport("Phone.dll")]
private static extern int PhoneMakeCall

[DllImport("Phone.dll")]
private static extern void PhoneOpenCallLog

[DllImport("Phone.dll")]
private static extern void PhoneCloseCallLog

[DllImport("Phone.dll")]
private static extern void PhoneGetCallLogEntry

[DllImport("Phone.dll")]
private static extern void PhoneSeekCallLog

'VB
 _
Private Shared Function PhoneMakeCall

 _
Private Shared Sub PhoneOpenCallLog

 _
Private Shared Sub PhoneCloseCallLog

 _
Private Shared Sub PhoneGetCallLogEntry

 _
Private Shared Sub PhoneSeekCallLog

Folders

The Folders class provides methods for accessing folder information. The test sample enumerates all storage devices on the device, retrieves the path to the Programs folder, and determines the available space of the Programs folder. Figure 15 shows sample output from the Folders test.

Figure 15. Folders test results.

The following functions are implemented by the Folder class

//C#
[DllImport("Coredll.dll")]
static extern int SHGetSpecialFolderPath

[DllImport("coredll.dll")]
public static extern bool GetDiskFreeSpaceEx

'VB
 _
Shared Function SHGetSpecialFolderPath

 _
Public Shared Function GetDiskFreeSpaceEx

--------------------next---------------------