TUISPI_lineConfigDialogEdit函式 (tspi.h)

發行項
08/26/2023

TUISPI_lineConfigDialogEdit函式會導致指定之線條裝置的提供者將強制回應對話方塊顯示為hwndOwner的子視窗，讓使用者設定與線條裝置相關的參數。此函式讓 2.0 版和更新版本 (1.4 版和更早版本中支援的 TSPI_lineConfigDialogEdit 函式過時) 。

實作是選擇性的。

語法

LONG TSPIAPI TUISPI_lineConfigDialogEdit(
  TUISPIDLLCALLBACK lpfnUIDLLCallback,
  DWORD             dwDeviceID,
  HWND              hwndOwner,
  LPCWSTR           lpszDeviceClass,
  LPVOID const      lpDeviceConfigIn,
  DWORD             dwSize,
  LPVARSTRING       lpDeviceConfigOut
);

參數

lpfnUIDLLCallback

UI DLL 可以呼叫的函式指標，以與服務提供者 DLL 通訊，以取得顯示對話方塊所需的資訊。

dwDeviceID

要設定的線路裝置。

hwndOwner

要附加對話方塊之視窗的控制碼。

lpszDeviceClass

識別裝置類別名稱 之 Null終止 Unicode 字串的指標。此裝置類別可讓呼叫端選取適用于該裝置類別之組態資訊的特定子畫面。如果此參數為 Null 或指向空字串，則會選取最高層級組態。允許的字串與 TSPI_lineGetID相同。

lpDeviceConfigIn

TSPI_lineGetDevConfig (或VARSTRING結構變數部分中先前TUISPI_lineConfigDialogEdit) 調用所傳回的不透明組態資料結構指標。

dwSize

lpDeviceConfigIn所指向結構中的位元組數目。此值會在varSTRING結構中的dwStringSize成員中傳回TSPI_lineGetDevConfig或先前的TUISPI_lineConfigDialogEdit調用。

注意如果結構中的大小參數不正確，可能會覆寫資料。如需設定結構大小的詳細資訊，請參閱記憶體配置主題。

lpDeviceConfigOut

VARSTRING類型的記憶體位置指標，其中會傳回裝置組態結構。成功完成要求時，此位置會填入裝置組態。 VARSTRING結構中的dwStringFormat成員會設定為 STRINGFORMAT_BINARY。在呼叫 lineGetDevConfig (或 lineConfigDialogEdit) 的未來調用之前，應用程式應設定此結構的 dwTotalSize 成員，以指出 TAPI 可用來傳回信息的記憶體數量。

傳回值

如果要求成功或發生錯誤，則傳回零。可能的傳回值為：

LINEERR_INVALDEVICECLASS、LINEERR_OPERATIONFAILED、LINEERR_INVALPARAM、LINEERR_RESOURCEUNAVAIL、LINEERR_NODRIVER、LINEERR_OPERATIONUNAVAIL、LINEERR_NOMEM。

備註

lpszDeviceClass參數會選取適用于使用者感興趣的裝置類別的特定組態資訊子畫面;允許的字串與TSPI_lineGetID相同。例如，如果行支援 Comm API，將 comm/datamodem 當做 lpszDeviceClass 傳遞，會導致提供者顯示與 Comm (相關的參數，或至少從多層級設定對話方塊鏈結中的對應點開始，因此使用者不需要「dig」來尋找感興趣的參數) 。

lpszDeviceClass參數為「tapi/line」、「」或Null，導致提供者顯示該行的最高層級設定。

此函式與 TUISPI_lineConfigDialog 之間的差異是要編輯的參數來源，以及編輯的結果。 在TUISPI_lineConfigDialog中，編輯的參數是目前在裝置上使用的參數 (或設定供下一個呼叫) 使用，而且所做的任何變更 (到可能的最大範圍，) 對任何作用中連線的立即影響;此外，應用程式必須使用lineGetDevConfig，從TUISPI_lineConfigDialog擷取參數變更的結果。使用 TUISPI_lineConfigDialogEdit時，要編輯的參數會從應用程式傳入，且結果會傳回至應用程式，且不會影響作用中的連線;編輯的結果會使用此函式傳回，而且應用程式不需要呼叫 lineGetDevConfig。因此， TUISPI_lineConfigDialogEdit 允許應用程式提供使用者設定未來呼叫參數的能力，而不會影響任何作用中的呼叫。不過，此函式的輸出可以傳遞至 TSPI_lineSetDevConfig ，以影響目前的呼叫或下一個呼叫。

為了回溯相容性，舊版服務提供者不會匯出此函式。 TAPI 會偵測此條件，並報告應用程式是否嘗試在較舊的提供者上呼叫此函式LINEERR_OPERATIONUNAVAIL。