C#调用API函数的方法及研究.docx
《C#调用API函数的方法及研究.docx》由会员分享,可在线阅读,更多相关《C#调用API函数的方法及研究.docx(24页珍藏版)》请在冰豆网上搜索。
C#调用API函数的方法及研究
C#调用API函数收藏
一、调用格式
usingSystem.Runtime.InteropServices;//引用此名称空间,简化后面的代码
//使用DllImportAttribute特性来引入api函数,注意声明的是空方法,即方法体为空。
[DllImport("user32.dll")]
publicstaticexternReturnTypeFunctionName(typearg1,typearg2,...);
//调用时与调用其他方法并无区别
可以使用字段进一步说明特性,用逗号隔开,如:
[DllImport("kernel32",EntryPoint="GetVersionEx")]
DllImportAttribute特性的公共字段如下:
1、CallingConvention指示向非托管实现传递方法参数时所用的CallingConvention值。
CallingConvention.Cdecl:
调用方清理堆栈。
它使您能够调用具有varargs的函数。
CallingConvention.StdCall:
被调用方清理堆栈。
它是从托管代码调用非托管函数的默认约定。
2、CharSet控制调用函数的名称版本及指示如何向方法封送String参数。
此字段被设置为CharSet值之一。
如果CharSet字段设置为Unicode,则所有字符串参数在传递到非托管实现之前都转换成Unicode字符。
这还导致向DLLEntryPoint的名称中追加字母“W”。
如果此字段设置为Ansi,则字符串将转换成ANSI字符串,同时向DLLEntryPoint的名称中追加字母“A”。
大多数Win32API使用这种追加“W”或“A”的约定。
如果CharSet设置为Auto,则这种转换就是与平台有关的(在WindowsNT上为Unicode,在Windows98上为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,则匹配规则与平台有关(在WindowsNT上为Unicode,在Windows98上为Ansi)。
如果ExactSpelling设置为true,则只有当DLL中存在“MyMethod”时才返回“MyMethod”。
3、EntryPoint指示要调用的DLL入口点的名称或序号。
如果你的方法名不想与api函数同名的话,一定要指定此参数,例如:
[DllImport("user32.dll",CharSet="CharSet.Auto",EntryPoint="MessageBox")]
publicstaticexternintMsgBox(IntPtrhWnd,stringtxt,stringcaption,inttype);
4、ExactSpelling指示是否应修改非托管DLL中的入口点的名称,以与CharSet字段中指定的CharSet值相对应。
如果为true,则当DllImportAttribute.CharSet字段设置为CharSet的Ansi值时,向方法名称中追加字母A,当DllImportAttribute.CharSet字段设置为CharSet的Unicode值时,向方法的名称中追加字母W。
此字段的默认值是false。
5、PreserveSig指示托管方法签名不应转换成返回HRESULT、并且可能有一个对应于返回值的附加[out,retval]参数的非托管签名。
6、SetLastError指示被调用方在从属性化方法返回之前将调用Win32APISetLastError。
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)]
publicclassMySystemTime
{
[FieldOffset(0)]publicushortwYear;
[FieldOffset
(2)]publicushortwMonth;
[FieldOffset(4)]publicushortwDayOfWeek;
[FieldOffset(6)]publicushortwDay;
[FieldOffset(8)]publicushortwHour;
[FieldOffset(10)]publicushortwMinute;
[FieldOffset(12)]publicushortwSecond;
[FieldOffset(14)]publicushortwMilliseconds;
}
下面是针对API中OSVERSIONINFO结构,在.net中定义对应类或结构的例子:
/**********************************************
*API中定义原结构声明
*OSVERSIONINFOASTRUCT
*dwOSVersionInfoSizeDWORD?
*dwMajorVersionDWORD?
*dwMinorVersionDWORD?
*dwBuildNumberDWORD?
*dwPlatformIdDWORD?
*szCSDVersionBYTE128dup(?
)
*OSVERSIONINFOAENDS
*
*OSVERSIONINFOequ
*********************************************/
//.net中声明为类
[StructLayout(LayoutKind.Sequential)]
publicclassOSVersionInfo
{
publicintOSVersionInfoSize;
publicintmajorVersion;
publicintminorVersion;
publicintbuildNumber;
publicintplatformId;
[MarshalAs(UnmanagedType.ByValTStr,SizeConst=128)]
publicStringversionString;
}
//或者
//.net中声明为结构
[StructLayout(LayoutKind.Sequential)]
publicstructOSVersionInfo2
{
publicintOSVersionInfoSize;
publicintmajorVersion;
publicintminorVersion;
publicintbuildNumber;
publicintplatformId;
[MarshalAs(UnmanagedType.ByValTStr,SizeConst=128)]
publicStringversionString;
}
此例中用到MashalAs特性,它用于描述字段、方法或参数的封送处理格式。
用它作为参数前缀并指定目标需要的数据类型。
例如,以下代码将两个参数作为数据类型长指针封送给WindowsAPI函数的字符串(LPStr):
[MarshalAs(UnmanagedType.LPStr)]
Stringexistingfile;
[MarshalAs(UnmanagedType.LPStr)]
Stringnewfile;
注意结构作为参数时候,一般前面要加上ref修饰符,否则会出现错误:
对象的引用没有指定对象的实例。
[DllImport("kernel32",EntryPoint="GetVersionEx")]
publicstaticexternboolGetVersionEx2(refOSVersionInfo2osvi);
三、如何保证使用托管对象的平台调用成功?
如果在调用平台invoke后的任何位置都未引用托管对象,则垃圾回收器可能将完成该托管对象。
这将释放资源并使句柄无效,从而导致平台invoke调用失败。
用HandleRef包装句柄可保证在平台invoke调用完成前,不对托管对象进行垃圾回收。
例如下面:
FileStreamfs=newFileStream("a.txt",FileMode.Open);
StringBuilderbuffer=newStringBuilder(5);
intread=0;
ReadFile(fs.Handle,buffer,5,outread,0);//调用WinAPI中的ReadFile函数
由于fs是托管对象,所以有可能在平台调用还未完成时候被垃圾回收站回收。
将文件流的句柄用HandleRef包装后,就能避免被垃圾站回收:
[DllImport("Kernel32.dll")]
publicstaticexternboolReadFile(
HandleRefhndRef,
StringBuilderbuffer,
intnumberOfBytesToRead,
outintnumberOfBytesRead,
refOverlappedflag);
......
......
FileStreamfs=newFileStream("HandleRef.txt",FileMode.Open);
HandleRefhr=newHandleRef(fs,fs.Handle);
StringBuilderbuffer=newStringBuilder(5);
intread=0;
//platforminvokewillholdreferencetoHandleRefuntilcallends
ReadFile(hr,buffer,5,outread,0);
我在自己最近的编程中注意到一个趋势,正是这个趋势才引出本月的专栏主题。
最近,我在基于Microsoft?
.NETFramework的应用程序中完成了大量的Win32?
Interop。
我并不是要说我的应用程序充满了自定义的interop代码,但有时我会在.NETFramework类库中碰到一些次要但又繁絮、不充分的内容,通过调用该Windows?
API,可以快速减少这样的麻烦。
因此我认为,.NETFramework1.0或1.1版类库中存在任何Windows所没有的功能限制都不足为怪。
毕竟,32位的Windows(不管何种版本)是一个成熟的操作系统,为广大客户服务了十多年。
相比之下,.NETFramework却是一个新事物。
随着越来越多的开发人员将生产应用程序转到托管代码,开发人员更频繁地研究底层操作系统以图找出一些关键功能显得很自然—至少目前是如此。
值得庆幸的是,公共语言运行库(CLR)的interop功能(称为平台调用(P/Invoke))非常完善。
在本专栏中,我将重点介绍如何实际使用P/Invoke来调用WindowsAPI函数。
当指CLR的COMInterop功能时,P/Invoke当作名词使用;当指该功能的使用时,则将其当作动词使用。
我并不打算直接介绍COMInterop,因为它比P/Invoke具有更好的可访问性,却更加复杂,这有点自相矛盾,这使得将COMInterop作为专栏主题来讨论不太简明扼要。
走进P/Invoke
首先从考察一个简单的P/Invoke示例开始。
让我们看一看如何调用Win32MessageBeep函数,它的非托管声明如以下代码所示:
BOOLMessageBeep(
UINTuType//beeptype
);
为了调用MessageBeep,您需要在C#中将以下代码添加到一个类或结构定义中:
[DllImport("User32.dll")]
staticexternBooleanMessageBeep(UInt32beepType);
令人惊讶的是,只需要这段代码就可以使托管代码调用非托管的MessageBeepAPI。
它不是一个方法调用,而是一个外部方法定义。
(另外,它接近于一个来自C而C#允许的直接端口,因此以它为起点来介绍一些概念是有帮助的。
)来自托管代码的可能调用如下所示:
MessageBeep(0);
请注意,现在MessageBeep方法被声明为static。
这是P/Invoke方法所要求的,因为在该WindowsAPI中没有一致的实例概念。
接下来,还要注意该方法被标记为extern。
这是提示编译器该方法是通过一个从DLL导出的函数实现的,因此不需要提供方法体。
说到缺少方法体,您是否注意到MessageBeep声明并没有包含一个方法体?
与大多数算法由中间语言(IL)指令组成的托管方法不同,P/Invoke方法只是元数据,实时(JIT)编译器在运行时通过它将托管代码与非托管的DLL函数连接起来。
执行这种到非托管世界的连接所需的一个重要信息就是导出非托管方法的DLL的名称。
这一信息是由MessageBeep方法声明之前的DllImport自定义属性提供的。
在本例中,可以看到,MessageBeep非托管API是由Windows中的User32.dll导出的。
到现在为止,关于调用MessageBeep就剩两个话题没有介绍,请回顾一下,调用的代码与以下所示代码片段非常相似:
[DllImport("User32.dll")]
staticexternBooleanMessageBeep(UInt32beepType);
最后这两个话题是与数据封送处理(datamarshaling)和从托管代码到非托管函数的实际方法调用有关的话题。
调用非托管MessageBeep函数可以由找到作用域内的externMessageBeep声明的任何托管代码执行。
该调用类似于任何其他对静态方法的调用。
它与其他任何托管方法调用的共同之处在于带来了数据封送处理的需要。
C#的规则之一是它的调用语法只能访问CLR数据类型,例如System.UInt32和System.Boolean。
C#显然不识别WindowsAPI中使用的基于C的数据类型(例如UINT和BOOL),这些类型只是C语言类型的类型定义而已。
所以当WindowsAPI函数MessageBeep按以下方式编写时
BOOLMessageBeep(UINTuType)
外部方法就必须使用CLR类型来定义,如您在前面的代码片段中所看到的。
需要使用与基础API函数类型不同但与之兼容的CLR类型是P/Invoke较难使用的一个方面。
因此,在本专栏的后面我将用完整的章节来介绍数据封送处理。
样式
在C#中对WindowsAPI进行P/Invoke调用是很简单的。
但如果类库拒绝使您的应用程序发出嘟声,应该想方设法调用Windows使它进行这项工作,是吗?
是的。
但是与选择的方法有关,而且关系甚大!
通常,如果类库提供某种途径来实现您的意图,则最好使用API而不要直接调用非托管代码,因为CLR类型和Win32之间在样式上有很大的不同。
我可以将关于这个问题的建议归结为一句话。
当您进行P/Invoke时,不要使应用程序逻辑直接属于任何外部方法或其中的构件。
如果您遵循这个小规则,从长远看经常会省去许多的麻烦。
图1中的代码显示了我所讨论的MessageBeep外部方法的最少附加代码。
图1中并没有任何显著的变化,而只是对无包装的外部方法进行一些普通的改进,这可以使工作更加轻松一些。
从顶部开始,您会注意到一个名为Sound的完整类型,它专用于MessageBeep。
如果我需要使用WindowsAPI函数PlaySound来添加对播放波形的支持,则可以重用Sound类型。
然而,我不会因公开单个公共静态方法的类型而生气。
毕竟这只是应用程序代码而已。
还应该注意到,Sound是密封的,并定义了一个空的私有构造函数。
这些只是一些细节,目的是使用户不会错误地从Sound派生类或者创建它的实例。
图1中的代码的下一个特征是,P/Invoke出现位置的实际外部方法是Sound的私有方法。
这个方法只是由公共MessageBeep方法间接公开,后者接受BeepTypes类型的参数。
这个间接的额外层是一个很关键的细节,它提供了以下好处。
首先,应该在类库中引入一个未来的beep托管方法,可以重复地通过公共MessageBeep方法来使用托管API,而不必更改应用程序中的其余代码。
该包装方法的第二个好处是:
当您进行P/Invoke调用时,您放弃了免受访问冲突和其他低级破坏的权利,这通常是由CLR提供的。
缓冲方法可以保护您的应用程序的其余部分免受访问冲突及类似问题的影响(即使它不做任何事而只是传递参数)。
该缓冲方法将由P/Invoke调用引入的任何潜在的错误本地化。
将私有外部方法隐藏在公共包装后面的第三同时也是最后的一个好处是,提供了向该方法添加一些最小的CLR样式的机会。
例如,在图1中,我将WindowsAPI函数返回的Boolean失败转换成更像CLR的异常。
我还定义了一个名为BeepTypes的枚举类型,它的成员对应于同该WindowsAPI一起使用的定义值。
由于C#不支持定义,因此可以使用托管枚举类型来避免幻数向整个应用程序代码扩散。
包装方法的最后一个好处对于简单的WindowsAPI函数(如MessageBeep)诚然是微不足道的。
但是当您开始调用更复杂的非托管函数时,您会发现,手动将WindowsAPI样式转换成对CLR更加友好的方法所带来的好处会越来越多。
越是打算在整个应用程序中重用interop功能,越是应该认真地考虑包装的设计。
同时我认为,在非面向对象的静态包装方法中使用对CLR友好的参数也并非不可以。
DLLImport属性
现在是更深入地进行探讨的时候了。
在对托管代码进行P/Invoke调用时,DllImportAttribute类型扮演着重要的角色。
DllImportAttribute的主要作用是给CLR指示哪个DLL导出您想要调用的函数。
相关DLL的名称被作为一个构造函数参数传递给DllImportAttribute。
如果您无法肯定哪个DLL定义了您要使用的WindowsAPI函数,PlatformSDK文档将为您提供最好的帮助资源。
在WindowsAPI函数主题文字临近结尾的位置,SDK文档指定了C应用程序要使用该函数必须链接的.lib文件。
在几乎所有的情况下,该.lib文件具有与定义该函数的系统DLL文件相同的名称。
例如,如果该函数需要C应用程序链接到Kernel32.lib,则该函数就定义在Kernel32.dll中。
您可以在MessageBeep中找到有关MessageBeep的PlatformSDK文档主题。
在该主题结尾处,您会注意到它指出库文件是User32.lib;这表明MessageBeep是从User32.dll中导出的。
可选的DllImportAttribute属性
除了指出宿主DLL外,DllImportAttribute还包含了一些可选属性,其中四个特别有趣:
EntryPoint、CharSet、SetLastError和CallingConvention。
EntryPoint在不希望外部托管方法具有与DLL导出相同的名称的情况下,可以设置该属性来指示导出的DLL函数的入口点名称。
当您定义两个调用相同非托管函数的外部方法时,这特别有用。
另外,在Windows中还可以通过它们的序号值绑定到导出的DLL函数。
如果您需要这样做,则诸如“#1”或“#129”的EntryPoint值指示DLL中非托管函数的序号值而不是函数名。
CharSet对于字符集,并非所有版本的Windows都是同样创建的。
Windows9x系列产品缺少重要的Unicode支持,而WindowsNT和WindowsCE系列则一开始就使用Unicode。
在这些操作系统上运行的CLR将Unicode用于String和Char数据的内部表示。
但也不必担心—当调用Windows9xAPI函数时,CLR会自动进行必要的转换,将其从Unicode转换为ANSI。
如果DLL函数不以任何方式处理文本,则可以忽略DllImportAttribute的Char