tapi.h (PHONEBUTTONINFO 結構)

發行項
03/05/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 版本之結構之固定部分原始結尾以外的固定部分字段內容。