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

IFaxDevice

COMIDispatch (デュアル)
📘 Microsoft Learn (日本語) · English
✅ IDispatch を実装(デュアルインターフェース)。HSP では comobj 経由でメソッド名による遅延バインド呼び出しができます(vtableインデックス不要)。
IID49306c59-b52e-4867-9df4-ca5841c956d0継承元IDispatch呼び出し名前(IDispatch) または vtbl自前メソッド開始 vtbl7

公式ドキュメント

IFaxDevice インターフェースは、FAX クライアント アプリケーションが FAX デバイスの情報を取得および設定したり、FAX デバイスに関連付けられた FAX ルーティング方法を追加および削除したりするために使用する構成オブジェクトを定義します。

解説(Remarks)

IFaxDevice の既定の実装は、FaxDevice オブジェクトとして提供されます。

メソッド 26

vtbl = vtable インデックス(0始まり)。IDispatch 実装のため HSP ではメソッド名でも呼べます(上記)。低レベルの index 呼び出し用に vtbl も掲載。0〜2 は IUnknown。

vtbl 7 HRESULT get_Id(INT* plId)

Id (IFaxDevice::get_Id) は、FAX デバイスを一意に識別する数値です。

plIdINT*outファクスデバイスを一意に識別するIDを受け取るINTポインタ。
vtbl 8 HRESULT get_DeviceName(LPWSTR* pbstrDeviceName)

IFaxDevice::get_DeviceName プロパティは、FAX デバイスの名前を格納する null 終端文字列です。

pbstrDeviceNameLPWSTR*outファクスデバイスの名前を受け取るBSTRポインタ。
vtbl 9 HRESULT get_ProviderUniqueName(LPWSTR* pbstrProviderUniqueName)

IFaxDevice::get_ProviderUniqueName プロパティは、デバイスに関連付けられた FAX サービス プロバイダー (FSP) の一意の名前を格納する null 終端文字列です。

pbstrProviderUniqueNameLPWSTR*outこのデバイスを提供するプロバイダの一意名を受け取るBSTRポインタ。
vtbl 10 HRESULT get_PoweredOff(VARIANT_BOOL* pbPoweredOff)

IFaxDevice::get_PoweredOff プロパティは、FAX デバイスが現在 FAX の送受信に使用できるかどうかを示すブール値です。

pbPoweredOffVARIANT_BOOL*outデバイスの電源が切れているかを受け取るVARIANT_BOOLポインタ。

解説(Remarks)

このプロパティが TRUE の場合、FAX デバイスは現在オフラインであり、FAX の送受信に使用できません。このプロパティが FALSE の場合、FAX デバイスはオンラインであり使用可能です。

注意 このプロパティの値は FaxDevice オブジェクトの作成時に設定され、IFaxDevice::Refresh メソッドを呼び出したときに更新されます。
vtbl 11 HRESULT get_ReceivingNow(VARIANT_BOOL* pbReceivingNow)

IFaxDevice::get_ReceivingNow プロパティは、プロパティを取得した時点で FAX デバイスが FAX を受信中かどうかを示すブール値です (状態はその直後に変化する可能性があります)。

pbReceivingNowVARIANT_BOOL*outデバイスが現在受信中かを受け取るVARIANT_BOOLポインタ。

解説(Remarks)

このプロパティが TRUE の場合、FAX デバイスは現在 FAX を受信中です。このプロパティが FALSE の場合、FAX デバイスは現在 FAX を受信していません。

注意 このプロパティの値は FaxDevice オブジェクトの作成時に設定され、IFaxDevice::Refresh メソッドを呼び出したときに更新されます。
vtbl 12 HRESULT get_SendingNow(VARIANT_BOOL* pbSendingNow)

IFaxDevice::get_SendingNow プロパティは、プロパティを取得した時点で FAX デバイスが FAX を送信中かどうかを示すブール値です (状態はその直後に変化する可能性があります)。

pbSendingNowVARIANT_BOOL*outデバイスが現在送信中かを受け取るVARIANT_BOOLポインタ。

解説(Remarks)

このプロパティが TRUE の場合、FAX デバイスは現在 FAX を送信中です。このプロパティが FALSE の場合、FAX デバイスは現在 FAX を送信していません。

注意 このプロパティの値は FaxDevice オブジェクトの作成時に設定され、IFaxDevice::Refresh メソッドを呼び出したときに更新されます。
vtbl 13 HRESULT get_UsedRoutingMethods(VARIANT* pvUsedRoutingMethods)

IFaxDevice::get_UsedRoutingMethods プロパティは、デバイスが使用するルーティング方法に関連付けられた GUID を格納する文字列の配列です。各 GUID は 1 つの受信ルーティング方法 (FaxInboundRoutingMethod) を表します。

pvUsedRoutingMethodsVARIANT*outこのデバイスで有効なルーティングメソッドのGUID配列を格納したVARIANTを受け取るポインタ。

解説(Remarks)

ルーティング方法の GUID の配列にルーティング方法を追加する、または配列から削除するには、IFaxDevice::UseRoutingMethod メソッドを呼び出します。

このプロパティを読み取るには、ユーザーに farQUERY_CONFIG アクセス権が必要です。

vtbl 14 HRESULT get_Description(LPWSTR* pbstrDescription)

IFaxDevice::get_Description プロパティは、FAX デバイスのわかりやすい説明を格納する null 終端文字列です。この文字列はユーザーへの表示に適しています。(Get)

pbstrDescriptionLPWSTR*outデバイスの説明文字列を受け取るBSTRポインタ。
vtbl 15 HRESULT put_Description(LPWSTR bstrDescription)

IFaxDevice::get_Description プロパティは、FAX デバイスのわかりやすい説明を格納する null 終端文字列です。この文字列はユーザーへの表示に適しています。(Put)

bstrDescriptionLPWSTRinデバイスの説明文字列を設定するBSTR。
vtbl 16 HRESULT get_SendEnabled(VARIANT_BOOL* pbSendEnabled)

IFaxDevice::get_SendEnabled プロパティは、FAX デバイスで FAX の送信が有効になっているかどうかを示すブール値です。(Get)

pbSendEnabledVARIANT_BOOL*outこのデバイスで送信が有効かを受け取るVARIANT_BOOLポインタ。

解説(Remarks)

このプロパティが TRUE の場合、FAX デバイスは FAX の送信が有効になっています。このプロパティが FALSE の場合、FAX デバイスは FAX の送信が有効になっていません。

vtbl 17 HRESULT put_SendEnabled(VARIANT_BOOL bSendEnabled)

IFaxDevice::get_SendEnabled プロパティは、FAX デバイスで FAX の送信が有効になっているかどうかを示すブール値です。(Put)

bSendEnabledVARIANT_BOOLinこのデバイスの送信有効/無効を設定するVARIANT_BOOL。

解説(Remarks)

このプロパティが TRUE の場合、FAX デバイスは FAX の送信が有効になっています。このプロパティが FALSE の場合、FAX デバイスは FAX の送信が有効になっていません。

vtbl 18 HRESULT get_ReceiveMode(FAX_DEVICE_RECEIVE_MODE_ENUM* pReceiveMode)

ReceiveMode プロパティは、デバイスが着信呼び出しに応答する方法を定義する FAX_DEVICE_RECEIVE_MODE_ENUM 列挙体の値です。(Get)

pReceiveModeFAX_DEVICE_RECEIVE_MODE_ENUM*out受信モードを表すFAX_DEVICE_RECEIVE_MODE_ENUM値を受け取るポインタ。自動/手動/無効を示す。

解説(Remarks)

FAX を手動で受信するように設定できるデバイスは、常に 1 台だけです。あるデバイスを手動応答に設定したときに、別のデバイスが既に手動モードに設定されている場合、以前に設定されていたデバイスは自動的に応答なしモードに変更されます。この変更を確認するには、そのデバイスに対して IFaxDevice::Refresh メソッドを呼び出してください。

仮想デバイスなど、一部のデバイスは手動応答の受信モードをサポートしていません。そのようなデバイスでは、受信モードを fdrmMANUAL_ANSWER に設定すると ReceiveMode は失敗します。C++ では、HRESULT 形式の ERROR_NOT_SUPPORTED エラー コードが返されます。

vtbl 19 HRESULT put_ReceiveMode(FAX_DEVICE_RECEIVE_MODE_ENUM ReceiveMode)

ReceiveMode プロパティは、デバイスが着信呼び出しに応答する方法を定義する FAX_DEVICE_RECEIVE_MODE_ENUM 列挙体の値です。(Put)

ReceiveModeFAX_DEVICE_RECEIVE_MODE_ENUMin受信モードを設定するFAX_DEVICE_RECEIVE_MODE_ENUM値。自動/手動/無効を指定する。

解説(Remarks)

FAX を手動で受信するように設定できるデバイスは、常に 1 台だけです。あるデバイスを手動応答に設定したときに、別のデバイスが既に手動モードに設定されている場合、以前に設定されていたデバイスは自動的に応答なしモードに変更されます。この変更を確認するには、そのデバイスに対して IFaxDevice::Refresh メソッドを呼び出してください。

仮想デバイスなど、一部のデバイスは手動応答の受信モードをサポートしていません。そのようなデバイスでは、受信モードを fdrmMANUAL_ANSWER に設定すると ReceiveMode は失敗します。C++ では、HRESULT 形式の ERROR_NOT_SUPPORTED エラー コードが返されます。

vtbl 20 HRESULT get_RingsBeforeAnswer(INT* plRingsBeforeAnswer)

IFaxDevice::get_RingsBeforeAnswer プロパティは、FAX デバイスが着信 FAX 呼び出しに応答するまでの呼び出し音の回数を指定する数値です。(Get)

plRingsBeforeAnswerINT*out自動応答までの呼出回数を受け取るINTポインタ。

解説(Remarks)

このプロパティは、デバイスの ReceiveMode プロパティが fdrmAUTO_ANSWER に設定されている場合にのみ使用されます。

vtbl 21 HRESULT put_RingsBeforeAnswer(INT lRingsBeforeAnswer)

IFaxDevice::get_RingsBeforeAnswer プロパティは、FAX デバイスが着信 FAX 呼び出しに応答するまでの呼び出し音の回数を指定する数値です。(Put)

lRingsBeforeAnswerINTin自動応答までの呼出回数を設定するINT。

解説(Remarks)

このプロパティは、デバイスの ReceiveMode プロパティが fdrmAUTO_ANSWER に設定されている場合にのみ使用されます。

vtbl 22 HRESULT get_CSID(LPWSTR* pbstrCSID)

IFaxDevice::get_CSID プロパティは、デバイスの着信側局識別子 (CSID) を格納する null 終端文字列です。(Get)

pbstrCSIDLPWSTR*outこのデバイスの被呼局識別(CSID)文字列を受け取るBSTRポインタ。

解説(Remarks)

注意 CSID は 20 文字までに制限されています。また、ほとんどの FAX 機は FAX 送信の CSID および送信側局識別子 (TSID) の文字列に使用できる文字が限られているため、これらの文字列には英字、数字、句読点 (ASCII の 0x20 から 0x7F の範囲) のみを使用することをお勧めします。
vtbl 23 HRESULT put_CSID(LPWSTR bstrCSID)

IFaxDevice::get_CSID プロパティは、デバイスの着信側局識別子 (CSID) を格納する null 終端文字列です。(Put)

bstrCSIDLPWSTRinこのデバイスの被呼局識別(CSID)文字列を設定するBSTR。

解説(Remarks)

注意 CSID は 20 文字までに制限されています。また、ほとんどの FAX 機は FAX 送信の CSID および送信側局識別子 (TSID) の文字列に使用できる文字が限られているため、これらの文字列には英字、数字、句読点 (ASCII の 0x20 から 0x7F の範囲) のみを使用することをお勧めします。
vtbl 24 HRESULT get_TSID(LPWSTR* pbstrTSID)

IFaxDevice::get_TSID プロパティは、デバイスの送信側局識別子 (TSID) を格納する null 終端文字列です。(Get)

pbstrTSIDLPWSTR*outこのデバイスの送信局識別(TSID)文字列を受け取るBSTRポインタ。

解説(Remarks)

注意 TSID は 20 文字までに制限されています。また、ほとんどの FAX 機は FAX 送信の着信側局識別子 (CSID) および TSID の文字列に使用できる文字が限られているため、これらの文字列には英字、数字、句読点 (ASCII の 0x20 から 0x7F の範囲) のみを使用することをお勧めします。
vtbl 25 HRESULT put_TSID(LPWSTR bstrTSID)

IFaxDevice::get_TSID プロパティは、デバイスの送信側局識別子 (TSID) を格納する null 終端文字列です。(Put)

bstrTSIDLPWSTRinこのデバイスの送信局識別(TSID)文字列を設定するBSTR。

解説(Remarks)

注意 TSID は 20 文字までに制限されています。また、ほとんどの FAX 機は FAX 送信の着信側局識別子 (CSID) および TSID の文字列に使用できる文字が限られているため、これらの文字列には英字、数字、句読点 (ASCII の 0x20 から 0x7F の範囲) のみを使用することをお勧めします。
vtbl 26 HRESULT Refresh()

IFaxDevice::Refresh メソッドは、FaxDevice オブジェクトの情報を FAX サーバーから更新します。IFaxDevice::Refresh メソッドを呼び出すと、最後に IFaxDevice::Save メソッドを呼び出した後に行われた構成の変更はすべて失われます。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラー コードを返します。

解説(Remarks)

このメソッドを使用するには、ユーザーに farQUERY_CONFIG アクセス権が必要です。

vtbl 27 HRESULT Save()

IFaxDevice::Save メソッドは、FaxDevice オブジェクトのデータを保存します。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラー コードを返します。

解説(Remarks)

このメソッドを使用するには、ユーザーに farMANAGE_CONFIG アクセス権が必要です。

vtbl 28 HRESULT GetExtensionProperty(LPWSTR bstrGUID, VARIANT* pvProperty)

IFaxDevice::get_GetExtensionProperty メソッドは、デバイス レベルで格納されている拡張機能の構成プロパティを取得します。

bstrGUIDLPWSTRin取得するデータを一意に識別する文字列 GUID を指定します。
pvPropertyVARIANT*outデータを指定する VARIANT です。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラー コードを返します。

解説(Remarks)

注意 返されるデータは、符号なし char のバリアント セーフ配列 (VT_UI1 | VT_ARRAY) として表されるバイトの BLOB です。このデータは、それを使用する特定の拡張機能にのみ意味を持ちます。詳細については、FAX 拡張機能構成 API についてを参照してください。
このメソッドを使用するには、ユーザーに farQUERY_CONFIG アクセス権が必要です。
vtbl 29 HRESULT SetExtensionProperty(LPWSTR bstrGUID, VARIANT vProperty)

IFaxDevice::SetExtensionProperty メソッドは、拡張機能の構成プロパティをデバイス レベルで格納します。

bstrGUIDLPWSTRin設定するデータを識別する文字列 GUID を指定します。
vPropertyVARIANTin格納するデータを指定する VARIANT です。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラー コードを返します。

解説(Remarks)

このメソッドを使用するには、ユーザーに farMANAGE_CONFIG アクセス権が必要です。

注意 必要なデータは、符号なし char のバリアント セーフ配列 (VT_UI1 | VT_ARRAY) として表されるバイトの BLOB です。このデータは、それを使用する特定の拡張機能にのみ意味を持ちます。詳細については、FAX 拡張機能構成 API についてを参照してください。
vtbl 30 HRESULT UseRoutingMethod(LPWSTR bstrMethodGUID, VARIANT_BOOL bUse)

IFaxDevice::UseRoutingMethod メソッドは、FAX デバイスに関連付けられたルーティング方法の一覧に受信 FAX ルーティング方法を追加するか、一覧から FAX ルーティング方法 (FaxInboundRoutingMethod) を削除します。

bstrMethodGUIDLPWSTRin追加または削除する FAX ルーティング方法を一意に識別する null 終端文字列を指定します。
bUseVARIANT_BOOLinブール値を指定します。このパラメーターが TRUE の場合、このメソッドは FAX デバイスに関連付けられた受信方法の一覧に FAX ルーティング方法を追加します。このパラメーターに FALSE を設定した場合、このメソッドは一覧からそのルーティング方法を削除します。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラー コードを返します。

解説(Remarks)

このメソッドを使用するには、ユーザーに farMANAGE_CONFIG アクセス権が必要です。

vtbl 31 HRESULT get_RingingNow(VARIANT_BOOL* pbRingingNow)

IFaxDevice::get_RingingNow プロパティは、プロパティを取得した時点で FAX デバイスが呼び出し中かどうかを示すブール値です (状態はその直後に変化する可能性があります)。

pbRingingNowVARIANT_BOOL*outデバイスの回線が現在着信(呼出)中かを受け取るVARIANT_BOOLポインタ。

解説(Remarks)

このプロパティが TRUE の場合、FAX デバイスは現在呼び出し中です。このプロパティが FALSE の場合、FAX デバイスは呼び出し中ではありません。

注意 このプロパティの値は FaxDevice オブジェクトの作成時に設定され、IFaxDevice::Refresh メソッドを呼び出したときに更新されます。
vtbl 32 HRESULT AnswerCall()

IFaxDevice::AnswerCall メソッドは、FAX デバイスに着信呼び出しへ応答させます。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラー コードを返します。

解説(Remarks)

IFaxDevice::AnswerCall メソッドは、ローカル サーバー上の FAX デバイスに対してのみ機能します。このメソッドは、ReceiveMode プロパティの値にかかわらず機能します。

このメソッドを使用すると、呼び出しに手動で応答できます。ReceiveMode プロパティが手動応答、自動応答、応答なしのいずれに設定されていても、このメソッドを使用できます。着信呼び出しが成功するには、FAX デバイスがアイドル状態である必要があります。

このメソッドを使用するには、ユーザーに farQUERY_IN_ARCHIVE アクセス権が必要です。

このメソッドが成功した場合、サービスは要求を正常に受け入れ、パラメーターとアクセス権を検証したことを意味します。メソッドの成功は、サービスが呼び出しに応答して FAX の受信を開始したことを示すものではありません。メソッドが成功しても、デバイスが想定どおりに応答しない場合など、サービスがデバイス上で呼び出しに応答できなかった場合には、通知は送信されません。

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

HSP用 COM定義

#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。

出力引数: 
#define global IID_IFaxDevice "{49306C59-B52E-4867-9DF4-CA5841C956D0}"
#usecom global IFaxDevice IID_IFaxDevice "{}"
#comfunc global IFaxDevice_get_Id                  7 var
#comfunc global IFaxDevice_get_DeviceName          8 var
#comfunc global IFaxDevice_get_ProviderUniqueName  9 var
#comfunc global IFaxDevice_get_PoweredOff          10 var
#comfunc global IFaxDevice_get_ReceivingNow        11 var
#comfunc global IFaxDevice_get_SendingNow          12 var
#comfunc global IFaxDevice_get_UsedRoutingMethods  13 var
#comfunc global IFaxDevice_get_Description         14 var
#comfunc global IFaxDevice_put_Description         15 wstr
#comfunc global IFaxDevice_get_SendEnabled         16 var
#comfunc global IFaxDevice_put_SendEnabled         17 int
#comfunc global IFaxDevice_get_ReceiveMode         18 var
#comfunc global IFaxDevice_put_ReceiveMode         19 int
#comfunc global IFaxDevice_get_RingsBeforeAnswer   20 var
#comfunc global IFaxDevice_put_RingsBeforeAnswer   21 int
#comfunc global IFaxDevice_get_CSID                22 var
#comfunc global IFaxDevice_put_CSID                23 wstr
#comfunc global IFaxDevice_get_TSID                24 var
#comfunc global IFaxDevice_put_TSID                25 wstr
#comfunc global IFaxDevice_Refresh                 26
#comfunc global IFaxDevice_Save                    27
#comfunc global IFaxDevice_GetExtensionProperty    28 wstr,var
#comfunc global IFaxDevice_SetExtensionProperty    29 wstr,int
#comfunc global IFaxDevice_UseRoutingMethod        30 wstr,int
#comfunc global IFaxDevice_get_RingingNow          31 var
#comfunc global IFaxDevice_AnswerCall              32
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※IDispatch 実装。HSP では comobj 経由でメソッド名による呼び出しも可能(vtbl 不要)。