phoneBUTTONINFO 结构 (tapi.h)

项目
03/02/2024

PHONEBUTTONINFO 结构包含有关手机设备上的按钮的信息。此结构由多个 TAPI 和 TSPI 函数使用。

语法

typedef struct phonebuttoninfo_tag {
  DWORD dwTotalSize;
  DWORD dwNeededSize;
  DWORD dwUsedSize;
  DWORD dwButtonMode;
  DWORD dwButtonFunction;
  DWORD dwButtonTextSize;
  DWORD dwButtonTextOffset;
  DWORD dwDevSpecificSize;
  DWORD dwDevSpecificOffset;
  DWORD dwButtonState;
} PHONEBUTTONINFO, *LPPHONEBUTTONINFO;

成员

dwTotalSize

分配给此数据结构的总大小（以字节为单位）。

dwNeededSize

保存所有返回信息所需的此数据结构的大小（以字节为单位）。

dwUsedSize

包含有用信息的此数据结构部分的大小（以字节为单位）。

dwButtonMode

按钮的模式或常规用法类。此成员使用 PHONEBUTTONMODE_常量之一。

dwButtonFunction

分配给按钮的函数。此成员使用 PHONEBUTTONFUNCTION_常量之一。

dwButtonTextSize

按钮的描述性文本的大小（以字节为单位）。

dwButtonTextOffset

从此结构的开头到包含此按钮的描述性文本的可变大小的字段的偏移量。此信息的格式是手机设备功能的 dwStringFormat 成员中指定的。字段的大小由 dwButtonTextSize 指定。

dwDevSpecificSize

设备特定字段的大小（以字节为单位）。如果特定于设备的字段是指向字符串的指针，则大小必须包含 null 终止符。

dwDevSpecificOffset

从结构开头到大小可变的设备特定字段的偏移量。字段的大小由 dwDevSpecificSize 指定。

dwButtonState

对于 phoneGetButtonInfo 函数，此字段使用常量PHONEBUTTONSTATE_指示按钮的当前状态。 phoneSetButtonInfo 函数忽略此字段。

注解

特定于设备的扩展应使用 DevSpecific (dwDevSpecificSize 和 dwDevSpecificOffset) 此数据结构的可变大小区域。

较旧的应用程序是在 PHONEBUTTONINFO 结构中没有此字段的情况下编译的，并且使用小于新大小的 SIZEOF PHONEBUTTONINFO。应用程序使用 phoneOpen 函数传入 dwAPIVersion 参数，该参数可用于 TAPI 在处理这种情况时的指导。如果应用程序传入的 dwTotalSize 小于指定的 dwAPIVersion 中定义的结构的固定部分的大小，则返回PHONEERR_STRUCTURETOOSMALL。如果应用程序已分配足够的内存，则在调用 TSPI_phoneGetButtonInfo 函数之前，TAPI 会将 dwNeededSize 和 dwUsedSize 成员设置为在指定的 API 版本中存在的结构的固定大小。

支持新 API 版本的新服务提供商 () 必须检查传入的 API 版本。如果 API 版本低于提供程序支持的最高版本，则服务提供程序不得填写较旧 API 版本不支持的字段，因为这些字段将落在较旧结构的可变部分。

新应用程序必须识别协商的 API 版本，并且不检查已协商 API 版本结构固定部分的原始末尾之外的固定部分中字段的内容。