TSPI_lineSetDevConfig函式 (tspi.h)

發行項
03/13/2024

TSPI_lineSetDevConfig函式會從先前使用 TSPI_lineGetDevConfig取得的數據結構，還原與裝置相關聯的裝置組態。此數據結構的內容專屬於 [服務提供者] 和裝置類別。

語法

LONG TSPIAPI TSPI_lineSetDevConfig(
  DWORD        dwDeviceID,
  LPVOID const lpDeviceConfig,
  DWORD        dwSize,
  LPCWSTR      lpszDeviceClass
);

參數

dwDeviceID

要設定的線路裝置。

lpDeviceConfig

TSPI_lineGetDevConfig，在 VARSTRING 結構的變數部分中傳回之組態數據結構的指標。

dwSize

lpDeviceConfig 所指向結構中的位元元組數目。此值會在 TSPI_lineGetDevConfig 所傳回之 VARSTRING 結構中的 dwStringSize 成員中傳回。

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

lpszDeviceClass

Null 終止 Unicode 字串的指標，指定要還原其組態之裝置的裝置類別。當 dwSelect 具有值LINECALLSELECT_LINE) 时，有效的裝置類別字串與TSPI_lineGetID函式所指定的字串相同，也就是套用至“line” 裝置 (。

傳回值

如果函式成功，則傳回零，如果發生錯誤，則傳回錯誤號碼。可能的傳回值為：

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

備註

呼叫狀態為裝置特定。

如果 lpDeviceConfig 所指向結構中包含的信息不適用於此裝置，服務提供者會傳回LINEERR_INVALPARAM。

如果裝置組態無法變更為目前行狀態，服務提供者會傳回LINEERR_INVALLINESTATE。此行可能由另一個應用程式使用。

此函式可用來使用 TSPI_lineGetDevConfig 函式，從先前從服務提供者擷取的數據結構，還原與一對一相關聯的裝置組態。 lpszDeviceClass 參數會選取其中可能有多個不同裝置類別的其中之一，就是還原其組態。支援的類別集僅限於裝置對應一對一與線條裝置對應的類別。如需常見裝置類別的詳細資訊，請參閱 TSPI 裝置類別。

服務提供者通常允許此函式下的 tapi/line 裝置類別。它會還原具有「行」範圍的參數，例如此行中的位址清單，以及對應至地址的實體硬體裝置清單，或) 可設定的並行呼叫數目上限， (。

一般而言，此函式不允許媒體相關的裝置類別，例如mci waveaudio、低階波浪或datamodem裝置類別，因為這些通常適用於特定呼叫或特定位址。因為每一行裝置可以有一個以上，所以只由此函式中的線路裝置標識符參數來識別特定呼叫或位址是模棱兩可的。如果類別組態資訊適用於整個線路裝置範圍，例如初始預設值，則可以針對呼叫特定或位址特定的裝置類別進行例外狀況。

有數個原因導致呼叫特定和位址特定裝置類別的例外支援只屬於此函式下的值有限。首先，因為這些類別在多個位址、多呼叫服務提供者上可能模棱兩可，所以只有一部分的服務提供者支持它們。應用程式可能不會新增裝置特定的相依性，以納入此函式中的這些類別。其次，隨著較高層級的媒體類別出現，實作高階通訊協定，例如在低階傳輸 API 方面進行撥入文件系統存取，這些類別的設定通常會導向實例範圍，而不是類別範圍。高階媒體 API 必須提供自己的函式，以設定呼叫特定或位址特定實例。

不論此函式支援何種裝置和裝置類別，它都可能會影響兩種組態資訊：永久和暫時性。永久資訊在行的不同「開啟」之間存留，甚至跨越服務提供者本身的不同「inits」。暫時資訊只會在行的唯一「開啟」記憶體留。關閉行時，已透過 TSPI_lineGetDevConfig 設定或擷取的任何這類暫存資訊，都可以還原為預設或未定義的值。呼叫端只能依序列可靠地擷取任何暫存組態，例如 TSPI_lineOpen、 TSPI_lineConfigDialog、 TSPI_lineGetDevConfig。呼叫端可以透過像是 TSPI_lineOpen等序列，可靠地設定這類序列擷取的暫存組態資訊， TSPI_lineSetDevConfig。設定的暫存部分只會維持穩定，直到下一個 TSPI_lineConfigDialog、 TSPI_lineSetDevConfig或 TSPI_lineClose為止。服務提供者必須負責儲存組態的任何永久部分，通常是在 .ini 檔案中，並在每次初始化服務提供者時重載它。

傳遞至此函式之結構內所含數據的確切格式是行和裝置類別 API 的特定格式，已取消記載，而且未定義。傳遞至此函式的結構無法由應用程式直接存取或操作，但只能完整儲存，稍後才能從先前 TSPI_lineGetDevConfig 取得設定。結構也不一定會傳遞至其他裝置，即使是相同的裝置類別 (，雖然這在某些實例中可能正常運作，但並不保證) 。服務提供者應該檢查此數據結構是否有一致性，以防止因為用戶端應用程式傳遞不相容的信息而失敗。

注意有些服務提供者可能會允許在裝置正在使用時設定組態，而其他服務提供者可能不允許設定。