この製品のマニュアルセットは、偏向のない言語を使用するように配慮されています。このマニュアルセットでの偏向のない言語とは、年齢、障害、性別、人種的アイデンティティ、民族的アイデンティティ、性的指向、社会経済的地位、およびインターセクショナリティに基づく差別を意味しない言語として定義されています。製品ソフトウェアのユーザーインターフェイスにハードコードされている言語、RFP のドキュメントに基づいて使用されている言語、または参照されているサードパーティ製品で使用されている言語によりドキュメントに例外が存在する場合があります。シスコのインクルーシブランゲージに対する取り組みの詳細は、こちらをご覧ください。
このドキュメントは、米国シスコ発行ドキュメントの参考和訳です。リンク情報につきましては、日本語版掲載時点で、英語版にアップデートがあり、リンク先のページが移動/変更されている場合がありますことをご了承ください。あくまでも参考和訳となりますので、正式な内容については米国サイトのドキュメントを参照ください。
Cisco Media Driver は、TAPI ベースのアプリケーションでの音声案内の再生、コールの記録などのメディアとの相互通信を可能にする、新しく革新的な方法を採用しています。
Cisco TSP 8.0(1) では、Cisco Media Driver と Cisco Wave Driver の両方がサポートされていますが、一度にアクティブにできるドライバは常に 1 つのみです。
Cisco Media Driver には、次のように複数の利点があります。
容易なインストールと管理:Cisco Media Driver の設定は、Cisco TSP インストール ウィザードで完了できます。チャネルおよびポート設定は、設定済みのすべての TSP インスタンスに一貫して自動的に適用されます。
パフォーマンスとスケーラビリティ:Cisco Media Driver を使用すると、最大 1000 個の設定済みポートで数百の同時にアクティブなメディア チャネルをサポートするように拡張できます。TAPI アプリケーションでサポートされるチャネルの数を確認するには、アプリケーション ベンダーのインストール ガイドを参照してください。
コーデックのサポート:Cisco Media Driver は、8KHz、16 ビット PCM、G.711 a-law、G.711 u-law をネイティブにサポートします。さらに、パススルー モードが有効な場合は、G.729a もサポートされます。
信頼性:Cisco Media Driver は、Windows アプリケーションと同様に独立したプロセスとして実行されるので、アプリケーションの安定性および信頼性が向上します。メディア アプリケーションの作成およびデバッグが、大幅に容易になります。
次のヘッダー ファイルには、Cisco Rtp Library によって公開されているすべての関数、データ構造体などの宣言が含まれています。
通常のアプリケーションでは、Cisco Rtp Library の機能を使用するためには、ciscortpapi.h および ciscortpep.h ファイルだけを明示的に取り込めば十分です。
Cisco Rtp Library の機能を使用するためには、次のインポート ライブラリをアプリケーションにリンクする必要があります。
次の DLL は、CiscoTSP プラグインの一部としてインストールされ、Cisco Rtp Library によって使用されます。
Windows 32bit OS(x86):
ciscortplib.dll
ciscortpmon.dll
ciscortpg711a.dll
ciscortpg711u.dll
ciscortpg729.dll
ciscortppcm16.dll
Windows 64bit OS(x64):
TAPI アプリケーションで、TAPI 回線デバイスと Rtp Library メディア エンドポイントの関連付けを可能にするために、Cisco TSP は、ciscowave/in と ciscowave/out の 2 つの新しいデバイス クラスを実装しています。TAPI 回線デバイスが、Cisco Rtp Library によってメディアを終端できれば、アプリケーションは TAPI lineGetID() 関数内で ciscowave/in および ciscowave/out デバイス クラス名を使用することによって、関連付けられたメディア デバイス ID を取得できます。メディア デバイス ID は、Cisco Rtp Library API で使用して、メディア エンドポイントを作成したり、対応する TAPI 回線デバイス上でメディアを操作したりすることができます。
次の図は、Cisco TAPI サービス プロバイダーと Cisco Rtp Library の機能を使用する TAPI アプリの概要を示します。
Cisco Media Driver デバイスは、G.711 のサポートをネイティブにアドバタイズします。トランスコーディングが必要になると、Cisco Unified CM がメディア ターミネーション ポイント(MTP)を自動的に呼び出します(例 1 を参照)。MTP が設定されておらず、トランスコーディングが必要な場合、コールは確立できません(例 2 を参照)。
G.729 をネイティブにサポートするアプリケーションでは、G729PassThrough レジストリ オプションを ON(1)に設定してデフォルト コーデックのアドバタイズメントを変更できます。
次に TSP アプリケーションは、メディアを受信するデバイスがサポートする互換性のあるコーデックに基づいて、適切なメディア ファイル(G.711 または G.729)を再生します(以下の例 3 を参照)。
次の図のメッセージ フローを、ステップ 1 と 2 で説明します。
TAPI を初期化し、利用可能な回線デバイスについて LINEINFO を取得し、Cisco Rtp Library の機能を使用できるデバイスを検索します。
特定の回線デバイスに関連付けられたメディア デバイス ID を取得します。
次の図のメッセージ フローを、ステップ 3 ~ 5 で説明します。
Rtp Library を初期化します。
Cisco lineDevSpecific 拡張を使用して、関連するデバイスに関するメディア ストリーム イベントの受信を登録します。
メディア イベントのモニタリングを開始します。
次の図のメッセージ フローを、ステップ 6 ~ 10 で説明します。
メディア エンドポイントを作成します。
in/out 用のストリーム ハンドルを取得し、データ ストリーミングを開始します。
データを送受信します。
データ ストリーミングを停止し、エンドポイントを閉じます。
プログラムを終了する前に、EpAPI を閉じます。
CMAPI bool EpApiInit ( PRTPLIBTRACE pTraceCallback, USHORT portRangeStart, USHORT numPorts, int IPAddressFamily, PRTPADDR pDefaultRtpAddr );
渡されたトレース レコード データを使用して呼び出される、アプリケーション コールバック関数へのポインタです。
エンドポイントの作成に使用できる、連続した UDP ポート範囲(ポート プール)の最初のポート番号です。
エンドポイントの作成に使用できる、UDP ポート範囲(ポート プール)にあるポートの数です。
Rtp Library がエンドポイントの作成に使用する IP アドレス ファミリは、次のように設定できます。
この設定は、pDefaultRtpAddr パラメータによって上書きできます。
Rtp Library がエンドポイントの作成に使用する IP アドレス。NULL 以外は、このアドレスのみを使用します。
エラーが発生しなければ、この関数は true を返します。エラーが発生した場合、false が返されます。具体的なエラー コードは、EpApiGetLastError を呼び出して取得できます。
EpApiInit が true を返す場合でも、エラー コードが設定される場合があります。場合によっては、パラメータやレジストリ設定が無効な場合でも、デフォルトのアクションや値を想定できるからです。そのような場合、EpApiInit は true を返しますが、同時に適切なエラー コードを設定して問題点を示します。
CMAPI bool EpApiInitByDefault ( PRTPLIBTRACEpTraceCallback, );
渡されたトレース レコード データを使用して呼び出される、アプリケーション コールバック関数へのポインタです。
エラーが発生しなければ、この関数は true を返します。エラーが発生した場合、false が返されます。具体的なエラー コードは、EpApiGetLastError を呼び出して取得できます。
Rtp Library は、レジストリが次のように設定されている場合と同様に初期化されます。
CMAPI bool EpApiClose ();
エラーが発生しなければ、この関数は true を返します。エラーが発生した場合、false が返されます。具体的なエラー コードは、EpApiGetLastError を呼び出して取得できます。
この関数を実行すると、その結果、すべてのアクティブなセッション、接続およびストリームが終了し、タイマーが閉じ、すべてのデータが解放されます。
CMAPI int EpLocalAddressPortGetAll( PRTPADDR pBuffer, int * pBufSize );
エラーが発生しなければ、この関数は利用可能なローカル IP アドレスの数および pBuffer の RTPADDR 構造体の配列を返します。
pBuffer パラメータ値が NULL の場合、この関数は、利用可能なローカル IP アドレスの数を返し、pBufSize には RTPADDR 構造体の配列に必要なバッファ サイズが含まれます。
エラーが発生した場合、0 が返されます。具体的なエラー コードは、EpApiGetLastError を呼び出して取得できます。EP_ERR_PARAM_INVALID エラーの場合、pBufSize には、必要なバッファのサイズが含まれます。
CMAPI PRTPADDR EpLocalAddressPortGet();
エラーが発生しなければ、この関数は RTPADDR 構造体へのポインタに加え、Rtp Library が使用する最初の(またはデフォルトの)ローカル IP アドレス、および予約された UDP ポート番号を返します。
エラーが発生した場合、NULL が返されます。具体的なエラー コードは、EpApiGetLastError を呼び出して取得できます。
CMAPI PRTPADDR EpLocalAddressPortGetByFamily( int IPAddressFamily );
IP アドレス ファミリ:AF_INET または AF_INET6
エラーが発生しなければ、この関数は RTPADDR 構造体へのポインタに加え、Rtp Library が使用する、指定されたファミリの最初のローカル IP アドレス、および予約された UDP ポート番号を返します。エラーが発生した場合、NULL が返されます。具体的なエラー コードは、EpApiGetLastError を呼び出して取得できます。
Rtp Library ポート プールから UDP ポートを予約し、index パラメータによって指定されたネットワーク インターフェイス カードの IP アドレスを使用して、RTPADDR データ構造体のみに返します。
CMAPI PRTPADDR EpLocalAddrPortGetByIdx ( int index );
EpLocalAddressGetAll 関数呼び出しによって返された使用可能なローカル ネットワーク アドレスのリスト内でのインデックス。
エラーが発生しなければ、この関数は、ローカル IP アドレスと予約された UDP ポート番号が入った RTPADDR 構造体へのポインタを返します。エラーが発生した場合、NULL が返されます。具体的なエラー コードは、EpApiGetLastError を呼び出して取得できます。
使用可能なローカル ネットワーク アドレスのリストは、EpLocalAddressGetAll 関数呼び出しによって取得できます。
以前に EpLocalAddressGet、EpLocalAddressGetByIdx、または EpLocalAddressGetByFamily によって予約されたローカル UDP ポートを元のポート プールに戻します。
CMAPI bool EpLocalAddrPortFree ( PRTPADDR pLocalAddrPort );
以前に予約されたローカル UDP ポートのポート番号が入った RTPADDR データ構造体へのポインタ。
エラーが発生しなければ、この関数は true を返します。エラーが発生した場合、false が返されます。具体的なエラー コードは、EpApiGetLastError を呼び出して取得できます。
ローカル UDP は、EpLocalAddressGet、EpLocalAddressGetByIdx または EpLocalAddressGetByFamily によって予約される場合があります。
CMAPI HANDLE EpOpenById ( DWORD deviceId, StreamDirection streamDir, PRTPDATACALLBACK pCallback );
エラーが発生しなければ、この関数は、エンドポイントの参照に使用できるハンドルを返します。エラーが発生した場合、NULL が返されます。具体的なエラー コードは、EpApiGetLastError を呼び出して取得できます。
CMAPI bool EpClose ( HANDLE hEp );
EpOpen によって返されたエンドポイント ハンドル。
エラーが発生しなければ、この関数は true を返します。エラーが発生した場合、false が返されます。具体的なエラー コードは、EpApiGetLastError を呼び出して取得できます。
CMAPI HANDLE EpGetStreamHandle ( HANDLE hEp, StreamType streamType, StreamDirection streamDir );
エラーが発生しなければ、この関数は、エンドポイントの参照に使用できるストリーム ハンドルを返します。エラーが発生した場合、NULL が返されます。具体的なエラー コードは、EpApiGetLastError を呼び出して取得できます。
CMAPI bool EpStreamStart ( HANDLE hStream, PRTPDATACALLBACK pCallback );
EpGetStreamHandle によって返されたストリーム ハンドル。
データ バッファの送受信の際や、エラー発生時に呼び出されるアプリケーション コールバック関数へのポインタです。
エラーが発生しなければ、この関数は true を返します。エラーが発生した場合、false が返されます。具体的なエラー コードは、EpApiGetLastError を呼び出して取得できます。
データ フローのストリーミングを開始する(Socket、ポートのオープン)ためには、EpStreamStart() をアプリケーションから明示的に呼び出す必要があります。レガシーなカーネル モード Wave Driver とは違い、ストリーミングは Rtp Library によって暗黙的に終了されません。
CMAPI bool EpStreamStop ( HANDLE hStream );
EpGetStreamHandle によって返されたストリーム ハンドル。
エラーが発生しなければ、この関数は true を返します。エラーが発生した場合、false が返されます。具体的なエラー コードは、EpApiGetLastError を呼び出して取得できます。
データ フローのストリーミングを終了するには、EpStreamStop() をアプリケーションから明示的に呼び出す必要があります。レガシーなカーネル モード Wave Driver とは違い、ストリーミングは Rtp Library によって暗黙的に終了されません。
CMAPI bool EpStreamRead ( HANDLE hStream, PUCHAR pBuffer, int bufLen, PVOID pAppData, PRTPDATACALLBACK pCallback );
EpGetStreamHandle によって返されたストリーム ハンドル。
着信データ用バッファへのポインタ。
バッファ サイズ。
アプリケーション データ領域へのポインタ。バッファとアソシエートされ、pAppData パラメータとしてアプリケーション コールバック関数に戻されます。
データ バッファの送信の際や、エラー発生時に呼び出されるアプリケーション コールバック関数へのポインタです。
エラーが発生しなければ、この関数は true を返します。エラーが発生した場合、false が返されます。具体的なエラー コードは、EpApiGetLastError を呼び出して取得できます。
CMAPI bool EpStreamWrite ( HANDLE hStream, PUCHAR pBuffer, int bufLen, PVOID pAppData, PRTPDATACALLBACK pCallback );
EpGetStreamHandle によって返されたストリーム ハンドル。
データが入ったバッファへのポインタ。
データ長。
アプリケーション データ領域へのポインタ。バッファとアソシエートされ、pAppData パラメータとしてアプリケーション コールバック関数に戻されます。
データ バッファに書き込まれたときや、エラー発生時に呼び出されるアプリケーション コールバック関数へのポインタです。
エラーが発生しなければ、この関数は true を返します。エラーが発生した場合、false が返されます。具体的なエラー コードは、EpApiGetLastError を呼び出して取得できます。
CMAPI bool EpStreamCodecInGet ( HANDLE hStream, PWAVEFORMATEX pWaveFormat );
EpGetStreamHandle によって返されたストリーム ハンドル。
WAVEFORMATEX データ構造体へのポインタ。要求が正常に完了すると、この構造体にストリーム インバウンド コーデック形式のデータが入ります。
エラーが発生しなければ、この関数は true を返します。エラーが発生した場合、false が返されます。具体的なエラー コードは、EpApiGetLastError を呼び出して取得できます。
CMAPI bool EpStreamCodecInSet ( HANDLE hStream, PWAVEFORMATEX pWaveFormat, ULONG pktSizeMs );
EpGetStreamHandle によって返されたストリーム ハンドル。
コーデック情報が格納された WAVEFORMATEX データ構造体へのポインタ。
パケット サイズ(ミリ秒単位)。値 0 が指定されている場合、デフォルト値(20)が指定されます。
エラーが発生しなければ、この関数は true を返します。エラーが発生した場合、false が返されます。具体的なエラー コードは、EpApiGetLastError を呼び出して取得できます。
CMAPI bool EpStreamCodecOutGet ( HANDLE hStream, PWAVEFORMATEX pWaveFormat );
EpGetStreamHandle によって返されたストリーム ハンドル。
WAVEFORMATEX データ構造体へのポインタ。要求が正常に完了すると、この構造体にストリーム アウトバウンド コーデック形式のデータが入ります。
エラーが発生しなければ、この関数は true を返します。エラーが発生した場合、false が返されます。具体的なエラー コードは、EpApiGetLastError を呼び出して取得できます。
CMAPI bool EpStreamCodecInSet ( HANDLE hStream, PWAVEFORMATEX pWaveFormat, ULONG pktSizeMs );
EpGetStreamHandle によって返されたストリーム ハンドル。
コーデック情報が格納された WAVEFORMATEX データ構造体へのポインタ。
パケット サイズ(ミリ秒単位)。値 0 が指定されている場合、デフォルト値(20)が指定されます。
エラーが発生しなければ、この関数は true を返します。エラーが発生した場合、false が返されます。具体的なエラー コードは、EpApiGetLastError を呼び出して取得できます。
CMAPI bool EpApiTraceLevelSet ( int traceLevel );
ほとんどの EpApi 関数は、関数が戻ったときに具体的なエラーの原因を返すのではなく、EpApiGetLastError 関数の呼び出しによって取得できるグローバル エラー コード値を設定します。次のリストに、EpApiGetLastError 関数によって返される主なエラー コードを示します。エラーは、数字の順に表示します。
アプリケーションは業務完了、データ転送、およびエラーなどに関する情報を入手するためにコールバック関数を定義できます。コールバック関数は、エンドポイントの作成時、ストリーム コールバックのオープン時、ストリーム コールバック演算の開始時に指定できます。コールバック演算が指定されていないと、対応するストリーム コールバックが呼び出されます(定義されている場合)。ストリーム コールバックが指定されていないと、対応するコールバック エンドポイントが呼び出されます(定義されている場合)。
(注) | コールバック関数が定義されている場合、対応するストリーム、エンドポイントなどで開始される演算ごとに呼び出されます。コールバック関数が動的に作成され、破壊されるオブジェクトのメソッドとして定義される場合に考慮する必要があります。その場合、破壊は開始されたすべての演算が完了するまで発生しません。 |
typedef void (WINAPI *PRTPENDPOINTCALLBACK) ( HANDLE hEp, HANDLE hStream, DWORD dwError, PUCHAR pData, DWORD dwDataSize, LPVOID pUserData, bool bIsSilence, StreamDirection streamDir );
typedef void (WINAPI *PRTPDATACALLBACK) ( HANDLE hStream, DWORD dwError, PUCHAR pData, DWORD dwDataSize, LPVOID pUserData, bool bIsSilence, );
Rtp ストリーム ハンドル。
0 でない場合は、エラーが発生したことを示します。
エンドポイント ハンドル。
受信/転送したバイト数。
操作に関連付けられたアプリケーション データ。
true の場合、無音状態が検出されたことを示します。
IP アドレス、UDP ポート番号など、エンドポイント関連のすべてのデータが入った基本的なエンドポイント データ構造体。
typedef struct sRTPAddrInfo { ADDRINFOT info, SOCKADDR_STORAGE addr, SOCKET sock, bool multicast, DWORD dscp, SRTPINFO2 srtp, RTPSIL silence, ULONG pktSizeMs } RTPADDR, *PRTPADDR;
システム定義の ADDRINFOT 構造体
システム定義の SOCKADDR_STORAGE 構造体
システム定義の SOCKET データ(バウンド ソケット)
true に設定すると、RTPADDR インスタンスがマルチキャスト アドレスを表します。そうでない場合は、ユニキャストです。
DSCP/QoS データ
SRTP データ
無音処理パラメータ
パケット サイズ(ミリ秒単位)
特定のエンドポイントに関する無音処理関連のデータが入っています。次の SilenceType 列挙型が使用されます。
typedef enum { Off = 0, Packets = Off + 1, Energy = Packets +1 } SilenceType; typedef struct { SilenceType type, ULONG duration, ULONG threshold, ULONG currentOffset, bool detecting } RTPSIL, *PRPTSIL;
SilenceType に定義されている無音検出タイプ
継続時間(ミリ秒単位)
エネルギーしきい値
無音オフセット(G.729)
無音検出が有効です。
typedef struct { WAVEFORMATEX wfe; WORD (WINAPI *formatTag) (); WORD * (WINAPI *supported) (ULONG & nmb); ULONG (WINAPI *fmtBytesToThis) (WORD fmt, ULONG len); ULONG (WINAPI *thisBytesToFmt) (ULONG len, WORD fmt); UCHAR (WINAPI *pad) (); PXLATE xlateTo; PXLATE xlateFrom; PRTPSIL (WINAPI *silenceInit)(PRTPSIL ps, SilenceType type, ULONG duration, ULONG threshold); ULONG (WINAPI *silenceSet) (PRTPSIL, PUCHAR, ULONG); bool (WINAPI *isSilence) (PRTPSIL, ULONG pcktSizeInMs, bool & beenChanged, PUCHAR, ULONG); void (WINAPI *silenceFree)(PRTPSIL); } RTPCODEC, *PRTPCODEC;
Rtp Library には、アプリケーションのデバッグとトラブルシューティングを容易にするために、複数のロギング オプションが用意されています。
トレース データを OutputDebugString に送信する。これにより、たとえば Sysinternals DebugView など、任意の"トレース リスナー"で表示できます。
トレース レベルは、トレース出力に含まれるメッセージの種類を指定し、次のように定義されています。
トレース レベル |
説明 |
---|---|
0:エラー |
エラー メッセージのみを出力します(Windows のイベント ログに報告されます)。 |
1:アラーム |
アラームおよびエラー メッセージを出力します(Windows のイベント ログに報告されます)。 |
2:警告 |
警告、アラームおよびエラー メッセージを出力します(Windows のイベント ログに報告されます)。 |
3:情報 |
情報メッセージ、アラーム、警告およびエラー メッセージを出力します(Windows のイベント ログには報告されません)。 |
4:デバッグ |
デバッグ情報、情報メッセージ、アラーム、警告およびエラー メッセージを出力します(Windows のイベント ログには報告されません)。 |
アプリケーションは、トレース コールバックを設定できます。コールバック関数は、トレースを記録する準備が整いさえすれば、Rtp Library によっていつでも起動でき、トレース レコード データを入力されます。トレース コールバックは、EpApi の初期化時に、設定および変更が可能です。トレース コールバック関数タイプは、次のように宣言されています。
typedef void (WINAPI *PRTPLIBTRACE) ( int level, const _TCHAR *pData );
現在のトレース レコード レベル
現在のトレース レコード データへのポインタ