ITAddress2

COMIDispatch (デュアル)

✅ IDispatch を実装(デュアルインターフェース)。HSP では comobj 経由でメソッド名による遅延バインド呼び出しができます(vtableインデックス不要)。

IIDb0ae5d9b-be51-46c9-b0f7-dfa8a22a8bc4継承元ITAddress呼び出し名前(IDispatch) または vtbl自前メソッド開始 vtbl22

公式ドキュメント

ITAddress2 インターフェイスは ITAddress インターフェイスから派生します。ITAddress2 は、電話デバイスをサポートするために Address オブジェクトへメソッドを追加します。TAPI 3.1 で列挙されるすべての Address オブジェクトは、このインターフェイスを自動的に実装します。

メソッド 10

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

vtbl 22 HRESULT get_Phones(VARIANT* pPhones)

get_Phones メソッドは、このアドレスで使用できる電話デバイスに対応する電話オブジェクトの ITCollection への VARIANT ポインターを返します。

pPhones

VARIANT*

out

ITPhone インターフェイスポインターの ITCollection を格納する VARIANT へのポインター。

戻り値

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

解説(Remarks)

電話デバイスは、TSP が PHONECAPS 構造体の dwPhoneFeatures メンバーに PHONEFEATURE_GENERICPHONE ビットを設定することで、オーディオターミナルをサポートするすべてのアドレスで利用可能であることを宣言します。また、電話デバイスは、デバイスクラス tapi/line を指定した phoneGetID を通じて address/line ID を返すことにより、あるアドレスまたはアドレスの集合に対して優先されることを宣言することもできます。アドレスで使用できる電話がない場合、このメソッドは空のコレクションを生成し、S_OK を返します。

TAPI は、ITAddress2::get_Phones が返す ITPhone インターフェイスに対して AddRef メソッドを呼び出します。アプリケーションは、それに関連付けられたリソースを解放するために、 ITPhone インターフェイスに対して Release を呼び出す必要があります。

vtbl 23 HRESULT EnumeratePhones(IEnumPhone** ppEnumPhone)

EnumeratePhones メソッドは、このアドレスで使用できる電話デバイスに対応する電話オブジェクトを列挙します。

ppEnumPhone

IEnumPhone**

out

新しい IEnumPhone インターフェイスへのポインター。

戻り値

このメソッドは次のいずれかの値を返すことができます。

値	意味
S_OK	メソッドは成功しました。
E_POINTER	ppEnumPhone パラメーターが有効なポインターではありません。
E_OUTOFMEMORY	操作を実行するのに十分なメモリがありません。
E_UNEXPECTED	不明な理由でメソッドが失敗しました。

解説(Remarks)

電話デバイスは、TSP が PHONECAPS 構造体の dwPhoneFeatures メンバーに PHONEFEATURE_GENERICPHONE ビットを設定することで、オーディオターミナルをサポートするすべてのアドレスで利用可能であることを宣言します。また、電話デバイスは、デバイスクラス tapi/line を指定した phoneGetID を使用して address/line ID を返すことにより、あるアドレスまたはアドレスの集合に対して優先されることを宣言することもできます。アドレスで使用できる電話がない場合、このメソッドは空の列挙を生成し、S_OK を返します。

TAPI は、ITAddress2::EnumeratePhones が返す IEnumPhone インターフェイスに対して AddRef メソッドを呼び出します。アプリケーションは、それに関連付けられたリソースを解放するために、 IEnumPhone インターフェイスに対して Release を呼び出す必要があります。

vtbl 24 HRESULT GetPhoneFromTerminal(ITTerminal* pTerminal, ITPhone** ppPhone)

GetPhoneFromTerminal メソッドは、ターミナルに関連付けられた電話オブジェクトを返します。1 つのターミナルに関連付けられる電話は 1 つだけです。

pTerminal	ITTerminal*	in	ITTerminal インターフェイスへのポインター。
ppPhone	ITPhone**	out	ITPhone インターフェイスへのポインター。

戻り値

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

vtbl 25 HRESULT get_PreferredPhones(VARIANT* pPhones)

get_PreferredPhones メソッドは、このアドレスでの使用が優先される電話デバイスに対応する電話オブジェクトのコレクションを返します。

pPhones

VARIANT*

out

ITPhone インターフェイスポインターの ITCollection を格納する VARIANT へのポインター。

戻り値

このメソッドは次のいずれかの値を返すことができます。

値	意味
S_OK	メソッドは成功しました。
E_POINTER	pPhones パラメーターが有効なポインターではありません。
E_OUTOFMEMORY	コレクションオブジェクトを割り当てるのに十分なメモリがありません。

解説(Remarks)

電話デバイスは、デバイスクラス tapi/line を指定した phoneGetID を使用して address/line ID を返すことにより、あるアドレスまたはアドレスの集合に対して優先されることを宣言します。このアドレスで使用できる電話がない場合、このメソッドは空のコレクションを生成し、S_OK を返します。

TAPI は、ITAddress2::get_PreferredPhones が返す ITPhone インターフェイスに対して AddRef メソッドを呼び出します。アプリケーションは、それに関連付けられたリソースを解放するために、 ITPhone インターフェイスに対して Release を呼び出す必要があります。

vtbl 26 HRESULT EnumeratePreferredPhones(IEnumPhone** ppEnumPhone)

EnumeratePreferredPhones メソッドは、このアドレスに対して優先される電話オブジェクトを列挙します。

ppEnumPhone

IEnumPhone**

out

成功時に、返される電話のリストを格納する列挙オブジェクトへのポインターをこのメソッドが配置する場所へのポインター。

戻り値

このメソッドは次のいずれかの値を返すことができます。

値	意味
S_OK	メソッドは成功しました。
E_POINTER	ppEnumPhone パラメーターが有効なポインターではありません。
E_OUTOFMEMORY	列挙オブジェクトを割り当てるのに十分なメモリがありません。

解説(Remarks)

電話デバイスは、デバイスクラス tapi/line を指定した phoneGetID を使用して address/line ID を返すことにより、あるアドレスまたはアドレスの集合に対して優先されることを宣言します。アドレスで使用できる電話がない場合、このメソッドは空の列挙を生成し、S_OK を返します。

TAPI は、ITAddress2::EnumeratePreferredPhones が返す IEnumPhone インターフェイスに対して AddRef メソッドを呼び出します。アプリケーションは、それに関連付けられたリソースを解放するために、 IEnumPhone インターフェイスに対して Release を呼び出す必要があります。

vtbl 27 HRESULT get_EventFilter(TAPI_EVENT TapiEvent, INT lSubEvent, VARIANT_BOOL* pEnable)

get_EventFilter メソッドは、現在のアドレスと指定された TAPI_EVENT 値に対する現在のフィルター設定を取得します。

TapiEvent	TAPI_EVENT	in	チェックするイベント型情報の TAPI_EVENT 記述子。
lSubEvent	INT	in	サブイベント値。該当しない場合は NULL。
pEnable	VARIANT_BOOL*	out	現在のイベントがアプリケーションで必要とされているかどうかを示す VARIANT_BOOL へのポインター。

戻り値

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

vtbl 28 HRESULT put_EventFilter(TAPI_EVENT TapiEvent, INT lSubEvent, VARIANT_BOOL bEnable)

put_EventFilter メソッドは、現在のアドレスにイベントフィルターを設定します。イベントフィルターが 1 つも設定されていない場合、アプリケーションはこのアドレスのイベントについて通知されません。

TapiEvent	TAPI_EVENT	in	イベント型の TAPI_EVENT 記述子。
lSubEvent	INT	in	サブイベント記述子。
bEnable	VARIANT_BOOL	in	アプリケーションがこのイベント型の通知を必要とする場合は VARIANT_TRUE。アプリケーションがこのイベントの通知を必要としない場合は VARIANT_FALSE。

戻り値

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

vtbl 29 HRESULT DeviceSpecific(ITCallInfo* pCall, BYTE* pParams, DWORD dwSize)

DeviceSpecific メソッドは、他の TAPI 関数では提供されない機能へのアクセスをサービスプロバイダーが提供できるようにします。

pCall	ITCallInfo*	in	コールオブジェクトの ITCallInfo インターフェイスへのポインター。
pParams	BYTE*	in	パラメーターブロックを保持するために使用されるメモリ領域へのポインター。このパラメーターブロックの形式はデバイス固有であり、TAPI はその内容をアプリケーションとサービスプロバイダーの間で受け渡します。
dwSize	DWORD	in	パラメーターブロック領域のサイズ(バイト単位)。

戻り値

このメソッドは次のいずれかの値を返すことができます。

値	意味
S_OK	メソッドは成功しました。
E_POINTER	pParams または pCall パラメーターが有効なポインターではありません。
E_OUTOFMEMORY	操作を実行するのに十分なメモリがありません。

解説(Remarks)

注意

TAPI は、LINE_REPLY メッセージが返されるときに、pParams が参照するバッファーに返却データを書き込みます。つまり、バッファーは LINE_REPLY メッセージが返されるまで有効なままである必要があります。そうでない場合、データの破損や例外が発生する可能性があります。

vtbl 30 HRESULT DeviceSpecificVariant(ITCallInfo* pCall, VARIANT varDevSpecificByteArray)

DeviceSpecificVariant メソッドは、他の TAPI 関数では提供されない機能へのアクセスをサービスプロバイダーが提供できるようにします。(ITAddress2.DeviceSpecificVariant)

pCall	ITCallInfo*	in	コールオブジェクトの ITCallInfo インターフェイスへのポインター。
varDevSpecificByteArray	VARIANT	in	パラメーターブロックを格納する VARIANT。このパラメーターブロックの形式はデバイス固有であり、TAPI はその内容をアプリケーションとサービスプロバイダーの間で受け渡します。

戻り値

このメソッドは次のいずれかの値を返すことができます。

リターンコード	説明
S_OK	メソッドは成功しました。
E_POINTER	pCall パラメーターが有効なポインターではありません。
E_OUTOFMEMORY	操作を実行するのに十分なメモリがありません。

vtbl 31 HRESULT NegotiateExtVersion(INT lLowVersion, INT lHighVersion, INT* plExtVersion)

NegotiateExtVersion メソッドは、指定された回線デバイスで使用する拡張バージョンをアプリケーションがネゴシエートできるようにします。アプリケーションがプロバイダー固有の拡張をサポートしない場合、このメソッドを呼び出す必要はありません。

lLowVersion	INT	in	アプリケーションが準拠している、 NegotiateExtVersion が返す拡張識別子の最も古い拡張バージョン。上位ワードがメジャーバージョン番号、下位ワードがマイナーバージョン番号です。
lHighVersion	INT	in	アプリケーションが準拠している、 NegotiateExtVersion が返す拡張識別子の最も新しい拡張バージョン。上位ワードがメジャーバージョン番号、下位ワードがマイナーバージョン番号です。
plExtVersion	INT*	out	ネゴシエートされた拡張バージョン番号を格納する long へのポインター。ネゴシエーションが成功した場合、この番号は lLowVersion から lHighVersion までの範囲内になります。

戻り値

このメソッドは次のいずれかの値を返すことができます。

値	意味
S_OK	メソッドは成功しました。
E_INVALIDARG	lLowVersion または lHighVersion に入力されたバージョンが無効です。
E_OUTOFMEMORY	操作を実行するのに十分なメモリがありません。
E_POINTER	plExtVersion パラメーターが有効なポインターではありません。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_ITAddress2 "{B0AE5D9B-BE51-46C9-B0F7-DFA8A22A8BC4}"
#usecom global ITAddress2 IID_ITAddress2 "{}"
#comfunc global ITAddress2_get_Phones                22 var
#comfunc global ITAddress2_EnumeratePhones           23 sptr
#comfunc global ITAddress2_GetPhoneFromTerminal      24 sptr,sptr
#comfunc global ITAddress2_get_PreferredPhones       25 var
#comfunc global ITAddress2_EnumeratePreferredPhones  26 sptr
#comfunc global ITAddress2_get_EventFilter           27 int,int,var
#comfunc global ITAddress2_put_EventFilter           28 int,int,int
#comfunc global ITAddress2_DeviceSpecific            29 sptr,var,int
#comfunc global ITAddress2_DeviceSpecificVariant     30 sptr,int
#comfunc global ITAddress2_NegotiateExtVersion       31 int,int,var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。
; ※IDispatch 実装。HSP では comobj 経由でメソッド名による呼び出しも可能(vtbl 不要)。#define global IID_ITAddress2 "{B0AE5D9B-BE51-46C9-B0F7-DFA8A22A8BC4}"
#usecom global ITAddress2 IID_ITAddress2 "{}"
#comfunc global ITAddress2_get_Phones                22 sptr
#comfunc global ITAddress2_EnumeratePhones           23 sptr
#comfunc global ITAddress2_GetPhoneFromTerminal      24 sptr,sptr
#comfunc global ITAddress2_get_PreferredPhones       25 sptr
#comfunc global ITAddress2_EnumeratePreferredPhones  26 sptr
#comfunc global ITAddress2_get_EventFilter           27 int,int,sptr
#comfunc global ITAddress2_put_EventFilter           28 int,int,int
#comfunc global ITAddress2_DeviceSpecific            29 sptr,sptr,int
#comfunc global ITAddress2_DeviceSpecificVariant     30 sptr,int
#comfunc global ITAddress2_NegotiateExtVersion       31 int,int,sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。
; ※IDispatch 実装。HSP では comobj 経由でメソッド名による呼び出しも可能(vtbl 不要)。