FaxDevVirtualDeviceCreation 函式 (faxdev.h)

發行項
08/23/2023

傳真服務會在初始化期間呼叫 FaxDevVirtualDeviceCreation 函式，以允許傳真服務提供者 (FSP) 呈現虛擬傳真裝置。每個向傳真服務呈現虛擬傳真裝置的 FSP 都必須匯出 FaxDevVirtualDeviceCreation 函式。

語法

BOOL FaxDevVirtualDeviceCreation(
  [out] LPDWORD   DeviceCount,
  [out] LPWSTR    DeviceNamePrefix,
  [out] LPDWORD   DeviceIdPrefix,
  [in]  HANDLE    CompletionPort,
  [in]  ULONG_PTR CompletionKey
);

參數

[out] DeviceCount

類型： LPDWORD

接收傳真服務必須為 FSP 建立之虛擬傳真裝置數目的未簽署 DWORD 變數指標。如果 FSP 將此參數設定為零，提供者的初始化將會失敗。

[out] DeviceNamePrefix

類型： LPWSTR

接收 Null 終止 Unicode 字元字串之變數的指標，限制為 128 個 WCHAR 字元。 FSP 必須將此字串設定為虛擬傳真裝置的名稱前置詞。傳真服務會將 DeviceIdPrefix 參數的值附加至此字串。結果是傳真服務所建立的每個虛擬傳真裝置的唯一裝置名稱。

[out] DeviceIdPrefix

類型： LPDWORD

接收非零值的未帶正負號 DWORD 變數指標。 FSP 必須將此成員設定為可識別虛擬傳真裝置的唯一數值。傳真服務會將此值新增至序號，從第一個虛擬裝置以零開始。結果是傳真服務所建立的每個虛擬傳真裝置的唯一裝置識別碼。

[in] CompletionPort

類型： HANDLE

指定 FSP 必須用來將 I/O 完成埠封包張貼至傳真服務的控制碼，以取得非同步線路狀態事件。目前 ，FaxDevVirtualDeviceCreation 函式僅支援發出連入呼叫訊號的事件。

完成埠封包必須是 TAPI 2.x LINEMESSAGE 結構。 FSP 必須為具有 LocalAlloc (LPTR、sizeof (LINEMESSAGE) ) 的結構配置記憶體。 傳真服務提供者必須將配置 (的記憶體大小傳遞給PostQueuedCompletionStatus方法的dwNumberOfBytesTransferred參數，此) 為 sizeof (LINEMESSAGE) 。傳真服務會釋放配置給完成封包結構的任何記憶體。

FSP 必須設定結構的成員，如下所示。

成員	目錄
hDevice	從FaxDevStartJob設定為DeviceId
dwMessageID	設定為 0
dwCallbackInstance	設定為 0
dwParam1	設定為 LINEDEVSTATE_RINGING
dwParam2	設定為 0
dwParam1	設定為 0

如需行狀態事件的相關資訊，請參閱 TAPI 檔中的LINEDEVSTATE_常數。如需 I/O 完成埠的相關資訊，請參閱 I/O 完成埠。

[in] CompletionKey

類型： ULONG_PTR

指定完成索引鍵值。當提供者將完成埠封包張貼至傳真服務時，FSP 必須使用此值。 FSP 應該將此不透明值傳遞至 PostQueuedCompletionStatus 函式。

傳回值

類型： BOOL

如果函式成功，則傳回值是非零值。

如果此函式失敗，則傳回值為零。若要取得延伸的錯誤資訊，傳真服務會呼叫 GetLastError。

備註

傳真服務會在初始化期間檢查 FSP DLL 中的 FaxDevVirtualDeviceCreation 函式。如果 FSP 匯出函式，傳真服務會假設提供者將呈現虛擬傳真裝置。傳真服務會以處理實體傳真裝置的相同方式處理虛擬傳真裝置。初始化之後，FSP 的功能或作業會呈現虛擬傳真裝置，以及未顯示虛擬傳真裝置的功能或作業之間沒有任何差異。

當 FSP 使用實體傳真裝置時，TAPI 和電話語音服務提供者 (TSP) 列舉傳真服務的裝置。如果 FSP 沒有實體傳真裝置，而且它只呈現虛擬傳真裝置，則 TSP 將不會存在，而 TAPI 不會列舉裝置。在此實例中， FaxDevVirtualDeviceCreation 會提供傳真服務的虛擬傳真裝置列舉。

需求


最低支援的用戶端	Windows 2000 專業版、Windows XP [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2003 [僅限傳統型應用程式]
目標平台	Windows
標頭	faxdev.h