ホーム › Devices.Tapi › ITAgent

ITAgent

COMIDispatch (デュアル)

📘 Microsoft Learn (日本語) · English

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

IID5770ece5-4b27-11d1-bf80-00805fc147d3継承元IDispatch呼び出し名前(IDispatch) または vtbl自前メソッド開始 vtbl7

公式ドキュメント

ITAgent インターフェイス (tapi3cc.h) は、着信コールを受け取って処理し、顧客や見込み客に対して発信コールを行う Agent オブジェクトを扱います。

メソッド 17

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

vtbl 7 HRESULT EnumerateAgentSessions(IEnumAgentSession** ppEnumAgentSession)

ITAgent::EnumerateAgentSessions メソッド (tapi3cc.h) は、現在のエージェントセッションを列挙します。

ppEnumAgentSession

IEnumAgentSession**

out

IEnumAgentSession エージェントセッション列挙子へのポインター。

戻り値

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

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

解説(Remarks)

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

vtbl 8 HRESULT CreateSession(ITACDGroup* pACDGroup, ITAddress* pAddress, ITAgentSession** ppAgentSession)

ITAgent::CreateSession メソッド (tapi3cc.h) は、入力された ACD グループとアドレスに対して新しいエージェントセッションを作成します。

pACDGroup	ITACDGroup*	inoptional	ITACDGroup インターフェイスへのポインター。
pAddress	ITAddress*	inoptional	ACD コールを受信できる ITAddress オブジェクトへのポインター。
ppAgentSession	ITAgentSession**	out	作成されたオブジェクトの ITAgentSession インターフェイスへのポインター。

戻り値

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

値	意味
S_OK	メソッドは成功しました。
E_POINTER	ppAgentSession パラメーターが有効なポインターではありません。
E_UNEXPECTED	対象のアドレスに対する回線を開くことに失敗しました。
E_INVALIDARG	pACDGroup または pAddress 引数が無効です。
E_OUTOFMEMORY	操作を実行するのに十分なメモリがありません。
TAPI_E_TIMEOUT	TAPI 3 DLL がタイムアウトしたため、操作は失敗しました。タイムアウト間隔は 2 分です。

解説(Remarks)

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

一部の電話環境では、セッションを開くために個人識別番号 (PIN) が必要です。 CreateSessionWithPIN を参照してください。

vtbl 9 HRESULT CreateSessionWithPIN(ITACDGroup* pACDGroup, ITAddress* pAddress, LPWSTR pPIN, ITAgentSession** ppAgentSession)

ITAgent::CreateSessionWithPIN メソッド (tapi3cc.h) は、入力された ACD グループとアドレスに対して、個人識別番号 (PIN) を使用して新しいエージェントセッションを作成します。

pACDGroup	ITACDGroup*	inoptional	ITACDGroup インターフェイスへのポインター。
pAddress	ITAddress*	inoptional	ACD コールを受信できるオブジェクトの ITAddress インターフェイスへのポインター。
pPIN	LPWSTR	in	エージェントの PIN を表す BSTR へのポインター。
ppAgentSession	ITAgentSession**	out	作成されたセッションへのポインター。

戻り値

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

値	意味
S_OK	メソッドは成功しました。
TAPI_E_CALLCENTER_NO_AGENT_ID	エージェントが CreateAgentWithID によって作成されていません。
TAPI_E_TIMEOUT	TAPI 3 DLL がタイムアウトしたため、操作は失敗しました。タイムアウト間隔は 2 分です。
E_INVALIDARG	pPIN が NULL です。
E_POINTER	pPIN または ppAgentSession パラメーターが有効なポインターではありません。
E_OUTOFMEMORY	操作を実行するのに十分なメモリがありません。

解説(Remarks)

アプリケーションは、 SysAllocString を使用して pPIN 用のメモリを割り当て、変数が不要になったときには SysFreeString を使用してそのメモリを解放する必要があります。

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

vtbl 10 HRESULT get_ID(LPWSTR* ppID)

ITAgent::get_ID メソッド (tapi3cc.h) は、エージェントの ID を取得します。

ppID

LPWSTR*

out

エージェント ID を格納する BSTR へのポインター。

戻り値

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

リターンコード	説明
S_OK	メソッドは成功しました。
TAPI_E_CALLCENTER_NO_AGENT_ID	ITAgent が ITAgentHandler::CreateAgentWithID ではなく ITAgentHandler::CreateAgent を使用して作成されました。ID は存在しません。
E_POINTER	ppID パラメーターが有効なポインターではありません。
E_OUTOFMEMORY	操作を実行するのに十分なメモリがありません。

解説(Remarks)

このメソッドは、従来の交換機ソリューションと連携するために提供されています。

アプリケーションは、変数が不要になったときに、 SysFreeString を使用して ppID パラメーターに割り当てられたメモリを解放する必要があります。

vtbl 11 HRESULT get_User(LPWSTR* ppUser)

ITAgent::get_User メソッド (tapi3cc.h) は、エージェントのユーザー名を取得します。これは、オペレーティングシステムのユーザーログインまたは電子メール名と同じです。

ppUser

LPWSTR*

out

ユーザー名を格納する BSTR へのポインター。

戻り値

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

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

解説(Remarks)

アプリケーションは、変数が不要になったときに、 SysFreeString を使用して ppUser パラメーターに割り当てられたメモリを解放する必要があります。

vtbl 12 HRESULT put_State(AGENT_STATE AgentState)

ITAgent::put_State メソッド (tapi3cc.h) は、エージェントセッションの状態を設定します。

AgentState

AGENT_STATE

AGENT_STATE。

戻り値

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

リターンコード	説明
S_OK	メソッドは成功しました。
E_INVALIDARG	エージェントセッションの状態が正しくありません。
E_OUTOFMEMORY	操作を実行するのに十分なメモリがありません。
TAPI_E_TIMEOUT	TAPI 3 DLL がタイムアウトしたため、操作は失敗しました。タイムアウト間隔は 2 分です。

解説(Remarks)

ITAgent::put_State メソッドは、TAPI 2.1 の lineSetAgentStateEx 関数の COM ラッパーです。

vtbl 13 HRESULT get_State(AGENT_STATE* pAgentState)

ITAgent::get_State メソッド (tapi3cc.h) は、エージェントセッションの状態を取得します。

pAgentState

AGENT_STATE*

out

AGENT_STATE へのポインター。

戻り値

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

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

vtbl 14 HRESULT put_MeasurementPeriod(INT lPeriod)

ITAgent::put_MeasurementPeriod メソッド (tapi3cc.h) は、交換機や実装が情報を保存して計算する期間 (秒単位) を設定します。

lPeriod

INT

測定期間 (秒単位)。

戻り値

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

リターンコード	説明
S_OK	メソッドは成功しました。
E_INVALIDARG	lPeriod の値が 0 です。
E_OUTOFMEMORY	操作を実行するのに十分なメモリがありません。
LINEERR_	この TAPI 2.1 関数から返されるエラーコードについては、 lineSetAgentMeasurementPeriod を参照してください。

解説(Remarks)

ITAgent::put_MeasurementPeriod メソッドは、TAPI 2.1 の lineSetAgentMeasurementPeriod 関数の COM ラッパーです。

このメソッドは測定期間として負の値も受け付けますが、通常はその結果として統計が信頼できないものになります。

vtbl 15 HRESULT get_MeasurementPeriod(INT* plPeriod)

ITAgent::get_MeasurementPeriod メソッド (tapi3cc.h) は、交換機や実装が情報を保存して計算する測定期間を取得します。

plPeriod

INT*

out

測定期間。

戻り値

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

リターンコード	説明
S_OK	メソッドは成功しました。
E_POINTER	plPeriod パラメーターが有効なポインターではありません。
E_OUTOFMEMORY	操作を実行するのに十分なメモリがありません。
TAPI_E_TIMEOUT	TAPI 3 DLL がタイムアウトしたため、操作は失敗しました。タイムアウト間隔は 2 分です。

vtbl 16 HRESULT get_OverallCallRate(CY* pcyCallrate)

ITAgent::get_OverallCallRate メソッド (tapi3cc.h) は、すべてのセッションにわたるエージェントのコールレートを取得します。

pcyCallrate

CY*

out

コールレート。

戻り値

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

リターンコード	説明
S_OK	メソッドは成功しました。
E_POINTER	pcyCallrate パラメーターが有効なポインターではありません。
E_OUTOFMEMORY	操作を実行するのに十分なメモリがありません。
TAPI_E_TIMEOUT	TAPI 3 DLL がタイムアウトしたため、操作は失敗しました。タイムアウト間隔は 2 分です。

解説(Remarks)

ここでは、Visual Basic および Java との互換性のために、FLOAT ではなく CURRENCY 型が使用されます。

vtbl 17 HRESULT get_NumberOfACDCalls(INT* plCalls)

ITAgent::get_NumberOfACDCalls メソッド (tapi3cc.h) は、すべてのセッションにわたってこのエージェントが処理した ACD コールの数を取得します。

plCalls

INT*

out

コールの総数。

戻り値

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

リターンコード	説明
S_OK	メソッドは成功しました。
E_POINTER	plCalls パラメーターが有効なポインターではありません。
E_OUTOFMEMORY	操作を実行するのに十分なメモリがありません。
TAPI_E_TIMEOUT	TAPI 3 DLL がタイムアウトしたため、操作は失敗しました。タイムアウト間隔は 2 分です。

vtbl 18 HRESULT get_NumberOfIncomingCalls(INT* plCalls)

ITAgent::get_NumberOfIncomingCalls メソッド (tapi3cc.h) は、このエージェントが処理した非 ACD 着信コールの数を取得します。

plCalls

INT*

out

着信コールの総数。

戻り値

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

リターンコード	説明
S_OK	メソッドは成功しました。
E_POINTER	plCalls パラメーターが有効なポインターではありません。
E_OUTOFMEMORY	操作を実行するのに十分なメモリがありません。
TAPI_E_TIMEOUT	TAPI 3 DLL がタイムアウトしたため、操作は失敗しました。タイムアウト間隔は 2 分です。

vtbl 19 HRESULT get_NumberOfOutgoingCalls(INT* plCalls)

ITAgent::get_NumberOfOutgoingCalls メソッド (tapi3cc.h) は、このエージェントが処理した非 ACD 発信コールの数を取得します。

plCalls

INT*

out

発信コールの総数。

戻り値

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

リターンコード	説明
S_OK	メソッドは成功しました。
E_POINTER	plCalls パラメーターが有効なポインターではありません。
E_OUTOFMEMORY	操作を実行するのに十分なメモリがありません。
TAPI_E_TIMEOUT	TAPI 3 DLL がタイムアウトしたため、操作は失敗しました。タイムアウト間隔は 2 分です。

vtbl 20 HRESULT get_TotalACDTalkTime(INT* plTalkTime)

ITAgent::get_TotalACDTalkTime メソッド (tapi3cc.h) は、すべてのセッションにわたってこのエージェントが ACD コールでの通話に費やした秒数を取得します。

plTalkTime

INT*

out

通話時間の合計。

戻り値

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

リターンコード	説明
S_OK	メソッドは成功しました。
E_POINTER	plTalkTime パラメーターが有効なポインターではありません。
E_OUTOFMEMORY	操作を実行するのに十分なメモリがありません。
TAPI_E_TIMEOUT	TAPI 3 DLL がタイムアウトしたため、操作は失敗しました。タイムアウト間隔は 2 分です。

vtbl 21 HRESULT get_TotalACDCallTime(INT* plCallTime)

ITAgent::get_TotalACDCallTime メソッド (tapi3cc.h) は、すべてのセッションにわたってこのエージェントが ACD コールに費やした秒数を取得します。

plCallTime

INT*

out

コール時間の合計。

戻り値

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

リターンコード	説明
S_OK	メソッドは成功しました。
E_POINTER	plCallTime パラメーターが有効なポインターではありません。
E_OUTOFMEMORY	操作を実行するのに十分なメモリがありません。
TAPI_E_TIMEOUT	TAPI 3 DLL がタイムアウトしたため、操作は失敗しました。タイムアウト間隔は 2 分です。

vtbl 22 HRESULT get_TotalWrapUpTime(INT* plWrapUpTime)

ITAgent::get_TotalWrapUpTime メソッド (tapi3cc.h) は、すべてのセッションにわたってこのエージェントが ACD コールのラップアップに費やした秒数を取得します。

plWrapUpTime

INT*

out

ラップアップ時間の合計。

戻り値

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

リターンコード	説明
S_OK	メソッドは成功しました。
E_POINTER	plWrapUpTime パラメーターが有効なポインターではありません。
E_OUTOFMEMORY	操作を実行するのに十分なメモリがありません。
TAPI_E_TIMEOUT	TAPI 3 DLL がタイムアウトしたため、操作は失敗しました。タイムアウト間隔は 2 分です。

vtbl 23 HRESULT get_AgentSessions(VARIANT* pVariant)

ITAgent::get_AgentSessions メソッド (tapi3cc.h) は、現在のエージェントセッションのコレクションを作成します。

pVariant

VARIANT*

out

ITAgentSession インターフェイスポインター (エージェントセッションオブジェクト) の ITCollection を格納する VARIANT へのポインター。

戻り値

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

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

解説(Remarks)

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

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_ITAgent "{5770ECE5-4B27-11D1-BF80-00805FC147D3}"
#usecom global ITAgent IID_ITAgent "{}"
#comfunc global ITAgent_EnumerateAgentSessions     7 sptr
#comfunc global ITAgent_CreateSession              8 sptr,sptr,sptr
#comfunc global ITAgent_CreateSessionWithPIN       9 sptr,sptr,wstr,sptr
#comfunc global ITAgent_get_ID                     10 var
#comfunc global ITAgent_get_User                   11 var
#comfunc global ITAgent_put_State                  12 int
#comfunc global ITAgent_get_State                  13 var
#comfunc global ITAgent_put_MeasurementPeriod      14 int
#comfunc global ITAgent_get_MeasurementPeriod      15 var
#comfunc global ITAgent_get_OverallCallRate        16 var
#comfunc global ITAgent_get_NumberOfACDCalls       17 var
#comfunc global ITAgent_get_NumberOfIncomingCalls  18 var
#comfunc global ITAgent_get_NumberOfOutgoingCalls  19 var
#comfunc global ITAgent_get_TotalACDTalkTime       20 var
#comfunc global ITAgent_get_TotalACDCallTime       21 var
#comfunc global ITAgent_get_TotalWrapUpTime        22 var
#comfunc global ITAgent_get_AgentSessions          23 var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。
; ※IDispatch 実装。HSP では comobj 経由でメソッド名による呼び出しも可能(vtbl 不要)。#define global IID_ITAgent "{5770ECE5-4B27-11D1-BF80-00805FC147D3}"
#usecom global ITAgent IID_ITAgent "{}"
#comfunc global ITAgent_EnumerateAgentSessions     7 sptr
#comfunc global ITAgent_CreateSession              8 sptr,sptr,sptr
#comfunc global ITAgent_CreateSessionWithPIN       9 sptr,sptr,wstr,sptr
#comfunc global ITAgent_get_ID                     10 sptr
#comfunc global ITAgent_get_User                   11 sptr
#comfunc global ITAgent_put_State                  12 int
#comfunc global ITAgent_get_State                  13 sptr
#comfunc global ITAgent_put_MeasurementPeriod      14 int
#comfunc global ITAgent_get_MeasurementPeriod      15 sptr
#comfunc global ITAgent_get_OverallCallRate        16 sptr
#comfunc global ITAgent_get_NumberOfACDCalls       17 sptr
#comfunc global ITAgent_get_NumberOfIncomingCalls  18 sptr
#comfunc global ITAgent_get_NumberOfOutgoingCalls  19 sptr
#comfunc global ITAgent_get_TotalACDTalkTime       20 sptr
#comfunc global ITAgent_get_TotalACDCallTime       21 sptr
#comfunc global ITAgent_get_TotalWrapUpTime        22 sptr
#comfunc global ITAgent_get_AgentSessions          23 sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。
; ※IDispatch 実装。HSP では comobj 経由でメソッド名による呼び出しも可能(vtbl 不要)。