C# API 大全(二)

C# API 大全(二) 
2010-03-23 13:11 
如果您不熟悉 C 语法或者调用 Windows API 函数，有时很难知道一个方法参数是否需要指针。一个常见的指示符是看参数类型是否是以字母 P 或 LP 开头的，例如 LPDWORD 或 PINT。在这两个例子中，LP 和 P 指示参数是一个指针，而它们指向的数据类型分别为 DWORD 或 INT。然而，在有些情况下，可以直接使用 C 语言语法中的星号 (*) 将 API 函数定义为指针。以下代码片段展示了这方面的示例： 
void TakesAPointer(DWORD* pNum); 
可以看到，上述函数的唯一一个参数是指向 DWORD 变量的指针。 
当 通过 P/Invoke 封送指针时，ref 和 out 只用于托管代码中的值类型。当一个参数的 CLR 类型使用 struct 关键字定义时，可以认为该参数是一个值类型。Out 和 ref 用于封送指向这些数据类型的指针，因为通常值类型变量是对象或数据，而在托管代码中并没有对值类型的引用。相反，当封送引用类型对象时，并不需要 ref 和 out 关键字，因为变量已经是对象的引用了。 如果您对引用类型和值类型之间的差别不是很熟悉，请查阅 2000 年 12 月发行的 MSDN? Magazine，在 .NET 专栏的主题中可以找到更多信息。大多数 CLR 类型都是引用类型；然而，除了 System.String 和 System.Object，所有的基元类型（例如 System.Int32 和 System.Boolean）都是值类型。 封送不透明 (Opaque) 指针：一种特殊情况 
有时在 Windows API 中，方法传递或返回的指针是不透明的，这意味着该指针值从技术角度讲是一个指针，但代码却不直接使用它。相反，代码将该指针返回给 Windows 以便随后进行重用。 
一个非常常见的例子就是句柄的概念。在 Windows 中，内部数据结构（从文件到屏幕上的按钮）在应用程序代码中都表示为句柄。句柄其实就是不透明的指针或有着指针宽度的数值，应用程序用它来表示内部的 OS 构造。 少数情况下，API 函数也将不透明指针定义为 PVOID 或 LPVOID 类型。在Windows API 的定义中，这些类型意思就是说该指针没有类型。 
当 一个不透明指针返回给您的应用程序（或者您的应用程序期望得到一个不透明指针）时，您应该将参数或返回值封送为 CLR 中的一种特殊类型— 
System.IntPtr。当您使用 IntPtr 类型时，通常不使用 out 或 ref 参数，因为 IntPtr 意为直接持有指针。不过，如果您将一个指针封送为一个指针，则对 IntPtr 使用 by-ref 参数是合适的。 
在 CLR 类型系统中，System.IntPtr 类型有一个特殊的属性。不像系统中的其他基类型，IntPtr 并没有固定的大小。相反，它在运行时的大小是依底层操作系统的正常指针大小而定的。这意味着在 32 位的 Windows 中，IntPtr 变量的宽度是 32 位的，而在 64 位的 Windows 中，实时编译器编译的代码会将 IntPtr 值看作 64 位的值。当在托管代码和非托管代码之间封送不透明指针时，这种自动调节大小的特点十分有用。 
请记住，任何返回或接受句柄的 API 函数其实操作的就是不透明指针。您的代码应该将 Windows 中的句柄封送成 System.IntPtr 值。 
您 可以在托管代码中将 IntPtr 值强制转换为 32 位或 64 位的整数值，或将后者强制转换为前者。然而，当使用 Windows API 函数时，因为指针应是不透明的，所以除了存储和传递给外部方法外，不能将它们另做它用。这种“只限存储和传递”规则的两个特例是当您需要向外部方法传递 null 指针值和需要比较 IntPtr 值与 null 值的情况。为了做到这一点，您不能将零强制转换为 System.IntPtr，而应该在 IntPtr 类型上使用 Int32.Zero 静态公共字段，以便获得用于比较或赋值的 null 值。 封送文本 
在 编程时经常要对文本数据进行处理。文本为 interop 制造了一些麻烦，这有两个原因。首先，底层操作系统可能使用 Unicode 来表示字符串，也可能使用 ANSI。在极少数情况下，例如 MultiByteToWideChar API 函数的两个参数在字符集上是不一致的。 
第 二个原因是，当需要进行 P/Invoke 时，要处理文本还需要特别了解到 C 和 CLR 处理文本的方式是不同的。在 C 中，字符串实际上只是一个字符值数组，通常以 null 作为结束符。大多数 Windows API 函数是按照以下条件处理字符串的：对于 ANSI，将其作为字符值数组；对于 Unicode，将其作为宽字符值数组。 
幸运的是，CLR 被设计得相当灵活，当封送文本时问题得以轻松解决，而不用在意 Windows API 函数期望从您的应用程序得到的是什么。这里是一些需要记住的主要考虑事项： 
? 是您的应用程序向 API 函数传递文本数据，还是 API 函数向您的应用程序返回字符串数据？或者二者兼有？ ? 您的外部方法应该使用什么托管类型？ 
? API 函数期望得到的是什么格式的非托管字符串？ 
 
我 们首先解答最后一个问题。大多数 Windows API 函数都带有 LPTSTR 或 LPCTSTR 值。（从函数角度看）它们分别是可修改和不可修改的缓冲区，包含以 null 结束的字符数组。“C”代表常数，意味着使用该参数信息不会传递到函数外部。LPTSTR 中的“T”表明该参数可以是 Unicode 或 ANSI，取决于您选择的字符集和底层操作系统的字符集。因为在 Windows API 中大多数字符串参数都是这两种类型之一，所以只要在 DllImportAttribute 中选择 CharSet.Auto，CLR 就按默认的方式工作。 
然而，有些 API 函数或自定义的 DLL 函数采用不同的方式表示字符串。如果您要用到一个这样的函数，就可以采用 MarshalAsAttribute 修饰外部方法的字符串参数，并指明一种不同于默认 LPTSTR 的字符串格式。有关 MarshalAsAttribute 的更多信息，请参阅位于 MarshalAsAttribute Class 的 Platform SDK 文档主题。 
现在让我们看一下字符串信息在您的代码 和非托管函数之间传递的方向。有两种方式可以知道处理字符串时信息的传递方向。第一个也是最可靠的一个方法就是首先理解参数的用途。例如，您正调用一个参 数，它的名称类似 
CreateMutex 并带有一个字符串，则可以想像该字符串信息是从应用程序向 API 函数传递的。同时，如果您调用 GetUserName，则该函数的名称表明字符串信息是从该函数向您的应用程序传递的。 
除了这种比较合理的方法外，第二种查找信息传 递方向的方式就是查找 API 参数类型中的字母“C”。例如，GetUserName API 函数的第一个参数被定义为 LPTSTR 类型，它代表一个指向 Unicode 或 ANSI 字符串缓冲区的长指针。但是 CreateMutex 的名称参数被类型化为 LTCTSTR。请注意，这里的类型定义是一样的，但增加一个字母“C”来表明缓冲区为常数，API 函数不能写入。 一旦明确了文本参数是只用作输入还是用作输入/输出，就可以确定使用哪种 CLR 类型作为参数类型。这里有一些规则。如果字符串参数只用作输入，则使用 System.String 类型。在托管代码中，字符串是不变的，适合用于不会被本机 API 函数更改的缓冲区。 

如 果字符串参数可以用作输入和/或输出，则使用 System.StringBuilder 类型。StringBuilder 类型是一个很有用的类库类型，它可以帮助您有效地构建字符串，也正好可以将缓冲区传递给本机函数，由本机函数为您填充字符串数据。一旦函数调用返回，您只 需要调用 StringBuilder 对象的 ToString 就可以得到一个 String 对象。

GetShortPathName API 函数能很好地用于显示什么时候使用 String、什么时候使用 StringBuilder，因为它只带有三个参数：一个输入字符串、一个输出字符串和一个指明输出缓冲区的字符长度的参数。 
图 3 所示为加注释的非托管 GetShortPathName 函数文档，它同时指出了输入和输出字符串参数。它引出了托管的外部方法定义，也如图 3 所示。请注意第一个参数被封送为 System.String，因为它是一个只用作输入的参数。第二个参数代表一个输出缓冲区，它使用了 System.StringBuilder。 小结 
本月专栏所介绍的 P/Invoke 功能足够调用 Windows 中的许多 API 函数。然而，如果您大量用到 interop，则会最终发现自己封送了很复杂的数据结构，甚至可能需要在托管代码中通过指针直接访问内存。实际上，本机代码中的 interop 可以是一个将细节和低级比特藏在里面的真正的潘多拉盒子。CLR、C# 和托管 C++ 提供了许多有用的功能；也许以后我会在本专栏介绍高级的 P/Invoke 话题。 
同时，只要您觉得 .NET Framework 类库无法播放您的声音或者为您执行其他一些功能，您可以知道如何向原始而优秀的 Windows API 寻求一些帮助。 API (应用编程接口)是程序与处理器接口的命令集。最常用的就是在外部调用微软WINDOWS内部的进程。WINDOWS API包括成千的你可以使用的函数、结构、常量。这些函数是用C语言写的，在使用他们之前，你必须声明。定义Dll的进程将相当的复杂，甚至比VB还复 杂。你可以使用API Viewer工具得到API函数的声明，但是必须注意的是，它的参数类型跟C#的不一样。 大部分的高级语言都支持API， 微软函数类库(MFC)封装了大部分的Win32 API。ODBC API对提高数据库的操作速度大有好处。使用API，可以请求更底层的系统服务。API从简单的对话框到复杂的加密运算都提供支持。开发者应该知道如何在 他们程序中使用API  
API有许多类型，（针对不同的操作系统、处理器„„„„） OS specific API:  操作系统特有API:  
每 种操作系统都有一套公用API和专有API。比如：Windows NT 支持MS-DOS, Win16, Win32, POSIX (便携式操作系统接口)，OS/2 console API ；同时Windows 95 supports MS-DOS, Win16 和Win32 API。 Win16 和 Win32 API:  
WIN16 是基于16位的处理器，并使用16位的值，它是一个独立的平台。比如：你可以运行TSR 程序在MS-DOS环境下。 
WIN32 是基于32位的处理器，并使用32位的值。他可用于任何操作系统，它的使用范围更广。 
Win32 API has 32 prefix after the library name e.g. KERNEL32, USER32 etc?  Win32 API的DLL一般都具有32的后缀，比如：KERNEL32, USER32等。 所有的API都在下面3个DLL中实现的。

Kernel  User  GDI  
1. KERNEL  
它的库名是：KERNEL32.DLL，它是操作系统管理的API集 Process loading. 加载进程 Context switching.  File I/O. 文件操作 
Memory management. 内存管理 
比如：GlobalMemoryStatus 函数获得目前系统物理虚拟内存的使用信息。 2. USER  
在WIN32下，它的库名是 USER32.DLL  
This allows managing the entire user interfaces such as  它管理全部的用户界面，比如： Windows 窗口 Menus 菜单 
Dialog Boxes 对话框 Icons etc., 图标等 
比如：DrawIcon 画一个图标在指定的设备上。 3. GDI (Graphical Device Interface)  
这个DLL是GDI32.dll，它负责图像的输出，使用GDI绘出窗口，菜单，对话框 
It can create Graphical Output. 输出图像 
比如：CreateBitmap 函数创建一个指定宽度、高度和颜色格式的位图。 
C#中API的工具对初学者是相当不错的。在C#使用中使用API之前，你应该先知道C#中如何使用结构、类型转换，安全与不安全代码等。 使用复杂的api之前，我们先用一个简单的MessageBox API作为列子。打开一个C#工程，增加一个按钮，在按钮的点击事件中，我们将显示一个信息框。 增加使用外部库的命名空间： 
using System.Runtime.InteropServices;  下面声明API  
[DllImport("User32.dll")]  
DllImport属性用来指定包含外部方法的动态连接库的位置。 "User32.dll"指出了库名，static 指明它不属于特定的对象。extern 指明是一个外部的方法。带有DllImport 属性的方法必须带有修饰符extern 。 
MessageBox 是一个汉数名，带四个参数返回一个int型值。 
许多API使用结构来传递、返回参数，这样可以减少复杂度。它也允许使用象MessageBox 函数那样，使用固定的参数。 
在按钮的点击事件中增加下面代码： 
protected void button1_Click (object sender, System.EventArgs e)  {  
MessageBox (0,"API Message Box","API Demo",0);  

}

编译并运行程序，点击按钮以后，你就可以看到一个由API调用的信息框。 Using structure 使用结构 
API中经常使用复杂的结构。不过一旦你明白了他们，将是很简单的。 
In next example we will use GetSystemInfo API which returns information about the current system.  
下面的列子，我们用GetSystemInfo API得到当前系统的信息。 
第一步：增加一个C#窗口，并在上面增加一个按钮，在窗口代码页增加一个命名空间： 
using System.Runtime.InteropServices;  声明 GetSystemInfo 的参数结构:  
[StructLayout(LayoutKind.Sequential)]  public struct SYSTEM_INFO {  public uint dwOemId;  public uint dwPageSize;  
public uint lpMinimumApplicationAddress;  public uint lpMaximumApplicationAddress;  public uint dwActiveProcessorMask;  public uint dwNumberOfProcessors;  public uint dwProcessorType;  
public uint dwAllocationGranularity;  public uint dwProcessorLevel;  public uint dwProcessorRevision;  } 
声明API函数： 
[DllImport("kernel32")]  
static extern void GetSystemInfo(ref SYSTEM_INFO pSI);  
ref是一个标志参量传递形式的关键字，它使传入传出的变量指向同一个变量（传址传递） 
在按钮点击事件中增加下面的代码， 
protected void button1_Click (object sender, System.EventArgs e)  {  try  { 
SYSTEM_INFO pSI = new SYSTEM_INFO();  GetSystemInfo(ref pSI);  Once you retrieve the structure perform operations on required parameter  比如： 
listBox1.Items.Insert(0,pSI.dwActiveProcessorMask.ToString());  }  
catch(Exception er)  {  
MessageBox.Show (er.Message);  } 

}

} 
 
用Visual C#调用Windows API函数 北京机械工业学院研00级（100085）冉林仓 
Api函数是构筑Windws应用程序的基石，每一种Windows应用程序开发工具，它提供的底层函数都间接或直接地调用了Windows API函数，同时为了实现功能扩展，一般也都提供了调用WindowsAPI函数的接口，也就是说具备调用动态连接库的能力。Visual C#和其它开发工具一样也能够调用动态链接库的API函数。.NET框架本身提供了这样一种服务,允许受管辖的代码调用动态链接库中实现的非受管辖函数, 包括操作系统提供的Windows API函数。它能够定位和调用输出函数,根据需要，组织其各个参数(整型、字符串类型、数组、和结构等等)跨越互操作边界。 
下面以C#为例简单介绍调用API的基本过程：  动态链接库函数的声明  
动态链接库函数使用前必须声明，相对于VB,C#函数声明显得更加罗嗦，前者通过 Api Viewer粘贴以后，可以直接使用，而后者则需要对参数作些额外的变化工作。 
动态链接库函数声明部分一般由下列两部分组成，一是函数名或索引号，二是动态链接库的文件名。  
譬如，你想调用User32.DLL中的MessageBox函数，我们必须指明函数的名字MessageBoxA或MessageBoxW，以及库名字 User32.dll,我们知道Win32 API对每一个涉及字符串和字符的函数一般都存在两个版本，单字节字符的ANSI版本和双字节字符的UNICODE版本。 
下面是一个调用API函数的例子：  
[DllImport("KERNEL32.DLL", EntryPoint="MoveFileW", SetLastError=true,  CharSet=CharSet.Unicode, ExactSpelling=true,  CallingConvention=CallingConvention.StdCall)]  
public static extern bool MoveFile(String src, String dst); 
其中入口点EntryPoint标识函数在动态链接库的入口位置，在一个受管辖的工程中，目标函数的原始名字和序号入口点不仅标识一个跨越互操作界限的函 数。而且，你还可以把这个入口点映射为一个不同的名字，也就是对函数进行重命名。重命名可以给调用函数带来种种便利，通过重命名，一方面我们不用为函数的 大小写伤透脑筋，同时它也可以保证与已有的命名规则保持一致，允许带有不同参数类型的函数共存，更重要的是它简化了对ANSI和Unicode版本的调 用。CharSet用于标识函数调用所采用的是Unicode或是ANSI版本，ExactSpelling＝false将告诉编译器,让编译器决定使用 Unicode或者是Ansi版本。其它的参数请参考MSDN在线帮助. 
在C#中，你可以在EntryPoint域通过名字和序号声明一个动态链接库函数，如果在方法定义中使用的函数名与DLL入口点相同，你不需要在EntryPoint域显示声明函数。否则，你必须使用下列属性格式指示一个名字和序号。 [DllImport("dllname", EntryPoint="Functionname")]  [DllImport("dllname", EntryPoint="#123")]  值得注意的是，你必须在数字序号前加“＃”  
下面是一个用MsgBox替换MessageBox名字的例子：  [C#]  
using System.Runtime.InteropServices; 
public class Win32 {  
[DllImport("user32.dll", EntryPoint="MessageBox")]  
public static extern int MsgBox(int hWnd, String text, String caption, uint type);  }  
许多受管辖的动态链接库函数期望你能够传递一个复杂的参数类型给函数，譬如一个用户定义的结构类型成员或者受管辖代码定义的一个类成员，这时你必须提供额外的信息格式化这个类型，以保持参数原有的布局和对齐。 C#提供了一个StructLayoutAttribute类，通过它你可以定义自己的格式化类型，在受管辖代码中，格式化类型是一个用StructLayoutAttribute说明的结构或类成员，通过它能够保证其内部成员预期的布局信息。布局的选项共有三种： 
布局选项  描述  
LayoutKind.Automatic  
为了提高效率允许运行态对类型成员重新排序。  
注意：永远不要使用这个选项来调用不受管辖的动态链接库函数。  LayoutKind.Explicit  
对每个域按照FieldOffset属性对类型成员排序  LayoutKind.Sequential  
对出现在受管辖类型定义地方的不受管辖内存中的类型成员进行排序。  传递结构成员  
下面的例子说明如何在受管辖代码中定义一个点和矩形类型，并作为一个参数传递给User32.dll库中的PtInRect函数，  函数的不受管辖原型声明如下：  
BOOL PtInRect(const RECT *lprc, POINT pt);  注意你必须通过引用传递Rect结构参数，因为函数需要一个Rect的结构指针。 

 [C#]

using System.Runtime.InteropServices; [StructLayout(LayoutKind.Sequential)]  public struct Point {  public int x;  public int y;  } 
[StructLayout(LayoutKind.Explicit]  public struct Rect {  
[FieldOffset(0)] public int left;  [FieldOffset(4)] public int top;  [FieldOffset(8)] public int right;  [FieldOffset(12)] public int bottom;  } 
class Win32API {  
[DllImport("User32.dll")]  
public static extern Bool PtInRect(ref Rect r, Point p);  }  
类似你可以调用GetSystemInfo函数获得系统信息：  ? using System.Runtime.InteropServices;  [StructLayout(LayoutKind.Sequential)]  public struct SYSTEM_INFO {  public uint dwOemId;  public uint dwPageSize;  
public uint lpMinimumApplicationAddress;  public uint lpMaximumApplicationAddress;  public uint dwActiveProcessorMask;  public uint dwNumberOfProcessors;  public uint dwProcessorType;  
public uint dwAllocationGranularity;  public uint dwProcessorLevel;  public uint dwProcessorRevision;  }  
[DllImport("kernel32")]  
static extern void GetSystemInfo(ref SYSTEM_INFO pSI); SYSTEM_INFO pSI = new SYSTEM_INFO();  GetSystemInfo(ref pSI); 
类成员的传递  
同 样只要类具有一个固定的类成员布局，你也可以传递一个类成员给一个不受管辖的动态链接库函数，下面的例子主要说明如何传递一个sequential顺序定义的MySystemTime类给User32.dll的GetSystemTime函数, 函数用C/C++调用规范如下: 
void GetSystemTime(SYSTEMTIME* SystemTime);  不像传值类型,类总是通过引用传递参数.  [C#]  
[StructLayout(LayoutKind.Sequential)]  public class MySystemTime {  public ushort wYear;  public ushort wMonth;  public ushort wDayOfWeek;  public ushort wDay;  public ushort wHour;  public ushort wMinute;  public ushort wSecond;  
public ushort wMilliseconds;  }  
class Win32API {  
[DllImport("User32.dll")]  
public static extern void GetSystemTime(MySystemTime st);  }  
回调函数的传递:  
从受管辖的代码中调用大多数动态链接库函数,你只需创建一个受管辖的函数定义，然后调用它即可,这个过程非常直接。  
如果一个动态链接库函数需要一个函数指针作为参数，你还需要做以下几步：  首先，你必须参考有关这个函数的文档，确定这个函数是否需要一个回调；第二，你必须在受管辖代码中创建一个回调函数；最后，你可以把指向这个函数的指针作为一个参数创递给DLL函数,. 
回调函数及其实现:  
回 调函数经常用在任务需要重复执行的场合,譬如用于枚举函数,譬如Win32 API 中的EnumFontFamilies(字体枚举), EnumPrinters(打印机), EnumWindows (窗口枚举)函数. 下面以窗口枚举为例,谈谈如何通过调用EnumWindow 函数遍历系统中存在的所有窗口 
分下面几个步骤:  
1. 在实现调用前先参考函数的声明  
BOOL EnumWindows(WNDENUMPROC lpEnumFunc, LPARMAM IParam)  显然这个函数需要一个回调函数地址作为参数.  
2. 创建一个受管辖的回调函数,这个例子声明为代表类型(delegate),也就是我们所说的回调,它带有两个参数hwnd和lparam,第一个参数是一个窗口句柄，第二个参数由应用程序定义，两个参数均为整形。 
当这个回调函数返回一个非零值时，标示执行成功，零则暗示失败，这个例子

总是返回True值，以便持续枚举。  
3. 最后创建以代表对象(delegate)，并把它作为一个参数传递给EnumWindows 函数，平台会自动地把代表转化成函数能够识别的回调格式。 [C#]  
using System;  
using System.Runtime.InteropServices; 
public delegate bool CallBack(int hwnd, int lParam); public class EnumReportApp { 
[DllImport("user32")]  
public static extern int EnumWindows(CallBack x, int y); public static void Main()  {  
CallBack myCallBack = new CallBack(EnumReportApp.Report);  EnumWindows(myCallBack, 0);  } 
public static bool Report(int hwnd, int lParam) {  Console.Write("窗口句柄为");  Console.WriteLine(hwnd);  return true;  }  } 
指针类型参数传递：  
在Windows API函数调用时，大部分函数采用指针传递参数，对一个结构变量指针，我们除了使用上面的类和结构方法传递参数之外，我们有时还可以采用数组传递参数。 
下面这个函数通过调用GetUserName获得用户名  BOOL GetUserName(  
LPTSTR lpBuffer, // 用户名缓冲区  
LPDWORD nSize // 存放缓冲区大小的地址指针  ); 
[DllImport("Advapi32.dll",  EntryPoint="GetComputerName",  ExactSpelling=false,  SetLastError=true)]  
static extern bool GetComputerName (  
[MarshalAs(UnmanagedType.LPArray)] byte[] lpBuffer,[MarshalAs(UnmanagedType.LPArray)] Int32[] nSize );  
这个函数接受两个参数，char * 和int *,因为你必须分配一个字符串缓冲区以接受字符串指针，你可以使用String类代替这个参数类型，当然你还可以声明一个字节数组传递ANSI字符串，同 样你也可以声明一个只有一个元素的长整型数组，使用数组名作为第二个参数。上面的函数可以调用如下： byte[] str=new byte[20];  Int32[] len=new Int32[1];  len[0]=20;  
GetComputerName (str,len);  
MessageBox.Show(System.Text.Encoding.ASCII.GetString(str));  最后需要提醒的是，每一种方法使用前必须在文件头加上：  using System.Runtime.InteropServices;