TSPI_lineConfigDialogEdit函式 (tspi.h)

發行項
03/09/2024

TSPI_lineConfigDialogEdit函式已過時。 TAPI 1.4 版或更早版本的服務提供者可以實作此 TSPI 函式。 TAPI 2.0 版或更新版本的 TSP 會實作 TUISPI_lineConfigDialogEdit。

TSPI_lineConfigDialogEdit函式會導致指定之線條裝置的提供者將強制回應對話框顯示為 hwndOwner 的子視窗，讓使用者設定與線條裝置相關的參數。

語法

LONG TSPIAPI TSPI_lineConfigDialogEdit(
  DWORD        dwDeviceID,
  HWND         hwndOwner,
  LPCSTR       lpszDeviceClass,
  LPVOID const lpDeviceConfigIn,
  DWORD        dwSize,
  LPVARSTRING  lpDeviceConfigOut
);

參數

dwDeviceID

要設定的線路裝置。

hwndOwner

要附加對話框之視窗的句柄。

lpszDeviceClass

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

lpDeviceConfigIn

TSPI_lineGetDevConfig (或 VARSTRING 結構之變數部分TSPI_lineConfigDialogEdit) 先前調用所傳回之不透明組態數據結構的指標。

dwSize

lpDeviceConfigIn 所指向結構中的位元元組數目。此值會在 varSTRING 結構中的 dwStringSize 成員中傳回TSPI_lineGetDevConfig或先前的TSPI_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。

備註

此函式會讓服務提供者顯示附加至 hwndOwner () 的強制回應對話框，讓使用者設定 與 dwDeviceID 所指定行相關的參數。

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

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

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

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