ボイス クライアント メッセージの処理

  • [アーティクル]

ボイス クライアント メッセージの処理

ここでは、Microsoft® DirectPlay® ボイス セッションのクライアントのメッセージを処理する方法について説明する。ホスト関連のメッセージングの説明については、「ボイス ホスト メッセージの処理」を参照すること。メッセージングの全般的な内容については、「DirectPlay メッセージングの処理」を参照すること。

  • Voice メッセージングに関する全般的な考慮点
  • 起動メッセージ
  • 通常のゲーム プレイ中のメッセージング
  • セッション終了メッセージ

Voice メッセージングに関する全般的な考慮点

DirectPlay Voice で使われる多くのメッセージは、DirectPlay コア アプリケーション プログラミング インターフェイス (API) で使われるものと類似している。しかし、類似したコア メッセージと Voice メッセージであっても、使い方が異なる場合がある。

たとえば、コア セッションまたはボイス セッションに接続すると、DirectPlay は接続試行の結果が含まれた完了メッセージを返す。コア セッションでは、同期的に接続する場合でも、状況によっては DPN_MSGID_CONNECT_COMPLETE 完了メッセージを受信することがある。しかし、DirectPlay Voice では、同期的にボイス セッションに接続しようとする場合、完了メッセージを受信することはない。非同期にボイス セッションに接続する場合のみ、DVMSGID_CONNECTRESULT 完了メッセージを受信する。

コア メッセージと音声メッセージの処理で大きく違う点の 1 つは、コア メッセージ ハンドラはすべてのコア メッセージを受信することである。DirectPlay Voice には、IDirectPlayVoiceClient::SetNotifyMask を呼び出して、受信したいメッセージのリストを指定するオプションがある。pdwMessageMask パラメータを通じてこのメソッドに渡す、通知リストにあるメッセージのみが受信される。このリストには、少なくとも 1 つのメッセージが含まれている必要がある。IDirectPlayVoiceClient::SetNotifyMask を使って、すべての DirectPlay Voice メッセージを無効にすることはできない。

注  DirectPlay セッションと DirectPlay Voice セッションは異なるエンティティである。各インターフェイスのメッセージの順序には保証があるが、インターフェイス間のメッセージの順序については保証がない。

起動メッセージ

DirectPlay Voice は、通常の DirectPlay セッションに対する追加のオプションである。これにより、セッションのメンバ間の音声通信が可能になる。ボイス セッションのクライアントとなるには、適切な DirectPlay オブジェクトを作成し、通常のピアツーピアまたはクライアント/サーバー セッションに接続している必要がある。詳細については、「ピアツーピア セッション」または「クライアント/サーバー セッション」を参照すること。

すべてのボイス セッションには、ホストが必要である。ピアツーピア セッションの場合は、メンバの 1 人がボイス セッションのホストとして選択されている必要がある。ボイス ホストは、コア セッションのホストとなっているメンバと同じである必要はない。クライアント/サーバー セッションの場合、サーバーはボイス セッションとコア セッションのホストとなる必要がある。セッション ホストが決定したら、ホストはボイス サーバー オブジェクトを作成し、IDirectPlayVoiceServer::StartSession を呼び出して、ボイス セッションを開始する必要がある。セッションが開始されると、クライアントは接続できる。

ここでは、ボイス クライアントがセッションに参加するときに受信できるメッセージの概要を示す。

  • DVMSGID_CONNECTRESULT

    セッションが設定されたら、クライアントは IDirectPlayVoiceClient::Connect を呼び出して、ボイス セッションに接続する必要がある。このメソッドを非同期に呼び出し、メソッドが DV_PENDING を返す場合、接続試行の結果が含まれた DVMSGID_CONNECTRESULT メッセージを受信する。このメッセージは、IDirectPlayVoiceClient::Connect が DV_PENDING を返す前または後に届く。同期的にこのメソッドを呼び出す場合、DVMSGID_CONNECTRESULT メッセージは受信しない。同期接続の試行結果は、メソッドの戻り値により示される。

  • DVMSGID_CREATEVOICEPLAYER

    ボイス クライアントは、ピアツーピアボイス セッションのメンバである場合のみ、このメッセージを受信する。接続して DVMSGID_CONNECTRESULT を処理した後は、自分とボイス セッションのメンバごとに、DVMSGID_CREATEVOICEPLAYER メッセージを受信する。このメッセージに付属する構造体には、セッション中にプレーヤを識別するために使う DVID 値が含まれている。この構造体の dwFlags メンバには、プレーヤを示す 2 つのフラグが含まれている。プレーヤがローカル プレーヤの場合、DVPLAYERCAPS_LOCAL フラグが設定される。プレーヤが半二重の場合、DVPLAYERCAPS_HALFDUPLEX フラグが設定される。

    プレーヤのボイス セッション プレーヤ値を作成する場合は、このメッセージを処理するときに行う必要がある。プレーヤ コンテキスト値の詳細については、「プレーヤ コンテキスト値の使い方」を参照すること。該当する DVMSGID_CREATEVOICEPLAYER メッセージを処理するまでは、プレーヤは対応するメッセージを受信しない。

通常のゲーム プレイ中のメッセージング

正常に接続した後は、ボイス セッション中に数多くのメッセージを受信する。受信する可能性のあるメッセージは、ピアツーピア セッションかクライアント/サーバー セッションかによって異なる。原則として、クライアント/サーバー ボイス セッションのボイス クライアントは、特定のプレーヤに関連付けられたメッセージを受信しない。

共通の Voice メッセージ

次のメッセージは、ボイス セッションの両方の種類のクライアントが受信する。

  • DVMSGID_GAINFOCUS および DVMSGID_LOSTFOCUS

    これらのメッセージにより、キャプチャ フォーカスがあるかどうかと、オーディオをキャプチャしているかどうかがわかる。チャプチャ フォーカスを取得してオーディオ キャプチャを開始すると、DVMSGID_GAINFOCUS メッセージを受信する。チャプチャ フォーカスを失い、オーディオ キャプチャが停止すると、DVMSGID_LOSTFOCUS メッセージを受信する。両方のメッセージは簡単な通知であり、関連する構造体はない。キャプチャ フォーカスの詳細については、「キャプチャ フォーカス」および「DirectPlay と DirectPlay Voice におけるコールバック関数の実装」を参照すること。

    注  キャプチャ フォーカスの取得と喪失は、必ずしも転送の開始または終了を意味しない。転送の開始または終了は、DVMSGID_RECORDSTART および DVMSGID_RECORDSTOP メッセージによって示される。

  • DVMSGID_RECORDSTART および DVMSGID_RECORDSTOP

    これらのメッセージは、ローカル プレーヤが転送を実行していることを通知する。転送が開始すると DVMSGID_RECORDSTART メッセージを受信し、転送が終了すると DVMSGID_RECORDSTOP を受信する。これらのメッセージに付属する構造体には、ローカル プレーヤの Voice プレーヤ コンテキスト値が含まれている。転送の開始と停止が発生する原因は、プッシュツートークまたは音声起動による転送制御を使っているかと、アプリケーションがオーディオ キャプチャ フォーカスを取得したか失ったかによって異なる。

    最も簡単なケースは、オーディオ キャプチャのフォーカスが変更されない場合である。この場合、ユーザーの音声が、アクティブにするしきい値を超えたときに、音声起動による転送が開始する。この転送は、音声がしきい値を下回ったときに停止する。プッシュツートーク転送では、通常、ユーザーがボタンを押して離すことにより、転送は手動で開始し、停止する。

    プレーヤの音声が、アクティブになるしきい値を超えるか、[プッシュツートーク] を押した場合でも、アプリケーションが転送を実行するためにはキャプチャ フォーカスが必要である。プレーヤが話しているが、アプリケーションにオーディオ キャプチャ フォーカスがない場合、アプリケーションがオーディオ キャプチャ フォーカスを取得しないと、転送は開始されない。このとき、DVMSGID_GAINFOCUS メッセージを受信し、続いて DVMSGID_RECORDSTART メッセージを受信する。プレーヤが話しているときにオーディオ キャプチャ フォーカスが失われると、DVMSGID_LOSTFOCUS メッセージを受信し、続いて DVMSGID_RECORDSTOP メッセージを受信する。オーディオ キャプチャ フォーカスを取得し、プレーヤがまだ話している場合、転送はもう一度開始される。

    通常、転送が停止すると、その理由とは無関係に DVMSGID_RECORDSTOP メッセージを受信する。しかし、転送中にボイス セッションから接続を解除すると、DVMSGID_RECORDSTOP メッセージの受信は保証されない。

    キャプチャ フォーカスの詳細については、「キャプチャ フォーカス」を参照すること。転送制御の詳細については、「伝送制御」を参照すること。

  • DVMSGID_INPUTLEVEL および DVMSGID_OUTPUTLEVEL

    DVMSGID_INPUTLEVEL メッセージは、プレーヤのマイクからの現在の音声入力レベルを示す。DVMSGID_OUTPUTLEVEL メッセージは、プレーヤのスピーカまたはヘッドフォンからの現在の音声入力レベルを示す。これらのメッセージは、周期的に送信される。また、DVMSGID_RECORDSTART メッセージを処理した後に開始され、対応する DVMSGID_RECORDSTOP メッセージを処理すると停止する。メッセージの送信間隔を指定するには、DVCLIENTCONFIG 構造体の dwNotifyPeriod メンバに、適切な間隔を設定する。メッセージを送信しないようにするには、dwNotifyPeriod に 0 を設定する。

ピアツーピア メッセージ

次のメッセージは、ピアツーピアボイス セッションのクライアントが受信する。

  • DVMSGID_CREATEVOICEPLAYER および DVMSGID_DELETEVOICEPLAYER

    ボイス セッションにプレーヤが追加されるたびに、DVMSGID_CREATEVOICEPLAYER メッセージを受信する。このメッセージは、セッションに接続したときに受信したプレーヤの作成メッセージと同じ方法で処理する必要がある。プレーヤがボイス セッションを抜けると、DVMSGID_DELETEVOICEPLAYER メッセージを受信する。DVMSGID_CREATEVOICEPLAYER メッセージごとに、DVMSGID_DELETEVOICEPLAYER メッセージを受信する。DVMSGID_DELETEVOICEPLAYER メッセージを処理した後は、そのプレーヤのメッセージを受信しなくなる。

  • DVMSGID_SETTARGETS

    ボイス ターゲットの一覧が変更されると、DVMSGID_SETTARGETS メッセージを受信する。このメッセージは、ボイス クライアントが IDirectPlayVoiceClient::SetTransmitTargets を呼び出すか、ボイス ホストが IDirectPlayVoiceServer::SetTransmitTargets を呼び出すと、いつでも生成される。

  • DVMSGID_PLAYERVOICESTART および DVMSGID_PLAYERVOICESTOP

    プレーヤから転送を受信し始めると、DVMSGID_PLAYERVOICESTART メッセージが送信される。レベル通知を有効にしている場合、DVMSGID_PLAYEROUTPUTLEVEL メッセージの受信を開始する。プレーヤの転送が停止すると、DVMSGID_PLAYERVOICESTOP メッセージが送信される。このメッセージを処理すると、DVMSGID_PLAYEROUTPUTLEVEL メッセージは停止する。オーディオ キャプチャ フォーカスが変更された場合、基本的に DVMSGID_RECORDSTART および DVMSGID_RECORDSTOP と同じ方法で、これらのメッセージが処理される。該当する DVMSGID_CREATEVOICEPLAYER メッセージを処理するまで、プレーヤに関連するこれらのメッセージは受信されない。

  • DVMSGID_PLAYEROUTPUTLEVEL

    DVMSGID_PLAYEROUTPUTLEVEL は、特定のプレーヤの送信に対して、プレーヤのスピーカまたはヘッドフォンの現在の音声出力レベルを示す。これらのメッセージは、周期的に送信される。また、DVMSGID_RECORDSTART メッセージを処理した後に開始され、対応する DVMSGID_RECORDSTOP メッセージを処理すると停止する。メッセージの送信間隔を指定するには、DVCLIENTCONFIG 構造体の dwNotifyPeriod メンバに、適切な間隔を設定する。メッセージを送信しないようにするには、dwNotifyPeriod に 0 を設定する。

  • DVMSGID_LOCALHOSTSETUP

    ボイス ホストが移行すると、DVMSGID_LOCALHOSTSETUP メッセージが新しいボイス ホストに送信される。このメッセージにより、新しいボイス ホストは、新しいボイス サーバー オブジェクトを作成するときに使われるコールバック関数と、コンテキスト値を設定する。アプリケーションがこのメッセージの処理から戻ると、DVMSGID_HOSTMIGRATED メッセージを受信する。

  • DVMSGID_HOSTMIGRATED

    ホストが移行すると、ボイス セッションの他のすべてのメンバに DVMSGID_HOSTMIGRATED メッセージが送信される。関連する構造体には、新しいボイス ホストの DVID が含まれる。ホストが移行すると、DirectPlay Voice は自動的に新しいボイス サーバー オブジェクトを作成する。アプリケーションが新しいボイス ホストである場合、DVMSGID_HOSTMIGRATED メッセージの構造体に、ボイス サーバーの IDirectPlayVoiceServer インターフェイスへのポインタも含まれる。このインターフェイスを使う場合、インターフェイスの AddRef メソッドを呼び出して、インターフェイスの参照カウントをインクリメントする必要がある。IDirectPlayVoiceServer で AddRef を呼び出した場合、インターフェイスの操作を終了したときに、必ず Release を呼び出す必要がある。

セッション終了メッセージ

  • DVMSGID_DISCONNECTRESULT

    IDirectPlayVoiceClient::Disconnect を呼び出して、ボイス セッションへの接続を解除する。このメソッドを非同期に呼び出し、メソッドが DV_PENDING を返す場合、結果を知らせる DVMSGID_DISCONNECTRESULT メッセージを受信する。このメッセージは、IDirectPlayVoiceClient::Disconnect が戻る前または後に届く。同期的に IDirectPlayVoiceClient::Disconnect を呼び出す場合、DVMSGID_DISCONNECTRESULT メッセージは送信されない。同期接続解除の試行結果は、メソッドの戻り値により示される。

    ピアツーピア ボイス セッションでは、クライアントは DVMSGID_DISCONNECTRESULT を受け取る前に、セッションのすべてのプレーヤの DVMSGID_DELETEVOICEPLAYER を受信する。

  • DVMSGID_SESSIONLOST

    回復不可能なエラーでセッションが予期せずに終了した場合、クライアントは DVMSGID_SESSIONLOST メッセージを受信する。失敗の理由は、関連する構造体の hrResult メンバに指定されている。

    ピアツーピア ボイス セッションでは、クライアントは DVMSGID_SESSIONLOST を受け取る前に、セッションのすべてのプレーヤの DVMSGID_DELETEVOICEPLAYER を受信する。

  • DVMSGID_DELETEVOICEPLAYER

    ピアツーピア セッションでは、IDirectPlayVoiceClient::Disconnect を呼び出すか、セッションが失われるかとは関係なく、接続を解除したときに、ボイス セッションの他のすべてのプレーヤの DVMSGID_DELETEVOICEPLAYER メッセージを受信する。これにより、受信するすべての DVMSGID_CREATEVOICEPLAYER には対応する DVMSGID_DELETEVOICEPLAYER メッセージがあることになる。接続解除が完了するまでに、すべての DVMSGID_DELETEVOICEPLAYER を受信する。