TSPI_lineGetDevConfig函式 (tspi.h)

發行項
08/26/2023

TSPI_lineGetDevConfig函式會傳回資料結構物件，其內容專屬於線路 (服務提供者) 和裝置類別，提供與線路裝置相關聯的裝置目前組態。

語法

LONG TSPIAPI TSPI_lineGetDevConfig(
  DWORD       dwDeviceID,
  LPVARSTRING lpDeviceConfig,
  LPCWSTR     lpszDeviceClass
);

參數

dwDeviceID

要設定的線路裝置。

lpDeviceConfig

VARSTRING類型的資料結構的指標，其中會傳回相關聯裝置的裝置組態結構。成功完成要求時，服務提供者會以裝置組態填入此資料結構。 VARSTRING結構中的dwStringFormat成員必須設定為 STRINGFORMAT_BINARY。如果lpDeviceConfig參數所指向之 VARSTRING結構的dwTotalSize成員大於或等於結構固定部分的大小，則服務提供者會將dwNeededsize成員設定為所需的大小，並傳回零。

lpszDeviceClass

Null 終止 Unicode 字串的指標，指定要求其設定之裝置的裝置類別。將有效的裝置類別字串套用至行裝置 (dwSelect LINECALLSELECT_LINE) 的值時，與為TSPI_lineGetID函式指定的字串相同。

傳回值

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

LINEERR_INVALDEVICECLASS、LINEERR_NOMEM、LINEERR_INVALPOINTER、LINEERR_OPERATIONUNAVAIL、LINEERR_STRUCTURETOOSMALL、LINEERR_OPERATIONFAILED、LINEERR_NODRIVER LINEERR_RESOURCEUNAVAIL。

備註

撥號狀態是裝置特定的。

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

服務提供者通常應該允許此函式下的 tapi/line 裝置類別。它會擷取具有「行」範圍的參數，例如這一行中的地址清單、對應至位址的 COMM 埠等實體硬體裝置清單、可設定) 時 (並行呼叫數目上限等等。

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

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

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

此函式所傳回之結構內所含資料的確切格式是行和裝置類別 API 的特定格式、已取消記載，且未定義。此函式所傳回的結構無法由應用程式直接存取或操作，但只能完整儲存，稍後在 TSPI_lineSetDevConfig 中用來還原設定。結構也不一定傳遞至其他裝置，即使是相同的裝置類別 (，雖然這可能在某些實例中運作，但不保證) 。服務提供者應該將資料結構中的專案放在資料結構中，以允許其檢查是否有一致性，以防止因為用戶端應用程式傳遞不相容的資訊而失敗。