ホーム › Devices.Fax › PFAXDEVVIRTUALDEVICECREATION

PFAXDEVVIRTUALDEVICECREATION

コールバック

シグネチャ

BOOL PFAXDEVVIRTUALDEVICECREATION(
    DWORD* DeviceCount,
    LPWSTR DeviceNamePrefix,
    DWORD* DeviceIdPrefix,
    HANDLE CompletionPort,
    UINT_PTR CompletionKey
);

パラメーター

フィールド

型

説明

DeviceCount

DWORD*

FAX サービスが FSP のために作成する必要のある仮想 FAX デバイスの数を受け取る、符号なしの DWORD 変数へのポインターです。FSP がこのパラメーターに 0 を設定した場合、プロバイダーの初期化は失敗します。

DeviceNamePrefix

LPWSTR

NULL で終わる Unicode 文字列 (最大 128 WCHAR 文字) を受け取る変数へのポインターです。FSP は、この文字列に仮想 FAX デバイスの名前プレフィックスを設定する必要があります。FAX サービスは、この文字列の後ろに DeviceIdPrefix パラメーターの値を追加します。その結果、FAX サービスが作成する各仮想 FAX デバイスに対して一意のデバイス名が得られます。

DeviceIdPrefix

DWORD*

0 以外の値を受け取る、符号なしの DWORD 変数へのポインターです。FSP は、仮想 FAX デバイスを識別する一意の数値をこのメンバーに設定する必要があります。FAX サービスは、この値に連番 (最初の仮想デバイスは 0 から開始) を加算します。その結果、FAX サービスが作成する各仮想 FAX デバイスに対して一意のデバイス識別子が得られます。

CompletionPort

HANDLE

非同期の回線状態イベントについて、FSP が FAX サービスへ I/O 完了ポートパケットをポストするために使用しなければならないハンドルを指定します。現在、FaxDevVirtualDeviceCreation 関数は着信を通知するイベントのみをサポートします。

完了ポートパケットは、TAPI 2.x の LINEMESSAGE 構造体である必要があります。FSP は、この構造体のメモリを LocalAlloc(LPTR, sizeof(LINEMESSAGE)) で割り当てる必要があります。FAX サービスプロバイダーは、割り当てたメモリのサイズ (この場合は sizeof(LINEMESSAGE)) を PostQueuedCompletionStatus メソッドの dwNumberOfBytesTransferred パラメーターに渡す必要があります。完了パケット構造体に割り当てられたメモリは、FAX サービスが解放します。

FSP は、この構造体のメンバーを次のように設定する必要があります。

メンバー	内容
hDevice	FaxDevStartJob の DeviceId を設定します
dwMessageID	0 を設定します
dwCallbackInstance	0 を設定します
dwParam1	LINEDEVSTATE_RINGING を設定します
dwParam2	0 を設定します
dwParam1	0 を設定します

回線状態イベントについては、TAPI のドキュメントの LINEDEVSTATE_ 定数を参照してください。I/O 完了ポートについては、I/O 完了ポートを参照してください。

CompletionKey

UINT_PTR

完了キーの値を指定します。FSP は、FAX サービスへ完了ポートパケットをポストするときにこの値を使用する必要があります。FSP は、この不透明な値を PostQueuedCompletionStatus 関数に渡します。

公式ドキュメント

FAX サービスは、初期化中に FaxDevVirtualDeviceCreation 関数を呼び出し、FAX サービスプロバイダー (FSP) が仮想 FAX デバイスを提示できるようにします。仮想 FAX デバイスを FAX サービスに提示する FSP は、いずれも FaxDevVirtualDeviceCreation 関数をエクスポートする必要があります。

戻り値

型: BOOL

関数が成功すると、戻り値は 0 以外の値です。

関数が失敗すると、戻り値は 0 です。拡張エラー情報を取得するために、FAX サービスは GetLastError を呼び出します。

解説(Remarks)

FAX サービスは、初期化中に FSP の DLL に FaxDevVirtualDeviceCreation 関数があるかどうかを確認します。FSP がこの関数をエクスポートしている場合、FAX サービスは、そのプロバイダーが仮想 FAX デバイスを提示するものと見なします。FAX サービスは、仮想 FAX デバイスを物理 FAX デバイスと同じように扱います。初期化後は、仮想 FAX デバイスを提示する FSP と提示しない FSP との間で、機能や動作に違いはありません。

FSP が物理 FAX デバイスを使用する場合は、TAPI とテレフォニーサービスプロバイダー (TSP) が FAX サービスのためにデバイスを列挙します。FSP が物理 FAX デバイスを持たず、仮想 FAX デバイスのみを提示する場合は、TSP が存在しないため、TAPI はデバイスを列挙しません。この場合、FaxDevVirtualDeviceCreation が FAX サービスのために仮想 FAX デバイスの列挙を行います。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)