この製品のマニュアルセットは、偏向のない言語を使用するように配慮されています。このマニュアルセットでの偏向のない言語とは、年齢、障害、性別、人種的アイデンティティ、民族的アイデンティティ、性的指向、社会経済的地位、およびインターセクショナリティに基づく差別を意味しない言語として定義されています。製品ソフトウェアのユーザーインターフェイスにハードコードされている言語、RFP のドキュメントに基づいて使用されている言語、または参照されているサードパーティ製品で使用されている言語によりドキュメントに例外が存在する場合があります。シスコのインクルーシブランゲージに対する取り組みの詳細は、こちらをご覧ください。
このドキュメントは、米国シスコ発行ドキュメントの参考和訳です。リンク情報につきましては、日本語版掲載時点で、英語版にアップデートがあり、リンク先のページが移動/変更されている場合がありますことをご了承ください。あくまでも参考和訳となりますので、正式な内容については米国サイトのドキュメントを参照ください。
この章では、Cisco Unified TAPI サービス プロバイダー(TSP)でサポートされている、TAPI 2.1 の関数、イベントおよびメッセージの概要を説明します。この章では、次の項で関数を説明します。
TAPI は、Cisco Unified Communications ソリューションの機能を利用するための、一連のクラスによって構成されています。TAPI を利用すると、Cisco Unified Communications Manager とサービス プロバイダーの間の通信プロトコルに関する特別な知識がなくても、Cisco Unified Communications Manager 用にカスタマイズした IP テレフォニー アプリケーションを開発できます。たとえば、外部の音声メッセージング システムと通信する TAPI アプリケーションを開発することができます。
使用可能な回線数は、Cisco Unified Communications Manager で設定した TAPI デバイス数で決まります。Cisco Media Driver を使用して、ファーストパーティ呼制御モデルのメディア ストリームを終了させます。
LONG lineAccept(HCALL hCall, LPCSTR lpsUserUserInfo, DWORD dwSize );
受け入れるコールのハンドル。アプリケーションは、このコールのオーナーになっている必要があります。有効な hCall のコール状態は、offering です。
コール受け入れ時にリモート側へ送信されるユーザ間情報を格納している文字列へのポインタです。ユーザ間情報を送信したくない場合は、このポインタを NULL にしておきます。ユーザ間情報は、基盤となるネットワークでサポートされている場合にだけ送信されます。ユーザ間情報のプロトコル識別メンバが必要な場合は、lpsUserUserInfo がポイントするバッファの先頭バイトを使用し、これを dwSize に算入する必要があります。
(注) | Cisco Unified TSP は、ユーザ間情報をサポートしていません。 |
lpsUserUserInfo 内のユーザ間情報のサイズ(バイト単位)。lpsUserUserInfo が NULL の場合は、発呼側にユーザ間情報が送信されないため、dwSize は無視されます。
lineAddProvider 関数は、テレフォニー システム内に新規のテレフォニー サービス プロバイダーをインストールします。
LONG WINAPI lineAddProvider( LPCSTR lpszProviderFilename, HWND hwndOwner, LPDWORD lpdwPermanentProviderID );
追加するサービス プロバイダーのパスを格納している NULL 終端文字列へのポインタ。
(サービス プロバイダーの TSPI_providerInstall 関数などによる)インストール処理中に表示されるダイアログボックスに関連付けるウィンドウのハンドル。関数の実行中に生成されるウィンドウを特定のオーナー ウィンドウに関連付ける必要がない場合は、NULL にしておくことができます。
新規にインストールされたサービス プロバイダーの固定プロバイダー ID を TAPI が書き込むメモリ位置(DWORD サイズ)へのポインタ。
この関数は、hConsultCall で指定されたコンサルト コールを受け取り、hConfCall で指定された電話会議にそのコールを追加します。
LONG lineAddToConference( HCALL hConfCall, HCALL hConsultCall );
電話会議ハンドルへのポインタ。この電話会議の状態は、OnHoldPendingConference または OnHold になっている必要があります。
電話会議に追加するコンサルト コールへのポインタ。アプリケーションは、このコールのオーナーになっている必要があります。また、このコールを他の電話会議のメンバーにはできません。このコンサルト コールの状態は、connected、onHold、proceeding、または ringback になっている必要があります。
lineAnswer 関数は、指定されたオファー中のコールに応答します。
(注) | CallProcessing では、デバイス上にすでに存在するコールが Connected 状態になっていないと、同じデバイスで新しいコールに応答できません。同じデバイス上にすでに存在するコールの状態を確認せずにコールに応答した場合でも、Cisco Unified TSP から正常な応答が返されることがありますが、そのコールは Connected 状態にならないため、再度応答する必要があります。 |
LONG lineAnswer( HCALL hCall, LPCSTR lpsUserUserInfo, DWORD dwSize );
応答するコールのハンドル。アプリケーションは、このコールのオーナーになっている必要があります。有効な hCall のコール状態は、offering または accepted です。
コールへの応答時にリモート側へ送信されるユーザ間情報を格納している文字列へのポインタ。送信するユーザ間情報がない場合は、このポインタを NULL にしておくことができます。
ユーザ間情報は、基盤となるネットワークでサポートされている場合にだけ送信されます。ユーザ間情報のプロトコル識別フィールドが必要な場合は、lpsUserUserInfo がポイントするバッファの先頭バイトを使用し、これを dwSize に算入する必要があります。
(注) | Cisco Unified TSP は、ユーザ間情報をサポートしていません。 |
lpsUserUserInfo 内のユーザ間情報のサイズ(バイト単位)。lpsUserUserInfo が NULL の場合は、発呼側にユーザ間情報が送信されないため、dwSize は無視されます。
lineBlindTransfer 関数は、指定されたコールを指定された宛先アドレスにブラインド転送(シングル ステップ転送)します。
(注) | Cisco Unified TSP 3.3 以前のバージョンに実装されている lineBlindTransfer 関数は、TAPI 仕様に準拠していません。この関数は、実際には、シングル ステップ転送としてではなく、打診転送として実装されています。Cisco Unified TSP 4.0 以降の lineBlindTransfer では、転送がシングル ステップで行われるという点において、TAPI 仕様に準拠しています。 |
lineBlindTransfer 関数を使用して、FAC、CMC、またはその両方を必要とするアドレスにコールをブラインド転送しようとすると、エラーが返されます。FAC が必要な場合は、TSP から LINEERR_FACREQUIRED エラーが返されます。CMC が必要な場合は、TSP から LINEERR_CMCREQUIRED エラーが返されます。FAC と CMC の両方が必要な場合は、TSP から LINEERR_FACANDCMCREQUIRED エラーが返されます。FAC、CMC、またはその両方を必要とするアドレスにコールをブラインド転送する場合は、lineDevSpecific -BlindTransferFACCMC 関数を使用する必要があります。
LONG lineBlindTransfer( HCALL hCall, LPCSTR lpszDestAddress, DWORD dwCountryCode );
転送するコールのハンドル。アプリケーションは、このコールのオーナーになっている必要があります。有効な hCall のコール状態は、connected です。
コールの転送先を識別する NULL 終端文字列へのポインタ。宛先アドレスの指定には、標準のダイヤル番号形式を使用します。
宛先の国番号。このパラメータは、その宛先アドレスに適したコール プログレス プロトコルを選択するために使用されます。0 を指定すると、デフォルトのコール プログレス プロトコルが使用されます。
VOID FAR PASCAL lineCallbackFunc( DWORD hDevice, DWORD dwMsg, DWORD dwCallbackInstance, DWORD dwParam1, DWORD dwParam2, DWORD dwParam3 );
コールバックに関連付けられた回線デバイスまたはコールのハンドル。その dwMsg が提供するコンテキストは、このハンドルの特性(回線ハンドル、またはコール ハンドル)を決定します。HANDLE 型を使用するとエラーが発生する可能性があるため、このパラメータには DWORD 型を使用する必要があります。
回線またはコール デバイスのメッセージ。
コールバックでアプリケーションに返されたコールバック インスタンス データ。TAPI は DWORD を解釈しません。
メッセージのパラメータ。
メッセージのパラメータ。
メッセージのパラメータ。
この関数に渡されるパラメータ値については、「TAPI 回線関数」を参照してください。
LONG lineClose( HLINE hLine );
クローズする回線デバイスのハンドル。回線が正常にクローズされると、このハンドルは無効になります。
LONG lineCompleteTransfer( HCALL hCall, HCALL hConsultCall, LPHCALL lphConfCall, DWORD dwTransferMode );
転送するコールのハンドル。アプリケーションは、このコールのオーナーになっている必要があります。有効な hCall のコール状態は、onHold、onHoldPendingTransfer です。
転送先との接続を表すコールのハンドル。アプリケーションは、このコールのオーナーになっている必要があります。有効な hConsultCall のコール状態は、connected、ringback、busy、または proceeding です。
hCall ハンドルを返すことができるメモリ位置へのポインタ。dwTransferMode が LINETRANSFERMODE_CONFERENCE の場合は、新規作成された電話会議が lphConfCall に返され、アプリケーションがその電話会議の唯一のオーナーになります。それ以外の場合、TAPI はこのパラメータを無視します。
発行された転送要求の解決方法を指定します。このパラメータには、次の LINETRANSFERMODE_定数が入ります。
lineConfigProvider 関数を呼び出すと、サービス プロバイダーの設定ダイアログボックスが表示されます。この関数は基本的に、TSPI_providerConfig への単純なパススルーを提供します。
LONG WINAPI lineConfigProvider( HWND hwndOwner, DWORD dwPermanentProviderID );
(TSPI_providerConfig によって表示される)設定ダイアログボックスに関連付けるウィンドウのハンドル。関数の実行中に生成されるウィンドウを特定のオーナー ウィンドウに関連付ける必要がないことを表すために、このパラメータを NULL にすることができます。
設定するサービス プロバイダーの固定プロバイダー ID。
LONG lineDeallocateCall( HCALL hCall );
割り当てを解除するコール ハンドル。コールに対してモニタ特権を持っているアプリケーションは、そのコールへのハンドル割り当てをいつでも解除できます。コールに対してオーナー特権を持っているアプリケーションは、そのコールの唯一のオーナーではなく、そのコールがアイドル状態ではない場合にだけハンドルの割り当てを解除できます。割り当てを解除されると、コール ハンドルは無効になります。
lineDevSpecific 関数を使用すると、サービス プロバイダーは、他の TAPI 関数では提供されていない機能にアクセスできます。機能拡張はデバイス固有のものであり、拡張機能を利用するには、アプリケーションが拡張機能を読み込み可能である必要があります。
Cisco Unified TSP では、lineDevSpecific を使用して次の機能を実現できます。
特定の回線のメッセージ受信ランプをオンにする。
(シスコ提供の Wave ドライバを使用せずに)オーディオ ストリームを処理する。
特定の回線に関するメディア ストリーム メッセージのレポートをオンまたはオフにする。
動的メディアの終端に使用する CTI ポートまたはルート ポイントを登録する。
動的メディアの終端の CTI ポートまたはルート ポイントにあるコールの IP アドレスと UDP ポートを設定する。
コールをリダイレクトし、そのコールの OriginalCalledID をリダイレクト先の通話者にリセットする。
コールをリダイレクトし、そのコールの OriginalCalledID を任意の通話者に設定する。
2 つ以上のコールを 1 つの電話会議に加入させる。
FAC、CMC、またはその両方が必要となる宛先にコールをリダイレクトする。
FAC、CMC、またはその両方が必要となる宛先にコールをブラインド転送する。
サードパーティ モードで CTI ポートをオープンする。
CTI ポートでサポートされている SRTP アルゴリズム ID を設定する。
スーパー プロバイダー モードでオープンする必要がある、Cisco Unified Communications Manager システム内の CTI 対応デバイスを取得する。
Cisco Unified Communications Manager システム内の CTI 対応デバイスの取得解除を行う。
実際の回線オープンを TSP 側から起動する。この方法は、時間差を付けて回線をオープンする場合に便利です。
インターコム回線のインターコム ウィスパー コールで応答(TalkBack)を開始する。
インターコム回線のスピード ダイヤルおよびラベル設定を問い合わせる。
インターコム回線のスピード ダイヤルおよびラベル設定を設定する。
コールのモニタリングを開始する
コールの録音を開始する
コールの録音を停止する
機能プライオリティが設定された直接コール(詳細は、「セキュアな会議」を参照してください)。
メディアなしで転送する
直接転送
メッセージの概要
(注) | Cisco Unified TSP Release 4.0 以降では、同じ回線上の 2 つのコール(CONNECTED 状態のコールと ONHOLD 状態のコール)の SwapHold および SetupTransfer を実行できなくなっています。したがって、これらのコールは lineCompleteTransfer を使用して転送できます。Cisco Unified TSP Release 4.0 以降では、SwapHold および SetupTransfer を事前に実行しなくても、lineCompleteTransfer 関数を使用してこれらのコールを転送できます。 |
LONG lineDevSpecific( HLINE hLine, DWORD dwAddressID, HCALL hCall, LPVOID lpParams, DWORD dwSize );
回線デバイスのハンドル。このパラメータは必須です。
指定された回線デバイスのアドレス ID。
コールのハンドル。このパラメータは省略可能ですが、このパラメータが指定された場合、そのコールは hLine の回線デバイスに属している必要があります。hCall のコール状態は、デバイス固有です。
パラメータ ブロックを格納するメモリ領域へのポインタ。このパラメータ ブロックの形式は、デバイス固有の形式を指定します。このパラメータ ブロックの内容は、TAPI とサービス プロバイダーの間で送受信されます。
パラメータ ブロック領域のサイズ(バイト単位)。
lineDevSpecificFeature 関数を使用すると、サービス プロバイダーは、他の TAPI 関数では提供されていない機能にアクセスできます。機能拡張はデバイス固有のものであり、拡張機能を利用するには、アプリケーションが拡張機能を読み込み可能である必要があります。Cisco TSP では、lineDevSpecificFeature を使用して、デバイス上でサイレント機能を有効または無効にすることができます。
LONG lineDevSpecificFeature(HLINE hLine, DWORD dwFeature, LPVOID lpParams, DWORD dwSize );
回線デバイスのハンドル。このパラメータは必須です。
回線デバイス上で呼び出す機能。このパラメータには、次に示す PHONEBUTTONFUNCTION_TAPI 定数が入ります。Cisco TSP では、有効と見なされる値は PHONEBUTTONFUNCTION_DONOTDISTURB (0x0000001A) だけです。
パラメータ ブロックを格納するメモリ領域へのポインタ。このパラメータ ブロックは、デバイス固有の形式です。このパラメータ ブロックの内容は、TAPI とサービス プロバイダーの間で送受信されます。
パラメータ ブロック領域のサイズ(バイト単位)。
関数が非同期的に完了した場合は、正の要求 ID が返されます。エラーが発生した場合は、負の番号が返されます。対応する LINE_REPLY メッセージの dwParam2 パラメータは、関数が成功するとゼロ、エラーが発生すると負の番号になります。
lineDial 関数は、指定されたコールを使用して、指定された番号をダイヤルします。
アプリケーションはこの関数を使用して FAC または CMC を入力できます。FAC または CMC は、1 度に 1 桁ずつ入力することも複数の桁を同時に入力することもできます。また、必要な場合は、1 つの lineDial() 要求で FAC と CMC の両方を入力することもできます。その場合は、FAC と CMC を「#」文字で区切ります。FAC と CMC の両方を 1 つの lineDial() 要求で送信する場合は、T.302 タイマーがタイムアウトになるまでアプリケーションが待機することを防ぐために、lpszDestAddress の末尾に「#」文字を入力することをお勧めします。
この関数を使用して、FAC、CMC、またはその両方と一緒にダイヤル文字列を入力することはできません。FAC、CMC、またはその両方を入力するには、別の lineDial 要求を使用する必要があります。
LONG lineDial( HCALL hCall, LPCSTR lpszDestAddress, DWORD dwCountryCode );
番号をダイヤルするコールのハンドル。アプリケーションは、このコールのオーナーになっている必要があります。有効な hCall のコール状態は、idle と disconnected を除くすべての状態です。
ダイヤルする宛先(標準のダイヤル番号形式を使用)。
宛先の国番号。このコードは、その宛先アドレスに適したコール プログレス プロトコルを選択するために使用されます。0 を指定すると、デフォルトのコール プログレス プロトコルが使用されます。
lineDrop 関数は、指定されたコールをドロップ(接続解除)します。アプリケーションは、コールの接続を解除する際に送信されるユーザ間情報を指定できます。
LONG lineDrop( HCALL hCall, LPCSTR lpsUserUserInfo, DWORD dwSize );
ドロップするコールのハンドル。アプリケーションは、このコールのオーナーになっている必要があります。有効な hCall のコール状態は、idle を除くすべての状態です。
コールの接続解除時にリモート側へ送信されるユーザ間情報を格納する文字列へのポインタ。送信するユーザ間情報がない場合は、このポインタを NULL にしておくことができます。ユーザ間情報は、基盤となるネットワークでサポートされている場合にだけ送信されます。ユーザ間情報のプロトコル識別フィールドが必要な場合は、lpsUserUserInfo がポイントするバッファの先頭バイトを使用し、これを dwSize に算入する必要があります。
(注) | Cisco Unified TSP は、ユーザ間情報をサポートしていません。 |
lpsUserUserInfo 内のユーザ間情報のサイズ(バイト単位)。lpsUserUserInfo が NULL の場合は、発呼側にユーザ間情報が送信されないため、dwSize は無視されます。
lineForward 関数は、指定された回線の指定されたアドレスに宛てて発信されたコールを、指定された方法に基づいて転送します。発信元アドレス(dwAddressID)が転送されると、そのアドレスに着信した特定のコールが交換機によって他の番号へ転送されます。この関数では、不在転送機能の組み合わせを使用することができます。この API を使用すると、無条件にコールを転送できます。この関数は、現在有効な転送をキャンセルすることもできます。
lineForward が完了すると、TAPI から LINEADDRESSSTATE イベントが発行されます。このイベントは、転送設定が有効または無効になったことにより、回線の転送ステータスが変化したことを示します。
lineForward を呼び出して転送先を変更する場合、その回線の現在の転送をキャンセルする必要はありません。
(注) | Cisco Unified TSP の lineForward 実装で設定できる転送方式は、dwForwardMode = UNCOND の 1 種類だけです。lpLineForwardList データ構造体に、dwForwardMode = UNCOND と指定された LINEFORWARD エントリが格納されます。 |
LONG lineForward( HLINE hLine, DWORD bAllAddresses, DWORD dwAddressID, LPLINEFORWARDLIST const lpForwardList, DWORD dwNumRingsNoAnswer, LPHCALL lphConsultCall, LPLINECALLPARAMS const lpCallParams );
回線デバイスのハンドル。
回線上のすべてのアドレスからの転送を有効にするか、指定された 1 つのアドレスからの転送だけを有効にするかを指定します。TRUE の場合は、回線上のすべてのアドレスからの転送が有効になり、dwAddressID は無視されます。FALSE の場合は、dwAddressID で指定されたアドレスからの転送だけが有効になります。
着信コールが転送される指定された回線のアドレス。bAllAddresses が TRUE の場合、このパラメータは無視されます。
(注) | bAllAddresses が FALSE の場合は dwAddressID を 0 にする必要があります。 |
LINEFORWARDLIST 型の詳細な転送指示が記述された可変サイズ データ構造体へのポインタ。
(注) | 現在有効な転送をキャンセルするには、lpForwardList パラメータを NULL に設定します。 |
応答なしと見なすまでの呼び出し音の回数。dwNumRingsNoAnswer に有効範囲外の値が指定されている場合は、有効範囲内でその値に最も近い値に設定されます。
(注) | このバージョンの Cisco Unified TSP では、無応答時コール転送がサポートされていないため、このパラメータは使用されません。 |
HCALL 位置へのポインタ。一部のテレフォニー環境では、転送先を調査するために使用されるコンサルト コールのハンドルがこの位置に読み込まれ、当初はそのアプリケーションがこのコールの唯一のオーナーになります。コール転送にコンサルト コールを必要としない環境であっても、このポインタは有効である必要があります。コンサルト コールが確立されない場合、このハンドルは NULL に設定されます。
(注) | また、lineForward のセットアップではコンサルト コールが確立されないので、このパラメータは無視されます。 |
LINECALLPARAMS 型の構造体へのポインタ。lineForward によって転送先へのコールの確立が要求されない場合(lphConsultCall が返されない場合)、このパラメータは無視されます(その場合、lpCallParams は省略可能です)。NULL の場合は、デフォルトのコール パラメータが使用されます。コール パラメータが指定されている場合は、hConsultCall を確立する際にそれらのパラメータが使用されます。
(注) | 現バージョンの Cisco Unified TSP では、コンサルト コールを確立しないため、このパラメータは NULL にする必要があります。 |
要求が成功した場合はゼロを返し、エラーが発生した場合は負の番号を返します。戻り値には次の値があります。
LINEERR_INVALLINEHANDLE
LINEERR_NOMEM
LINEERR_INVALADDRESSID
LINEERR_OPERATIONUNAVAIL
LINEERR_INVALADDRESS
LINEERR_OPERATIONFAILED
LINEERR_INVALCOUNTRYCODE
LINEERR_RESOURCEUNAVAIL
LINEERR_INVALPOINTER
LINEERR_STRUCTURETOOSMALL
LINEERR_INVALPARAM
LINEERR_UNINITIALIZED
(注) | lpForwardList[0].dwForwardMode が UNCOND 以外の場合、lineForward は LINEERR_OPERATIONUNAVAIL を返します。lpForwardList.dwNumEntries が 1 より大きい場合、lineForward は LINEERR_INVALPARAM を返します。 |
lineGenerateDigits 関数は、指定されたシグナリング モードを使用して、指定された桁を指定されたコール上にアウトオブバンド トーンとして生成します。
LONG lineGenerateDigits( HCALL hCall, DWORD dwDigitMode, LPCSTR lpszDigits, DWORD dwDuration );
コールのハンドル。アプリケーションは、このコールのオーナーになっている必要があります。hCall のコール状態は、すべての状態です。
これらの桁生成に使用する形式。dwDigitMode に格納できるフラグ セットは 1 つだけです。このパラメータには、次の LINEDIGITMODE_定数が入ります。
lineGenerateTone 関数は、指定されたコール上に指定されたトーンを生成します。
(注) | Cisco Unified TSP では、dwToneMode の値を 0 にしてこの関数を呼び出しても、現在進行しているトーン生成は中止されません。また、トーン生成の進行中に lineGenerateTone を呼び出すこともできません。Cisco Unified IP Phone は、トーンをアウトオブバンドで伝送します。つまり、トーンはオーディオ ストリーム(インバンド)には挿入されず、制御ストリーム内のメッセージとして送信されます。トーンは、遠端の電話機によってオーディオ ストリームに挿入されて、ユーザに提示されます。また、一部のゲートウェイは、LAN の外に出るオーディオ ストリームにトーンを挿入しません。 |
LONG lineGenerateTone( HCALL hCall, DWORD dwToneMode, DWORD dwDuration, DWORD dwNumTones, LPLINEGENERATETONE const lpTones );
トーンを生成するコールのハンドル。アプリケーションは、このコールのオーナーになっている必要があります。有効な hCall のコール状態は、すべての状態です。
生成するトーンの定義。標準トーンおよびカスタム トーンのいずれかを使用できます。カスタム トーンは、任意の周波数のセットで構成されます。また、何種類かのトーンが標準トーンとして事前定義されています。標準トーン、カスタム トーンともに、トーンの継続時間は dwDuration で指定します。dwToneMode パラメータに格納できるビット セットは 1 つだけです。ビットが設定されていない場合(値 0 が渡される場合)は、トーン生成がキャンセルされます。
このパラメータには、次の LINETONEMODE_ 定数が入ります。
トーンの継続時間(ミリ秒単位)。
(注) | Cisco Unified TSP は、dwDuration をサポートしていません。 |
lpTones 配列内のエントリ数。dwToneMode が CUSTOM でない場合、このパラメータは無視されます。
トーンの構成要素を指定する LINEGENERATETONE 配列へのポインタ。カスタム トーンでない場合、このパラメータは無視されます。lpTones が多重周波数トーンの場合は、複数のトーンが同時に発音されます。
lineGetAddressCaps 関数は、指定された回線デバイス上の指定されたアドレスに対し、そのアドレスのテレフォニー機能を問い合わせます。
LONG lineGetAddressCaps( HLINEAPP hLineApp, DWORD dwDeviceID, DWORD dwAddressID, DWORD dwAPIVersion, DWORD dwExtVersion, LPLINEADDRESSCAPS lpAddressCaps );
アプリケーションを TAPI に登録するためのハンドル。
問い合わせ先のアドレスが存在する回線デバイス。1 回線につき 1 アドレスしかサポートされていないため、dwAddressID はゼロにする必要があります。
機能を問い合わせる指定された回線デバイス上のアドレス。
使用する API のバージョン番号(lineNegotiateAPIVersion で取得する)。上位の桁にはメジャー バージョン番号が入り、下位の桁にはマイナー バージョン番号が入ります。
使用する拡張のバージョン番号。デバイス固有拡張を使用しない場合は、ゼロにしておくことができます。そうでない場合は、上位の桁にメジャー バージョン番号が入り、下位の桁にマイナー バージョン番号が入ります。
LINEADDRESSCAPS 型の可変サイズ構造体へのポインタ。要求が正常に完了すると、この構造体にアドレスの機能情報が入ります。lineGetAddressCaps を呼び出す前に、この構造体の dwTotalSize メンバを設定しておく必要があります。このメンバは、返された情報を格納するために TAPI が使用できるメモリの量を指定します。
lineGetAddressID 関数は、指定された回線上の別形式のアドレスに関連付けられたアドレス ID を返します。
LONG lineGetAddressID( HLINE hLine, LPDWORD lpdwAddressID, DWORD dwAddressMode, LPCSTR lpsAddress, DWORD dwSize );
オープン状態の回線デバイスのハンドル。
アドレス ID を返すメモリ位置(DWORD サイズ)へのポインタ。
lpsAddress に格納されたアドレスのアドレス モード。dwAddressMode パラメータに格納できるフラグ セットは 1 つだけです。このパラメータには、次の LINEADDRESSMODE_ 定数が入ります。
指定された回線デバイスに割り当てられたアドレスが格納されているデータ構造体へのポインタ。dwAddressMode がアドレスの形式を決定します。有効な値は LINEADDRESSMODE_DIALABLEADDR だけです。したがって、lpsAddress は共通のダイヤル可能番号形式になり、NULL で終端されます。
lpsAddress に格納されたアドレスのサイズ。
lineGetAddressStatus 関数を使用すると、指定されたアドレスの現在のステータスを問い合わせることができます。
LONG lineGetAddressStatus( HLINE hLine, DWORD dwAddressID, LPLINEADDRESSSTATUS lpAddressStatus );
オープン状態の回線デバイスのハンドル。
指定されたオープン状態の回線デバイス上のアドレス。このパラメータは、問い合わせ先のアドレスを指定します。
LINEADDRESSSTATUS 型の可変サイズ データ構造体へのポインタ。lineGetAddressStatus を呼び出す前に、この構造体の dwTotalSize メンバを設定しておく必要があります。このメンバは、返された情報を格納するために TAPI が使用できるメモリの量を指定します。
LONG lineGetCallInfo( HCALL hCall, LPLINECALLINFO lpCallInfo );
問い合わせるコールのハンドル。有効な hCall のコール状態は、すべての状態です。
LINECALLINFO 型の可変サイズ データ構造体へのポインタ。要求が正常に完了すると、この構造体にコール関連情報が入ります。lineGetCallInfo を呼び出す前に、この構造体の dwTotalSize メンバを設定しておく必要があります。このメンバは、返された情報を格納するために TAPI が使用できるメモリの量を指定します。
LONG lineGetCallStatus( HCALL hCall, LPLINECALLSTATUS lpCallStatus );
問い合わせるコールのハンドル。有効な hCall のコール状態は、すべての状態です。
LINECALLSTATUS 型の可変サイズ データ構造体へのポインタ。要求が正常に完了すると、この構造体にコール ステータス情報が入ります。lineGetCallStatus を呼び出す前に、この構造体の dwTotalSize メンバを設定しておく必要があります。このメンバは、返された情報を格納するために TAPI が使用できるメモリの量を指定します。
lineGetConfRelatedCalls 関数は、指定されたコールと同じ電話会議に参加しているコール ハンドルのリストを返します。指定されるコールは、電話会議または電話会議に参加しているコールのいずれかに相当します。まだハンドルが割り当てられていないコールについては新しいハンドルが生成され、それらのコールに対するモニタ特権がアプリケーションに与えられます。
LONG WINAPI lineGetConfRelatedCalls( HCALL hCall, LPLINECALLLIST lpCallList );
コールのハンドル。これは、電話会議または電話会議に参加しているコールのいずれかに相当します。親の電話会議の場合、有効な hCall のコール状態はすべての状態になります。会議に参加しているコールの場合、有効なコール状態は conferenced 状態だけです。
LINECALLLIST 型の可変サイズ データ構造体へのポインタ。要求が正常に完了すると、電話会議に参加しているすべてのコールのコール ハンドルがこの構造体に返ります。このリストの最初のコールは電話会議で、その他のコールはこの電話会議に参加しているコールに相当します。このリストの中で、まだハンドルが割り当てられていないコールについては、アプリケーションにモニタ特権が与えられます。また、すでにハンドルが割り当てられているコールに対する特権はそのままです。lineGetConfRelatedCalls を呼び出す前に、この構造体の dwTotalSize メンバを設定しておく必要があります。このメンバは、返された情報を格納するために TAPI が使用できるメモリの量を指定します。
lineGetDevCaps 関数は、指定された回線デバイスに対し、その回線のテレフォニー機能を問い合わせます。返される情報は、その回線デバイス上のすべてのアドレスに対して適用されます。
LONG lineGetDevCaps( HLINEAPP hLineApp, DWORD dwDeviceID, DWORD dwAPIVersion, DWORD dwExtVersion, LPLINEDEVCAPS lpLineDevCaps );
アプリケーションを TAPI に登録するためのハンドル。
問い合わせる回線デバイス。
使用する API のバージョン番号(lineNegotiateAPIVersion で取得する)。上位の桁にはメジャー バージョン番号が入り、下位の桁にはマイナー バージョン番号が入ります。
使用する拡張のバージョン番号(lineNegotiateExtVersion で取得する)。デバイス固有拡張を使用しない場合は、ゼロのままにしておくことができます。そうでない場合は、上位の桁にメジャー バージョン番号が入り、下位の桁にマイナー バージョン番号が入ります。
LINEDEVCAPS 型の可変サイズ構造体へのポインタ。要求が正常に完了すると、この構造体に回線デバイスの機能情報が入ります。lineGetDevCaps を呼び出す前に、この構造体の dwTotalSize メンバを設定しておく必要があります。このメンバは、返された情報を格納するために TAPI が使用できるメモリの量を指定します。
lineGetID 関数は、選択された回線、アドレスまたはコールに関連付けられている、指定されたデバイス クラスのデバイス ID を返します。
LONG lineGetID( HLINE hLine, DWORD dwAddressID, HCALL hCall, DWORD dwSelect, LPVARSTRING lpDeviceID, LPCSTR lpszDeviceClass );
オープン状態の回線デバイスのハンドル。
指定されたオープン状態の回線デバイス上のアドレス。
コールのハンドル。
要求されたデバイス ID が回線、アドレス、またはコールのうちのいずれに関連付けられるかを指定します。dwSelect パラメータに格納できるフラグ セットは 1 つだけです。このパラメータには、次の LINECALLSELECT_ 定数が入ります。
デバイス ID が返される、VARSTRING 型のメモリ位置へのポインタ。要求が正常に完了すると、この位置にデバイス ID が入ります。返される情報の形式は、各デバイス クラス API が使用しているデバイス指定方式に依存します。lineGetID を呼び出す前に、この構造体の dwTotalSize メンバを設定しておく必要があります。このメンバは、返された情報を格納するために TAPI が使用できるメモリの量を指定します。
ID を要求するデバイスのデバイス クラスを指定する ASCII 形式 NULL 終端文字列へのポインタ。デバイス クラスには、wave/in、wave/out、tapi/line などがあります。
有効なデバイス クラス文字列は、SYSTEM.INI セクションでデバイス クラスを識別するために使用されている文字列です。
lineGetLineDevStatus 関数を使用すると、指定されたオープン状態の回線デバイスに対して、現在のステータスを問い合わせることができます。
LONG lineGetLineDevStatus( HLINE hLine, LPLINEDEVSTATUS lpLineDevStatus );
問い合わせをするオープン状態の回線デバイスのハンドル。
LINEDEVSTATUS 型の可変サイズ データ構造体へのポインタ。要求が正常に完了すると、この構造体が回線のデバイスのステータスに入ります。lineGetLineDevStatus を呼び出す前に、この構造体の dwTotalSize メンバを設定しておく必要があります。このメンバは、返された情報を格納するために TAPI が使用できるメモリの量を指定します。
lineGetMessage 関数は、イベント ハンドル通知メカニズム(詳細は、lineInitializeExを参照してください)を使用しているアプリケーションへ次に配信される TAPI メッセージを返します。
LONG WINAPI lineGetMessage( HLINEAPP hLineApp, LPLINEMESSAGE lpMessage, DWORD dwTimeout );
lineInitializeEx によって返されるハンドル。LINEINITIALIZEEXPARAMS 構造体の dwOptions メンバで LINEINITIALIZEEXOPTION_USEEVENT オプションが設定されている必要があります。
LINEMESSAGE 構造体へのポインタ。この関数が正常に終了すると、アプリケーションへ次に配信されるメッセージがこの構造体に入ります。
タイムアウトまでの時間(ミリ秒単位)。この関数は、返すメッセージがない場合でも、指定された時間が経過すると終了します。dwTimeout がゼロの場合、この関数は配信待ちのメッセージがないかどうかを確認して、ただちに終了します。dwTimeout が INFINITE の場合、この関数のタイムアウト時間は無限になります。
lineGetNewCalls 関数は、指定された回線またはアドレス上のコールで、現在アプリケーションによってハンドルが割り当てられていないコールのコール ハンドルを返します。アプリケーションには、これらのコールに対するモニタ特権が与えられます。
lineGetNewCalls を使用すると、現在そのアプリケーションによってハンドルが割り当てられていないコールのハンドルを取得できます。また、どのコールのハンドルを取得するかを選択する際には、スコープを指定することもできます(指定された回線上のコール、または指定されたアドレス上のコール)。たとえば、指定されたアドレス上で現在ハンドルが割り当てられていないすべてのコールのコール ハンドルを要求することができます。
LONG WINAPI lineGetNewCalls( HLINE hLine, DWORD dwAddressID, DWORD dwSelect, LPLINECALLLIST lpCallList );
オープン状態の回線デバイスのハンドル。
指定されたオープン状態の回線デバイス上のアドレス。アドレス ID とアドレスは固定的に関連付けられているため、オペレーティング システムをアップグレードしてもアドレス ID は変更されません。
要求するコールの選択。このパラメータには、LINECALLSELECT_定数のうちの 1 つだけが入ります。
LINECALLLIST 型の可変サイズ データ構造体へのポインタ。要求が正常に完了すると、選択されたすべてのコールのコール ハンドルがこの構造体に返されます。lineGetNewCalls を呼び出す前に、この構造体の dwTotalSize メンバを設定しておく必要があります。このメンバは、返された情報を格納するために TAPI が使用できるメモリの量を指定します。
lineGetNumRings 関数は、指定されたアドレスへコールが着信した際に、コールが応答される前に呼び出し音を何回鳴らすかを決定します。
LONG WINAPI lineGetNumRings( HLINE hLine, DWORD dwAddressID, LPDWORD lpdwNumRings );
オープン状態の回線デバイスのハンドル。
回線デバイス上のアドレス。アドレス ID とアドレスは固定的に関連付けられているため、オペレーティング システムをアップグレードしてもアドレス ID は変更されません。
現在のすべての lineSetNumRings 要求のうちで、最小の呼び出し音の回数。
lineGetProviderList 関数は、テレフォニー システムに現在インストールされているサービス プロバイダーのリストを返します。
LONG WINAPI lineGetProviderList( DWORD dwAPIVersion, LPLINEPROVIDERLIST lpProviderList );
アプリケーションがサポートしている TAPI の最上位バージョン(一部の回線デバイスでは、lineNegotiateAPIVersion によってこの値がネゴシエートされない場合もあります)。
TAPI が LINEPROVIDERLIST 構造体を返すことができるメモリ位置へのポインタです。lineGetProviderList を呼び出す前に、この構造体の dwTotalSize メンバを設定しておく必要があります。このメンバは、返された情報を格納するために TAPI が使用できるメモリの量を指定します。
LONG WINAPI lineGetRequest( HLINEAPP hLineApp, DWORD dwRequestMode, LPVOID lpRequestBuffer );
取得する要求のタイプ。dwRequestMode に格納できるビット セットは、1 つだけです。このパラメータには、LINEREQUESTMODE_ 定数のうちの 1 つだけが入ります。
要求のパラメータが入るメモリ バッファへのポインタ。このバッファに格納される情報のサイズおよび解釈方法は、要求モードによって異なります。アプリケーションが割り当てたバッファは、要求を格納するのに十分なサイズを提供します。dwRequestMode が LINEREQUESTMODE_MAKECALL の場合は、LINEREQMAKECALL 構造体を使用して要求バッファの内容を解釈します。dwRequestMode が LINEREQUESTMODE_MEDIACALL の場合は、LINEREQMEDIACALL 構造体を使用して要求バッファの内容を解釈します。
lineGetStatusMessages 関数を使用すると、特定の回線または回線上のアドレスにおいてステータス変化に関連するイベントが発生した場合に、アプリケーションが受け取る通知メッセージを問い合わせることができます。
LONG WINAPI lineGetStatusMessages( HLINE hLine, LPDWORD lpdwLineStates, LPDWORD lpdwAddressStates );
回線デバイスのハンドル。
メッセージがアプリケーションに送信される回線デバイスのステータス変化を示すビット配列。フラグが TRUE の場合、そのメッセージは有効です。FALSE の場合、そのメッセージは無効です。このパラメータは、1 つ以上の LINEDEVSTATE_ 定数を使用します。
アドレスのどのようなステータス変化に関するメッセージがアプリケーションに送信されるかを表すビット配列。フラグが TRUE の場合、そのメッセージは有効です。FALSE の場合、そのメッセージは無効です。このパラメータは、1 つ以上の LINEADDRESSSTATE_ 定数を使用します。
LONG WINAPI lineGetTranslateCaps( HLINEAPP hLineApp, DWORD dwAPIVersion, LPLINETRANSLATECAPS lpTranslateCaps );
lineInitializeEx によって返されるアプリケーションのハンドル。アプリケーションがまだ lineInitializeEx 関数を呼び出していない場合は、hLineApp パラメータを NULL に設定できます。
アプリケーションがサポートしている TAPI の最上位バージョン(一部の回線デバイスでは、lineNegotiateAPIVersion によってこの値がネゴシエートされない場合もあります)。
LINETRANSLATECAPS 構造体が読み込まれる位置へのポインタ。lineGetTranslateCaps を呼び出す前に、この構造体の dwTotalSize メンバを設定しておく必要があります。このメンバは、返された情報を格納するために TAPI が使用できるメモリの量を指定します。
lineHandoff 関数は、指定されたコールの所有権を別のアプリケーションに移管します。移管先のアプリケーションは、直接的、または間接的に指定します。直接的に移管先のアプリケーションを指定する場合は、そのアプリケーションのファイル名を指定します。間接的にアプリケーションを指定する場合は、メディア モードを指定します。その場合は、指定されたメディア モードのコールをハンドルしているアプリケーションの中で、最もプライオリティが高いアプリケーションに所有権が移管されます。
LONG WINAPI lineHandoff( HCALL hCall, LPCSTR lpszFileName, DWORD dwMediaMode );
ハンドオフするコールのハンドル。アプリケーションは、このコールのオーナーになっている必要があります。有効な hCall のコール状態は、すべての状態です。
NULL 終端文字列へのポインタ。このポインタ パラメータが NULL でない場合は、ハンドオフ先のアプリケーションのファイル名がここに入ります。NULL の場合は、回線をオープンしているアプリケーションのうち、指定されたメディア モードのオーナー特権に関してプライオリティが最も高いアプリケーションがハンドオフ先に相当します。有効な文字列は、パスを含まないファイル名です。
所有権を間接的にハンドオフする場合に、ハンドオフ先の識別に使用されるメディア モード。dwMediaMode パラメータによって、コールの所有権のハンドオフ先となるアプリケーションが間接的に決定されます。lpszFileName が NULL でない場合、このパラメータは無視されます。このパラメータには、LINEMEDIAMODE_ 定数のうちの 1 つだけが入ります。
LONG lineHold( HCALL hCall );
保留状態にするコールのハンドル。アプリケーションをそのコールのオーナーにして、hCall のコール状態を connected にします。
lineInitialize 関数は旧バージョンの関数ですが、API バージョン 1.3 および 1.4 を使用するアプリケーションとの下位互換性を維持するために、tapi.dll および tapi32.dll によってエクスポートが継続されています。
LONG WINAPI lineInitialize( LPHLINEAPP lphLineApp, HINSTANCE hInstance, LINECALLBACK lpfnCallback, LPCSTR lpszAppName, LPDWORD lpdwNumDevs );
アプリケーションによる TAPI の使用状態のハンドルが入っている位置へのポインタ。
クライアント アプリケーションまたは DLL のインスタンス ハンドル。
回線デバイス、アドレス、またはコールのステータスとイベントを確認するために呼び出されるコールバック関数のアドレス。詳細は、lineCallbackFunc を参照してください。
表示可能な文字だけが入る NULL 終端文字列へのポインタ。このパラメータが NULL でない場合は、アプリケーションで指定されたアプリケーション名が入ります。LINECALLINFO 構造体はこの名前を提供して、コールを発信したアプリケーション、コールを最初に受け入れたアプリケーション、コールに応答したアプリケーションなどを、ユーザにわかりやすい形式で提示します。この情報は、コールのロギングに便利なことがわかっています。lpszAppName が NULL の場合は、アプリケーションのファイル名が代わりに使用されます。
DWORD サイズの位置へのポインタ。要求が正常に完了すると、アプリケーションで使用できる回線デバイスの数がここに入ります。
lineInitializeEx 関数は、アプリケーションによる TAPI の使用状態を初期化し、以後の line 抽象関数の使用を可能にします。この関数は、アプリケーションの特定の通知メカニズムを登録し、使用可能な回線デバイスの数を返します。回線デバイスとは、line で始まる Telephony API の関数を実行できるすべてのデバイスを示します。
LONG lineInitializeEx( LPHLINEAPP lphLineApp, HINSTANCE hInstance, LINECALLBACK lpfnCallback, LPCSTR lpszFriendlyAppName, LPDWORD lpdwNumDevs, LPDWORD lpdwAPIVersion, LPLINEINITIALIZEEXPARAMS lpLineInitializeExParams );
アプリケーションによる TAPI の使用状態のハンドルが格納されている位置へのポインタ。
クライアント アプリケーションまたは DLL のインスタンス ハンドル。アプリケーションまたは DLL はこのパラメータに NULL を渡すことができます。その場合、TAPI はそのプロセスの root 実行可能ファイルのモジュール ハンドルを使用します(コールのハンドオフ先、およびメディア モードのプライオリティを識別するため)。
アプリケーションが「ウィンドウ非表示」方式でイベント通知を使用している場合に、回線デバイス、アドレス、またはコールのステータスおよびイベントを確認するために呼び出すコールバック関数のアドレス。アプリケーションが「イベント ハンドル」または「完了ポート」のいずれかのイベント通知メカニズムを使用している場合は、このパラメータが無視されて、NULL に設定されます。
標準の ASCII 文字だけが入った ASCII 形式 NULL 終端文字列へのポインタ。このパラメータが NULL でない場合は、アプリケーションで指定されたアプリケーション名が入ります。LINECALLINFO 構造体はこの名前を提供して、コールを発信したアプリケーション、コールを最初に受け入れたアプリケーション、コールに応答したアプリケーションなどを、ユーザにわかりやすい形式で提示します。この情報は、コールのロギングに便利なことがわかっています。lpszFriendlyAppName が NULL の場合は、(Windows の API GetModuleFileName から返された)アプリケーションのモジュール ファイル名が代わりに使用されます。
DWORD サイズの位置へのポインタ。要求が正常に完了すると、アプリケーションで使用できる回線デバイスの数がここに入ります。
DWORD サイズの位置へのポインタ。アプリケーションは、この関数を呼び出す前に、この関数をサポートしている最新の API バージョン(たとえば、lineNegotiateAPIVersion の dwAPIHighVersion パラメータに渡されるバージョン番号)へこの DWORD を初期化する必要があります。故意に高い値を使用していないことを確認してください。この値は 0x00020000 に設定する必要があります。新しいバージョンの TAPI のメッセージや構造体は、アプリケーションがサポートしている値および書式に変換されます。要求が正常に完了すると、TAPI でサポートされている最新の API バージョンがここに入るため、古いバージョンの TAPI を使用するシステムにインストールされていても、アプリケーションは適応できます。
アプリケーションと TAPI の間の連携を確立するために使用される追加パラメータ(具体的には、アプリケーションで選択されているイベント通知メカニズムと関連パラメータ)が格納されている LINEINITIALIZEEXPARAMS 型の構造体へのポインタ。
lineMakeCall 関数は、指定された回線上で、指定された宛先アドレスにコールを発信します。デフォルトのコール セットアップ パラメータ以外のコール パラメータを要求する場合は、コール パラメータをオプションで指定することもできます。
LONG lineMakeCall(HLINE hLine, LPHCALL lphCall, LPCSTR lpszDestAddress, DWORD dwCountryCode, LPLINECALLPARAMS const lpCallParams ); typedef struct LineParams { DWORD FeaturePriority;
コールを開始するオープン状態の回線デバイスのハンドル。
HCALL ハンドルへのポインタ。このハンドルは、lineMakeCall 関数の成功を示す LINE_REPLY メッセージをアプリケーションが受信した後にだけ有効になります。そのコールに関して他のテレフォニー操作を呼び出す場合は、このハンドルを使用してコールを指定します。当初は、このアプリケーションがこのコールの唯一のオーナーとして機能します。応答メッセージが(同期的または非同期的に)エラーを返す場合、このハンドルは無効として登録します。
宛先アドレスへのポインタ。このパラメータでは標準のダイヤル可能番号形式を使用します。ダイヤル可能なアドレスでない場合、または lineDial を使用してすべてのダイヤル動作を実行する場合は、このポインタを NULL にします。後者の場合は、lineMakeCall を呼び出すと、使用可能なコール標示が割り当てられ、通常は、ダイヤル動作が開始されるまで、ダイヤル トーン状態が維持されます。
着信側の国番号。0 を指定すると、この実装ではデフォルト値が使用されます。
lpCallParams フィールドの dwNoAnswerTimeout 属性がチェックされて、その値がゼロに指定されていない場合、指定された時間内に応答がなかったときは、コールの接続が自動的に解除されます。詳細については、LINECALLPARAMSを参照してください。
lineMonitorDigits 関数は、コール上で受信したディジットのリアルタイム検出を有効または無効にします。指定されたディジット モードのディジットが検出されるたびに、検出されたディジットを示すメッセージがアプリケーションに送信されます。
LONG lineMonitorDigits( HCALL hCall, DWORD dwDigitModes );
ディジットを検出するコールのハンドル。有効な hCall のコール状態は、idle と disconnected を除くすべての状態です。
モニタするディジット モード。dwDigitModes がゼロの場合、システムはディジットのモニタリングをキャンセルします。複数のフラグ セットを格納できるこのパラメータには、次の LINEDIGITMODE_ 定数が入ります。
LINEDIGITMODE_DTMF:ディジットを DTMF トーンとして検出します。DTMF で有効なディジットは、「0」~「9」、「*」、および「#」です。
lineMonitorTones 関数は、コール上でのインバンド トーンの検出を有効または無効にします。指定されたトーンが検出されるたびに、メッセージがアプリケーションに送信されます。
LONG lineMonitorTones( HCALL hCall, LPLINEMONITORTONE const lpToneList, DWORD dwNumEntries );
トーンの検出を行うコールのハンドル。有効な hCall のコール状態は、idle を除くすべての状態です。
モニタするトーンのリスト(LINEMONITORTONE 型)。このリストの各トーンには、アプリケーションによって定義されるタグ フィールドがあります。このフィールドは、リスト内にある個々のトーンを識別し、トーンの検出を報告するために使用されます。lpToneList を NULL にしてこの操作を呼び出すか、別のトーン リストを指定してこの操作を呼び出すことで、現在有効なトーン モニタリングをキャンセルまたは変更します。
lpToneList のエントリ数。lpToneList が NULL の場合、このパラメータは無視されます。
lineNegotiateAPIVersion 関数を使用すると、アプリケーションで使用する API バージョンをネゴシエートできます。Cisco Unified TSP は、TAPI 2.0 および 2.1 をサポートしています。
LONG lineNegotiateAPIVersion( HLINEAPP hLineApp, DWORD dwDeviceID, DWORD dwAPILowVersion, DWORD dwAPIHighVersion, LPDWORD lpdwAPIVersion, LPLINEEXTENSIONID lpExtensionID );
アプリケーションを TAPI に登録するためのハンドル。
問い合わせる回線デバイス。
アプリケーションが準拠している最も古い API バージョン。上位の桁はメジャー バージョン番号、下位の桁はマイナー バージョン番号を示します。
アプリケーションが準拠している最新の API バージョン。上位の桁はメジャー バージョン番号、下位の桁はマイナー バージョン番号を示します。
ネゴシエートされた API のバージョン番号を格納する DWORD サイズの位置へのポインタ。ネゴシエーションが成功すると、この番号は dwAPILowVersion から dwAPIHighVersion の範囲の値になります。
LINEEXTENSIONID 型の構造体へのポインタ。指定された dwDeviceID のサービス プロバイダーで、プロバイダー固有の拡張がサポートされている場合、ネゴシエーションが成功すると、この構造体にはこれらの拡張の拡張 ID が入ります。その回線で拡張がサポートされていない場合、この構造体にはゼロだけが入ります。アプリケーションで拡張を使用していない場合は、返されたパラメータを無視できます。
Cisco Unified TSP で指定されている extensionID は、0x8EBD6A50、0x138011d2、0x905B0060、0xB03DD275 です。
lineNegotiateExtVersion 関数を使用すると、指定された回線デバイスに対して使用する拡張のバージョンをネゴシエートできます。アプリケーションで拡張がサポートされていない場合は、この操作を呼び出さないでください。
LONG lineNegotiateExtVersion( HLINEAPP hLineApp, DWORD dwDeviceID, DWORD dwAPIVersion, DWORD dwExtLowVersion, DWORD dwExtHighVersion, LPDWORD lpdwExtVersion );
アプリケーションを TAPI に登録するためのハンドル。
問い合わせる回線デバイス。
指定された回線デバイスについて lineNegotiateAPIVersion を使用してネゴシエートされた API バージョン番号。
lineNegotiateAPIVersion が返した拡張 ID のうち、アプリケーションが準拠している最も古い拡張バージョン。上位の桁はメジャー バージョン番号、下位の桁はマイナー バージョン番号を示します。
lineNegotiateAPIVersion が返した拡張 ID のうち、アプリケーションが準拠している最新の拡張バージョン。上位の桁はメジャー バージョン番号、下位の桁はマイナー バージョン番号を示します。
ネゴシエートされた拡張バージョン番号を格納する DWORD サイズの位置へのポインタ。ネゴシエーションが成功すると、この番号は dwExtLowVersion から dwExtHighVersion の間になります。
lineOpen 関数は、デバイス ID が指定した回線デバイスをオープンし、オープンした回線デバイスの回線ハンドルを返します。回線デバイスに関して何らかの操作を実行するには、この回線ハンドルを使用します。
LONG lineOpen( HLINEAPP hLineApp, DWORD dwDeviceID, LPHLINE lphLine, DWORD dwAPIVersion, DWORD dwExtVersion, DWORD dwCallbackInstance, DWORD dwPrivileges, DWORD dwMediaModes, LPLINECALLPARAMS const lpCallParams );
アプリケーションを TAPI に登録するためのハンドル。
オープンする回線デバイスを指定します。有効なデバイス ID または値 LINEMAPPER を指定できます。
(注) | 現在のところ、Cisco Unified TSP は LINEMAPPER をサポートしていません。 |
HLINE ハンドルへのポインタ。オープンされた回線デバイスを表すハンドルがここに読み込まれます。このハンドルは、オープンされた回線デバイスに対して他の関数を呼び出す際に、そのデバイスを識別するために使用します。
アプリケーションと Telephony API の間で操作する API のバージョン番号。この番号は、lineNegotiateAPIVersion を使用して取得します。
アプリケーションとサービス プロバイダーの間で操作する拡張のバージョン番号。アプリケーションが拡張を使用しない場合、この番号はゼロのままです。この番号は、lineNegotiateExtVersion を使用して取得します。
この回線またはこの回線上のアドレスやコールに関連付けられた各メッセージによってアプリケーションに返されるユーザ インスタンス データ。Telephony API はこのパラメータを解釈しません。
コールについての通知を受け取るためにアプリケーションが必要とする特権。このパラメータには、複数の LINECALLPRIVILEGE_ 定数を組み合わせて指定できます。TAPI バージョン 2.0 以降を使用しているアプリケーションの場合は、このパラメータの値として LINEOPENOPTION_ 定数も使用できます。
LINECALLPRIVILEGE_NONE:このアプリケーションは発信コールだけを確立できます。
LINECALLPRIVILEGE_MONITOR:このアプリケーションは着信コールと発信コールのモニタだけを実行できます。
LINECALLPRIVILEGE_OWNER:このアプリケーションは dwMediaModes で指定されたタイプの着信コールだけを所有できます。
LINECALLPRIVILEGE_MONITOR + LINECALLPRIVILEGE_OWNER:このアプリケーションは dwMediaModes で指定されたタイプの着信コールだけを所有できます。ただし、アプリケーションがコールのオーナーでない場合は、モニタとしての役割を果たします。
他の組み合わせを使用すると、LINEERR_INVALPRIVSELECT エラーが返されます。
メディア モード(そのアプリケーションに関係するモード)。このパラメータを使用して、指定されたメディア モードのコールの着信先またはハンドオフ先の候補としてアプリケーションを登録します。このパラメータは、dwPrivileges で LINECALLPRIVILEGE_OWNER ビットが設定されている場合にだけ有効になります(設定されていない場合は無視されます)。
このパラメータには、次の LINEMEDIAMODE_ 定数が入ります。
LINEMEDIAMODE_INTERACTIVEVOICE:このアプリケーションは、対話式音声メディア タイプのコールを処理できます。つまり、ユーザが一方に存在しているボイス コールを管理できます。このパラメータは、物理的な電話機や、他のアプリケーションでオープンされた CTI ポートと CTI ルート ポイント デバイスのサードパーティ呼制御に使用します。
LINEMEDIAMODE_AUTOMATEDVOICE:コールの音声エネルギー。音声は自動化されたアプリケーションにより、ローカルで処理されます。これはファーストパーティ呼制御に相当し、CTI ポートおよび CTI ルート ポイント デバイスを使用します。
lpCallParams フィールドの dwNoAnswerTimeout 属性がチェックされて、その値がゼロでなかった場合、そこで指定されている時間内に応答がなかったときは、コールの接続が自動的に解除されます。
LONG WINAPI linePark(HCALL hCall, DWORD dwParkMode, LPCSTR lpszDirAddress, LPVARSTRING lpNonDirAddress );
パークするコールのハンドル。アプリケーションは、このコールのオーナーとして機能している必要があります。有効な hCall のコール状態は、connected です。
コールをパークする際に使用するパーク モード。このパラメータに格納できるフラグ セットは 1 つだけで、LINEPARKMODE_ 定数の 1 つを使用します。
(注) | LINEPARKMODE_ 定数が LINEPARKMODE_NONDIRECTED に設定されていることを確認します。 |
DIRECTED パーク モードが使用される際に、コールのパーク場所となるアドレスを示す NULL 終端文字列へのポインタ。このアドレスは、ダイヤル可能番号形式で指定します。NONDIRECTED パーク モードの場合、このパラメータは無視されます。
(注) | このパラメータは無視されます。 |
VARSTRING 型の構造体へのポインタ。NONDIRECTED パーク モードの場合は、コールがパークされているアドレスがこの構造体に返されます。DIRECTED パーク モードの場合、このパラメータは無視されます。VARSTRING 構造体内の dwStringFormat は、必ず STRINGFORMAT_ASCII(NULL 終端文字列を含む ASCII 文字列のバッファ)に設定し、終端の NULL も dwStringSize に算入する必要があります。linePark を呼び出す前に、この構造体の dwTotalSize メンバを設定しておく必要があります。このメンバは、返された情報を格納するために TAPI が使用できるメモリの量を指定します。
linePrepareAddToConference 関数は、既存の電話会議に新しい通話者を追加するための準備を実行します。
LINEERR_INVALLINESTATE が返された場合、その回線は現在、この操作を実行できない状態になっていることを意味します。LINEDEVSTATUS 構造体の dwLineFeatures メンバ(LINEFEATURE 型)は、現在有効な操作のリストを含んでいます(lineGetLineDevStatus を呼び出すと、LINEDEVSTATUS の情報を更新します)。
lineSetupConference または lineCompleteTransfer で電話会議のハンドルを取得し、3 者間の電話会議として解決します。通常、linePrepareAddToConference 関数は、既存の電話会議を onHoldPendingConference 状態にして、コンサルト コールを作成します。このコンサルト コールは、lineAddToConference を使用して電話会議に追加できます。
lineDrop を使用して、コンサルト コールをキャンセルできます。また、lineSwapHold を使用して、コンサルト コールと保留中の電話会議のアプリケーションをスワップすることもできます。
LONG WINAPI linePrepareAddToConference( HCALL hConfCall, LPHCALL lphConsultCall, LPLINECALLPARAMS const lpCallParams );
電話会議のハンドル。アプリケーションは、このコールのオーナーとして機能している必要があります。hConfCall のコール状態が connected になっていることを確認します。
HCALL ハンドルへのポインタ。追加するコンサルト コールを識別するハンドルが、この位置にロードされます。当初は、このアプリケーションがこのコールの唯一のオーナーになります。
コンサルト コールの確立時に使用されるコール パラメータへのポインタ。特別なコール セットアップ パラメータを使用しない場合、このパラメータを NULL に設定できます。
関数が非同期的に完了した場合は、正の要求 ID が返されます。エラーが発生した場合は、負の番号が返されます。対応する LINE_REPLY メッセージの dwParam2 パラメータは、関数が成功するとゼロ、エラーが発生すると負の番号を指定します。
LINEERR_BEARERMODEUNAVAIL
LINEERR_INVALPOINTER
LINEERR_CALLUNAVAIL
LINEERR_INVALRATE
LINEERR_CONFERENCEFULL
LINEERR_NOMEM
LINEERR_INUSE
LINEERR_NOTOWNER
LINEERR_INVALADDRESSMODE
LINEERR_OPERATIONUNAVAIL
LINEERR_INVALBEARERMODE
LINEERR_OPERATIONFAILED
LINEERR_INVALCALLPARAMS
LINEERR_RATEUNAVAIL
LINEERR_INVALCALLSTATE
LINEERR_RESOURCEUNAVAIL
LINEERR_INVALCONFCALLHANDLE
LINEERR_STRUCTURETOOSMALL
LINEERR_INVALLINESTATE
LINEERR_USERUSERINFOTOOBIG
LINEERR_INVALMEDIAMODE
LINEERR_UNINITIALIZED
lineRedirect 関数は、指定されたオファー中のコールまたは受け入れ済みコールを、指定された宛先アドレスにリダイレクトします。
(注) | lineRedirect 関数を使用して FAC、CMC、またはその両方を必要とするアドレスにコールをリダイレクトしようとすると、エラーが返されます。FAC が必要な場合は、TSP から LINEERR_FACREQUIRED メッセージが返されます。CMC が必要な場合は、TSP から LINEERR_CMCREQUIRED メッセージが返されます。FAC と CMC の両方が必要な場合は、TSP から LINEERR_FACANDCMCREQUIRED メッセージが返されます。FAC、CMC、またはその両方を必要とするアドレスにコールをリダイレクトする場合は、lineDevSpecific RedirectFACCMC 関数を使用する必要があります。 |
LONG lineRedirect( HCALL hCall, LPCSTR lpszDestAddress, DWORD dwCountryCode );
リダイレクトするコールのハンドル。アプリケーションは、このコールのオーナーとして機能している必要があります。有効な hCall のコール状態は、offering、accepted、または connected です。
(注) | Cisco Unified TSP は、connected 状態のコールのリダイレクトをサポートしています。 |
宛先アドレスへのポインタ。標準のダイヤル可能番号形式を使用します。
コールのリダイレクト先の国番号。0 を指定すると、この実装ではデフォルト値が使用されます。
lineRegisterRequestRecipient 関数を呼び出したアプリケーションは、指定された要求モードに関し、要求の受け入れ先として登録されます。
LONG WINAPI lineRegisterRequestRecipient( HLINEAPP hLineApp, DWORD dwRegistrationInstance, DWORD dwRequestMode, DWORD bEnable );
アプリケーションによる TAPI の回線部分の使用状態のハンドル。
LINE_REQUEST メッセージのパラメータとして返される、アプリケーション固有の DWORD。このメッセージは、処理待ちの要求があることをアプリケーションに通知します。bEnable がゼロに設定されている場合、このパラメータは無視されます。TAPI はこのパラメータを確認して、登録だけを行います(登録解除は行いません)。登録解除の際に使用する dwRegistrationInstance の値が、登録の際の要求モードに使用する dwRegistrationInstance と一致する必要はありません。
どの種類の要求に関して、アプリケーションを登録するかを指定します。このパラメータは、1 つ以上の LINEREQUESTMODE_ 定数を使用します。
TRUE の場合は、指定された要求モードに関してアプリケーションが登録され、FALSE の場合は、指定された要求モードに関してアプリケーションの登録が解除されます。
lineRemoveFromConference 関数は、現在属している電話会議から指定されたコールを削除します。電話会議に残っているコールには影響しません。
LONG WINAPI lineRemoveFromConference( HCALL hCall );
会議から削除されるコールのハンドル。アプリケーションは、このコールのオーナーになっている必要があります。有効な hcall のコール状態は、conference です。
関数が非同期的に完了した場合は、正の要求 ID が返されます。エラーが発生した場合は、負の番号が返されます。対応する LINE_REPLY メッセージの dwParam2 パラメータは、関数が成功するとゼロ、エラーが発生すると負の番号になります。次の表は、この関数の戻り値を示しています。
LONG WINAPI lineRemoveProvider( DWORD dwPermanentProviderID, HWND hwndOwner );
削除するサービス プロバイダーの固定プロバイダー ID。
(サービス プロバイダーの TSPI_providerRemove 関数による確認ダイアログボックスなど)削除処理中に表示されるダイアログボックスに関連付けるウィンドウのハンドル。関数の実行中に生成されるウィンドウを特定のオーナー ウィンドウに関連付ける必要がない場合、パラメータを NULL 値にして、これを示すことができます。
lineSetAppPriority 関数を使用すると、特定のメディア タイプまたは Assisted Telephony 要求モードに関するハンドオフ プライオリティ リスト内で、そのアプリケーションのプライオリティを設定することができます。また、プライオリティ リストからそのアプリケーションを削除することもできます。
LONG WINAPI lineSetAppPriority( LPCSTR lpszAppFilename, DWORD dwMediaMode, LPLINEEXTENSIONID lpExtensionID, DWORD dwRequestMode, LPCSTR lpszExtensionName, DWORD dwPriority );
アプリケーションの実行可能モジュール ファイル名(ディレクトリ情報を除く)を格納する文字列へのポインタ。TAPI バージョン 2.0 以降では、このパラメータにロングファイル名形式と 8.3 ファイル名形式のいずれかを使用できます。
どのメディア タイプに関して、このアプリケーションのプライオリティを設定するかを指定します。この値には LINEMEDIAMODE_ 定数の 1 つを使用できます(有効になるビットは 1 つだけです)。この値にゼロを使用すると、Assisted Telephony 要求に関してこのアプリケーションのプライオリティが設定されます。
LINEEXTENSIONID 型の構造体へのポインタ。このパラメータは無視されます。
dwMediaMode パラメータがゼロの場合は、このパラメータで、どの Assisted Telephony 要求モードに関するプライオリティを設定するかを指定します。このパラメータは、LINEREQUESTMODE_MAKECALL または LINEREQUESTMODE_MEDIACALL のいずれかに設定する必要があります。dwMediaMode がゼロでない場合、このパラメータは無視されます。
このパラメータは無視されます。
アプリケーションの新しいプライオリティ。0 が渡される場合は、指定されたメディアまたは要求モードのプライオリティ リストから、このアプリケーションが削除されます(このアプリケーションがすでに存在していなかった場合、エラーは生成されません)。1 が渡される場合は、指定されたメディアまたは要求モードに関して、最高位のプライオリティがこのアプリケーションに与えられます(すでにこのアプリケーションがリスト内に存在していた場合は、以前のプライオリティの位置から削除されます)。その他の値が渡された場合は、エラーが生成されます。
LONG WINAPI lineSetCallPrivilege( HCALL hCall, DWORD dwCallPrivilege );
特権を設定するコールのハンドル。有効な hCall のコール状態は、すべての状態です。
指定されたコールに対して、どのような特権をアプリケーションに与えるかを指定します。このパラメータには、LINECALLPRIVILEGE_ 定数のうちの 1 つだけが入ります。
lineSetNumRings 関数は、呼び出し音を何回鳴らした後に着信コールに応答するかを設定します。この関数を使用して、トールセーバー方式の機能を実装します。これにより、複数の独立したアプリケーションが、呼び出し音の回数を個別に登録できます。lineGetNumRings 関数は、要求されている呼び出し音の回数のうちで、最小の値を返します。着信コールに応答するアプリケーションは、この関数を使用して、呼び出し音が何回鳴った後にコールに応答する必要があるかを判別できます。
LONG WINAPI lineSetNumRings( HLINE hLine, DWORD dwAddressID, DWORD dwNumRings );
オープン状態の回線デバイスのハンドル。
回線デバイス上のアドレス。アドレス ID とアドレスは固定的に関連付けられているため、オペレーティング システムをアップグレードしてもアドレス ID は変更されません。
すべてのアプリケーションからのトールセーバー要求に応じるために、コールへの応答までに何回呼び出し音を鳴らすかを指定します。
lineSetStatusMessages 関数を使用すると、特定の回線または回線上のアドレスにおいてステータス変化に関連するイベントが発生した場合に、アプリケーションが受け取る通知メッセージを設定することができます。
LONG lineSetStatusMessages( HLINE hLine, DWORD dwLineStates, DWORD dwAddressStates );
回線デバイスのハンドル。
回線デバイスのどのようなステータス変化に関するメッセージがアプリケーションに送信されるかを表すビット配列。このパラメータには、次の LINEDEVSTATE_定数が入ります。
LINEDEVSTATE_OTHER:次のデバイス ステータス以外の項目が変化したことを示します。アプリケーションは、現在のデバイス ステータスを調べて、変化した項目を確認する必要があります。
LINEDEVSTATE_RINGING:交換機がその回線に対し、呼び出し音を鳴らすよう指示していることを示します。サービス プロバイダーは、一定の呼び出し周期ごとに、この定数を格納する LINE_LINEDEVSTATE メッセージを送信して、アプリケーションに通知します。たとえば米国の場合は、この定数を含むメッセージが 6 秒ごとにサービス プロバイダーから送信されます。
LINEDEVSTATE_NUMCALLS:回線デバイス上のコール数が変化したことを示します。
LINEDEVSTATE_REINIT:回線デバイスの設定で項目に変化があったことを示します。(新しい回線デバイスの出現と同様に)これらの変化を検出するには、アプリケーションによる TAPI の使用状態を再初期化する必要があります。その後に発行された lineInitialize 要求、lineInitializeEx 要求、および lineOpen 要求は、アプリケーションが TAPI の使用をシャットダウンするまで拒否されます。この状態変化はシステム内のすべての回線に関係するため、この状態変化が発生しても、LINE_LINEDEVSTATE メッセージの hDevice パラメータは NULL のままです。LINEDEVSTATE_REINIT は非常に重要なメッセージであるため、無効にできません。したがって、それらのメッセージは、このビットの設定とは無関係に、常にアプリケーションへ配信されます。
LINEDEVSTATE_REMOVED:サービス プロバイダーがこのデバイスをシステムから削除したことを示します(主な原因は、ユーザの操作や、コントロール パネルなどのユーティリティによる操作です)。通常は、この値を持つ LINE_LINEDEVSTATE メッセージの直後に、デバイスに関する LINE_CLOSE メッセージが送信されます。この場合、TAPI が再初期化される前に、そのデバイスへのアクセスを試みると、LINEERR_NODEVICE がアプリケーションに返されます。この値を格納する LINE_LINEDEVSTATE メッセージがサービス プロバイダーから TAPI に送信された場合、TAPI バージョン 1.4 以降を使用しているアプリケーションには、TAPI からメッセージが渡されます。古い TAPI バージョンをネゴシエートしているアプリケーションには、通知が届きません。
アドレスのどのようなステータス変化に関するメッセージがアプリケーションに送信されるかを表すビット配列。このパラメータには、次の LILINEADDRESSSTATE_定数が入ります。
LONG WINAPI lineSetTollList( HLINEAPP hLineApp, DWORD dwDeviceID, LPCSTR lpszAddressIn, DWORD dwTollListOption );
lineInitializeEx によって返されるアプリケーションのハンドル。アプリケーションがまだ lineInitializeEx 関数を呼び出していない場合は、hLineApp パラメータを NULL に設定できます。
ダイヤル時に使用する回線デバイスのデバイス ID。これにより、回線ごとに異なるダイヤリング手順を、変換処理の際に適用することができます。
処理を実行するために必要なプレフィックス情報の抽出元となるアドレスを格納する NULL 終端文字列へのポインタ。このパラメータは NULL 以外に設定し、正規アドレス形式を使用する必要があります。
実行するトール リスト操作。このパラメータには、LINETOLLLISTOPTION_ 定数のうちの 1 つだけが入ります。
lineSetupConference 関数は、hCall パラメータが指定した既存の 2 者間コールの電話会議を開始します。電話会議およびコンサルト コールが確立され、アプリケーションにそれぞれのハンドルが返ります。このコンサルト コールを使用して、サードパーティをダイヤルします。元の 2 者間コールはこの電話会議によって置き換えられます。また、このコンサルト コールの宛先アドレスをアプリケーションで指定すると、PBX からこのコールをアプリケーションに対してダイヤルできるようになります。
LONG lineSetupConference (HCALL hCall, HLINE hLine, LPHCALL lphConfCall, LPHCALL lphConsultCall, DWORD dwNumParties, LPLINECALLPARAMS const lpCallParams );
既存の 2 者間コールのハンドル。アプリケーションをコールのオーナーにします。
元の 2 者間コールが確立された回線。hCall が必ず設定されるため、このパラメータは使用されません。
電話会議ハンドルへのポインタ。サービス プロバイダーは、アプリケーションにこのコールを割り当て、ハンドルを返します。
コンサルト コールへのポインタ。コール パラメータで宛先アドレスが指定されていない場合は、このコール ハンドルを使用してコンサルト コールがダイヤルされます。宛先アドレスが指定されている場合は、このハンドルを使用してコンサルト コールが確立されます。
電話会議の参加者数。現行の Cisco Unified TAPI サービス プロバイダーでは、3 者間の電話会議がサポートされています。
コンサルト コールのセットアップに使用するコール パラメータ。電話会議のセットアップ時にコンサルト コールをダイヤルする場合、アプリケーションで宛先アドレスを指定できます。
lineSetupTransfer 関数は、hCall パラメータで指定されたコールの転送を開始します。この関数は、コンサルト コール(lphConsultCall)を確立し、転送先となる通話者をダイヤルする際にはこのコンサルト コールが使用できます。アプリケーションは、lphConsultCall パラメータに対するオーナー特権を取得します。
LONG lineSetupTransfer( HCALL hCall, LPHCALL lphConsultCall, LPLINECALLPARAMS const lpCallParams );
転送するコールのハンドル。アプリケーションをそのコールのオーナーにして、hCall のコール状態を connected にします。
hCall ハンドルへのポインタ。ここには、一時的なコンサルト コールを識別するハンドルが読み込まれます。転送のためのコール セットアップが行われると、コンサルト コールが自動的に割り当てられます。これにより、lineDial を使用して、そのコールの新しい転送先に関連付けられたアドレスをダイヤルすることが可能になります。発信者は、転送が成立するまでの間、このコンサルト コールを通じて会話を続けることができます。hConsultCall のコール状態はあてはまりません。
この転送手順は、一部の回線デバイスに対しては有効になりません。そのような場合は、新規のコンサルト コールを無視し、(lineUnhold を使用して)既存のコールの保留を解除して、転送先を識別する必要があります。クロスアドレス コール転送をサポートしている交換機の場合は、転送するコールとコンサルト コールとが別々のアドレス上に存在している場合があります。また、コンサルト コールを転送先へのまったく新しいコールとしてセットアップする必要もあります(lineMakeCall を使用します)。使用可能な転送方式は、コールのアドレス機能で指定されます。
lpCallParams フィールドの dwNoAnswerTimeout 属性がチェックされて、その値がゼロでなかった場合、そこで指定されている時間内に応答がなかったときは、コールの接続が自動的に解除されます。
LONG lineShutdown( HLINEAPP hLineApp );
アプリケーションによる回線 API の使用状態のハンドル。
LONG WINAPI lineTranslateAddress( HLINEAPP hLineApp, DWORD dwDeviceID, DWORD dwAPIVersion, LPCSTR lpszAddressIn, DWORD dwCard, DWORD dwTranslateOptions, LPLINETRANSLATEOUTPUT lpTranslateOutput );
lineInitializeEx によって返されるアプリケーションのハンドル。TAPI 2.0 アプリケーションの場合、lineInitializeEx 関数をまだ呼び出していないときは、hLineApp パラメータを NULL に設定できます。TAPI 1.4 アプリケーションの場合は、従来どおり、lineInitialize を最初に呼び出す必要があります。
ダイヤル時に使用する回線デバイスのデバイス ID。これにより、回線ごとに異なるダイヤリング手順を、変換処理の際に適用することができます。
アプリケーションがサポートしている TAPI の最上位バージョンを示します(一部の回線デバイスでは、lineNegotiateAPIVersion がこの値をネゴシエートしない場合もあります)。
変換を実行するために必要な情報の抽出元となるアドレスを格納する NULL 終端文字列へのポインタ。このパラメータには、正規アドレス形式、またはダイヤル可能なディジットで構成された任意の文字列(非正規)のいずれかを使用する必要があります。このパラメータは NULL にできません。AddressIn にサブアドレスまたは名前フィールドが含まれている場合や、CR および LF 文字によって最初のアドレスから分離された別のアドレスが指定されている場合は、最初のアドレスだけが変換されます。
ダイヤルに使用するクレジット カード。このパラメータは、dwTranslateOptions の CARDOVERRIDE ビットが設定されている場合にだけ有効です。レジストリの [Cards] セクションに含まれる Card エントリの固定 ID(lineTranslateCaps で取得)をこのパラメータで指定すると、その ID が、CurrentLocation の定義で指定されている PreferredCardID の代わりに使用されます。このパラメータを指定しても、現在の Location エントリの PreferredCardID パラメータはレジストリ内で変更されません。このオーバーライド動作は、現在の変換操作だけに適用されます。dwTranslateOptions の CARDOVERRIDE ビットが設定されていない場合、このパラメータは無効になります。
アドレスをダイヤル可能文字列に変換する前に実行される関連処理。このパラメータは、LINETRANSLATEOPTION_ 定数の 1 つを使用します。
(注) | LINETRANSLATEOPTION_CANCELCALLWAITING ビットを設定した場合は、LINECALLPARAMS 構造体の dwCallParamFlags メンバで LINECALLPARAMFLAGS_SECURE ビットも設定します(これは lpCallParams パラメータを使用して lineMakeCall に渡されます)。このアクションにより、回線デバイスがダイヤル可能なディジットを使用することによって、コールの中断を妨げる可能性がなくなります。 |
変換処理の出力結果を格納するためにアプリケーションで割り当られたメモリ領域へのポインタ(LINETRANSLATEOUTPUT 型)。lineTranslateAddress を呼び出す前に、この構造体の dwTotalSize メンバを設定しておく必要があります。このメンバは、返された情報を格納するために TAPI が使用できるメモリの量を指定します。
lineTranslateDialog 関数は、アプリケーションモーダル ダイアログボックスを表示します。ユーザはこのダイアログボックスを使用して、ダイヤルする電話番号の現在の場所を変更したり、場所や電話カードに関するパラメータを調整したり、結果を確認することができます。
LONG WINAPI lineTranslateDialog( HLINEAPP hLineApp, DWORD dwDeviceID, DWORD dwAPIVersion, HWND hwndOwner, LPCSTR lpszAddressIn );
lineInitializeEx によって返されるアプリケーションのハンドル。アプリケーションがまだ lineInitializeEx 関数を呼び出していない場合は、hLineApp パラメータを NULL に設定できます。
ダイヤル時に使用する回線デバイスのデバイス ID。これにより、回線ごとに異なるダイヤリング手順を、変換処理の際に適用することができます。
アプリケーションがサポートしている TAPI の最上位バージョンを示します(dwDeviceID が示す回線デバイスでは、lineNegotiateAPIVersion によってこの値がネゴシエートされない場合もあります)。
ダイアログボックスに関連付けるウィンドウのハンドル。関数の実行中に生成されるウィンドウを特定のオーナー ウィンドウに関連付ける必要がない場合は、NULL にして、これを示すことができます。
電話番号を格納する NULL 終端文字列へのポインタ。この電話番号は、ユーザが場所のパラメータに変更を加えた結果をダイアログボックスの下部で表示するために使用されます。この番号は正規形式で記述されている必要があります。正規形式でない場合は、ダイアログボックスの電話番号部分が表示されません。このポインタは NULL にしておくことができます。NULL にすると、ダイアログボックスの電話番号部分が表示されません。lpszAddressIn パラメータにサブアドレスまたは名前フィールドが含まれている場合や、CR および LF 文字によって最初のアドレスから分離された別のアドレスが指定されている場合は、最初のアドレスだけがダイアログボックス内で使用されます。
LONG lineUnhold( HCALL hCall );
取得するコールのハンドル。アプリケーションは、このコールのオーナーになっている必要があります。有効な hCall のコール状態は、onHold、onHoldPendingTransfer、または onHoldPendingConference です。
LONG WINAPI lineUnpark(HLINE hLine, DWORD dwAddressID, LPHCALL lphCall, LPCSTR lpszDestAddress );
コールのパークを解除するオープン状態の回線デバイスのハンドル。
パークの解除を行う hLine 上のアドレス。アドレス ID とアドレスは固定的に関連付けられているため、オペレーティング システムをアップグレードしてもアドレス ID は変更されません。
パーク解除されたコールのハンドルが返される HCALL 型の位置へのポインタ。このハンドルは、取得したコールにそれまで関連付けられていた他のどのハンドル(そのコールが最初にパークされた際に関連付けられていたハンドルなど)とも関連付けられていません。当初は、このアプリケーションがこのコールの唯一のオーナーとして機能します。
コールがパークされているアドレスが入る、NULL で終端された文字バッファへのポインタ。このアドレスは、標準のダイヤル可能アドレス形式で表示されます。
このセクションでは、Cisco Unified TSP でサポートされている回線メッセージについて説明します。これらのメッセージは、Cisco Unified Communications Manager における新規コールの着信など、非同期イベントをアプリケーションに通知します。これらのメッセージは、アプリケーションが LineInitializeEx で指定した方式で送信されます。
。LINE_ADDRESSSTATE メッセージは、アプリケーションによって現在オープンされている回線上で、アドレスのステータスが変化したときに送信されます。アプリケーションは、lineGetAddressStatus を呼び出して、そのアドレスの現在の状態を確認できます。
LINE_ADDRESSSTATE dwDevice = (DWORD) hLine; dwCallbackInstance = (DWORD) hCallback; dwParam1 = (DWORD) idAddress; dwParam2 = (DWORD) AddressState; dwParam3 = (DWORD) 0;
回線デバイスのハンドル。
回線をオープンする際に渡されるコールバック インスタンス。
ステータスが変化したアドレスのアドレス ID。
次のリストは、アドレス ステータス項目以外の項目に変化があったことを示します。アプリケーションは、現在のアドレス ステータスを調べて、変化した項目を確認する必要があります。
アドレス ステータスのデバイス固有項目に変化があったことを示します。
アドレスの状態がアイドルに変わった(現在そのアドレスを使用しているステーションが存在しない)ことを示します。
アドレスの状態が、アイドル状態、またはブリッジされている複数のステーションによって使用されていた状態から、1 つのステーションだけによって使用されている状態に変わったことを示します。
モニタまたはブリッジされているアドレスの状態が、1 つのステーションによって使用されている状態から、複数のステーションによって使用されている状態に変わったことを示します。
アドレス上のコール数が変化したことを示します。この変化は、そのアドレスで新規のインバウンド コールやアウトバウンド コールがあったり、コールの保留ステータスが変化したなどのイベントの結果です。
アドレスの転送ステータスに変化があったことを示します(応答なし条件の基準となる呼び出し音の回数など)。アプリケーションは、そのアドレスのステータスをチェックして、そのアドレスの現在の転送ステータスに関する詳細を確認する必要があります。
アドレスのターミナル設定に変化があったことを示します。
ユーザまたはその他の要因によって設定が変更されたために、そのアドレスに関する LINEADDRESSCAPS 構造体のメンバが 1 つ以上変更されたことを示します。アプリケーションは、lineGetAddressCaps を使用して、最新状態の構造体を読み込む必要があります。バージョン 1.4 よりも古い API をサポートしているアプリケーションは、LINEDEVSTATE_REINIT メッセージを受信するため、最新の情報を取得するには、アプリケーションをシャット ダウンして、TAPI との接続を再初期化する必要があります。
このパラメータは使用されません。
LINE_APPNEWCALL メッセージは、(アプリケーションから API を呼び出さずに)新規のコール ハンドルがアプリケーションのために自発的に作成されるときに、アプリケーションに通知します(その場合、このハンドルはポインタ パラメータを介して関数に渡されます)。
LINE_APPNEWCALL dwDevice = (DWORD) hLine; dwCallbackInstance = (DWORD) dwInstanceData; dwParam1 = (DWORD) dwAddressID; dwParam2 = (DWORD) hCall; dwParam3 = (DWORD) dwPrivilege;
コールが確立された回線デバイスに対するアプリケーションのハンドル。
そのコールで使用される回線をオープンする際に渡されるコールバック インスタンス。
そのコールが存在する回線のアドレスの ID。
新しいコールに対するアプリケーションのハンドル。
新しいコールに対するアプリケーションの特権(LINECALLPRIVILEGE_OWNER または LINECALLPRIVILEGE_MONITOR)。
TSPI の LINE_CALLDEVSPECIFIC メッセージは、コール上で発生したデバイス固有のイベントを TAPI に通知するために送信されます。メッセージの意味および dwParam1 ~ dwParam3 パラメータの解釈方法は、デバイスによって異なります。
LINE_CALLDEVSPECIFIC htLine = (HTAPILINE) hLineDevice; htCall = (HTAPICALL) hCallDevice; dwMsg = (DWORD) LINE_CALLDEVSPECIFIC; dwParam1 = (DWORD) DeviceData1; dwParam2 = (DWORD) DeviceData2; dwParam3 = (DWORD) DeviceData3;
回線デバイスの TAPI opaque オブジェクト ハンドル。
コール デバイスの TAPI opaque オブジェクト ハンドル。
値 LINE_CALLDEVSPECIFIC。
デバイス固有
デバイス固有
デバイス固有
TAPI LINE_CALLINFO メッセージは、指定されたコールのコール情報が変更されたときに送信されます。アプリケーションは、lineGetCallInfo を呼び出して、現在のコール情報を確認できます。
LINE_CALLINFO hDevice = (DWORD) hCall; dwCallbackInstance = (DWORD) hCallback; dwParam1 = (DWORD) CallInfoState; dwParam2 = (DWORD) 0; dwParam3 = (DWORD) 0;
コールのハンドル。
そのコールの回線をオープンする際に渡されるコールバック インスタンス。
変更されたコール情報の項目。1 つ以上の
LINECALLINFOSTATE_ 定数を指定できます。
このパラメータは使用されません。
このパラメータは使用されません。
LINE_CALLSTATE メッセージは、指定されたコールのステータスが変化するときに送信されます。通常、この種のメッセージは、コールのライフタイム期間内に発生します。アプリケーションは、このメッセージによって新規の着信コールがあることを通知されます。この新規コールの状態は、offering です。アプリケーションは、lineGetCallStatus 関数を使用して、そのコールの現在のステータスに関する詳細を取得できます。
LINE_CALLSTATE dwDevice = (DWORD) hCall; dwCallbackInstance = (DWORD) hCallback; dwParam1 = (DWORD) CallState; dwParam2 = (DWORD) CallStateDetail; dwParam3 = (DWORD) CallPrivilege;
コールのハンドル。
このコールで使用する回線をオープンする際に渡されるコールバック インスタンス。
コールがアイドル状態のままです(実際には、コールが存在しません)。
コールがステーションにオファーされました(新しいコールが到着したことが通知されています)。一部の環境では、offering 状態のコールが出現しても、ユーザへの通知が自動的には行われません。交換機が回線に対して呼び出し音を鳴らすように指示を出すことで、警報が出されます。その場合は、どのコール状態にも影響しません。
システムがコールをオファーし、そのコールが受け入れられました。これにより、現在のオーナー アプリケーションがそのコールに応答する責任を引き受けたことが、他の(モニタ中の)アプリケーションに対して通知されます。ISDN の場合は、発呼側と着信側の両方に対する通知が開始されたことも示しています。
このコールは電話会議のメンバであり、論理的には connected 状態です。
このコールは、交換機からのダイヤル トーンを受信しています。ダイヤル トーンは、交換機側で着信番号を受信する準備が整っていることを示しています。
このコールを介して、宛先アドレス情報(電話番号)が交換機に送信されています。lineGenerateDigits は回線の状態を DIALING にしません。
このコールは、着信側アドレスからのリングバックを受信しています。リングバックは、相手側のステーションにコールが到達していて、呼び出し音が鳴っていることを示します。
このコールは会議に追加されましたが、現在は保留状態になっています。
コールが確立され、接続が確立されました。発信元アドレスと宛先アドレスの間では、このコールを介して情報を交換することができます。
このコールはダイヤリングが完了し、交換機または電話網を通過しています。
交換機がこのコールを保留にしています。
現在このコールは保留されており、別の番号への転送を待機しています。
このコールは、リモート側によって接続解除されました。
このコールの状態は不明です。コール プログレスを検知する実装が、その状態の原因になっている可能性があります。
Cisco Unified TSP は、Cisco Unified Communications Manager の設定内のコール状態についてさらに詳しい情報を示す 2 つの新しいコール状態をサポートしています。標準の TAPI コール状態は、LINECALLSTATE_UNKNOWN に設定されて、次のコール状態が不明なコール状態に論理和として追加されます。
#define CLDSMT_CALL_PROGRESSING_STATE 0x0100000
Progressing 状態は、ネットワーク上でコールが進行中であることを示しています。このコール状態を受信するには、拡張バージョン 0x00050001 をアプリケーションでネゴシエートする必要があります。
#define CLDSMT_CALL_WAITING_STATE 0x02000000
Waiting 状態は、Referrer の回線で REFER 要求が進行中で、アプリケーションはこのコールに対して別の機能を要求できないことを示しています。要求を行った場合、結果はすべて LINEERR_INVALCALLSTATE になります。このコール状態を受信するには、拡張バージョン 0x00070000 をアプリケーションでネゴシエートする必要があります。
#define CLDSMT_CALL_WHISPER_STATE 0x03000000
WHISPER 状態は、片通話モードでインターコム コールが接続されていることを示します。インターコムの発信側から発行できる要求は、インターコム コールの終了だけです。また、着信側から発行できる要求は、応答(Talkback)とコールの終了だけです。その他の要求を発行すると、LINEERR_OPERATIONUNAVAIL が返されます。
コール状態別の情報。
コールが現在のステーションで接続されます(このコールでは、現在のステーションが受信者として機能します)。
このコールは他の 1 つ以上のステーションでアクティブになっていますが、現在のステーションはそのコールの受信者ではありません。
原因コード = DISCONNECTMODE_TEMPFAILURE および lineState = LINEDEVSTATE_INSERVICE でコールが接続解除された場合は、アプリケーション側でコールをドロップする必要があります。アプリケーションでデバイスのメディア終端を行っている場合は、同じコールの RTP ストリームを停止するのもアプリケーションの責任になります。この場合、Cisco Unified TSP からは送信停止イベントまたは受信停止イベントが送信されません。この動作は、IP Phone の場合もまったく同じです。メディアを停止するには、接続解除された(DISCONNECTMODE_TEMPFAILURE の)コールをユーザが IP フォン上で切る必要があります。回線がアウト オブ サービス(LINEDEVSTATE_OUTOFSERVICE)になって、回線上のコールが IDLE と報告された場合も、RTP ストリームを停止させる責任はアプリケーションにあります。
(注) | 拡張バージョン 0x00050001 以上をネゴシエートする場合、アプリケーションはデバイス固有の CLDSMT_CALL_PROGRESSING_STATE = 0x01000000 と LINECALLSTATE_UNKNOWN を受信できます。これにより原因コードが、dwParam2 で標準の Q931 原因コードとして報告されます。 |
dwParam1 が LINECALLSTATE_DIALTONE を指定する場合、dwParam2 にはダイヤル トーン モードの詳細が格納されます。このパラメータには、次の LINEDIALTONEMODE_ 定数が入ります。
ダイヤル トーン モードを取得できないため、認識できません。
このコールは現在のステーションで(LINEDEVSTATE_RINGING メッセージとともに)呼び出し音を鳴らしています。コールに自動的に応答するように設定されたアプリケーションは、そのコールに応答します。TAPI バージョン 1.4 以降では、コール状態のモードがゼロの場合、アプリケーションではその値がアクティブ(ブリッジされていないアドレスの状態)であると見なします。
(注) | Cisco Unified TSP は、コールが受け入れられて、LINECALLSTATE_ACCEPTED 状態に移行するまでは、LINEDEVSTATE_RINGING メッセージを送信しません。IP Phone は、コールを自動的に受け入れます。CTI ポートおよび CTI ルート ポイントでは、コールを自動的に受け入れません。このタイプのデバイスでコールを受け取るには、lineAccept() 関数を呼び出します。 |
これはリモート側による通常の接続解除要求を示します。このコールは通常の方法で終了されました。
接続解除要求の原因が不明です。
リモート ユーザがこのコールを拒否しました。
リモート ユーザのステーションが使用中です。
リモート ユーザのステーションが応答しません。
このメッセージは、ネットワークが輻輳していることを示します。
接続解除の原因を取得できないため、認識できません。
FAC/CMC の機能によりコールが接続解除されたことを示します。
(注) | LINEDISCONNECTMODE_FACCMC が返されるのは、回線に対してネゴシエートされた拡張バージョンが 0x00050000 (6.0(1)) 以上の場合に限られます。ネゴシエートされた拡張バージョンが 0x00050000 未満の場合、TSP は接続解除モードを LINEDISCONNECTMODE_UNAVAIL に設定します。 |
このパラメータがゼロの場合は、このコールに対するこのアプリケーションの特権が変化していないことを示しています。
このパラメータがゼロでない場合は、このコールに対するこのアプリケーションの特権が指定されます。これは、次に示す状況で発生します。(1)アプリケーションが初めてコールのハンドルを受け取ったとき。(2)アプリケーションがコールのハンドオフ先になったとき(このアプリケーションが、すでにそのコールのオーナーである場合も含む)。このパラメータには、次に示す LINECALLPRIVILEGE_ 定数が入ります。
このアプリケーションには、モニタ特権が与えられています。
このアプリケーションには、オーナー特権が与えられています。
LINE_CLOSE メッセージは、指定された回線デバイスが強制的にクローズされると送信されます。このメッセージが送信されると、その回線デバイスのハンドル、およびその回線上のコールのコール ハンドルが無効になります。
LINE_CLOSE dwDevice = (DWORD) hLine; dwCallbackInstance = (DWORD) hCallback; dwParam1 = (DWORD) 0; dwParam2 = (DWORD) 0; dwParam3 = (DWORD) 0;
クローズされた回線デバイスのハンドル。このハンドルは無効になります。
このコールで使用する回線をオープンする際に渡されるコールバック インスタンス。
このパラメータは使用されません。
このパラメータは使用されません。
このパラメータは使用されません。
LINE_CREATE メッセージは、新しい回線デバイスが作成されたことをアプリケーションに通知します。
(注) | CTI Manager のクラスタ サポート、エクステンション モビリティ、変更通知、およびユーザがディレクトリに追加されると、LINE_CREATE イベントが生成されます。 |
LINE_CREATE dwDevice = (DWORD) 0; dwCallbackInstance = (DWORD) 0; dwParam1 = (DWORD) idDevice; dwParam2 = (DWORD) 0; dwParam3 = (DWORD) 0;
このパラメータは使用されません。
このパラメータは使用されません。
新たに作成された電話機の dwDeviceID。
このパラメータは使用されません。
このパラメータは使用されません。
LINE_DEVSPECIFIC メッセージは、回線、アドレスまたはコール上で発生したデバイス固有のイベントを、アプリケーションに通知します。メッセージの意味およびパラメータの解釈方法は、デバイスによって異なります。
LINE_DEVSPECIFIC dwDevice = (DWORD) hLineOrCall; dwCallbackInstance = (DWORD) hCallback; dwParam1 = (DWORD) DeviceSpecific1; dwParam2 = (DWORD) DeviceSpecific2; dwParam3 = (DWORD) DeviceSpecific3;
このデバイス固有のパラメータは、回線デバイスまたはコールのハンドルを指定します。
回線をオープンする際に渡されるコールバック インスタンス。
デバイス固有です。
デバイス固有です。
デバイス固有です。
この回線メッセージは、Cisco Unified Communications Manager Release 6.0 で追加されました。この回線メッセージにより、サイレント(DND)変更通知イベントが有効になります。DND の設定または状態が変更されると、Cisco TSP からアプリケーションに LINE_DEVSPECIFICFEATURE メッセージを使用して通知されます。この変更通知を受信するには、lineDevSpecific SLDST_SET_STATUS_MESSAGES 要求を使用して DEVSPECIFIC_DONOTDISTURB_CHANGED メッセージ フラグを有効にする必要があります。
LINE_DEVSPECIFICFEATURE メッセージは、回線デバイス上で発生したデバイス固有のイベントをアプリケーションに通知するために送信されます。DND 変更通知の場合、このメッセージには、デバイス上で発生した変更のタイプと、その結果としての機能ステータスまたは設定されたオプションに関する情報が含まれます。
dwDevice = (DWORD) hLine; dwCallbackInstance = (DWORD) hCallback; dwParam1 = (DWORD) PHONEBUTTONFUNCTION_DONOTDISTURB; dwParam2 = (DWORD) typeOfChange; dwParam3 = (DWORD) currentValue; enum CiscoDoNotDisturbOption { DoNotDisturbOption_NONE = 0, DoNotDisturbOption_RINGEROFF = 1, DoNotDisturbOption_REJECT = 2 }; enum CiscoDoNotDisturbStatus { DoNotDisturbStatus_UNKNOWN = 0, DoNotDisturbStatus_ENABLED = 1, DoNotDisturbStatus_DISABLED = 2 }; enum CiscoDoNotDisturbNotification { DoNotDisturb_STATUS_CHANGED = 1, DoNotDisturb_OPTION_CHANGED = 2 };
回線デバイスのハンドル。
回線をオープンする際に渡されるコールバック インスタンス。
サイレント変更通知の場合、常に PHONEBUTTONFUNCTION_DONOTDISTURB に同じ。
変更のタイプを示し、次のいずれかの enum 値になります。
enum CiscoDoNotDisturbNotification { DoNotDisturb_STATUS_CHANGED = 1, DoNotDisturb_OPTION_CHANGED = 2 };
dwParam2 の値がステータスの変更を示している(DoNotDisturb_STATUS_CHANGED である)場合、このパラメータは次のいずれかの enum 値になります。
enum CiscoDoNotDisturbStatus { DoNotDisturbStatus_UNKNOWN = 0, DoNotDisturbStatus_ENABLED = 1, DoNotDisturbStatus_DISABLED = 2 };
dwParam2 の値がオプションの変更を示している(DoNotDisturb_OPTION_CHANGED である)場合、このパラメータは次のいずれかの enum 値になります。
enum CiscoDoNotDisturbOption { DoNotDisturbOption_NONE = 0, DoNotDisturbOption_RINGEROFF = 1, DoNotDisturbOption_REJECT = 2 };
TAPI の LINE_GATHERDIGITS メッセージは、バッファにある現在のディジットの収集要求が終了したかキャンセルされたときに送信されます。このメッセージをアプリケーションが受け取ると、ディジット バッファを確認できます。
LINE_GATHERDIGITS hDevice = (DWORD) hCall; dwCallbackInstance = (DWORD) hCallback; dwParam1 = (DWORD) GatherTermination; dwParam2 = (DWORD) 0; dwParam3 = (DWORD) 0;
コールのハンドル。
回線をオープンする際に渡されるコールバック インスタンス。
ディジットの収集が終了した理由。このパラメータには、LINEGATHERTERM_定数のうちの 1 つだけが入ります。
ディジットの収集が完了した時点のチックカウント(Windows 起動後の経過時間)(ミリ秒単位)。バージョン 2.0 よりも古い TAPI の場合、このパラメータは使用されません。
TAPI LINE_GENERATE メッセージは、現在のディジット生成またはトーン生成が終了したことをアプリケーションに通知します。1 つのコールに対して同時に処理できる生成要求は、1 つだけです。このメッセージは、ディジットまたはトーンの生成がキャンセルされた場合にも送信されます。
LINE_GENERATE hDevice = (DWORD) hCall; dwCallbackInstance = (DWORD) hCallback; dwParam1 = (DWORD) GenerateTermination; dwParam2 = (DWORD) 0; dwParam3 = (DWORD) 0;
コールのハンドル。
回線をオープンする際に渡されるコールバック インスタンス。
ディジットまたはトーンの生成が終了した原因。このパラメータには、LINEGENERATETERM_ 定数のうちの 1 つだけが入ります。
このパラメータは使用されません。
ディジットまたはトーンの生成が完了した時点のチックカウント(Windows 起動後の経過時間)(ミリ秒単位)。バージョン 2.0 よりも古い API の場合、このパラメータは使用されません。
TAPI LINE_LINEDEVSTATE メッセージは、回線デバイスの状態が変更されると送信されます。アプリケーションは、lineGetLineDevStatus を呼び出すことで、その回線の新しいステータスを確認できます。
LINE_LINEDEVSTATE hDevice = (DWORD) hLine; dwCallbackInstance = (DWORD) hCallback; dwParam1 = (DWORD) DeviceState; dwParam2 = (DWORD) DeviceStateDetail1; dwParam3 = (DWORD) DeviceStateDetail2;
回線デバイスのハンドル。dwParam1 が LINEDEVSTATE_REINIT の場合、このパラメータは NULL になります。
回線をオープンする際に渡されるコールバック インスタンス。dwParam1 パラメータが LINEDEVSTATE_REINIT の場合、dwCallbackInstance パラメータは無効になり、ゼロに設定されます。
変化した回線デバイス ステータスの項目。このパラメータには、1 つ以上の LINEDEVSTATE_ 定数を指定できます。
回線デバイスが Energywise DeepSleep/PowersavePlus モードに移行して登録解除することを示します。
このパラメータの解釈は dwParam1 の値に依存します。dwParam1 が LINEDEVSTATE_RINGING の場合、dwParam2 には交換機が回線に対して呼び出し音を鳴らすように指示する際に使用する呼び出し音モードが格納されます。有効な呼び出し音モードには、1 から dwNumRingModes の間の数字が含まれます(dwNumRingModes は回線デバイス機能を指定します)。
新しい API メッセージが REINIT メッセージに変換された結果として、TAPI が REINIT メッセージを発行し、そのメッセージの dwParam1 が LINEDEVSTATE_REINIT になっている場合は、dwParam2 に、元のメッセージ(たとえば、LINE_CREATE または LINE_LINEDEVSTATE)の dwMsg パラメータが格納されます。dwParam2 がゼロの場合、その REINIT メッセージは、本物の REINIT メッセージを表します。アプリケーションは、できるだけ早く lineShutdown を呼び出す必要があります。
dw Param1 が LINEDEVSTATE_OUTOFSERVICE の場合、dwParam2 には、回線デバイスが EnergywiseDeepSleep に移行して登録解除するときの EnergyWisePowerSavePlus 理由が格納されます。
このパラメータの解釈は dwParam1 の値に依存します。dwParam1 が LINEDEVSTATE_RINGING の場合、dwParam3 にはこの呼び出し音イベントの呼び出し音回数が格納されます。呼び出し音のカウントは、ゼロから始まります。
dwParam1 が LINEDEVSTATE_REINIT で、新しい API メッセージが REINIT メッセージに変換された結果として、TAPI がメッセージを発行した場合、dwParam3 に、元のメッセージの dwParam1 パラメータが格納されます(たとえば、dwParam2 が LINE_LINEDEVSTATE の場合は、LINEDEVSTATE_TRANSLATECHANGE やその他の LINEDEVSTATE_ 値。dwParam2 が LINE_CREATE の場合は、新しいデバイス ID)。
LINE_MONITORDIGITS メッセージは、ディジットが検出されると送信されます。このメッセージの送信は、lineMonitorDigits 関数で制御します。
LINE_MONITORDIGITS dwDevice = (DWORD) hCall; dwCallbackInstance = (DWORD) hCallback; dwParam1 = (DWORD) Digit; dwParam2 = (DWORD) DigitMode; dwParam3 = (DWORD) 0;
コールのハンドル。
このコールで使用される回線をオープンする際に渡されるコールバック インスタンス。
下位バイトは、最後に受け取ったディジットを ASCII 形式で格納します。
検出されたディジット モード。このパラメータには、次の LINEDIGITMODE_ 定数のうちの 1 つだけが入ります。
ディジットを DTMF トーンとして検出します。DTMF で有効なディジットは、「0」~「9」、「*」、および「#」です。
指定されたディジットが検出された時点の「チック カウント」(Windows 起動後の経過時間)(ミリ秒単位)。バージョン 2.0 よりも古い API の場合、このパラメータは使用されません。
LINE_MONITORTONE メッセージは、トーンが検出されると送信されます。このメッセージの送信は、lineMonitorTones 関数で制御します。
(注) | Cisco Unified TSP は、LINE_MONITORTONE を使用した無音検出だけをサポートしています。 |
LINE_MONITORTONE dwDevice = (DWORD) hCall; dwCallbackInstance = (DWORD) hCallback; dwParam1 = (DWORD) dwAppSpecific; dwParam2 = (DWORD) 0; dwParam3 = (DWORD) tick count;
コールのハンドル。
このコールで使用される回線をオープンした際に渡されたコールバック インスタンス。
検出されたトーンに関する、LINE_MONITORTONE 構造体のアプリケーション固有 dwAppSpecific メンバ。
このパラメータは使用されません。
指定されたディジットが検出された時点の「チック カウント」(Windows 起動後の経過時間)(ミリ秒単位)。
LINE_REMOVE メッセージは、回線デバイスが(システムから)削除されたことを、アプリケーションに通知します。通常、このパラメータは PCMCIA デバイスの取り外しなどの一時的な削除には使用されず、デバイスの恒久的な削除が行われた場合にだけ使用されます(TAPI が再初期化されると、サービス プロバイダーはそのデバイスに関する報告を送信しなくなります)。
(注) | CTI Manager のクラスタ サポート、エクステンション モビリティ、変更通知、およびユーザがディレクトリから削除されると、LINE_REMOVE イベントが生成されます。 |
LINE_REMOVE dwDevice = (DWORD) 0; dwCallbackInstance = (DWORD) 0; dwParam1 = (DWORD) dwDeviceID; dwParam2 = (DWORD) 0; dwParam3 = (DWORD) 0;
予約済み。ゼロに設定されます。
予約済み。ゼロに設定されます。
削除された回線デバイスの ID。
予約済み。ゼロに設定されます。
予約済み。ゼロに設定されます。
LINE_REPLY dwDevice = (DWORD) 0; dwCallbackInstance = (DWORD) hCallback; dwParam1 = (DWORD) idRequest; dwParam2 = (DWORD) Status; dwParam3 = (DWORD) 0;
LINE_REQUEST hDevice = (DWORD) 0; dwCallbackInstance = (DWORD) hRegistration; dwParam1 = (DWORD) RequestMode; dwParam2 = (DWORD) RequestModeDetail1; dwParam3 = (DWORD) RequestModeDetail2;
このパラメータは使用されません。
lineRegisterRequestRecipient で指定されたアプリケーションの登録インスタンス。
新たに処理待ちになった要求の要求モード。このパラメータには、LINEREQUESTMODE_定数が入ります。
dwParam1 が LINEREQUESTMODE_DROP に設定されている場合、dwParam2 にはドロップを要求するアプリケーションの hWnd が格納されます。それ以外の場合、dwParam2 は使用されません。
dwParam1 が LINEREQUESTMODE_DROP に設定されている場合、dwParam3 の下位の桁には、ドロップを要求しているアプリケーションによって指定された wRequestID が格納されます。それ以外の場合、dwParam3 は使用されません。
次の表は、Cisco Unified TSP がサポートする TAPI 回線デバイス構造体を示します。このセクションでは、TSP で設定される構造体メンバの取りうる値を示し、それらを使用する関数への相互参照も示します。構造体メンバの値が、デバイス、回線またはコールに固有の場合は、システムによって各条件の値が説明されます。
LINEAPPINFO 構造体は、現在実行中のアプリケーションに関する情報を格納します。LINEDEVSTATUS 構造体は、LINEAPPINFO 構造体の配列を格納できます。
typedef struct lineappinfo_tag { DWORD dwMachineNameSize; DWORD dwMachineNameOffset; DWORD dwUserNameSize; DWORD dwUserNameOffset; DWORD dwModuleFilenameSize; DWORD dwModuleFilenameOffset; DWORD dwFriendlyNameSize; DWORD dwFriendlyNameOffset; DWORD dwMediaModes; DWORD dwAddressID; } LINEAPPINFO, *LPLINEAPPINFO;
このコールに関連付けられた回線デバイスのハンドル。 |
|
このコールに関連付けられた回線デバイスのデバイス ID。 |
|
LINEBEARERMODE_SPEECH LINEBEARERMODE_VOICE |
|
CTI ポートおよび CTI ルート ポイント:LINEMEDIAMODE_AUTOMATEDVOICE LINEMEDIAMODE_INTERACTIVEVOICE |
|
この値は、API 実装およびサービス プロバイダーによって解釈されません。このコールのオーナーになっているアプリケーションのいずれでも、lineSetAppSpecific 関数を使用して、この値を設定することができます。 |
|
一部のテレフォニー環境では、交換機またはサービス プロバイダーによって、各コールに一意の ID が割り当てられます。これにより、転送やフォワーディングなどのさまざまなイベントを通じて 1 つのコールを追跡することが可能になります。これらのコール ID のドメインとその有効範囲は、サービス プロバイダーで定義されます。dwCallID メンバは、このような一意の ID をアプリケーションに提供します。Cisco Unified TSP では、dwCallID に各コールの「GlobalCallID」が格納されます。「GlobalCallID」は固有識別子を表しているので、アプリケーションは同じコールに関連付けられたすべてのコール ハンドルを識別することができます。 |
|
IP Phone および CTI ポート:LINECALLSTATE_ACCEPTED LINECALLSTATE_CONFERENCED LINECALLSTATE_CONNECTED LINECALLSTATE_DIALING LINECALLSTATE_DIALTONE LINECALLSTATE_DISCONNECTED LINECALLSTATE_IDLE LINECALLSTATE_OFFERING LINECALLSTATE_ONHOLD LINECALLSTATE_ONHOLDPENDCONF LINECALLSTATE_ONHOLDPENDTRANSFER LINECALLSTATE_PROCEEDING LINECALLSTATE_RINGBACK LINECALLSTATE_UNKNOWN |
|
CTI ルート ポイント(メディアなし):LINECALLSTATE_ACCEPTED LINECALLSTATE_DISCONNECTED LINECALLSTATE_IDLE LINECALLSTATE_OFFERING LINECALLSTATE_UNKNOWN CTI ルート ポイント(メディアあり):LINECALLSTATE_ACCEPTED LINECALLSTATE_BUSY LINECALLSTATE_CONNECTED LINECALLSTATE_DIALING LINECALLSTATE_DIALTONE LINECALLSTATE_DISCONNECTED LINECALLSTATE_IDLE LINECALLSTATE_OFFERING LINECALLSTATE_ONHOLD LINECALLSTATE_PROCEEDING LINECALLSTATE_RINGBACK LINECALLSTATE_UNKNOWN |
|
LINECALLSTATE_CONFERENCED LINECALLSTATE_CONNECTED LINECALLSTATE_DISCONNECTED LINECALLSTATE_IDLE LINECALLSTATE_OFFERING LINECALLSTATE_ONHOLD LINECALLSTATE_UNKNOWN |
|
IP Phone、CTI ポート、および CTI ルート ポイント(メディアあり): LINEDIGITMODE_DTMF |
|
CTI ポートおよび CTI ルート ポイント:LINEMEDIAMODE_AUTOMATEDVOICE LINEMEDIAMODE_INTERACTIVEVOICE |
|
すべてのデバイス:LINECALLORIGIN_CONFERENCE LINECALLORIGIN_EXTERNAL LINECALLORIGIN_INTERNAL LINECALLORIGIN_OUTBOUND LINECALLORIGIN_UNAVAIL LINECALLORIGIN_UNKNOWN |
|
LINECALLREASON_DIRECT LINECALLREASON_FWDBUSY LINECALLREASON_FWDNOANSWER LINECALLREASON_FWDUNCOND LINECALLREASON_PARKED LINECALLREASON_PICKUP LINECALLREASON_REDIRECT LINECALLREASON_REMINDER LINECALLREASON_TRANSFER LINECALLREASON_UNKNOWN LINECALLREASON_UNPARK |
|
このコールに対してオーナー特権を持ち、異なるコール ハンドルを使用しているアプリケーション モジュールの数。 |
|
このコールに対してモニタ特権を持ち、異なるコール ハンドルを使用しているアプリケーション モジュールの数。 |
|
すべてのデバイス:LINECALLPARTYID_ADDRESS LINECALLPARTYID_NAME LINECALLPARTYID_UNKNOWN LINECALLPARTYID_BLOCKED |
|
dwCallerIDOffset |
発信側 ID 番号情報を格納する可変サイズ フィールドのサイズ(バイト単位)、およびこのデータ構造体の先頭からのオフセット(バイト単位)。 |
dwCallerIDNameOffset |
発信側 ID 名前情報を格納する可変サイズ フィールドのサイズ(バイト単位)、およびこのデータ構造体の先頭からのオフセット(バイト単位)。 |
LINECALLPARTYID_ADDRESS LINECALLPARTYID_NAME LINECALLPARTYID_UNKNOWN |
|
dwCalledIDOffset |
着信側 ID 番号情報を格納する可変サイズ フィールドのサイズ(バイト単位)、およびこのデータ構造体の先頭からのオフセット(バイト単位)。 |
dwCalledIDNameOffset |
着信側 ID 名情報を格納する可変サイズ フィールドのサイズ(バイト単位)、およびこのデータ構造体の先頭からのオフセット(バイト単位)。 |
LINECALLPARTYID_ADDRESS LINECALLPARTYID_NAME LINECALLPARTYID_UNKNOWN LINECALLPARTYID_BLOCKED |
|
dwConnectedIDOffset |
接続先 ID 番号情報を格納する可変サイズ フィールドのサイズ(バイト単位)、およびこのデータ構造体の先頭からのオフセット(バイト単位)。 |
dwConnectedIDNameOffset |
接続先 ID 名前情報を格納する可変サイズ フィールドのサイズ(バイト単位)、およびこのデータ構造体の先頭からのオフセット(バイト単位)。 |
LINECALLPARTYID_ADDRESS LINECALLPARTYID_NAME LINECALLPARTYID_UNKNOWN LINECALLPARTYID_BLOCKED |
|
dwRedirectionIDOffset |
リダイレクト先 ID 番号情報を格納する可変サイズ フィールドのサイズ(バイト単位)、およびこのデータ構造体の先頭からのオフセット(バイト単位)。 |
dwRedirectionIDNameOffset |
リダイレクト先 ID 名前情報を格納する可変サイズ フィールドのサイズ(バイト単位)、およびこのデータ構造体の先頭からのオフセット(バイト単位)。 |
LINECALLPARTYID_ADDRESS LINECALLPARTYID_NAME LINECALLPARTYID_UNKNOWN |
|
dwRedirectingIDOffset |
リダイレクト元 ID 番号情報を格納する可変サイズ フィールドのサイズ(バイト単位)、およびこのデータ構造体の先頭からのオフセット(バイト単位)。 |
dwRedirectingIDNameOffset |
リダイレクト元 ID 名前情報を格納する可変サイズ フィールドのサイズ(バイト単位)、およびこのデータ構造体の先頭からのオフセット(バイト単位)。 |
dwAppNameOffset |
コールを最初に発信したアプリケーション、コールを受け入れたアプリケーション、またはコールに応答したアプリケーションのユーザフレンドリな名前が入る可変サイズ フィールドのサイズ(バイト単位)、およびこのデータ構造体の先頭からのオフセット(バイト単位)。これは、アプリケーションが lineInitializeEx で指定できる名前を指定します。このような名前がアプリケーションで指定されていない場合は、アプリケーション モジュールのファイル名が代わりに使用されます。 |
dwDisplayableAddressOffset |
|
dwCalledPartyOffset |
|
dwCommentOffset |
|
dwDisplayOffset |
|
dwUserUserInfoOffset |
|
dwHighLevelCompOffset |
|
dwLowLevelCompOffset |
|
dwChargingInfoOffset |
|
dwTerminalModesOffset |
|
dwDevSpecificOffset |
dwExtVersion が 0x00060000(6.0)以上の場合は、このフィールドが TSP_Unicode_Party_Names 構造体を指します。 dwExtVersion が 0x00070000(7.0)以上の場合、このフィールドは、SRTP 構造体、DSCPValueForAudioCalls 値およびパーティション情報へのポインタがある共通構造体も指します。この構造体の定義については、LINECALLINFOを参照してください。 ExtendedCallInfo 構造体には、このコールの callinfo または callstatus の変更原因となった最後の機能に関連する理由を示す ExtendedCallReason が格納されています。ExtendedCallInfo には、コールのすべての通話者の SIP URL 情報も格納されています。 dwExtVersion が 0x00080000(8.0)以上の場合、このフィールドは、CallSecurityStatus 構造体へのポインタがある共通構造体も指します。 IP フォン:dwExtVersion が 0x00080000(8.0)以上の場合、このフィールドは、CallAtributeInfo 構造体および CCMCallID 構造体へのポインタがある共通構造体も指します。これらの構造体の定義については、後述します。 dwExtVersion が 0x00080000(8.0)以上の場合、このフィールドは、CallSecurityStatus 構造体へのポインタがある共通構造体も指します。 |
CallAttributeType:このフィールドは、通常のコール、モニタリング元のコール、モニタリング先のコール、および録音元のコールの DN.Partition.DeviceName に関する情報を格納します。 PartyDNOffset および PartyDNSize は、モニタリング元、モニタリング先、録音元通話者の DN 情報を格納する可変サイズ フィールドのサイズ(バイト単位)、および LINECALLINFO データ構造体の先頭からのオフセット(バイト単位)を提供します。PartyPartitionOffset PartyPartitionSize は、モニタリング元、モニタリング先、録音元通話者の DN 情報を格納する可変サイズ フィールドのサイズ(バイト単位)、および LINECALLINFO データ構造体の先頭からのオフセット(バイト単位)を提供します。 DevcieNameSize は、モニタリング元、モニタリング先、録音元通話者のデバイス名を格納する可変サイズ フィールドのサイズ(バイト単位)、および LINECALLINFO データ構造体の先頭からのオフセット(バイト単位)を提供します。OverallCallSecurityStatus は、2 者間コールと電話会議のセキュリティ状態を格納します。CCMCallID フィールドは、各コール レッグの CCM コール ID を格納します。 |
|
dwCallDataOffset |
|
dwSendingFlowspecOffset |
|
dwReceivingFlowspecOffset |
LINECALLLIST 構造体は、コール ハンドルのリストを表します。lineGetNewCalls および lineGetConfRelatedCalls 関数は、この型の構造体を返します。
(注) | この構造体を拡張してはいけません。 |
typedef struct linecalllist_tag { DWORD dwTotalSize; DWORD dwNeededSize; DWORD dwUsedSize; DWORD dwCallsNumEntries; DWORD dwCallsSize; DWORD dwCallsOffset; } LINECALLLIST, FAR *LPLINECALLLIST;
wCallsOffset |
HCALL サイズのハンドルの配列が入る可変サイズ フィールドのサイズ(バイト単位)、およびこのデータ構造体の先頭からのオフセット(バイト単位)。 |
dwOrigAddressOffset |
|
dwDisplayableAddressOffset |
|
dwCalledPartyOffset |
|
dwCommentOffset |
|
dwUserUserInfoOffset |
|
dwHighLevelCompOffset |
|
dwLowLevelCompOffset |
|
dwDevSpecificOffset |
|
dwTargetAddressOffset |
|
dwSendingFlowspecOffset |
|
dwReceivingFlowspecOffset |
|
dwDeviceClassOffset |
|
dwDeviceConfigOffset |
|
dwCallDataOffset |
|
ダイヤル完了後、このコールが PROCEEDING 状態または RINGBACK 状態で待機できる秒数。この待機時間が経過すると、サービス プロバイダーが LINECALLSTATE_DISCONNECTED および LINEDISCONNECTMODE_NOANSWER を使用して、このコールを自動的に中止します。この値が 0 の場合は、コールの自動中止が行われないことを示しています。 |
|
dwCallingPartyIDOffset |
LINECARDENTRY 構造体は、電話カードに関する情報を提供します。LINETRANSLATECAPS 構造体は、LINECARDENTRY 構造体の配列を格納できます。
(注) | この構造体を拡張してはいけません。 |
typedef struct linecardentry_tag { DWORD dwPermanentCardID; DWORD dwCardNameSize; DWORD dwCardNameOffset; DWORD dwCardNumberDigits; DWORD dwSameAreaRuleSize; DWORD dwSameAreaRuleOffset; DWORD dwLongDistanceRuleSize; DWORD dwLongDistanceRuleOffset; DWORD dwInternationalRuleSize; DWORD dwInternationalRuleOffset; DWORD dwOptions; } LINECARDENTRY, FAR *LPLINECARDENTRY;
LINECOUNTRYENTRY 構造体は、1 つの国エントリに関する情報を提供します。この構造体の 1 つ以上の配列が、lineGetCountry 関数によって返される LINECOUNTRYLIST 構造体の一部になります。
(注) | この構造体を拡張してはいけません。 |
typedef struct linecountryentry_tag { DWORD dwCountryID; DWORD dwCountryCode; DWORD dwNextCountryID; DWORD dwCountryNameSize; DWORD dwCountryNameOffset; DWORD dwSameAreaRuleSize; DWORD dwSameAreaRuleOffset; DWORD dwLongDistanceRuleSize; DWORD dwLongDistanceRuleOffset; DWORD dwInternationalRuleSize; DWORD dwInternationalRuleOffset; } LINECOUNTRYENTRY, FAR *LPLINECOUNTRYENTRY;
LINECOUNTRYLIST 構造体は、国/地域のリストを表します。この構造体は、LINECOUNTRYENTRY 構造体の配列を格納できます。lineGetCountry 関数は、LINECOUNTRYLIST を返します。
(注) | この構造体を拡張してはいけません。 |
typedef struct linecountrylist_tag { DWORD dwTotalSize; DWORD dwNeededSize; DWORD dwUsedSize; DWORD dwNumCountries; DWORD dwCountryListSize; DWORD dwCountryListOffset; } LINECOUNTRYLIST, FAR *LPLINECOUNTRYLIST;
dwCountryListSize および dwCountryListOffset で指定された配列の中に存在する LINECOUNTRYENTRY 構造体の数。 |
|
各国または地域に関する情報を提供する LINECOUNTRYENTRY 要素の配列のサイズ(バイト単位)、およびこのデータ構造体の先頭からのオフセット(バイト単位)。 |
0x8EBD6A50 |
|
0x128011D2 |
|
0x905B0060 |
|
0xB03DD275 |
typedef struct lineforward_tag { DWORD dwForwardMode; DWORD dwCallerAddressSize; DWORD dwCallerAddressOffset; DWORD dwDestCountryCode; DWORD dwDestAddressSize; DWORD dwDestAddressOffset; } LINEFORWARD, FAR *LPLINEFORWARD;
typedef struct lineforwardlist_tag { DWORD dwTotalSize; DWORD dwNumEntries; LINEFORWARD ForwardList[1]; } LINEFORWARDLIST, FAR *LPLINEFORWARDLIST;
LINEGENERATETONE 構造体は、生成されるトーンについての情報を格納します。lineGenerateTone および TSPI_lineGenerateTone 関数は、この構造体を使用します。
(注) | この構造体を拡張してはいけません。 |
typedef struct linegeneratetone_tag { DWORD dwFrequency; DWORD dwCadenceOn; DWORD dwCadenceOff; DWORD dwVolume; } LINEGENERATETONE, FAR *LPLINEGENERATETONE;
このトーン要素の周波数(ヘルツ)。アプリケーションによって指定された周波数がサービス プロバイダーの分解能に適合しない場合は、値の調整(端数の切り上げまたは切り下げ)が行われることがあります。 |
|
生成されるカスタム トーンのパターンが「オフ」になる時間(ミリ秒単位)。ゼロの場合は、オフの時間がなくなります(つまり、トーンが発音され続けます)。 |
|
生成されるトーンの音量レベル。この値が 0x0000FFFF の場合は最大音量、0x00000000 の場合は無音に相当します。 |
LINEINITIZALIZEEXPARAMS 構造体は、コールが LINEINITIALIZEEX を使用して作成される際に指定されるパラメータを表します。
typedef struct lineinitializeexparams_tag { DWORD dwTotalSize; DWORD dwNeededSize; DWORD dwUsedSize; DWORD dwOptions; union { HANDLE hEvent; HANDLE hCompletionPort; } Handles; DWORD dwCompletionKey; } LINEINITIALIZEEXPARAMS, FAR *LPLINEINITIALIZEEXPARAMS;
LINEINITIALIZEEXOPTION_ 定数の 1 つ。アプリケーションが使用するイベント通知メカニズムを指定します。 |
|
dwOptions で LINEINITIALIZEEXOPTION_USEEVENT が指定されている場合、TAPI はこのフィールドでイベント ハンドルを返します。 |
|
dwOptions で LINEINITIALIZEEXOPTION_USECOMPLETIONPORT が指定されている場合、アプリケーションは、CreateIoCompletionPort を使用してオープンされた既存の完了ポートのハンドルをこのフィールドで指定する必要があります。 |
|
dwOptions で LINEINITIALIZEEXOPTION_USECOMPLETIONPORT が指定されている場合、アプリケーションは、GetQueuedCompletionStatus の lpCompletionKey パラメータによって返される値をこのフィールドで指定して、その完了メッセージがテレフォニー メッセージであることを明示する必要があります。 |
これらのオプションの詳細は、lineInitializeExを参照してください。
LINELOCATIONENTRY 構造体は、アドレス変換のコンテキストを提供するために使用される場所を表します。LINETRANSLATECAPS 構造体は、LINELOCATIONENTRY 構造体の配列を格納できます。
(注) | この構造体を拡張してはいけません。 |
typedef struct linelocationentry_tag { DWORD dwPermanentLocationID; DWORD dwLocationNameSize; DWORD dwLocationNameOffset; DWORD dwCityCodeSize; DWORD dwCityCodeOffset; DWORD dwPreferredCardID; DWORD dwLocalAccessCodeSize; DWORD dwLocalAccessCodeOffset; DWORD dwLongDistanceAccessCodeSize; DWORD dwLongDistanceAccessCodeOffset; DWORD dwTollPrefixListSize; DWORD dwTollPrefixListOffset; DWORD dwCountryID; DWORD dwOptions; DWORD dwCancelCallWaitingSize; DWORD dwCancelCallWaitingOffset; } LINELOCATIONENTRY, FAR *LPLINELOCATIONENTRY;
dwLocationNameOffset |
ユーザフレンドリな方法で記述された場所の説明を含む NULL 終端文字列が格納されます(サイズには NULL も含まれます)。 |
dwCityCodeOffset |
その場所に関連付けられた市外局番(エリア コード)を指定する NULL 終端文字列が格納されます(サイズには NULL も含まれます)。電話番号の入力時に、この情報と国番号がユーザ用の「デフォルト」の入力フィールドに使用され、正規形式の番号を簡単に入力できます。 |
dwLocalAccessCodeOffset |
市内通話エリア内のアドレスを呼び出す前にダイヤルされるアクセス コードを示す NULL 終端文字列のサイズ(バイト単位)、および LINETRANSLATECAPS 構造体の先頭からのオフセット(バイト単位)。 |
dwLongDistanceAccessCodeOffset |
市内通話エリア外のアドレスを呼び出す前にダイヤルされるアクセス コードを示す NULL 終端文字列のサイズ(バイト単位)、および LINETRANSLATECAPS 構造体の先頭からのオフセット(バイト単位)。 |
dwTollPrefixListOffset |
その場所の市外通話プレフィックス リストが格納された NULL 終端文字列のサイズ(バイト単位)、および LINETRANSLATECAPS 構造体の先頭からのオフセット(バイト単位)。この文字列には、「0」~「9」の数字で構成されるプレフィックスだけが格納され、各プレフィックスが 1 個の「,」(カンマ)で区切られます。 |
その場所に対して選択された国または地域の国 ID。この ID を使用して lineGetCountry 関数を呼び出し、該当する国/地域についての追加情報(国/地域名など)を取得します(国番号は一意ではないため、dwCountryCode メンバをこの目的には使用できません)。 |
|
dwCancelCallWaitingOffset |
アプリケーションが LineTranslateAddress の dwTranslateOptions パラメータで LINETRANSLATEOPTION_CANCELCALLWAITING ビットを設定している場合に、ダイヤル可能な文字列の前(パルスまたはトーン文字の後ろ)に付ける必要があるダイヤル ディジットと修飾子が格納された NULL 終端文字列のサイズ(バイト単位)、および LINETRANSLATECAPS 構造体の先頭からのオフセット(バイト単位)。dwCancelCallWaitingSize がゼロに設定されている場合、または dwCancelCallWaitingSize が 1 に設定され dwCancelCallWaitingOffset が空の文字列(1 個の NULL バイト)をポイントしている場合は、プレフィックスが 1 つも定義されていないことを示しています。 |
LINEMESSAGE 構造体には、アプリケーションが現在オープンしている回線のステータスの変化を示すパラメータ値が格納されます。LINEMESSAGE 構造体は、lineGetMessage 関数によって返されます。
typedef struct linemessage_tag { DWORD hDevice; DWORD dwMessageID; DWORD_PTR dwCallbackInstance; DWORD_PTR dwParam1; DWORD_PTR dwParam2; DWORD_PTR dwParam3; } LINEMESSAGE, FAR *LPLINEMESSAGE;
回線デバイスまたはコールのハンドル。dwMessageID が提供するコンテキストでは、このハンドルの特性(回線ハンドルまたはコール ハンドル)を判別できます。 |
|
アプリケーションに返された(アプリケーションが lineInitializeEx の dwCallBackInstance パラメータで指定した)インスタンス データ。TAPI はこの DWORD を解釈しません。 |
|
この構造体に渡されるパラメータ値の詳細については、「TAPI 回線メッセージ」を参照してください。
LINEMONITORTONE 構造体は、検出を目的としてトーンを定義します。この構造体は配列内のエントリとして使用します。lineMonitorTones 関数にトーンの配列が渡されると、それらのトーンがモニタされ、トーンが検出されると LINE_MONITORTONE メッセージがアプリケーションに送信されます。
すべての周波数がゼロに設定されているトーンは無音状態に相当します。したがって、アプリケーションは、コール情報ストリームの無音状態もモニタすることができます。
(注) | この構造体を拡張してはいけません。 |
typedef struct linemonitortone_tag { DWORD dwAppSpecific; DWORD dwDuration; DWORD dwFrequency1; DWORD dwFrequency2; DWORD dwFrequency3; } LINEMONITORTONE, FAR *LPLINEMONITORTONE;
アプリケーションがこのトーンを識別するために使用します。このトーンが検出されると、dwAppSpecific メンバの値がアプリケーションに返されます。 |
|
このトーンの要素の周波数(ヘルツ)。このトーンに必要な周波数が 2 つ以下の場合は、不要な周波数の値を 0 にする必要があります。3 つの周波数がすべてゼロに設定されているトーンは無音と解釈され、無音状態の検出に使用することができます。 |
LINEPROVIDERENTRY 構造体は、1 つのサービス プロバイダー エントリに関する情報を提供します。この構造体の配列が、lineGetProviderList 関数によって返される LINEPROVIDERLIST 構造体の一部になります。
(注) | この構造体は拡張できません。 |
typedef struct lineproviderentry_tag { DWORD dwPermanentProviderID; DWORD dwProviderFilenameSize; DWORD dwProviderFilenameOffset; } LINEPROVIDERENTRY, FAR *LPLINEPROVIDERENTRY;
サービス プロバイダー DLL(.TSP)ファイルのファイル名(パス)を含む NULL 終端文字列のサイズ(バイト単位)、および LINEPROVIDERLIST 構造体の先頭からのオフセット(バイト単位)。 |
LINEPROVIDERLIST 構造体は、サービス プロバイダーのリストを表します。lineGetProviderList 関数は、この型の構造体を返します。LINEPROVIDERLIST 構造体は、LINEPROVIDERENTRY 構造体の配列を格納できます。
(注) | この構造体を拡張してはいけません。 |
typedef struct lineproviderlist_tag { DWORD dwTotalSize; DWORD dwNeededSize; DWORD dwUsedSize; DWORD dwNumProviders; DWORD dwProviderListSize; DWORD dwProviderListOffset; } LINEPROVIDERLIST, FAR *LPLINEPROVIDERLIST;
dwProviderListSize および dwProviderListOffset で指定された配列の中に存在する LINEPROVIDERENTRY 構造体の数。 |
|
dwProviderListOffset |
各サービス プロバイダーに関する情報を提供する LINEPROVIDERENTRY 要素の配列のサイズ(バイト単位)、およびこのデータ構造体の先頭からのオフセット(バイト単位)。 |
LINEREQMAKECALL 構造体は、コールが lineGetRequest 関数に開始した要求を表します。
(注) | この構造体は拡張できません。 |
typedef struct linereqmakecall_tag { char szDestAddress[TAPIMAXDESTADDRESSSIZE]; char szAppName[TAPIMAXAPPNAMESIZE]; char szCalledParty[TAPIMAXCALLEDPARTYSIZE]; char szComment[TAPIMAXCOMMENTSIZE]; } LINEREQMAKECALL, FAR *LPLINEREQMAKECALL;
[TAPIMAXADDRESSSIZE] |
コール発信要求の宛先アドレスが入った NULL 終端文字列。このアドレスには、正規アドレス形式またはダイヤル可能アドレス形式を使用します。アドレスの最大文字数により TAPIMAXDESTADDRESSSIZE の文字数が指定されます(これには終端の NULL も含まれます)。これよりも長い場合は、文字列の末尾が切り捨てられます。 |
[TAPIMAXAPPNAMESIZE] |
要求を発行したアプリケーションのユーザフレンドリなアプリケーション名またはファイル名が入った NULL 終端文字列。アドレスの最大文字数により TAPIMAXAPPNAMESIZE の文字数が指定されます(これには終端の NULL も含まれます)。 |
[TAPIMAXCALLEDPARTYSIZE] |
ユーザフレンドリな着信側名が入った NULL 終端文字列。着信ユーザ情報の最大文字数により TAPIMAXCALLEDPARTYSIZE の文字数が指定されます(これには終端の NULL も含まれます)。 |
[TAPIMAXCOMMENTSIZE] |
このコール要求についてのコメントが入った NULL 終端文字列。コメント文字列の最大文字数により TAPIMAXCOMMENTSIZE の文字数が指定されます(これには終端の NULL も含まれます)。 |
LINETRANSLATECAPS 構造体は、アドレス変換機能を表します。この構造体は LINELOCATIONENTRY 構造体の配列、および LINECARDENTRY 構造体の配列を格納できます。lineGetTranslateCaps 関数は LINETRANSLATECAPS 構造体を返します。
(注) | この構造体を拡張してはいけません。 |
typedef struct linetranslatecaps_tag { DWORD dwTotalSize; DWORD dwNeededSize; DWORD dwUsedSize; DWORD dwNumLocations; DWORD dwLocationListSize; DWORD dwLocationListOffset; DWORD dwCurrentLocationID; DWORD dwNumCards; DWORD dwCardListSize; DWORD dwCardListOffset; DWORD dwCurrentPreferredCardID; } LINETRANSLATECAPS, FAR *LPLINETRANSLATECAPS;
場所リストに含まれるエントリの数。このリストには、現在定義されているすべての場所が含まれ、ゼロ(デフォルト)も含まれます。 |
|
dwLocationListOffset |
アドレス変換で認識されている場所のリスト。このリストは LINELOCATIONENTRY 構造体のシーケンスを構成します。dwLocationListOffset メンバは最初の LINELOCATIONENTRY 構造体の先頭バイトをポイントし、dwLocationListSize メンバはリスト全体の合計バイト数を示します。 |
CurrentLocation に対する、LINELOCATIONENTRY 構造体の dwPermanentLocationID メンバです。 |
|
dwCardListOffset |
アドレス変換で認識されている電話カードのリスト。このリストには、秘匿されていないカード エントリだけが含まれ、カード 0(直接ダイヤル)が常に含まれます。このリストは LINECARDENTRY 構造体のシーケンスを構成します。dwCardListOffset メンバは最初の LINECARDENTRY 構造体の先頭バイトをポイントし、dwCardListSize メンバはリスト全体の合計バイト数を示します。 |
CurrentLocation に関連付けられた、LINELOCATIONENTRY 構造体の dwPreferredCardID メンバ。 |
LINETRANSLATEOUTPUT 構造体は、アドレス変換の結果を表します。この構造体は、lineTranslateAddress 関数で使用されます。
(注) | この構造体を拡張してはいけません。 |
typedef struct linetranslateoutput_tag { DWORD dwTotalSize; DWORD dwNeededSize; DWORD dwUsedSize; DWORD dwDialableStringSize; DWORD dwDialableStringOffset; DWORD dwDisplayableStringSize; DWORD dwDisplayableStringOffset; DWORD dwCurrentCountry; DWORD dwDestCountry; DWORD dwTranslateResults; } LINETRANSLATEOUTPUT, FAR *LPLINETRANSLATEOUTPUT;
dwDialableStringOffset |
変換後の出力が格納されます。この出力は、lineMakeCall、lineDial、またはその他の、ダイヤル可能文字列を必要とする関数に渡すことができます。この出力は常に NULL 終端文字列を構成します(NULL も dwDialableStringSize に算入されます)。名前やサブアドレスなどの補助フィールドが入力文字列に含まれていた場合は、この出力文字列にもそれらが含まれます。この文字列には、電話カード番号などの個人情報が含まれている場合があります。権限のない人の目に触れないように、この文字列はユーザに対して表示しないでください。 |
dwDisplayableStringOffset |
変換後の出力が格納されます。この出力は、ユーザの確認を求めるために表示することができます。この文字列の内容は DialableString とほぼ同一ですが、電話カードの番号は、ブラケットで囲まれたカードの「フレンドリ名」に置き換えられます(例:「[AT&T Card]」)。名前やサブアドレスなどの補助フィールドは削除されます。個人情報を権限のない人の目に触れさせずに、コールステータス ダイアログボックス内でこの文字列を表示できます。この関数もコール ログに含めることができます。 |
CurrentLocation に設定されている国番号が格納されます。この値は、ローカルのコール プログレス トーンの検出などを目的として、特定のユーザ インターフェイス要素の表示を制御したい場合などに使用します。 |
|
変換されたアドレスの宛先の国番号が格納されます。この値は、lineMakeCall などのダイヤル関数の dwCountryCode パラメータに渡される可能性があります(これにより、宛先の国/地域のコール プログレス トーン(使用中信号など)を正しく検出することができます)。lineTranslateAddress に渡された宛先アドレスが正規形式でなかった場合は、このフィールドがゼロに設定されます。 |
|
変換プロセスによって得られた情報を示します。この情報は、アプリケーションのユーザ インターフェイス要素の表示などに役立つ可能性があります。このフィールドは、LINETRANSLATERESULT_ を 1 つ使用します。 |
TAPI の phone 関数を使用すると、アプリケーションから電話機を物理的に制御できます。
phoneCallbackFunc 関数は、アプリケーションで指定された関数名のプレースホルダになります。
すべてのコールバックが、アプリケーションのコンテキスト内で実行されます。コールバック関数は、ダイナミックリンク ライブラリ(DLL)またはアプリケーション モジュール内に常駐している必要があり、モジュール定義ファイルでエクスポートされている必要があります。
VOID FAR PASCAL phoneCallbackFunc( HANDLE hDevice, DWORD dwMsg, DWORD dwCallbackInstance, DWORD dwParam1, DWORD dwParam2, DWORD dwParam3 );
コールバックに関連付けられた電話機のハンドル。
回線またはコール デバイスのメッセージ。
コールバックでアプリケーションに渡されたコールバック インスタンス データ。TAPI はこの DWORD を解釈しません。
メッセージのパラメータ。
メッセージのパラメータ。
メッセージのパラメータ。
このコールバック関数に渡されるパラメータについては、「TAPI 回線メッセージ」および「TAPI の phone メッセージ」を参照してください。
LONG phoneClose( HPHONE hPhone );
クローズされる電話機のハンドル。関数が成功すると、このハンドルが無効になることを意味します。
phoneDevSpecific 関数は、他の TAPI 関数で定義されていない機能を Telephony API 実装で提供できるようにするための一般的な機能拡張メカニズムとして使用されます。これらの機能拡張の目的は、デバイス固有です。
Cisco Unified TSP で phoneDevSpecific を使用すると、デバイス固有のデータを電話機に送信できます。
LONG WINAPI phoneDevSpecific ( HPHONE hPhone, LPVOID lpParams, DWORD dwSize );
電話機のハンドル。
パラメータ ブロックを格納するメモリ領域へのポインタ。内容の解釈は、デバイス固有です。TAPI は、変更のないパラメータ ブロックの内容をサービス プロバイダーとの間で送受信します。
パラメータ ブロック領域のサイズ(バイト単位)。
LONG phoneGetDevCaps( HPHONEAPP hPhoneApp, DWORD dwDeviceID, DWORD dwAPIVersion, DWORD dwExtVersion, LPPHONECAPS lpPhoneCaps );
このアプリケーションの TAPI 登録のハンドル。
問い合わせを受ける電話機。
使用される Telephony API のバージョン番号。上位の桁にはメジャー バージョン番号が入り、下位の桁にはマイナー バージョン番号が入ります。関数 phoneNegotiateAPIVersion を使用してこの番号を取得できます。
使用するサービス プロバイダー固有拡張のバージョン番号。この番号は、関数 phoneNegotiateExtVersion を使用して取得されます。デバイス固有拡張を使用しない場合は、ゼロにしておくことができます。そうでない場合は、上位の桁にメジャー バージョン番号が入り、下位の桁にマイナー バージョン番号が入ります。
PHONECAPS 型の可変サイズ構造体へのポインタ。要求が正常に完了すると、この構造体に電話機の機能情報が入ります。
LONG phoneGetDisplay( HPHONE hPhone, LPVARSTRING lpDisplay );
オープン状態の電話機のハンドル。
表示内容が格納されるメモリ位置へのポインタ(VARSTRING 型)。
phoneGetLamp 関数は、指定されたランプの現在のランプ モードを返します。
(注) | この関数は Cisco Unified IP Phone 79xx シリーズではサポートされていません。 |
LONG phoneGetLamp( HPHONE hPhone, DWORD dwButtonLampID, LPDWORD lpdwLampMode );
オープン状態の電話機のハンドル。
問い合わせを受けるランプの ID。ランプの ID については、「PHONE_BUTTON」を参照してください。
(注) | この関数は Cisco Unified IP Phone 79xx シリーズではサポートされていません。 |
指定されたランプのランプ モード ステータスが格納されるメモリ位置へのポインタ。lpdwLampMode パラメータが持てるビット セットは、1 つまでです。このパラメータには、次の PHONELAMPMODE_ 定数が入ります。
phoneGetMessage 関数は、イベント ハンドル通知メカニズム(詳細は、「phoneInitializeEx」を参照してください)を使用しているアプリケーションへ次に配信される TAPI メッセージを返します。
LONG WINAPI phoneGetMessage( HPHONEAPP hPhoneApp, LPPHONEMESSAGE lpMessage, DWORD dwTimeout );
phoneInitializeEx によって返されるハンドル。PHONEINITIALIZEEXPARAMS 構造体の dwOptions メンバの PHONEINITIALIZEEXOPTION_USEEVENT オプションがアプリケーションによって設定されている必要があります。
PHONEMESSAGE 構造体へのポインタ。この関数が正常に終了すると、アプリケーションへ次に配信されるメッセージがこの構造体に入ります。
タイムアウトまでの時間(ミリ秒単位)。この関数は、返すメッセージがない場合でも、指定された時間が経過すると終了します。dwTimeout がゼロの場合、この関数は配信待ちのメッセージがないかどうかを確認して、ただちに終了します。dwTimeout が INFINITE の場合、タイムアウト時間は無限になります。
要求が成功した場合はゼロを返し、エラーが発生した場合は負の番号を返します。戻り値には次の値があります。
PHONEERR_INVALAPPHANDLE、PHONEERR_OPERATIONFAILED、PHONEERR_INVALPOINTER、PHONEERR_NOMEM。
phoneGetRing 関数を使用すると、指定されたオープン状態の電話機に対して、現在の呼び出し音モードを問い合わせることができます。
LONG phoneGetRing( HPHONE hPhone, LPDWORD lpdwRingMode, LPDWORD lpdwVolume );
phoneGetStatus 関数を使用すると、指定されたオープン状態の電話機に対して、その電話機全体のステータスを問い合わせることができます。
LONG WINAPI phoneGetStatusMessages( HPHONE hPhone, LPPHONESTATUS lpPhoneStatus ) ;
問い合わせの対象のオープン状態の電話機のハンドル。
PHONESTATUS 型の可変サイズ データ構造体へのポインタ。電話機のステータスに関して返された情報が読み込まれます。
要求が成功した場合はゼロを返し、エラーが発生した場合は負の番号を返します。戻り値には次の値があります。
PHONEERR_INVALPHONEHANDLE、PHONEERR_NOMEM、PHONEERR_INVALPOINTER、PHONEERR_RESOURCEUNAVAIL、PHONEERR_OPERATIONFAILED、PHONEERR_STRUCTURETOOSMALL、PHONEERR_OPERATIONUNAVAIL、PHONEERR_UNINITIALIZED
phoneGetStatusMessages 関数は、指定された電話機上でコールバックが発生する原因となった電話機状態の変化に関する情報を、アプリケーションに返します。
アプリケーションは、phoneGetStatusMessages を使用して、関連するメッセージの生成を問い合わせることができます。phoneSetStatusMessages はメッセージの生成を制御します。デフォルトでは、すべての電話機ステータス メッセージが無効のままです。
LONG WINAPI phoneGetStatusMessages( HPHONE hPhone, LPDWORD lpdwPhoneStates, LPDWORD lpdwButtonModes, LPDWORD lpdwButtonStates );
モニタされるオープン状態の電話機のハンドル。
ゼロまたは 1 つ以上の PHONESTATE_ 定数を含む DWORD へのポインタ。これらのフラグは、どの電話機ステータスの変更およびイベントに関する通知メッセージをアプリケーションで受信するかを指定します。次のステータスに関して、個別にモニタリングを有効または無効にできます。
PHONESTATE_OTHER
PHONESTATE_CONNECTED
PHONESTATE_DISCONNECTED
PHONESTATE_OWNER
PHONESTATE_MONITORS
PHONESTATE_DISPLAY
PHONESTATE_LAMP
PHONESTATE_RINGMODE
PHONESTATE_RINGVOLUME
PHONESTATE_HANDSETHOOKSWITCH
PHONESTATE_HANDSETVOLUME
PHONESTATE_HANDSETGAIN
PHONESTATE_SPEAKERHOOKSWITCH
PHONESTATE_SPEAKERVOLUME
PHONESTATE_SPEAKERGAIN
PHONESTATE_HEADSETHOOKSWITCH
PHONESTATE_HEADSETVOLUME
PHONESTATE_HEADSETGAIN
PHONESTATE_SUSPEND
PHONESTATE_RESUMEF
PHONESTATE_DEVSPECIFIC
PHONESTATE_REINIT
PHONESTATE_CAPSCHANGE
PHONESTATE_REMOVED
どの電話機ボタン モードに関する通知メッセージをアプリケーションで受信するかを指定したフラグが入っている DWORD へのポインタ。このパラメータには、ゼロまたは 1 つ以上の PHONEBUTTONMODE_ 定数が入ります。
どの電話機ボタン状態の変化に関する通知メッセージをアプリケーションで受信するかを指定したフラグが入っている DWORD へのポインタ。このパラメータには、ゼロまたは 1 つ以上の PHONEBUTTONSTATE_ 定数が入ります。
要求が成功した場合はゼロを返し、エラーが発生した場合は負の番号を返します。戻り値には次の値があります。
PHONEERR_INVALPHONEHANDLE
PHONEERR_NOMEM
PHONEERR_INVALPOINTER
PHONEERR_RESOURCEUNAVAIL
PHONEERR_OPERATIONFAILED
PHONEERR_UNINITIALIZED
phoneInitialize 関数は旧バージョンの関数ですが、TAPI バージョン 1.3 および 1.4 を使用するアプリケーションとの下位互換性を維持するために、tapi.dll および tapi32.dll によってエクスポートが継続されています。
LONG WINAPI phoneInitialize( LPHPHONEAPP lphPhoneApp, HINSTANCE hInstance, PHONECALLBACK lpfnCallback, LPCSTR lpszAppName, LPDWORD lpdwNumDevs );
アプリケーションによる TAPI の使用状態のハンドルが入っている位置へのポインタ。
クライアント アプリケーションまたは DLL のインスタンス ハンドル。
電話機のステータスとイベントを確認するために呼び出されるコールバック関数のアドレス。
表示可能な文字が入っている NULL 終端文字列へのポインタ。このパラメータが NULL でない場合は、アプリケーション側で指定されたアプリケーション名がこのパラメータに入ります。この名前は PHONESTATUS 構造体によって提供され、電話機の現在のオーナーとなっているアプリケーションを、ユーザにわかりやすく提示します。この情報は、ロギングやステータスの報告に使用できます。lpszAppName が NULL の場合は、アプリケーションのファイル名が代わりに使用されます。
DWORD へのポインタ。ここには、アプリケーションが使用できる電話機の台数が読み込まれます。
要求が成功した場合はゼロを返し、エラーが発生した場合は負の番号を返します。戻り値には次の値があります。
PHONEERR_INVALAPPNAME
PHONEERR_INIFILECORRUPT
PHONEERR_INVALPOINTER
PHONEERR_NOMEM
PHONEERR_OPERATIONFAILED
PHONEERR_REINIT
PHONEERR_RESOURCEUNAVAIL
PHONEERR_NODEVICE
PHONEERR_NODRIVER
PHONEERR_INVALPARAM
phoneInitializeEx 関数は、アプリケーションによる TAPI の使用状態を初期化し、以後の phone 抽象概念の使用を可能にします。この関数は、アプリケーション固有の通知メカニズムを登録し、アプリケーションで使用できる電話機の台数を返します。電話機デバイスとは、phone で始まる Telephony API の関数を実行できる、すべてのデバイスを表します。
LONG WINAPI phoneInitializeEx( LPHPHONEAPP lphPhoneApp, HINSTANCE hInstance, PHONECALLBACK lpfnCallback, LPCSTR lpszFriendlyAppName, LPDWORD lpdwNumDevs, LPDWORD lpdwAPIVersion, LPPHONEINITIALIZEEXPARAMS lpPhoneInitializeExParams );
アプリケーションによる TAPI の使用状態のハンドルが入っている位置へのポインタ。
クライアント アプリケーションまたは DLL のインスタンス ハンドル。アプリケーションまたは DLL はこのパラメータに NULL を渡すことができます。その場合、TAPI はそのプロセスの root 実行可能ファイルのモジュール ハンドルを使用します。
アプリケーションが「ウィンドウ非表示」方式でイベント通知を使用している場合に、回線デバイス、アドレス、またはコールのステータスおよびイベントを確認するために呼び出すコールバック関数のアドレス(詳細は、「phoneCallbackFunc」を参照してください)。アプリケーションがイベント ハンドルまたは完了ポートのイベント通知メカニズムを使用している場合は、このパラメータが無視されて、NULL に設定されます。
表示可能な文字だけが入っている NULL 終端文字列へのポインタ。このパラメータが NULL でない場合は、アプリケーションで指定されたアプリケーション名が入ります。この名前は PHONESTATUS 構造体によって提供され、電話機の所有権があるアプリケーションをユーザにわかりやすく提示します。lpszFriendlyAppName が NULL の場合は、(Windows の関数 GetModuleFileName から返された)アプリケーションのモジュール ファイル名が代わりに使用されます。
DWORD へのポインタ。要求が正常に完了すると、アプリケーションで使用できる電話機の数がここに入ります。
DWORD へのポインタ。アプリケーションは、この関数を呼び出す前に、この関数をサポートしている最新の API バージョン(たとえば、phoneNegotiateAPIVersion の dwAPIHighVersion パラメータに渡されるバージョン番号)へこの DWORD を初期化する必要があります。故意に高い値を使用しないでください。この値は必ず正確に設定してください。新しいバージョンの TAPI のメッセージや構造体は、アプリケーションのバージョンがサポートしている値および書式に変換されます。要求が正常に完了すると、TAPI でサポートされている最新の API バージョンがここに入るため、アプリケーションは古いバージョンの TAPI がシステムにインストールされていることを検出して、適応することができます。
アプリケーションと TAPI の間の連携を確立するために使用される追加パラメータ(具体的には、アプリケーションで選択されているイベント通知メカニズムと関連パラメータ)が格納されている PHONEINITIALIZEEXPARAMS 型の構造体へのポインタ。
要求が成功した場合はゼロを返し、エラーが発生した場合は負の番号を返します。戻り値には次の値があります。
PHONEERR_INVALAPPNAME
PHONEERR_OPERATIONFAILED
PHONEERR_INIFILECORRUPT
PHONEERR_INVALPOINTER
PHONEERR_REINIT
PHONEERR_NOMEM
PHONEERR_INVALPARAM
phoneNegotiateAPIVersion 関数を使用すると、指定された電話機に対して使用する API のバージョン番号をネゴシエートできます。この関数は、電話機がサポートしている拡張の ID を返し、拡張をサポートしていない場合はゼロを返します。
LONG WINAPI phoneNegotiateAPIVersion( HPHONEAPP hPhoneApp, DWORD dwDeviceID, DWORD dwAPILowVersion, DWORD dwAPIHighVersion, LPDWORD lpdwAPIVersion, LPPHONEEXTENSIONID lpExtensionID );
このアプリケーションの TAPI 登録のハンドル。
問い合わせをする電話機。
アプリケーションが準拠している最も古い API バージョン。上位の桁はメジャー バージョン番号、下位の桁はマイナー バージョン番号を示します。
アプリケーションが準拠している最新の API バージョン。上位の桁はメジャー バージョン番号、下位の桁はマイナー バージョン番号を示します。
ネゴシエート済みの API バージョン番号が返される DWORD へのポインタ。ネゴシエーションが成功すると、この番号は dwAPILowVersion から dwAPIHighVersion の範囲になります。
PHONEEXTENSIONID 型の構造体へのポインタ。指定された dwDeviceID パラメータのサービス プロバイダーで、プロバイダー固有の拡張がサポートされている場合、ネゴシエーションが成功すると、この構造体にはこれらの拡張の拡張 ID が入ります。その回線で拡張がサポートされていない場合、この構造体にはゼロだけが入ります。アプリケーションで拡張を使用していない場合は、返されたパラメータを無視できます。
要求が成功した場合はゼロを返し、エラーが発生した場合は負の番号を返します。戻り値には次の値があります。
PHONEERR_INVALAPPHANDLE
PHONEERR_OPERATIONFAILED
PHONEERR_BADDEVICEID
PHONEERR_OPERATIONUNAVAIL
PHONEERR_NODRIVER
PHONEERR_NOMEM
PHONEERR_INVALPOINTER
PHONEERR_RESOURCEUNAVAIL、PHONEERR_INCOMPATIBLEAPIVERSION
PHONEERR_UNINITIALIZED
PHONEERR_NODEVICE
phoneOpen 関数は、指定された電話機をオープンします。オーナー特権またはモニタ特権を使用して、デバイスをオープンします。オーナー特権を使用して電話機をオープンするアプリケーションの場合は、電話機のランプ、ディスプレイ、呼び出し音、およびフックスイッチを制御できます。モニタ特権を使用して電話機をオープンするアプリケーションの場合は、フックスイッチの変更やボタン操作など、電話機上で発生したイベントだけの通知を受け取ります。電話機の所有権は排他的なので、複数のアプリケーションでオーナー特権を使用して同じ電話機を同時にオープンできません。ただし、モニタ特権を使用する場合は、電話機を複数回オープンできます。
(注) | CTI ポート上で電話機をオープンするには、まず対応する回線デバイスをオープンします。 |
LONG phoneOpen( HPHONEAPP hPhoneApp, DWORD dwDeviceID, LPHPHONE lphPhone, DWORD dwAPIVersion, DWORD dwExtVersion, DWORD dwCallbackInstance, DWORD dwPrivilege );
アプリケーションを TAPI に登録するためのハンドル。
オープンする電話機。
オープンしている電話機を識別する HPHONE ハンドルへのポインタ。このハンドルは、他の電話機制御関数を呼び出す際に、電話機を識別するために使用します。
アプリケーションと Telephony API の間で操作することが合意された API のバージョン番号。この番号は、関数 phoneNegotiateAPIVersion から取得します。
アプリケーションとサービス プロバイダーの間で使用することが合意された拡張のバージョン番号。アプリケーションが拡張を使用しない場合、この番号はゼロになります。この番号は、関数 phoneNegotiateExtVersion から取得します。
各メッセージによりアプリケーションへ返されたユーザ インスタンス データ。Telephony API はこのパラメータを解釈しません。
要求された特権。dwPrivilege パラメータに格納できるビット セットは、1 つだけです。このパラメータには、次の PHONEPRIVILEGE_ 定数が入ります。
phoneSetDisplay 関数は、指定された文字列を、指定されたオープン状態の電話機上で表示します。
(注) | 4.0 よりも前のリリースでは、phoneSetDisplay() によって電話機に送信されたメッセージは、その電話機に渡された他の Cisco Unified Communications Manager メッセージによって自動的に上書きされていました。Cisco Unified Communications Manager 4.0 では、電話機が再起動されるまで、phoneSetDisplay() API で送信されたメッセージは電話機に残ります。ディスプレイからテキストを消去して、Cisco Unified Communications Manager メッセージを再表示する場合は、スペースではなく NULL 文字列を phoneSetDisplay() API で渡す必要があります。つまり、lpsDisplay パラメータを NULL にして、dwSize を 0 に設定する必要があります。 |
LONG phoneSetDisplay( HPHONE hPhone, DWORD dwRow, DWORD dwColumn, LPCSTR lpsDisplay, DWORD dwSize );
オープン状態の電話機のハンドル。このアプリケーションは、電話機のオーナーになっている必要があります。
新しいテキストを表示するディスプレイ上の行位置。
新しいテキストを表示するディスプレイ上のカラム位置。
表示内容が格納されるメモリ位置へのポインタ。この表示情報は、この電話機のデバイス機能の dwStringFormat メンバで指定されている書式に従う必要があります。
lpsDisplay でポイントされた情報のサイズ(バイト単位)。
phoneSetStatusMessages 関数は、指定された電話機上で発生する特定のステータス イベントをアプリケーションでモニタするための関数です。
サポートされているメッセージについては、TAPI の phone メッセージを参照してください。
LONG phoneSetStatusMessages( HPHONE hPhone, DWORD dwPhoneStates, DWORD dwButtonModes, DWORD dwButtonStates );
モニタするオープン状態の電話機のハンドル。
これらのフラグは、どの電話機ステータスの変更およびイベントに関する通知メッセージをアプリケーションで受信するかを指定します。このパラメータには、ゼロまたは 1 つ以上のビット セットが入ります。このパラメータには、次の PHONESTATE_ 定数が入ります。
PHONESTATE_OTHER:次のリストにある項目以外の項目に変化があったことを示します。アプリケーションは、現在の電話機ステータスを調べて、変化した項目を確認する必要があります。
PHONESTATE_OWNER:電話機のオーナー数が変わったことを示します。
PHONESTATE_MONITORS:電話機のモニタ数が変わったことを示します。
PHONESTATE_DISPLAY:電話機のディスプレイに変化があったことを示します。
PHONESTATE_LAMP:電話機のランプに変化があったことを示します。
PHONESTATE_RINGMODE:電話機の呼び出し音モードが変わったことを示します。
PHONESTATE_SPEAKERHOOKSWITCH:このスピーカフォンのフックスイッチの状態が変わったことを示します。
PHONESTATE_REINIT:電話機の設定で項目に変化があったことを示します。(新しい電話機の出現と同様に)これらの変化を検出するには、アプリケーションによる TAPI の使用状態を再初期化する必要があります。その後に発行された phoneInitialize 要求、phoneInitializeEx 要求、および phoneOpen 要求は、アプリケーションによる TAPI の使用状態がシャットダウンされるまで拒否されます。この状態変化はシステム内のすべての回線に関係するため、この状態変化が発生しても、PHONE_STATE メッセージの hDevice パラメータは NULL のままです。PHONESTATE_REINIT は非常に重要なメッセージであるため、無効にできません。したがって、それらのメッセージは、このビットの設定とは無関係に、常にアプリケーションへ配信されます。
PHONESTATE_REMOVED:サービス プロバイダーがこのデバイスをシステムから削除していることを示します(主な原因は、ユーザの操作や、コントロール パネルなどのユーティリティによる操作です)。この値を持つ PHONE_STATE メッセージの直後に、デバイスに関する PHONE_CLOSE メッセージが送信されます。この場合、TAPI が再初期化される前に、そのデバイスへのアクセスを試みると、PHONEERR_NODEVICE がアプリケーションに返されます。この値を格納する PHONE_STATE メッセージがサービス プロバイダーから TAPI に送信された場合、TAPI バージョン 1.4 以降を使用しているアプリケーションには、TAPI からメッセージが渡されます。古い TAPI バージョンを使用しているアプリケーションには、通知が届きません。
どの電話機ボタン モードに関する通知メッセージをアプリケーションで受信するかを指定します。このパラメータには、ゼロまたは 1 つ以上のビット セットが入ります。このパラメータには、次の PHONEBUTTONMODE_ 定数が入ります。
どの電話機ボタン状態の変化に関する通知メッセージをアプリケーションで受信するかを指定します。dwButtonModes パラメータがゼロの場合、システムは dwButtonStates を無視します。dwButtonModes に 1 つ以上のビット セットがある場合は、このパラメータにも最低 1 つのビット セットがあります。このパラメータには、次の PHONEBUTTONSTATE_ 定数が入ります。
phoneShutdown 関数は、アプリケーションによる TAPI phone abstraction の使用をシャットダウンします。
(注) | アプリケーションが電話機をオープンしているときにこの関数が呼び出されると、それらの電話機がクローズされます。 |
LONG WINAPI phoneShutdown( HPHONEAPP hPhoneApp );
アプリケーションによる TAPI の使用状態のハンドル。
要求が成功した場合はゼロを返し、エラーが発生した場合は負の番号を返します。戻り値には次の値があります。
PHONEERR_INVALAPPHANDLE、PHONEERR_NOMEM、PHONEERR_UNINITIALIZED、PHONEERR_RESOURCEUNAVAIL
メッセージは、アプリケーションに非同期イベントを通知します。すべてのメッセージは、アプリケーションが lineInitializeEx で指定したメッセージ通知メカニズムを使用して、アプリケーションに送信されます。このメッセージには関連オブジェクト(電話機、回線、またはコール)へのハンドルが必ず入ります。アプリケーションは、メッセージのタイプから、オブジェクトのタイプを判別します。次の表では、TAPI 電話メッセージについて説明します。
PHONE_BUTTON メッセージは、ローカルの電話機上でボタンの押下が検出された場合に、ボタン押下のモニタリングが可能であることをアプリケーションに通知します。
PHONE_BUTTON hPhone = (HPHONE) hPhoneDevice; dwCallbackInstance = (DWORD) hCallback; dwParam1 = (DWORD) idButtonOrLamp; dwParam2 = (DWORD) ButtonMode; dwParam3 = (DWORD) ButtonState;
電話機のハンドル。
このアプリケーションに対して電話機がオープンされる際に渡されるコールバック インスタンス。
押されたボタンのボタン/ランプ ID。0 ~ 11 のボタン ID は常にキーパッドのボタンを表し、「0」ボタンの ID は 0、「1」ボタンの ID は 1(以下、ボタン ID 9 まで同様)、「*」ボタンの ID は 10、「#」ボタンの ID は 11 になります。ボタン ID のその他の情報は、phoneGetDevCapsを参照してください。
ボタンのボタン モード。各ボタン ID に対応するボタン モードは、次の表に記載されています。
TAPI サービス プロバイダーは、ボタン ダウン/ボタン アップの状態変化を検出できません。TAPI 仕様に準拠するため、ダウン状態の後にアップ状態が発生したことをシミュレートする 2 つのメッセージが dwparam3 を使用して送信されます。
このパラメータには、次の PHONEBUTTONMODE_ 定数が入ります。
このイベントがボタンダウン イベントであるか、ボタンアップ イベントであるかを指定します。このパラメータには、次の PHONEBUTTONSTATE_ 定数が入ります。
PHONEBUTTONSTATE_UP:このボタンはアップの状態です。
PHONEBUTTONSTATE_DOWN:このボタンはダウンの状態(押下)です。
PHONEBUTTONSTATE_UNKNOWN:現時点では、このボタンのアップ/ダウン状態は不明ですが、後で判明する可能性があります。
PHONEBUTTONSTATE_UNAVAIL:このボタンのアップ/ダウン状態をサービス プロバイダーが認識しておらず、今後も状態を認識できません。
0 ~ 11 のボタン ID 値は、TAPI で定義されているキーパッド ボタンにマップされています。12 以上の値は、回線ボタンおよび機能ボタンにマップされています。この DWORD の下位部分は機能を指定します。この DWORD の上位部分は、その機能のインスタンス番号を表します。次の表に、各機能に対応する DWORD の下位部分を示します。
ボタン ID は、次のように表現します。
ButtonID = (instance << 16) | featureID
次の表に、有効な電話ボタンの値を示します。
PHONE_CLOSE メッセージは、オープンしている電話機がリソース再利用プロセスの一環として強制的にクローズされたときに送信されます。このメッセージが送信されると、このデバイスのハンドルが無効になります。
PHONE_CLOSE hPhone = (HPHONE) hPhoneDevice; dwCallbackInstance = (DWORD) hCallback; dwParam1 = (DWORD) 0; dwParam2 = (DWORD) 0; dwParam3 = (DWORD) 0;
クローズされた電話機のハンドル。このメッセージが送信されると、このハンドルが無効になります。
オープン状態の電話機に渡されたアプリケーションのコールバック インスタンス。
PHONE_CREATE メッセージは、新しい電話機が作成されたことを通知するために、アプリケーションへ送信されます。
(注) | CTI Manager のクラスタ サポート、エクステンション モビリティ、変更通知、およびユーザがディレクトリに追加されると、PHONE_CREATE イベントが生成されます。 |
PHONE_CREATE hPhone = (HPHONE) hPhoneDevice; dwCallbackInstance = (DWORD) 0; dwParam1 = (DWORD) idDevice; dwParam2 = (DWORD) 0; dwParam3 = (DWORD) 0;
PHONE_REMOVE メッセージは、電話機が(システムから)削除されたことを通知するために、アプリケーションへ送信されます。通常、この方法は PCMCIA デバイスの取り外しなどの一時的な削除には使用されず、デバイスの恒久的な削除が行われた場合にだけ使用されます(TAPI が再初期化されると、サービス プロバイダーはそのデバイスに関する報告を送信しなくなります)。
(注) | CTI Manager のクラスタ サポート、エクステンション モビリティ、変更通知、およびユーザがディレクトリから削除されると、PHONE_REMOVE イベントが生成されます。 |
PHONE_REMOVE dwDevice = (DWORD) 0; dwCallbackInstance = (DWORD) 0; dwParam1 = (DWORD) dwDeviceID; dwParam2 = (DWORD) 0; dwParam3 = (DWORD) 0;
削除された電話機の ID。
TAPI PHONE_REPLY メッセージは、非同期的に完了した関数呼び出しの結果を報告するために、アプリケーションへ送信されます。
PHONE_REPLY hPhone = (HPHONE) 0; dwCallbackInstance = (DWORD) hCallback; dwParam1 = (DWORD) idRequest; dwParam2 = (DWORD) Status; dwParam3 = (DWORD) 0;
アプリケーションのコールバック インスタンスを返します。
この応答に対応する要求の ID。
成功またはエラーの表示。アプリケーションは、このパラメータを LONG にキャストする必要があります。ゼロは成功を示し、負の数字はエラーを示します。
PHONE_STATE hPhone = (HPHONE) hPhoneDevice; dwCallbackInstance = (DWORD) hCallback; dwParam1 = (DWORD) PhoneState; dwParam2 = (DWORD) PhoneStateDetails; dwParam3 = (DWORD) 0;
電話機のハンドル。
このアプリケーションに対して電話機がオープンされる際に渡されるコールバック インスタンス。
変化した電話機状態。このパラメータには、次の PHONESTATE_ 定数が入ります。
PHONESTATE_OTHER:次の電話機ステータス項目以外の項目に変化があったことを示します。アプリケーションは、現在の電話機ステータスを調べて、変化した項目を確認する必要があります。
PHONESTATE_CONNECTED:電話機と TAPI の接続が確立されたことを示します。このイベントは、TAPI が初めて呼び出されたとき、または TAPI がアクティブになっている間に電話機とコンピュータを接続するワイヤが差し込まれたときに発生します。
PHONESTATE_DISCONNECTED:電話機と TAPI の接続が解除されたことを示します。このイベントは、TAPI がアクティブになっている間に電話機とコンピュータ間を接続しているワイヤが取り外されたときに発生します。
PHONESTATE_OWNER:電話機のオーナー数が変わったことを示します。
PHONESTATE_MONITORS:電話機のモニタ数が変わったことを示します。
PHONESTATE_DISPLAY:電話機のディスプレイに変化があったことを示します。
PHONESTATE_LAMP:電話機のランプに変化があったことを示します。
PHONESTATE_RINGMODE:電話機の呼び出し音モードが変わったことを示します。
PHONESTATE_SPEAKERHOOKSWITCH:このスピーカーフォンのフックスイッチの状態が変わったことを示します。
PHONESTATE_REINIT:電話機の設定で項目に変化があったことを示します。(新しい電話機の出現と同様に)これらの変化を検出するには、アプリケーションによる TAPI の使用状態を再初期化する必要があります。この状態変化はシステム内のすべての電話機に関係するため、この状態変化が発生しても、PHONE_STATE メッセージの hDevice パラメータは NULL のままです。
PHONESTATE_REMOVED:サービス プロバイダーによって電話機がシステムから削除されたことを示します(主な原因は、ユーザの操作や、コントロール パネルなどのユーティリティによる操作です)。通常は、この値を持つ PHONE_STATE メッセージの直後に、デバイスに関する PHONE_CLOSE メッセージが送信されます。この場合、TAPI が再初期化される前に、そのデバイスへのアクセスを試みると、PHONEERR_NODEVICE がアプリケーションに返されます。この値を格納する PHONE_STATE メッセージがサービス プロバイダーから TAPI に送信された場合、TAPI バージョン 1.4 以降を使用しているアプリケーションには、TAPI からメッセージが渡されます。古い API バージョンを使用しているアプリケーションには、通知が届きません。
PHONESTATE_SUSPEND:電話機が Energywise DeepSleep/PowersavePlus モードに移行して登録解除することを示します。
電話機ステータスの変化に関する詳細情報。dwParam1 に複数のフラグが設定されている場合は、複数のステータス項目が変わっているため、このパラメータは使用されません。全部の情報を取得するには、phoneGetStatus を呼び出す必要があります。
パラメータ dwparam2 は、PHONESTATE_LAMP、PHONESTATE_DISPLAY、PHONESTATE_HANDSETHOOKSWITCH、PHONESTATE_RINGMODE のいずれかで構成できます。Cisco Unified TSP は、ハンドセット、ヘッドセット、スピーカーそれぞれのフック スイッチを区別できないため、常にすべてのフック スイッチに対して PHONESTATE_HANDSETHOOKSWITCH 値が使用されます。
dwparam2 が PHONESTATE_LAMP の場合、dwparam2 は PHONE_BUTTON メッセージが定義するボタン ID になります。
dwParam1 が PHONESTATE_OWNER の場合、dwParam2 には新しいオーナー数が入ります。
dwParam1 が PHONESTATE_MONITORS の場合、dwParam2 には新しいモニタ数が入ります。
dwParam1 が PHONESTATE_LAMP の場合、dwParam2 には変更のあったランプのボタン/ランプ ID が入ります。
dwParam1 が PHONESTATE_RINGMODE の場合、dwParam2 には新しい呼び出し音モードが入ります。
dwParam1 が PHONESTATE_HANDSET、SPEAKER、または HEADSET の場合、dwParam2 にはそのフックスイッチ デバイスの新しいフックスイッチ モードが入ります。このパラメータには、次の PHONEHOOKSWITCHMODE_ 定数が入ります。
PHONEHOOKSWITCHMODE_ONHOOK:このデバイスのマイクロフォンおよびスピーカーは、いずれもオンフック状態のままです。
PHONEHOOKSWITCHMODE_MICSPEAKER:このデバイスのマイクロフォンおよびスピーカーは、いずれもアクティブなままです。Cisco Unified TSP は、ハンドセット、ヘッドセット、スピーカーを区別できないため、デバイスがオフフックの状態になると、この値が送信されます。
dw Param1 が PHONESTATE_SUSPEND の場合、dwParam2 は電話機が EnergywiseDeepSleep に移行して登録解除するときの EnergyWisePowerSavePlus 理由を格納します。
TAPI 仕様では、dwparam3 はゼロと規定されていますが、dwparam2 が PHONESTATE_LAMP の場合、Cisco Unified TSP は phoneGetLamp を呼び出してランプ状態を取得する代わりに、dwparam3 を使用して新しいランプ状態をアプリケーションに通知します。
このセクションでは、Cisco Unified TSP でサポートされている TAPI の phone 構造体について説明します。
。このセクションでは、シスコで設定された PHONECAPS 構造体の各メンバの属性について説明します。構造体メンバの値が、デバイス、回線またはコールに固有の場合は、リストで各条件の値が説明されます。
「Cisco Unified TSPxxx.TSP: Cisco IP PBX Service Provider Ver.X.X(x.x)」(コロンの前のテキストは TSP のファイル名を示し、「Ver.」の後のテキストはTSP のバージョンを示します)
「DeviceType:[type]」(type は、Cisco Unified Communications Manager データベースで指定されているデバイス タイプを指定します)
「Cisco Phone: [deviceName]」(deviceName は、Cisco Unified Communications Manager データベースのデバイス名を指定します)
STRINGFORMAT_ASCII
PHONESTATE_OWNER |
PHONESTATE_MONITORS |
PHONESTATE_DISPLAY |(CTI ルート ポイントの場合は設定されません)
PHONESTATE_LAMP |(CTI ルート ポイントの場合は設定されません)
PHONESTATE_RESUME |
PHONESTATE_REINIT |
PHONESTATE_SUSPEND
PHONEHOOKSWITCHDEV_HANDSET(CTI ルート ポイントの場合は設定されません)
PHONEHOOKSWITCHMODE_ONHOOK |(CTI ルート ポイントの場合は設定されません)
PHONEHOOKSWITCHMODE_MICSPEAKER |(CTI ルート ポイントの場合は設定されません)
PHONEHOOKSWITCHMODE_UNKNOWN(CTI ルート ポイントの場合は設定されません)
20(CTI ルート ポイントの場合は設定されません)
3(CTI ルート ポイントの場合は設定されません)
PHONEFEATURE_GETDISPLAY |
PHONEFEATURE_GETLAMP |
PHONEFEATURE_GETRING |
PHONEFEATURE_SETDISPLAY |
PHONEFEATURE_SETLAMP
PHONEHOOKSWITCHMODE_ONHOOK |(CTI ルート ポイントの場合は設定されません)
PHONEHOOKSWITCHMODE_MICSPEAKER |(CTI ルート ポイントの場合は設定されません)
PHONEINITIALIZEEXPARAMS 構造体には、アプリケーションと TAPI の関連付けを行うために使用されるパラメータ(アプリケーションによって選択されたイベント通知メカニズムなど)が入ります。phoneInitializeEx 関数は、この構造体を使用します。
typedef struct phoneinitializeexparams_tag { DWORD dwTotalSize; DWORD dwNeededSize; DWORD dwUsedSize; DWORD dwOptions; union { HANDLE hEvent; HANDLE hCompletionPort; } Handles; DWORD dwCompletionKey; } PHONEINITIALIZEEXPARAMS, FAR *LPPHONEINITIALIZEEXPARAMS;
このデータ構造体に割り当てられた合計サイズ(バイト単位)。
このデータ構造体に返されるすべての情報を格納するために必要なサイズ(バイト単位)。
有益な情報を格納するために使用されるこのデータ構造体の部分のサイズ(バイト単位)。
PHONEINITIALIZEEXOPTION_ 定数の 1 つ。アプリケーションが使用するイベント通知メカニズムを指定します。
dwOptions が PHONEINITIALIZEEXOPTION_USEEVENT になっている場合は、TAPI からこのメンバにイベント ハンドルが返されます。
dwOptions が PHONEINITIALIZEEXOPTION_USECOMPLETIONPORT となっている場合、アプリケーションはこのメンバを使用して、CreateIoCompletionPort によってオープンされた既存の完了ポートのハンドルを指定する必要があります。
dwOptions が PHONEINITIALIZEEXOPTION_USECOMPLETIONPORT となっている場合、アプリケーションはこのフィールドを使用して、GetQueuedCompletionStatus の lpCompletionKey パラメータで返された値を指定し、この完了メッセージをテレフォニー メッセージとして識別する必要があります。
PHONEMESSAGE 構造体には、次にアプリケーションへ配信されるメッセージが入ります。phoneGetMessage 関数は、次の構造体を返します。
typedef struct phonemessage_tag { DWORD hDevice; DWORD dwMessageID; DWORD_PTR dwCallbackInstance; DWORD_PTR dwParam1; DWORD_PTR dwParam2; DWORD_PTR dwParam3; } PHONEMESSAGE, FAR *LPPHONEMESSAGE;
電話機のハンドル。
phone メッセージ。
アプリケーションに返された(アプリケーションが phoneInitializeEx の中で指定した)インスタンス データ。TAPI は DWORD を解釈しません。
メッセージのパラメータ。
メッセージのパラメータ。
メッセージのパラメータ。
この構造体に渡されるパラメータ値の詳細については、「TAPI の phone メッセージ」を参照してください。
PHONESTATUS 構造体は、電話機の現在の状態に関する情報を提供します。phoneGetStatus および TSPI_phoneGetStatus 関数は、この構造体を返します。
デバイス固有拡張では、このデータ構造体のデバイス固有の(dwDevSpecificSize および dwDevSpecificOffset)可変サイズの領域を使用する必要があります。
(注) | dwPhoneFeatures メンバは、2.0 以降の API を使用して電話機をオープンするアプリケーションだけに使用できます。 |
typedef struct phonestatus_tag { DWORD dwTotalSize; DWORD dwNeededSize; DWORD dwUsedSize; DWORD dwStatusFlags; DWORD dwNumOwners; DWORD dwNumMonitors; DWORD dwRingMode; DWORD dwRingVolume; DWORD dwHandsetHookSwitchMode; DWORD dwHandsetVolume; DWORD dwHandsetGain; DWORD dwSpeakerHookSwitchMode; DWORD dwSpeakerVolume; DWORD dwSpeakerGain; DWORD dwHeadsetHookSwitchMode; DWORD dwHeadsetVolume; DWORD dwHeadsetGain; DWORD dwDisplaySize; DWORD dwDisplayOffset; DWORD dwLampModesSize; DWORD dwLampModesOffset; DWORD dwOwnerNameSize; DWORD dwOwnerNameOffset; DWORD dwDevSpecificSize; DWORD dwDevSpecificOffset; DWORD dwPhoneFeatures; } PHONESTATUS, FAR *LPPHONESTATUS;
このデータ構造体に割り当てられた合計サイズ(バイト単位)。
このデータ構造体に返されるすべての情報を格納するために必要なサイズ(バイト単位)。
有益な情報を格納するために使用されるこのデータ構造体の部分のサイズ(バイト単位)。
この電話機のステータス フラグのセット。このメンバには、PHONESTATUSFLAGS_ 定数のいずれかが使用されます。
この電話機に対してオーナー特権を持つアプリケーション モジュールの数。
この電話機に対してモニタ特権を持つアプリケーション モジュールの数。
電話機の現在の呼び出し音モード。
電話機のハンドセットの現在のフックスイッチ モード。PHONEHOOKSWITCHMODE_UNKNOWN
電話機のスピーカーフォンの現在のフックスイッチ モード。PHONEHOOKSWITCHMODE_UNKNOWN
電話機のヘッドセットの現在のフックスイッチ モード。PHONEHOOKSWITCHMODE_UNKNOWN
電話機の現在のオーナーになっているアプリケーションの名前を格納する可変サイズ フィールドのサイズ(バイト単位)、およびこのデータ構造体の先頭からのオフセット(バイト単位)。この名前は、phoneInitialize または phoneInitializeEx によってアプリケーションが呼び出されるときに提示するアプリケーション名に設定されます。アプリケーション名が提示されなかった場合は、アプリケーションのファイル名が使用されます。電話機のオーナーが存在しない場合、dwOwnerNameSize はゼロになります。
アプリケーションは、DeviceDataPassThrough デバイス固有拡張を使用して電話機に XSI データを送信できます。電話機は、アプリケーションにデータを返すことができます。そのデータは、このフィールドの一部として返されます。このデータの形式は、次のようになります。
struct PhoneDevSpecificData { DWORD m_DeviceDataSize ; // デバイス データのサイズ DWORD m_DeviceDataOffset ; // PHONESTATUS 構造体からの オフセット // これは実際の可変長デバイス データに従う。 }
アプリケーションは、0x00020000 以上の拡張バージョンをネゴシエートします。次の機能がサポートされます。
VARSTRING 構造体は、可変サイズの文字列を返します。これは、回線デバイス クラスおよび電話機クラスの両方で使用します。
(注) | VARSTRING には拡張性がありません。 |
typedef struct varstring_tag { DWORD dwTotalSize; DWORD dwNeededSize; DWORD dwUsedSize; DWORD dwStringFormat; DWORD dwStringSize; DWORD dwStringOffset; } VARSTRING, FAR *LPVARSTRING;
このデータ構造体に割り当てられた合計サイズ(バイト単位)。
このデータ構造体に返されるすべての情報を格納するために必要なサイズ(バイト単位)。
有益な情報を格納するために使用されるこのデータ構造体の部分のサイズ(バイト単位)。
文字列の書式。このメンバは、STRINGFORMAT_Constants の 1 つを使用します。
文字列情報が入る可変サイズ デバイス フィールドのサイズ(バイト単位)、およびこのデータ構造体の先頭からのオフセット(バイト単位)。
可変構造体で文字列を返せない場合、dwStringSize メンバおよび dwStringOffset メンバが、次のいずれかの方法で設定されます。
AVAudio32.dll は、シスコ製 Wave ドライバとの Wave インターフェイスを実装します。システムでは、ウェーブフォームの入出力デバイス用の、すべての API がサポートされています。
Cisco TSP 8.0 には Cisco Media Driver が含まれています。Cisco Media Driver は、TAPI ベースのアプリケーションがメディアとの相互通信を可能にする、新しく、革新的な方法です。Cisco TSP 8.0(1) では、Cisco Media Driver と Cisco Wave Driver がサポートされています。一度にアクティブになるのは、1 つのドライバだけです。詳細については、Cisco TSP Media Driverを参照してください。
waveInAddBuffer 関数は、指定されたウェーブフォーム オーディオ入力デバイスに、入力バッファを送信します。バッファにデータが入ると、アプリケーションは通知を受け取ります。
MMRESULT waveInAddBuffer( HWAVEIN hwi, LPWAVEHDR pwh, UINT cbwh );
ウェーブフォーム オーディオ入力デバイスのハンドル。
バッファを指定する WAVEHDR 構造体のアドレス。
WAVEHDR 構造体のサイズ(バイト単位)。
MMRESULT waveInClose( HWAVEIN hwi );
ウェーブフォーム オーディオ入力デバイスのハンドル。関数が成功した場合、この呼び出し後のハンドルは無効のままです。
waveInGetID 関数は、指定されたウェーブフォーム オーディオ入力デバイスのデバイス ID を取得します。
この関数は、下位互換性を維持するためにサポートされています。新しいアプリケーションでは、デバイス ID の取得ではなく、デバイス ID のキャストが可能です。
MMRESULT waveInGetID( HWAVEIN hwi, LPUINT puDeviceID );
ウェーブフォーム オーディオ入力デバイスのハンドル。
デバイス ID が入る変数のアドレス。
waveInGetPosition 関数は、指定されたウェーブフォーム オーディオ入力デバイスの現在の入力位置を取得します。
MMRESULT waveInGetPosition( HWAVEIN hwi, LPMMTIME pmmt, UINT cbmmt );
ウェーブフォーム オーディオ入力デバイスのハンドル。
MMTIME 構造体のアドレス。
MMTIME 構造体のサイズ(バイト単位)。
waveInOpen 関数は、録音を開始するために、指定されたウェーブフォーム オーディオ入力デバイスをオープンします。
MMRESULT waveInOpen( LPHWAVEIN phwi, UINT uDeviceID, LPWAVEFORMATEX pwfx, DWORD dwCallback, DWORD dwCallbackInstance, DWORD fdwOpen );
オープン状態のウェーブフォーム オーディオ入力デバイスを識別するハンドルが入っているアドレス。このハンドルは、他のウェーブフォーム オーディオ入力関数を呼び出す際に、デバイスを識別するために使用します。fdwOpen.HDR 構造体で WAVE_FORMAT_QUERY が指定されている場合、このパラメータは NULL になることがあります。
オープンするウェーブフォーム オーディオ入力デバイスの ID。オープン状態のウェーブフォーム オーディオ入力デバイスのハンドルまたはデバイス ID のいずれかになります。デバイス ID の代わりに次のフラグを使用できます。
WAVE_MAPPER:指定形式で録音できるウェーブフォーム オーディオ入力デバイスがこの関数によって選択されます。
ウェーブフォーム オーディオ データの録音に使用する形式を指定する WAVEFORMATEX 構造体のアドレス。この構造体は、waveInOpen が終了した直後に開放できます。
(注) | TAPI Wave Driver がサポートしている形式には、16 ビット PCM(8000 Hz)、8 ビット mulaw(8000 Hz)、および 8 ビット alaw(8000 Hz)があります。 |
ウェーブフォーム オーディオの録音中に、録音の進行状況に関するメッセージを処理するために呼び出される固定コールバック関数、イベント ハンドル、ウィンドウのハンドル、またはスレッドの ID のアドレス。コールバック関数が要求されない場合は、この値をゼロに指定することができます。コールバック関数の詳細は、TAPI API の「waveInProc」を参照してください。
コールバック メカニズムに渡されたユーザ インスタンス データ。このパラメータは、ウィンドウ コールバック メカニズムでは使用されません。
デバイスのオープンに関するフラグ。適用できる値の定義は次のとおりです。
CALLBACK_EVENT:dwCallback パラメータはイベント ハンドルを指定します。
CALLBACK_FUNCTION:dwCallback パラメータはコールバック プロシージャ アドレスを指定します。
CALLBACK_NULL:コールバック メカニズムなし。これはデフォルトの設定を表します。
CALLBACK_THREAD:dwCallback パラメータはスレッド ID を指定します。
CALLBACK_WINDOW:dwCallback パラメータはウィンドウ ハンドルを指定します。
WAVE_FORMAT_DIRECT:このフラグが指定されている場合、ACM ドライバはオーディオ データの変換を実行しません。
WAVE_FORMAT_QUERY:この関数は指定形式がそのデバイスでサポートされているかどうかを確認しますが、デバイスは開きません。
WAVE_MAPPED:uDeviceID パラメータが、Wave マッパーによってマップされるウェーブフォーム オーディオ デバイスを指定します。
MMRESULT waveInPrepareHeader( HWAVEIN hwi, LPWAVEHDR pwh, UINT cbwh );
ウェーブフォーム オーディオ入力デバイスのハンドル。
準備するバッファを指定する WAVEHDR 構造体のアドレス。
WAVEHDR 構造体のサイズ(バイト単位)。
waveInReset 関数は、指定されたウェーブフォーム オーディオ入力デバイスでの入力を停止し、現在の位置をゼロにリセットします。保留中のすべてのバッファが完了とマークされ、アプリケーションに返されます。
MMRESULT waveInReset( HWAVEIN hwi );
ウェーブフォーム オーディオ入力デバイスのハンドル。
MMRESULT waveInStart( HWAVEIN hwi );
ウェーブフォーム オーディオ入力デバイスのハンドル。
waveInUnprepareHeader 関数は、waveInPrepareHeader 関数によって行われた準備を消去します。この関数は、デバイス ドライバがバッファにデータを格納し、そのデータをアプリケーションに返した後に呼び出す必要があります。この関数は、バッファを開放する前に呼び出す必要があります。
MMRESULT waveInUnprepareHeader( HWAVEIN hwi, LPWAVEHDR pwh, UINT cbwh );
ウェーブフォーム オーディオ入力デバイスのハンドル。
消去するバッファを指定する WAVEHDR 構造体のアドレス。
WAVEHDR 構造体のサイズ(バイト単位)。
MMRESULT waveOutClose( HWAVEOUT hwo );
ウェーブフォーム オーディオ出力デバイスのハンドル。関数が成功した場合、この呼び出し後のハンドルは無効のままです。
MMRESULT waveOutGetDevCaps( UINT uDeviceID, LPWAVEOUTCAPS pwoc, UINT cbwoc );
ウェーブフォーム オーディオ出力デバイスの ID。オープン状態のウェーブフォーム オーディオ出力デバイスのハンドルまたはデバイス ID のいずれかになります。
デバイスの機能に関する情報が入っている WAVEOUTCAPS 構造体のアドレス。
WAVEOUTCAPS 構造体のサイズ(バイト単位)。
waveOutGetID 関数は、指定されたウェーブフォーム オーディオ出力デバイスのデバイス ID を取得します。
この関数は、下位互換性を維持するためにサポートされています。新しいアプリケーションでは、デバイス ID の取得ではなく、デバイス ID のキャストが可能です。
MMRESULT waveOutGetID( HWAVEOUT hwo, LPUINT puDeviceID );
ウェーブフォーム オーディオ出力デバイスのハンドル。
デバイス ID が入る変数のアドレス。
waveOutGetPosition 関数は、指定されたウェーブフォーム オーディオ出力デバイスの現在の再生位置を取得します。
MMRESULT waveOutGetPosition( HWAVEOUT hwo, LPMMTIME pmmt, UINT cbmmt );
ウェーブフォーム オーディオ出力デバイスのハンドル。
MMTIME 構造体のアドレス。
MMTIME 構造体のサイズ(バイト単位)。
waveOutOpen 関数は、ウェーブフォームを再生するために、指定されたウェーブフォーム オーディオ出力デバイスをオープンします。
MMRESULT waveOutOpen( LPHWAVEOUT phwo, UINT uDeviceID, LPWAVEFORMATEX pwfx, DWORD dwCallback, DWORD dwCallbackInstance, DWORD fdwOpen );
オープン状態のウェーブフォーム オーディオ出力デバイスを識別するハンドルが入っているアドレス。このハンドルは、他のウェーブフォーム オーディオ出力関数が呼び出される際に、デバイスを識別するために使用します。WAVE_FORMAT_QUERY フラグで fdwOpen が指定されている場合、このパラメータは NULL になることがあります。
オープンするウェーブフォーム オーディオ出力デバイスの ID。オープン状態のウェーブフォーム オーディオ入力デバイスのハンドルまたはデバイス ID のいずれかになります。デバイス ID の代わりに次のフラグを使用できます。
WAVE_MAPPER:この関数は、指定された形式を再生できるウェーブフォーム オーディオ出力デバイスを選択します。
デバイスに送信されるウェーブフォーム オーディオ データの形式を指定する WAVEFORMATEX 構造体のアドレス。この構造体は、waveOutOpen へ渡した直後に開放できます。
(注) | TAPI Wave Driver でサポートされている形式には、16 ビット PCM(8000 Hz)、8 ビット mulaw(8000 Hz)、および 8 ビット alaw(8000 Hz)があります。 |
ウェーブフォーム オーディオの再生中に、再生の進行状況に関するメッセージを処理するために呼び出される固定コールバック関数、イベント ハンドル、ウィンドウのハンドル、またはスレッドの ID のアドレス。コールバック関数が要求されない場合は、この値をゼロに指定することができます。コールバック関数の詳細は、TAPI API の「waveOutProc」を参照してください。
コールバック メカニズムに渡されたユーザ インスタンス データ。このパラメータは、ウィンドウ コールバック メカニズムでは使用されません。
デバイスのオープンに関するフラグ。適用できる値の定義は次のとおりです。
CALLBACK_EVENT:dwCallback パラメータはイベント ハンドルを表します。
CALLBACK_FUNCTION:dwCallback パラメータはコールバック プロシージャ アドレスを指定します。
CALLBACK_NULL:コールバック メカニズムなし。この値はデフォルトの設定を指定します。
CALLBACK_THREAD:dwCallback パラメータはスレッド ID を表します。
CALLBACK_WINDOW:dwCallback パラメータはウィンドウ ハンドルを指定します。
WAVE_ALLOWSYNC:このフラグが指定されている場合は、同期ウェーブフォーム オーディオ デバイスをオープンできます。同期ドライバのオープン時にこのフラグが指定されない場合、デバイスのオープンは失敗します。
WAVE_FORMAT_DIRECT:このフラグが指定されている場合、ACM ドライバはオーディオ データの変換を実行しません。
WAVE_FORMAT_QUERY:このフラグが指定されている場合、waveOutOpen によって、指定された形式がそのデバイスでサポートされているかどうかが確認されますが、実際にはデバイスはオープンしません。
WAVE_MAPPED:このフラグが指定されている場合、uDeviceID パラメータは、Wave マッパーによってマップされるウェーブフォーム オーディオ デバイスを指定します。
waveOutPrepareHeader 関数は、ウェーブフォームを再生するために、ウェーブフォーム オーディオ データ ブロックを準備します。
MMRESULT waveOutPrepareHeader( HWAVEOUT hwo, LPWAVEHDR pwh, UINT cbwh );
ウェーブフォーム オーディオ出力デバイスのハンドル。
準備するデータ ブロックを指定する WAVEHDR 構造体のアドレス。
WAVEHDR 構造体のサイズ(バイト単位)。
waveOutReset 関数は、指定されたウェーブフォーム オーディオ出力デバイスの再生を停止し、現在の位置をゼロにリセットします。保留中のすべての再生バッファが完了とマークされ、アプリケーションに返されます。
MMRESULT waveOutReset( HWAVEOUT hwo );
ウェーブフォーム オーディオ出力デバイスのハンドル。
waveOutUnprepareHeader 関数は、waveOUtPrepareHeader 関数によって行われた準備を消去します。デバイス ドライバがデータ ブロックの使用を完了した後に、この関数を呼び出します。この関数は、バッファを開放する前に呼び出す必要があります。
MMRESULT waveOutUnprepareHeader( HWAVEOUT hwo, LPWAVEHDR pwh, UINT cbwh );
ウェーブフォーム オーディオ出力デバイスのハンドル。
消去するデータ ブロックを識別する WAVEHDR 構造体のアドレス。
WAVEHDR 構造体のサイズ(バイト単位)。
MMRESULT waveOutWrite( HWAVEOUT hwo, LPWAVEHDR pwh, UINT cbwh );
ウェーブフォーム オーディオ出力デバイスのハンドル。
データ ブロックに関する情報を格納する WAVEHDR 構造体のアドレス。
WAVEHDR 構造体のサイズ(バイト単位)。