参考手册API函数的声明和调用

第2章API函数的声明和调用在PowerBuilder中，API函数的调用属于外部函数的范畴。

外部函数的调用与PowerBuilder的内部函数有许多不同之处，如在调用前必须预先声明、为函数传入正确的参数、指明函数传递的方式，以及定义函数返回值的类型等等。

2.1 PowerBuilder中API函数声明2.1.1 PowerBuilder与API函数数据类型的转换在微软出版的MSDN中给出了每个API函数C语言格式，函数的格式及参数的数据类型完全是按照C的要求定义的。

例如检索打印设备驱动性能的API函数DeviceCapabilities，在MSDN中的C定义如下：DWORD DeviceCapabilities(LPCTSTR pDevice, // printer nameLPCTSTR pPort, // port nameWORD fwCapability, // device capabilityLPTSTR pOutput, // output bufferCONST DEVMODE *pDevMode // device data buffer);该声明中还包括一个名为DEVMODE的结构，在结构中包含打印机设备的初始化和环境信息，结构的C语言定义如下：typedef struct _devicemode {BCHAR dmDeviceName[CCHDEVICENAME];WORD dmSpecVersion;WORD dmDriverVersion;WORD dmSize;WORD dmDriverExtra;DWORD dmFields;union {struct {short dmOrientation;short dmPaperSize;short dmPaperLength;short dmPaperWidth;};第2章 API函数的声明和调用19POINTL dmPosition;};short dmScale;short dmCopies;short dmDefaultSource;short dmPrintQuality;short dmColor;short dmDuplex;short dmYResolution;short dmTTOption;short dmCollate;BCHAR dmFormName[CCHFORMNAME];WORD dmLogPixels;DWORD dmBitsPerPel;DWORD dmPelsWidth;DWORD dmPelsHeight;union {DWORD dmDisplayFlags;DWORD dmNup;}DWORD dmDisplayFrequency;#if(WINVER >= 0x0400)DWORD dmICMMethod;DWORD dmICMIntent;DWORD dmMediaType;DWORD dmDitherType;DWORD dmReserved1;DWORD dmReserved2;#if (WINVER >= 0x0500) || (_WIN32_WINNT >= 0x0400)DWORD dmPanningWidth;DWORD dmPanningHeight;#endif#endif /* WINVER >= 0x0400 */} DEVMODE;在上述定义中，包含了各种各样的C的数据类型，由于这些数据类型无论从形式上还是从内在含义上都与PB中的数据类型有一定的差异，要在PB中调用这些过程，需要将它们转换成合法的PB外部函数声明语句，并使用正确的参数调用它们。

表2－1中列出了API函数的C原型的数据类型与PB中相应的数据类型对应关系。

C语言中的远指针，如LPBYTE、LPDWORD、LPRINT、LPLONG、LPVOID和LPWORD在PB中20PowerBuilder Win32 API函数调用参考手册被声明为Long的数据类型。

用于指示对象的句柄HANDLE表示环境设备的hDC被定义为一个32位无符号数，在PB中声明为无符号长整形ulong。

在PB中并不支持C语言中诸如PSTR 和NPSTR的近指针，并且关键字REF只适用于32位远指针。

Windows中的32位远指针LPCTSTR、LPSTR在PB中被声明为String，LBYTE有时也声明为String。

Windows中的BOOL是16位有符号数，在PB中被声明为Boolean或Long型。

Windows中定义的WORD在PB中声明为UnsignedInteger型，Windows中定义的DWORD在PB中声明为UnsignedLong。

PB中不支持Windows的80位双精度浮点数。

PB中的Date、DateTime和Time有其特定的格式，与C中的数据类型没有直接的对应关系。

表2－1 C数据类型与PB数据类型的转换2.1.2 API函数的声明约定对于PowerBuilder应用程序来讲，动态链接库中的函数是外部函数，为了调用这些函数，必须按照固定格式的约定向应用程序提供必要的信息，这种提供信息的的操作称为外部函数的声明。

在PowerBuilder任何脚本中使用外部函数之前，必须首先声明外部函数。

PowerBuilder就是通过这种声明来访问动态库中的。

声明的作用就是“告知”PB系统，可以使用外部函数了。

PB系统为窗口、菜单、函数、用户对象提供了一个声明区域，专门用于声明外部函数和第2章 API函数的声明和调用21变量，同PowerBuilder中的用户自定义函数一样，用户可以声明以下两种类型的外部函数: （1）全局外部函数（Global External Functions）：可以在应用的任意位置调用;（2）对象级外部函数（Local External Functions）：在窗口、菜单、用户对象或用户自定义函数等对象中定义。

在应用的开发过程中可以根据以下原则决定使用全局外部函数或局部对象级外部函数：（1）若外部函数作为一般用途并适用于整个应用，则定义为全局外部函数；（2）若外部函数作为特殊用途只适用于特定对象，则将函数定义为对象级外部函数。

对于对象级外部函数，用户仍可在应用的任何位置调用，只是需要把它作为一个特定的对象类型。

PB中外部函数的声明书写必须符合一定的约定，否则PB将警告错误调用外部函数。

在PB中根据外部函数代表的过程是否有返回值，函数的声明书写有所不同。

外部函数的声明以两个关键字FUNCTION或SUBROUTINE之一为开始，如果函数代表的过程返回一个值，应将其声明为FUNCTION，声明语法如下：{Access}FUNCTION ReturnDataType FunctionName ({REF}{DataTypel Arg1，...，DataTypeN ArgN})LIBRARY LibName {ALIAS FOR ExternalName}如果函数代表的过程无返回值，或者在C语言中返回一个Void数据类型，声明的语法是:{Access} SUBROUTINE SubroutineName({REF}{DataType1 Arg1，...，DataTypeN ArgN}) LIBRARY LibName {ALIAS FOR ExternalName}在上面声明语句中，大括号中的内容是可选的。

此外，PB对上面语句中的各个部分大小写不敏感，如FUNCTION与Function是一样的。

声明中的其它各个关键字作用如下：Access ：表示函数的访问级别，用户可以为对象级外部函数指定Public、Protected 或Private三个类型的访问级别，缺省为Public，此参数只能在对象级外部函数中使用；ReturnDataType：表示函数返回值的数据类型。

返回值的数据类型必须与PB支持的数据类型相匹配；FunctionName/SubroutineName：在PowerScript脚本中引用的外部函数或过程的名称。

该名称可以由用户自己定义，但如果指定了与动态库中函数不一致的名称，就必须通过Alias For子句给出动态库中函数过程的真正名称；REF：标明变量通过引用方式传递；DataType：外部函数中参数的数据类型；Arg：外部函数的参数名。

对于具有多个参数的过程，各参数以逗号分开；LibraryName：表示外部函数的动态库DLL或EXE的文件名。

如果引用的过程属于Windows 核心库（User32、Kernel32 或 GDI32），则可以不包含文件扩展名；ExternalName：表示在DLL库中的外部函数或子程序名。

如果调用的 Windows API 过程要使用字符串，或为函数指定别名，那么在声明语句中必须增加一个Alias For子句，以指定正确的字符集。

Alias For关键词后面的字符串必须是动态库中函数过程的真正名称。

Alias For的使用大致可分为以下四种情况：1. 区别ANSI和Unicode字符集22PowerBuilder Win32 API函数调用参考手册如果调用的 API函数或过程要使用字符串，那么在声明语句中必须增加一个 Alias For 子句，以指定正确的字符集。

包含字符串的API函数实际有两种版本，即ANSI版本和 Unicode 版本。

因此，在Windows头文件中，每个包含字符串的函数都同时定义了 ANSI 版本和Unicode 版本。

Windows NT、Windows 2000 、Windows XP同时支持 Unicode 和ANSI字符集，而 Windows 95/98 只支持ANSI字符集。

请注意，Alias For子句后面的字符串必须是过程的真正名称。

例如，下面是 SetWindowText 函数的两种 C 语言描述。

可以看到，第一个描述将函数定义为 SetWindowTextA，尾部的“A”表明它是一个 ANSI 函数：SetWindowTextA(HWND hWnd，LPCSTR lpString);第二个描述将它定义为 SetWindowTextW，尾部的“W”表明它是一个 Unicode 函数：SetWindowTextW(HWND hWnd，LPCWSTR lpString);因为两个函数实际的名称都不是“SetWindowText”，要引用正确的函数就必须增加一个Alias For子句:FUNCTION Long SetWindowText(Long hwnd，REF String lpString) LIBRARY "user32.dll" ALIAS FOR "SetWindowTextA"为了保证使用PB开发的应用系统能在所有主流Windows操作系统下运行，无论是Windows NT、Windows 2000还是Windows 95／98，可统一使用Alias For子句指定为ANSI 格式的版本。