PFAXENUMPORTSA

コールバック

シグネチャ

BOOL PFAXENUMPORTSA(
    HANDLE FaxHandle,
    FAX_PORT_INFOA** PortInfo,
    DWORD* PortsReturned
);

パラメーター

フィールド	型	説明
FaxHandle	HANDLE	FaxConnectFaxServer 関数の呼び出しによって返されたファックスサーバーのハンドルを指定します。
PortInfo	FAX_PORT_INFOA**	FAX_PORT_INFO 構造体の配列を受け取るバッファーのアドレスへのポインターです。各構造体は 1 つのファックスポートを記述します。このデータには、永続的な回線識別子や、ポートの現在の状態と機能などが含まれます。メモリの割り当てについては、後述の「解説」節を参照してください。
PortsReturned	DWORD*	関数が PortInfo パラメーターに返す FAX_PORT_INFO 構造体の数を受け取る DWORD 変数へのポインターです。

公式ドキュメント

FaxEnumPorts 関数は、クライアントが接続しているファックスサーバーに現在接続されているすべてのファックスデバイスを列挙します。この関数は、各ファックスポートの詳細情報をファックスクライアントアプリケーションに返します。

戻り値

型: BOOL

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

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

戻り値	説明
ERROR_ACCESS_DENIED	アクセスが拒否されました。FAX_JOB_QUERY アクセス権が必要です。
ERROR_INVALID_PARAMETER	PortsReturned、PortInfo、FaxHandle パラメーターのいずれか、またはすべてが NULL です。
ERROR_NOT_ENOUGH_MEMORY	メモリの割り当て中にエラーが発生しました。

解説(Remarks)

FaxEnumPorts 関数は、対象のファックスサーバー上のファックスジョブの一覧と、各ジョブについて利用可能な情報を返します。ファックス管理アプリケーションは通常、管理やクエリの目的でファックスジョブのキューを表示するためにこの関数を呼び出します。詳細については、ファックスジョブの管理を参照してください。

FaxEnumPorts 関数は、JobEntry パラメーターが指す FAX_JOB_ENTRY バッファー配列に必要なメモリを割り当てます。アプリケーションは、このパラメーターに関連付けられたリソースを解放するために FaxFreeBuffer 関数を呼び出す必要があります。詳細については、ファックスリソースの解放を参照してください。

メモ

winfax.h ヘッダーは、UNICODE プリプロセッサ定数の定義に基づいてこの関数の ANSI 版または Unicode 版を自動的に選択するエイリアスとして FaxEnumPorts を定義しています。エンコーディング中立のエイリアスと、エンコーディング中立でないコードを混在させると、不一致が生じてコンパイルエラーや実行時エラーの原因になることがあります。詳細については、関数プロトタイプの規則を参照してください。

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