lineConfigDialogEdit 函式 (tapi.h)

發行項
03/02/2024

lineConfigDialogEdit 函式會導致指定之線條裝置的提供者顯示對話框 (附加至應用程式的 hwndOwner) ，讓使用者設定與線路裝置相關的參數。

語法

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

參數

dwDeviceID

要設定之線路裝置的標識碼。

hwndOwner

要附加對話框的視窗句柄。可為 NULL ，表示函式期間建立的任何視窗都應該沒有擁有者視窗。

lpszDeviceClass

識別裝置類別名稱之 Null 終止字串的指標。此裝置類別可讓應用程式選取適用於該裝置類別的特定組態信息子畫面。此參數是選擇性的，而且可以保留 NULL 或空白，在此情況下，會選取最高層級組態。

lpDeviceConfigIn

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

dwSize

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

lpDeviceConfigOut

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

傳回值

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

LINEERR_BADDEVICEID、LINEERR_OPERATIONFAILED、LINEERR_INVALDEVICECLASS、LINEERR_RESOURCEUNAVAIL、LINEERR_INVALPARAM、LINEERR_STRUCTURETOOSMALL、LINEERR_INVALPOINTER、LINEERR_UNINITIALIZED、LINEERR_NODRIVER、LINEERR_OPERATIONUNAVAIL、LINEERR_NOMEM LINEERR_NODEVICE。

備註

如果傳回LINEERR_STRUCTURETOOSMALL，lpDeviceConfigOut 所指向之 VARSTRING 結構的 dwTotalSize 成員並未指定足夠的記憶體來包含整個組態結構。 dwNeededSize 成員已設定為所需的數量。在用戶專案因空間不足而無法傳回的資訊中反映，這些編輯將會遺失;因此，應用程式應該配置裝置類別可能需要的最大空間量，以傳回其組態結構 (，如需詳細資訊，請參閱 TAPI 裝置類別) 。

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

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

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

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