VB 与 Windows API 讲座(一) /王国荣
进入 Windows API 的热身运动
「VB 没有提供这样的功能， 必须呼叫 Windows API」， 有时候笔者会这样回答读者的问题， 虽然这麽回答有点偷懒， 或者说不负责任， 但这的确是事实， VB 所提供的叙述、函数、物件…虽然也不在少数， 但是都十分标准， 或者说规矩， 想变点花样， 通常是行不通的， 这是笔者决定开始撰写本文的主要原因。
Windows API 是大家的
感觉上 VB 程式要呼叫 Windows API 是一件比较困难的事情， 或者说比较麻烦的事情， 但别忘了 Windows API 是大家的， 凡是在 Windows 工作环境底下执行的应用程式， 都有权利呼叫 Windows API。
Windows 这个多工作业系统除了协调应用程式的执行、分配记忆体、管理系统资源…之外， 她同时也是一个很大的服务中心， 呼叫这个服务中心的各种服务(每一种服务就是一个函数)， 可以帮应用程式达到开启视窗、描绘图形、使用周边设备…等目的， 由於这些函数服务的对象是应用程式(Application)， 所以便称之为 Application Programming Interface， 简称 API 函数。
但 Windows API 与 C 语言最亲近
虽然说呼叫 Windows API(以下简称 API 或 API 函数) 是每一个应用程式的权利， 但不可否认的 API 却与 C 语言最亲近， 因为 API 函数在参数的传递上就是以 C 语言为标准。
但这并不表示 VB 程式不能呼叫含有参数的 API 函数， 如果传递的参数是单纯的资料型别， 例如「整数」， 则 VB 与 C 语言还是相通的， 如果是特殊的资料型别(包含「字串」)， 则必须遵循一定的规范， 否则不是无法得到正确的结果， 就是因为违反规定而被踢出系统。如何正确地传递各种资料型别的参数， 是 VB 程式呼叫 API 很重要的课题， 当然也是本系列讲座的重点。
物件 vs. handle
除了参数传递方式有所不同之外， 要以 VB 程式呼叫 API， 还要具备 Windows 程式设计的 handle 观念。VB 的程式设计模式是以物件为核心， 但 Windows 的程式设计模式却是以 handle 为核心， 以下笔者先举个简单的例子来说明， 假设有一 VB 的表单 Form1， 若要改变此一表单的标题， 则使用的方法是设定表单物件的 Caption 属性， 叙述如下：
Form1.Caption = "新的标题"
若以 API 来执行相同的工作， 则叙述如下：
ret = SetWindowText( Form1.hwnd, "新的标题" )
其中 Form1.hwnd (hwnd 是 handle of window 的缩写)代表的是 Form1 这个表单「视窗」的
handle 。以下是呼叫此一 API 函数的完整程式：
Private Declare Function SetWindowText Lib _
"user32" Alias "SetWindowTextA" _
(ByVal hwnd As Long, ByVal lpString As String) As Long
Private Sub Command1_Click()
ret = SetWindowText(Me.hwnd, "新的标题")
End Sub
由於笔者接下来的解说会继续使用此一函数， 请将以上程式输入於表单的程式视窗中， 并且在表单上布置一个 Command1 命令钮。(如果懒得输入， 可进入笔者网站下载)
handle 是什麽？
handle 是什麽？让我们来检查看看， 首先在 SetWindowText 之後增加以下叙述：
Print TypeName(Form1.hwnd)
Print Form1.hwnd
结果 TypeName 印出 Long， 这表示 handle 的资料型别是 Long， 而接下来的 Form1.hwnd 则印出一个整数值。
handle 只是一个整数值吗？一个整数值能够做什麽呢？
真实世界的 handle
handel 就字义来说， 是器具的「把手」， 以锅子为例， 把手的用途是方便我们取用锅子里的食物， 它本身虽然没什麽用， 却可以帮我们取得有用的食物， 再举个例子， 车子的门把也叫做 handle， 虽然门把好像也没什麽大用处， 但透过门把打开车门， 可以让我们使用整部车子， 也许有人会捧着锅子吃东西， 或者打破车窗进入车子， 但使用锅把取用食物及使用门把打开车门还是最方便的事情。
handle 者， 存取 Windows 资源之识别码
在 Windows 的世界里， 充满着各种不同的系统资源， 例如视窗、功能表、图片、记忆体、程式、程序…等， 都算是系统资源， 而 Windows 是这些资源的总管理者， 为了能够管理这些资源， Windows 必须给每一资源一个唯一的识别码， 此一识别码便称为 handle。
Windows 世界的 handle 与真实世界的把手在观念上很类似， 由於每一个 handle 都是一个唯一的识别码， 因此当程式要求 Windows 提供存取资源的服务时， 须出具此一识别码， 如此 Windows 便可以找到此一识别码所对应的资源， 然後进行存取的工作， 所以 handle 虽然只是一个整数值， 但它就像是锅子的把手可用来取用锅子的食物一样， 此一数值则可用来取用 Windows 的系统资源。
handle 最重要的特性是同一时间不会有两个资源的 handle 值是相同的， 在前面的 SetWindowText API 函数中， 程式传入 Form1 表单视窗的 handel， 所以 Windows 便能够根据此一唯一的 handle 值， 取得该 handle 所对应的视窗资源， 进而将把标题设定给这个视窗。
从 handle 到物件
对很多 VB 的物件而言， 都含有 handle 性质的属性， 如图-1， 当我们使用这类物件时， 除了可以利用该物件的属性及方法来操作物件外， 也可以利用其中 handle 性质的属性来呼叫 API， 直接启动 Windows 所提供的服务， 以前面的 SetWindowText(Form1.hwnd, "新的标题") 为例， hwnd 便是附属於 Form1 的 handle 性质属性。
图-1 含有 handle 的物件
简单地说， VB 所提供的物件并没有把 Windows 的 handle 程式设计模式丢到一边， 而是将 handle 封装起来， 使之成为物件的一个属性。
注：虽然说 Windows 的程式设计是以 handle 为核心， 但仍然有不少 API 函数是与 handle 无关的， 例如字串的复制， 这类 API 函数通常不会使用到 Windows 所配置的系统资源， 所以不需要使用 handle。
使用 Windows API 的难处
当我们要开始使用 API 时， 必须知道叁件事情：
(1) 要呼叫哪一个 API 函数。
(2) 如何宣告 API 函数。
(3) 如何传递参数。
要呼叫哪一个 API 函数
这是以上叁件事情当中最困难的一件， 主要的原因是 Windows 的 API 实在太多了， 大约有 1500 个， 这还不包含 OLE、ODBC…等特殊的 API， 此外， 如果我们把 API 按不同性质加以分类， 则使用每一类 API 函数所应具备的背景知识亦各有不同， 以系统注册区相关的 API 函数为例， 就必须先了解 Windows 如何安排系统注册区， 以及存取系统注册区的方式。
不过也不必被 1500++ 个函数给打退堂鼓了， 因为不是所有的程式设计都要仰赖 API， 当我们面对一个问题时， 首先还是寻求 VB 的解决方案， 如果 VB 实在无法解决， 才考虑使用 API， 当然， 笔者接下来的讲座也不是 API 函数一个一个往下介绍， 而会先过滤掉那些可用 VB 完成的 API。
如何宣告 API 函数
在 VB 程式中， 若要使用 VB 内建的叙述或函数， 不必事先宣告直接呼叫即可， 若要使用 API 函数， 则必须在先把 API 函数的出处、函数名称、参数、传回值…等宣告在表单的 "一般" 区块或是一般模组(.bas 档案)中， 感觉上也是一件挺麻烦的工作， 但由於 VB 提供有辅助程式， 所以相对於另外两件事情， 反倒是最轻松的。
如何传递参数
由於 API 采用了 C 语言的参数传递方式， 而 C 语言的参数传递又与 VB 有着不小的差异， 以致不少呼叫 API 所造成的错误都发生在参数传递时， 所以本期我们将会有不少的篇幅放在如何传递参数上面。
如何宣告 Windows API
API 函数的宣告并不困难， 因为我们可以请 VB 的「API 检视员」来帮忙， 以下是使用「API 检视员」的方法：
1. 首先选取 VB 功能表的「增益集/增益功能管理员」， 然後在「增益功能管理员」交谈窗中核取「VB API Viewer」， 按下「确定」钮後， VB 的「增益集」功能表栏底下就会出现「API 检视员」， 选取此一命令， 即可启动「API 检视员」。
2. 第一次执行 API 检视员时， 须利用功能表的「档案/载入文字档」载入 VB Winapi 目录底下的 Win32api.txt， 接着在「可选项的项目」底下即会列出所有的 API 函数， 若我们双按其中的函数， 则该函数的宣告即会出现在「选取的项目」底下， 此时再按下「复制」钮， 可将选取的函数宣告复制到剪贴簿， 过程如图-2， 接着回到 VB 的程式视窗， 再选取功能表的「编辑/复制」， 即可将函数的宣告从剪贴簿中复制过来。
图-2 利用「API 检视员」将 API 的宣告复制到剪贴簿
接下来请注意 API 宣告式复制到 VB 程式的位置， 此时您有两种选择：(1) 先利用 VB 功能表的「专案/新增模组」新增一个一般模组(.bas 档)， 然後将 API 宣告式复制到此一模组的程式视窗中， (2) 将 API 宣告式复制到表单程式视窗的 "(一般)" 区块底下， 但复制过来之後， 必须在 Declare 前面加上 Private 保留字。
将 API 宣告式放在一般模组与表单模组的差异是：放在一般模组的 API 函数， 可供同一专案的所有程式使用， 若放在表单模组， 则只有宣告 API 函数的表单可以使用。
提升载入 API 宣告式的速度
如果您经常使用 API 检视员， 就会发现载入 Win32api.txt 是蛮花时间的， API 检视员允许我们将此一档案转换成 mdb 格式的资料库， 此时所使用的命令是功能表的「转换文字档为资料库」， 转换之後， Win32api.txt 的所在目录会增加 Win32api.mdb 资料库档案， 将来我们便可以利用功能表的「档案/载入资料库档案」来载入此一资料库档案， 则载入的速度确实提升不少。
不过 API 检视员实在有点「阿达」， 因为载入 Win32api.txt 的 API 检视员具有「搜寻」API 的功能， 但如果载入的是 Win32api.mdb 资料库档案， 则「搜寻」的功能反而不见了。笔者实在很不满， 所以决定撰写一个改良版的 API 检视员， 也取您阅读本文时， 也经完成了， 请随时注意笔者的网站。
如何传递参数
在 API 函数所定义的参数型别中， 大致上可分成「数值」、「自订型别」、「字串」(String)、及「Any」四种资料型别， 以下让笔者按照这四种资料型别来说明 VB 程式与 API 的参数传递方式：
数值的传递
数值型别在 API 的参数定义中可能有两种形式：「参数名 As 数值型别」及「ByVal 参数名 As 数值型别」， 所代表的意义分别是数值的「传址」及「传值」呼叫， 与 VB 的习惯完全相同， 以 GetFileSize(读取档案的长度) API 为例， 其宣告式如下：
Declare Function GetFileSize Lib "kernel32" Alias "GetFileSize" (ByVal hFile As Long, lpFileSizeHigh As Long) As Long
而呼叫的例子如下：
Dim hFile As Long, lenFile As Long
hFile = OpenFile(…) ' OpenFile 也是 API 函数
ret = GetFileSize ( hFile, lenFile ) ' lenFile 将传回档案长度
其中 hFile 参数为 Long 型别的「传值」呼叫， lenFile 参数则是 Long 型别的「传址」呼叫， 若呼叫成功， 则 GetFileSize 会将档案的长度设定给 lenFile。
自订型别的参数传递
对 C 语言而言， 自订型别的参数只能以位址来传递， 因此在 API 函数中， 并没有「ByVal 参数名 As 自订型别」的参数宣告， 至於「参数名 As 自订型别」的传址呼叫， 则与 VB 的习惯完全相同， 以 GetCursorPos(读取滑鼠的位置) 为例， 其宣告式如下：
Type POINTAPI ' POINTAPI 为一自定型别
x As Long
y As Long
End Type
Declare Function GetCursorPos Lib "user32" Alias "GetCursorPos" (lpPoint As POINTAPI) As Long
而呼叫的例子则是：
Dim p As POINTAPI
ret = GetCursorPos ( p )
Print p.x, p.y ' p 传回滑鼠的位置
如果 API 函数的参数中含有自订型别， 则除了 API 函数的宣告式之外， API 所使用的自订型别(例如 GetCursorPos 的 POINTAPI)也必须放到 VB 程式中， 此时 API 检视员的操作方法如下：
1. 选取「API 类型」底下的「型态(Types)」， 接着「可选用的项目」底下所列示的不再是 API 函数的宣告式， 而是 API 函数的自订型别。
2. 接下来是选取并且复制自订型别的定义到剪贴簿中， 然後再从剪贴簿复制到 VB 程式中。
字串的传递
在 API 函数中， 字串参数的宣告只有「ByVal 参数名 As String」一种形式(没有「参数名 As String」形式)， 按照 VB 习惯， 这是「传值」呼叫， 但实际上， API 对於所有字串参数的处理， 却一概以「传址」视之， 所以当我们传递字串到 API 函数时， 心理上应有的准备是「这个字串的内容可能会被 API 改变掉」， 以 GetWindowText(读取视窗的标题) API 为例， 其宣告式如下：
Private Declare Function GetWindowText Lib "user32" Alias "GetWindowTextA" (ByVal hwnd As Long, ByVal lpString As String, ByVal cch As Long) As Long
表面上 lpString 参数为传值呼叫， 但执行以下的呼叫式之後， S 的内容却会改变(将等於 Form1 视窗的标题)：
Dim S As String
S = "某字串................................."
ret = GetWindowText(Form1.hwnd, S, Len(S) )
当然不是所有字串参数的内容都会被改变， 以下面的 SetWindowText 呼叫式为例， API
就只会读取字串 S 的内容， 而不会改变它：
Dim S As String
S = "某字串................................."
ret = SetWindowText(Form1.hwnd, S)
在呼叫含有字串参数的 API 函数以前， 我们必须先弄清楚 API 函数的本质， 确定 API 函数对於传入的参数是否会进行写入的动作， 因为两者在 VB 程式端应预先准备的工作并不相同。稍後笔者会进一步说明。
Any 型别的参数传递
所谓 Any 型别的参数， 指的是 VB 程式可以传入数值、字串、或自订型别…等资料的参数， 至於可以传入哪一种资料， 则与个别 API 函数有关系。Any 型别可说是 API 的参数类型中最为邪恶的一种， 因为如果传入的参数不正确， 轻则结果错误， 重则出现「这个程式执行的作业无效， 即将关闭」， 表示程式当掉了！
有哪些 API 函数含有 Any 型别的参数呢？还好不多， 而且使用过一两个之後， 就能够掌握参数传递的原则， 未来本讲座所介绍的 API 函数若属於此一性质， 也会特别说明。
VB 字串 vs. API 字串
其实以上所介绍几种的参数类型中， 最大宗还是「字串」的传递， 而且对初学者来说， 也是最容易犯错的。
VB 的字串
VB 字串可分成「非固定长度」及「固定长度」两种， 如下：
Dim S1 As String ' 非固定长度字串
Dim S2 As String*80 ' 固定长度字串
两者的差别除了长度是否可变之外， 非固定长度字串会在字串的最尾端补上 Chr(0) 字元， 以 "VB5" 字串为例， 在记忆体内部其实含有 "VB5"+Chr(0) 共 4 个字元， 至於固定长度的字串则会先用「空白」字元补满整个字串， 然後才补上 Chr(0) 字元， 以下面的 S2 字串为例：
Dim S2 As String * 80
S2 = "VB5"
在 S2 的记忆体中所包含的字元则有 "VB5"+77个空白字元+Chr(0)。
虽然 VB 会在字串的尾端补上 Chr(0) 字元， 但这个字元并不会计入字串的长度中， 以 "VB5" 为例， 虽然记忆体内部是 "VB5" + Chr(0)， 但长度依然等於 3。其实在 VB 的字串中， 除了补上 Chr(0) 字元之外， 还会在字串的前面预留 4 个字元来记录着字串的长度， 结构如图-3：
图-3 VB 字串的结构
当我们呼叫 Len() 函数时， VB 不是计算 Chr(0) 的位置来求取字串的长度， 而是直接取出记录於字串中的长度。
API 的字串
相对於 VB 的字串， API 的字串并不会记录「字串的长度」， 而它计算字串长度的方法是判断 Chr(0) 字元， 其结构如图-4：
图-4 API 字串的结构
虽然 VB 的字串与 API 的字串结构不同， 但是当我们传递 VB 的字串到 API 时， VB
只会传入图-3「字串的内容+Chr(0)」的部分， 如此才可以配合 API 的字串结构。
解决字串的不一致性问题
尽管 VB 已经把传入 API 的字串弄得跟 API 的字串结构一样， 但还是可能有问题， 直接来看例子， 请比较以下两个呼叫 SetWindowText 的例子：
ret = SetWindowText(Form1.hwnd, "某字串")
Dim S As String * 80
S = "某字串"
ret = SetWindowText(Form1.hwnd, S)
第一个 SetWindowText 呼叫式是直接传入「字串常数」， 结果没有问题， 但传入「固定长度」字串 S 的第二个 SetWindowText 呼叫式却有点小问题， 因为「S = "某字串"」其实表示「S = "某字串"+77个空白字元+Chr(0)」， 所以它比 "某字串" 要多出 77 个空白字元， 如果希望 S 只传入 "某字串"+Chr(0)， 则程式修正的方法如下：
S = "某字串" + Chr(0)
ret = SetWindowText(Form1.hwnd, S)
接下来让我们再来检视会改变字串内容的 API 函数， 例如：
Dim S As String * 80
ret = GetWindowText(Form1.hwnd, S, 80 )
以上的 GetWindowText 函数会把 Form1 视窗的标题填入 S 字串中， 然後传回来。(注：以上的参数叁表示参数二的长度， 目的是告诉 GetWindowText 参数二的长度只有 80 个字元， 如此一来， 即使 Form1 的标题超过 80 个字元， GetWindowText 也不会把资料写出 80 个字元的范围， 如此可避免破坏其他资料)
以上的呼叫式有没有问题呢？让我们假设 Form1 的标题是 "Form1"， 然後来检视执行的结果， 由於 API 以 Chr(0) 为字串的结束字元， 因此当 GetWindowText 将 "Form1" 指定给 S 字串时， 实际的动作等於「S = "Form1" + Ch(0)」， 结果使得 S 变成「"Form1"+Ch(0)+74个空白字元+Chr(0)」， 这样的结果虽然不算错， 但请注意 S 字串中所记录的长度仍然等於 80， 如图-5(a)， 而实际上我们期望的结果应该如图-5(b)。
图-5 字串的结果不是我们期望的
为了让 S 能够得到我们期望的图-5(b)， 呼叫 GetWindowText 之後， 应该将 S 第一个 Chr(0) 之前的字串指定给另一个非固定长度字串， 如下：
Dim S As String * 80
Dim Sx As String
ret = GetWindowText(Form1.hwnd, S, 80 )
Sx = Left( S, InStr(S, Chr(0)) - 1 )
则 Sx 就刚好等於 "Form1"。
GetWindowText 是直接把 Chr(0) 补在字串参数中， 藉以告诉呼叫端传回字串的长度， 有些函数则会把字串的长度当成参数传回来， 以 RegQueryValue 为例：
Declare Function RegQueryValue Lib "advapi32.dll" Alias "RegQueryValueA" (ByVal hKey As Long, ByVal lpSubKey As String, ByVal lpValue As String, lpcbValue As Long) As Long
参数叁 lpValue 是传入的字串， 参数四则是传回的字串长度， 若呼叫此类函数， 则呼叫之後可利用 Left 函数设定正确的传回字串， 如下：
Dim L As Long
ret = RegQueryValue(hKey, KeyName, S, L)
Sx = Left( S, L )
传递的字串常见的错误
其实我们可以把 API 的字串参数分成「唯读」及「可写入」两种， 以 SetWindowText 为例， API 会读取字串参数， 然後将参数内容设定给视窗的标题， 所以字串参数是唯读的， 以 GetWindowText 为例， API 会读取视窗的标题， 然後设定给字串参数， 所以字串参数是可写入的， 在使用上， 可写入的参数比较容犯以下两种错误：
(1)
Dim S ' 未将 S 宣告成「字串」型别
S = Space(80)
ret = GetWindowText(Form1.hwnd, S, 80 )
(2)
Dim S As String ' S 为一空字串
ret = GetWindowText(Form1.hwnd, S, 80 )
◇ 错误(1)：没有把 S 宣告成「字串」， 这将使得 S 无法正确地转换成 API
的字串， 所以呼叫 API 函数之後， 仍然无法得到正确的结果。
◇ 错误(2)：传入 API 函数的字串 S， 没有足够的空间容纳 API 函数所写入的字串， 此时 API 函数将会破坏 S 之後的资料， 而此一破坏资料的行为极可能让程式当掉。
准备工作
本期所介绍的内容只能算是 Windows API 的初步， 但也许这是您第一次接触 Windows API， 所以笔者并没有打算一开始就给您满汉大餐， 如果您有意继续跟着笔者进入 Windows API 的世界， 建议您先熟悉 API 检视员的使用， 然後试着写程式检测本期所介绍过的 API 函数， 在检测的过程中， 一定会遭遇不少挫折， 但这是正常的现象， 当然， 如果您想比对笔者所写的呼叫范例， 可进入网站下载， 下一期起笔者将会开始介绍 Windows API 中比较实用的函数。