TSPI_providerInit函式 (tspi.h)

發行項
03/08/2023

TSPI_providerInit函式會初始化服務提供者，並提供後續作業所需的參數。

語法

LONG TSPIAPI TSPI_providerInit(
  DWORD            dwTSPIVersion,
  DWORD            dwPermanentProviderID,
  DWORD            dwLineDeviceIDBase,
  DWORD            dwPhoneDeviceIDBase,
  DWORD_PTR        dwNumLines,
  DWORD_PTR        dwNumPhones,
  ASYNC_COMPLETION lpfnCompletionProc,
  LPDWORD          lpdwTSPIOptions
);

參數

dwTSPIVersion

此函式必須在其下運作的 TSPI 定義版本。呼叫端可以使用 TSPI_lineNegotiateTSPIVersion 搭配特殊的 dwDeviceIDINITIALIZE_NEGOTIATION ，交涉保證可接受給服務提供者的版本。

dwPermanentProviderID

此系統上服務提供者內要初始化之服務提供者的永久識別碼是唯一的。

dwLineDeviceIDBase

此服務提供者所支援之線路裝置的最低裝置識別碼。

dwPhoneDeviceIDBase

此服務提供者所支援電話裝置的最低裝置識別碼。

dwNumLines

此服務提供者支援的線路裝置數目。傳回的值是 TSPI_providerEnumDevices中所報告的行裝置數目。

dwNumPhones

此服務提供者支援的電話號碼裝置數目。傳回的值是 TSPI_providerEnumDevices中報告的電話裝置數目。

lpfnCompletionProc

服務提供者呼叫的程式，可報告線路和電話裝置上所有非同步作業程式完成的程式。

lpdwTSPIOptions

DWORD大小的記憶體位置指標，服務提供者可以在其中寫入指定值LINETSPIOPTIONS_值。此參數可讓服務提供者傳回位，指出 TAPI 所需的選擇性行為。 TAPI 會在呼叫TSPI_providerInit之前將DWORD選項設定為 0，因此如果服務提供者不想要任何這些選項，就只能將DWORD設定為 0。

此時，只會定義一個位，以透過這個指標傳回：LINETSPIOPTION_NONREENTRANT。如果服務提供者不是針對完全先占式、多執行緒、多工處理、多處理器作業 (所設計，則設定此位，例如更新受 mutex 保護的全域資料) 。設定此位時，TAPI 一次只會對服務提供者進行一次呼叫;它不會再次呼叫任何其他進入點，也不會再次呼叫該進入點，直到服務提供者從原始函式呼叫傳回為止。若未設定此位，TAPI 可能會呼叫多個服務提供者進入點，包括相同進入點的多次，同時 (在多處理器系統中實際同時) 。

注意：必須強調設定此位會降低效能。強烈建議您只用于開發，而不是隨附的生產服務提供者。

TAPI 不會序列化存取顯示對話方塊的 TSPI 函式， ( TUISPI_lineConfigDialog、TUISPI_lineConfigDialogEdit、TUISPI_phoneConfigDialog、TUISPI_providerConfig、TUISPI_providerInstall 、TUISPI_providerRemove) ，使其不會封鎖其他 TSPI 函式被呼叫;服務提供者必須包含這些函式的內部保護。

傳回值

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

LINEERR_INCOMPATIBLEAPIVERSION、LINEERR_OPERATIONFAILED、LINEERR_NOMEM、LINEERR_RESOURCEUNAVAIL、LINEERR_INIFILECORRUPT、LINEERR_NOMULTIPLEINSTANCE。

備註

除了TSPI_lineNegotiateTSPIVersion以外，保證會在前面加上 TSPI_line 或 TSPI_phone 的任何其他函式之前呼叫此函式。它與後續呼叫配對TSPI_providerShutdown這些配對可能會重迭，例如，當電話語音主控台公用程式在 1.4 版和更早版本中提供給 Windows Telephony 時，會在進行電話語音作業時使用。如果已經有未完成的配對，則必須忽略此函式的呼叫 (傳回成功) 。

服務提供者應該執行與當時一樣多的一致性檢查。 系統會呼叫 TSPI_providerInit ，以確保它已準備好執行。不過，在嘗試作業之前，無法偵測到某些一致性或安裝錯誤。錯誤LINEERR_NODRIVER可用來報告偵測到這類非特定錯誤。

TAPI 層級沒有直接對應的函式。在該層級，可以處理多個不同的使用實例，並傳回「應用程式控制碼」來識別後續作業中的實例。在 TSPI 層級，介面架構僅支援每個不同服務提供者的單一使用實例。