C# API
C:/ProgramFiles/MicrosoftVisual Studio .NET/ FrameworkSDK/Samples/ Technologies/ Interop/PlatformInvoke/ WinAPIs/CS
目录下有大量的调用
API
的例子。
一、调用格式
using System.Runtime.InteropServices; //
引用此名称空间,简化后面的代码
//
使用
DllImportAttribute
特性来引入
api
函数,注意声明的是空方法,即方法体为空。
[DllImport("user32.dll")]
public static extern ReturnType FunctionName(type arg1,type arg2,...);
//
调用时与调用其他方法并无区别
可以使用字段进一步说明特性,用逗号隔开,如:
[ DllImport( "kernel32", EntryPoint="GetVersionEx" )]
DllImportAttribute
特性的公共字段如下:
1
、
CallingConvention
指示向非托管实现传递方法参数时所用的
CallingConvention
值。
CallingConvention.Cdecl :
调用方清理堆栈。它使您能够调用具有
varargs
的函数。
CallingConvention.StdCall :
被调用方清理堆栈。它是从托管代码调用非托管函数的默认约定。
2
、
CharSet
控制调用函数的名称版本及指示如何向方法封送
String
参数。
此字段被设置为
CharSet
值之一。如果
CharSet
字段设置为
Unicode
,则所有字符串参数在传递到非托管实现之前都转换成
Unicode
字符。这还导致向
DLL EntryPoint
的名称中追加字母“
W
”。如果此字段设置为
Ansi
,则字符串将转换成
ANSI
字符串,同时向
DLL EntryPoint
的名称中追加字母“
A
”。大多数
Win32 API
使用这种追加“
W
”或“
A
”的约定。如果
CharSet
设置为
Auto
,则这种转换就是与平台有关的(在
Windows NT
上为
Unicode
,在
Windows 98
上为
Ansi
)。
CharSet
的默认值为
Ansi
。
CharSet
字段也用于确定将从指定的
DLL
导入哪个版本的函数。
CharSet.Ansi
和
CharSet.Unicode
的名称匹配规则大不相同。对于
Ansi
来说,如果将
EntryPoint
设置为“
MyMethod
”且它存在的话,则返回“
MyMethod
”。如果
DLL
中没有“
MyMethod
”,但存在“
MyMethodA
”,则返回“
MyMethodA
”。
对于
Unicode
来说则正好相反。如果将
EntryPoint
设置为“
MyMethod
”且它存在的话,则返回“
MyMethodW
”。如果
DLL
中不存在“
MyMethodW
”,但存在“
MyMethod
”,则返回“
MyMethod
”。如果使用的是
Auto
,则匹配规则与平台有关(在
Windows NT
上为
Unicode
,在
Windows 98
上为
Ansi
)。如果
ExactSpelling
设置为
true
,则只有当
DLL
中存在“
MyMethod
”时才返回“
MyMethod
”。
3
、
EntryPoint
指示要调用的
DLL
入口点的名称或序号。
如果你的方法名不想与
api
函数同名的话,一定要指定此参数
,
例如:
[DllImport("user32.dll",CharSet="CharSet.Auto",EntryPoint="MessageBox")]
public static extern int MsgBox(IntPtr hWnd,string txt,string caption, int type);
4
、
ExactSpelling
指示是否应修改非托管
DLL
中的入口点的名称,以与
CharSet
字段中指定的
CharSet
值相对应。
如果为
true
,则当
DllImportAttribute.CharSet
字段设置为
CharSet
的
Ansi
值时,向方法名称中追加字母
A
,当
DllImportAttribute.CharSet
字段设置为
CharSet
的
Unicode
值时,向方法的名称中追加字母
W
。此字段的默认值是
false
。
5
、
PreserveSig
指示托管方法签名不应转换成返回
HRESULT
、并且可能有一个对应于返回值的附加
[out, retval]
参数的非托管签名。
6
、
SetLastError
指示被调用方在从属性化方法返回之前将调用
Win32 API SetLastError
。
true
指示调用方将调用
SetLastError
,默认为
false
。运行时封送拆收器将调用
GetLastError
并缓存返回的值,以防其被其他
API
调用重写。用户可通过调用
GetLastWin32Error
来检索错误代码。
二、参数类型:
1
、数值型直接用对应的就可。(
DWORD -> int , WORD -> Int16
)
2
、
API
中字符串指针类型
-> .net
中
string
3
、
API
中句柄
(dWord) -> .net
中
IntPtr
4
、
API
中结构
-> .net
中结构或者类。注意这种情况下,要先用
StructLayout
特性限定声明结构或类
公共语言运行库利用
StructLayoutAttribute
控制类或结构的数据字段在托管内存中的物理布局
,
即类或结构需要按某种方式排列。如果要将类传递给需要指定布局的非托管代码,则显式控制类布局是重要的。它的构造函数中用
LayoutKind
值初始化
StructLayoutAttribute
类的新实例。
LayoutKind.Sequential
用于强制将成员按其出现的顺序进行顺序布局。
LayoutKind.Explicit
用于控制每个数据成员的精确位置。利用
Explicit
,
每个成员必须使用
FieldOffsetAttribute
指示此字段在类型中的位置。如:
[StructLayout(LayoutKind.Explicit, Size=16, CharSet=CharSet.Ansi)]
public class MySystemTime
{
[FieldOffset(0)]public ushort wYear;
[FieldOffset(2)]public ushort wMonth;
[FieldOffset(4)]public ushort wDayOfWeek;
[FieldOffset(6)]public ushort wDay;
[FieldOffset(8)]public ushort wHour;
[FieldOffset(10)]public ushort wMinute;
[FieldOffset(12)]public ushort wSecond;
[FieldOffset(14)]public ushort wMilliseconds;
}
下面是针对
API
中
OSVERSIONINFO
结构,在
.net
中定义对应类或结构的例子:
/**********************************************
* API
中定义原结构声明
* OSVERSIONINFOA STRUCT
* dwOSVersionInfoSize DWORD ?
* dwMajorVersion DWORD ?
* dwMinorVersion DWORD ?
* dwBuildNumber DWORD ?
* dwPlatformId DWORD ?
* szCSDVersion BYTE 128 dup (?)
* OSVERSIONINFOA ENDS
*
* OSVERSIONINFO equ <OSVERSIONINFOA>
*********************************************/
//.net
中声明为类
[ StructLayout( LayoutKind.Sequential )]
public class OSVersionInfo
{
public int OSVersionInfoSize;
public int majorVersion;
public int minorVersion;
public int buildNumber;
public int platformId;
[ MarshalAs( UnmanagedType.ByValTStr, SizeConst=128 )]
public String versionString;
}
//
或者
//.net
中声明为结构
[ StructLayout( LayoutKind.Sequential )]
public struct OSVersionInfo2
{
public int OSVersionInfoSize;
public int majorVersion;
public int minorVersion;
public int buildNumber;
public int platformId;
[ MarshalAs( UnmanagedType.ByValTStr, SizeConst=128 )]
public String versionString;
}
此例中用到
MashalAs
特性,它用于描述字段、方法或参数的封送处理格式。用它作为参数前缀并指定目标需要的数据类型。例如,以下代码将两个参数作为数据类型长指针封送给
Windows API
函数的字符串
(LPStr)
:
[MarshalAs(UnmanagedType.LPStr)]
String existingfile;
[MarshalAs(UnmanagedType.LPStr)]
String newfile;
注意结构作为参数时候,一般前面要加上
ref
修饰符,否则会出现错误:
对象的引用没有指定对象的实例。
[ DllImport( "kernel32", EntryPoint="GetVersionEx" )]
public static extern bool GetVersionEx2( ref OSVersionInfo2 osvi );
三、如何保证使用托管对象的平台调用成功?
如果在调用平台
invoke
后的任何位置都未引用托管对象,则垃圾回收器可能将完成该托管对象。这将释放资源并使句柄无效,从而导致平台
invoke
调用失败。用
HandleRef
包装句柄可保证在平台
invoke
调用完成前,不对托管对象进行垃圾回收。
例如下面:
FileStream fs = new FileStream( "a.txt", FileMode.Open );
StringBuilder buffer = new StringBuilder( 5 );
int read = 0;
ReadFile(fs.Handle, buffer, 5, out read, 0 ); //
调用
Win API
中的
ReadFile
函数
由于
fs
是托管对象,所以有可能在平台调用还未完成时候被垃圾回收站回收。将文件流的句柄用
HandleRef
包装后,就能避免被垃圾站回收
:
[ DllImport( "Kernel32.dll" )]
public static extern bool ReadFile(
HandleRef hndRef,
StringBuilder buffer,
int numberOfBytesToRead,
out int numberOfBytesRead,
ref Overlapped flag );
......
......
FileStream fs = new FileStream( "HandleRef.txt", FileMode.Open );
HandleRef hr = new HandleRef( fs, fs.Handle );
StringBuilder buffer = new StringBuilder( 5 );
int read = 0;
// platform invoke will hold reference to HandleRef until call ends
ReadFile( hr, buffer, 5, out read, 0 );
我在自己最近的编程中注意到一个趋势,正是这个趋势才引出本月的专栏主题。最近,我在基于
Microsoft? .NET Framework
的应用程序中完成了大量的
Win32? Interop
。我并不是要说我的应用程序充满了自定义的
interop
代码,但有时我会在
.NET Framework
类库中碰到一些次要但又繁絮、不充分的内容,通过调用该
Windows? API
,可以快速减少这样的麻烦。
因此我认为,
.NET Framework 1.0
或
1.1
版类库中存在任何
Windows
所没有的功能限制都不足为怪。毕竟,
32
位的
Windows
(不管何种版本)是一个成熟的操作系统,为广大客户服务了十多年。相比之下,
.NET Framework
却是一个新事物。
随着越来越多的开发人