Win32 API 日本語リファレンス
ホーム › Devices.Fax › PFAXINITIALIZEEVENTQUEUE

PFAXINITIALIZEEVENTQUEUE

コールバック

シグネチャ

BOOL PFAXINITIALIZEEVENTQUEUE(
    HANDLE FaxHandle,
    HANDLE CompletionPort,
    UINT_PTR CompletionKey,
    HWND hWnd,
    DWORD MessageStart
);

パラメーター

フィールド型説明
FaxHandleHANDLEFaxConnectFaxServer 関数の呼び出しによって返されたファックスサーバーのハンドルを指定します。
CompletionPortHANDLE

CreateIoCompletionPort 関数の呼び出しによって返された I/O 完了ポートへの有効なハンドルを指定します。このパラメーターは、I/O 完了パケットによる通知を使用する場合に必要です。通知メッセージを指定する場合は、このパラメーターを NULL にする必要があります。

I/O 完了ポートの詳細については、I/O 完了ポートを参照してください。

CompletionKeyUINT_PTRファックスサーバーが各 I/O 完了パケットに含める完了キーの値を格納する変数を指定します。このパラメーターは、I/O 完了パケットによる通知を使用する場合に必要です。通知メッセージを指定する場合は、このパラメーターを NULL にする必要があります。詳細については、後述の「解説」セクションを参照してください。
hWndHWND非同期イベントが発生したときに通知する、ファックスクライアントアプリケーションのウィンドウへのハンドルです。このパラメーターは、通知メッセージを使用する場合に必要です。I/O 完了パケットによる通知を指定する場合は、このパラメーターを NULL にする必要があります。
MessageStartDWORD

アプリケーションの基準となるウィンドウメッセージを識別する符号なし整数を指定します。アプリケーションはこの値を使用して、メッセージをファックスサーバーのイベントとして処理するかどうかを判断できます。詳細については、FAX_EVENT のトピックを参照してください。

このパラメーターは、通知メッセージを使用する場合に必要です。I/O 完了パケットによる通知を指定する場合は、このパラメーターをゼロにする必要があります。

公式ドキュメント

FaxInitializeEventQueue 関数は、呼び出し元のファックスクライアントアプリケーション用にファックスイベントキューを作成します。このキューにより、アプリケーションはファックスサーバーからの非同期イベントの通知を受け取ることができます。

戻り値

型: BOOL

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

関数が失敗すると、戻り値は 0 になります。拡張エラー情報を取得するには、GetLastError を呼び出します。GetLastError は次のいずれかのエラーを返すことがあります。

戻り値 説明
ERROR_INVALID_PARAMETER
 hWnd パラメーターと CompletionPort パラメーターの両方が NULL であるか、両方のパラメーターが指定されています。
ERROR_INVALID_PARAMETER
 FaxHandle パラメーターが NULL である、または hWnd パラメーターが指定されているが FaxHandle パラメーターがローカルのファックスサーバーとの接続を指していない、または MessageStart パラメーターが WM_USER 未満の範囲のメッセージを指定しています。
ERROR_INVALID_DATA
 Windows 2000 において、アプリケーションが 1 回のファックスサービスセッション中に FaxInitializeEventQueue 関数を複数回呼び出しました。Windows XP および Windows Server 2003 では、複数回の呼び出しがサポートされています。
ERROR_NOT_ENOUGH_MEMORY
 メモリの割り当て中にエラーが発生しました。

解説(Remarks)

アプリケーションは、ファックスサーバーがクライアントアプリケーションにイベントを通知する方法を指定できます。アプリケーションは、ファックスサーバーが I/O 完了パケットを I/O 完了ポートにキューイングするよう要求するか、通知メッセージを指定できます。

ファックスクライアントアプリケーションは、CompletionKey パラメーターに指定する値を取得するために GetQueuedCompletionStatus を呼び出す前に、FaxInitializeEventQueue 関数を呼び出す必要があります。この値は、WaitForMultipleObjects 関数の呼び出しを使用して複数の I/O 完了ポートから I/O 完了パケットを取得するメッセージループで役立ちます。I/O 完了ポートごとに異なる完了キーを指定すると、完了パケットに関連付けられた完了ポートを識別できます。

アプリケーションは、GetQueuedCompletionStatus 関数を呼び出して、完了した I/O 操作についてキューイングされた I/O 完了パケットを取得できます。GetQueuedCompletionStatus の呼び出しでは、FAX_EVENT 構造体のアドレスが設定される変数へのポインターも返されます。この構造体は、対象の I/O 完了パケットに関連付けられています。FAX_EVENT 構造体に割り当てられたメモリを解放するには、LocalFree 関数を呼び出します。

ファックスクライアントアプリケーションは、FEI_FAXSVC_ENDED メッセージを受け取った後は、ファックスサービスからファックスイベントを受け取らなくなります。ファックスイベントの受信を再開するには、ファックスサービスの再起動時にアプリケーションが FaxInitializeEventQueue 関数を再度呼び出す必要があります。アプリケーションは、サービスコントロールマネージャーを使用してファックスサービスが実行中かどうかを確認できます。詳細については、FaxClose および アプリケーションがファックスイベントの通知を受け取れるようにする を参照してください。

ファックスサーバー内で発生する可能性のある非同期イベントの一覧については、FAX_EVENT のトピックを参照してください。

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