CTR-Pia  5.4.3
Game Communication Engine
 全て クラス ネームスペース 関数 変数 型定義 列挙型 列挙型の値 ページ
クラス nn::pia::transport::ReliableBroadcastProtocol

大きなデータを全員に一斉送信するプロトコルです。 [詳細]

+ nn::pia::transport::ReliableBroadcastProtocolに対する継承グラフ

構成

class  Configuration
 データ転送の動作方式を表します。 [詳細]
 
struct  TransferSetting
 データ転送の設定情報を表します。 [詳細]
 

Public 型

enum  State {
  State_Invalid = Mode_Invalid | Condition_Wait,
  State_Wait = Mode_Wait | Condition_Wait,
  State_Sending = Mode_Send | Condition_InProgress,
  State_SendSuccess = Mode_Send | Condition_Success,
  State_SendFailure = Mode_Send | Condition_Failure,
  State_Receiving = Mode_Receive | Condition_InProgress,
  State_ReceiveSuccess = Mode_Receive | Condition_Success,
  State_ReceiveFailure = Mode_Receive | Condition_Failure
}
 動作状態を表します。 [詳細]
 

Public メソッド

Result Cancel ()
 送受信を中断します。
 
void Finalize ()
 終了処理を行います。
 
Result FinishSendEndless ()
 Configuration::IsSendEndless() が true となる設定で実行している送信を終了させます。 動作の詳細は Configuration::IsSendEndless() を参照してください。
 
const TransferSettingGetCurrentTransferSetting () const
 現在のデータ転送の設定情報を取得します。
 
uint32_t GetProgress () const
 送受信の進捗状況を取得します。
 
const TransferSettingGetRequest () const
 届いている受信要求を取得します。
 
const TransferSettingGetRequest (StationId stationId) const
 特定のステーションからの受信要求を取得します。
 
uint32_t GetSendProgress (StationId stationId) const
 特定の送信先への送信の進捗状況を取得します。
 
State GetState () const
 現在の動作状態を取得します。
 
uint32_t GetThroughputLimit () const
 common::Scheduler::Dispatch の 1 回の呼び出しあたりにこのプロトコルが送信するデータ量の上限を取得します。
 
Result Initialize ()
 インスタンスを初期化します。 BeginSetup()EndSetup() 間で呼び出す必要があります。
 
bool IsRunning () const
 送受信の非同期処理実行中かどうかを取得します。
 
bool IsSendTarget (StationId stationId) const
 指定したステーションが現在の送信の送信対象とされているかどうかを取得します。
 
Result RejectRequest ()
 GetRequest() で取得される受信要求を拒否します。
 
Result RejectRequest (StationId stationId)
 GetRequest ( nn::pia::StationId ) で取得される受信要求を拒否します。
 
Result Reset ()
 送受信結果の情報を破棄して State_Wait に戻ります。
 
void SetThroughputLimit (uint32_t throughputLimit)
 common::Scheduler::Dispatch の 1 回の呼び出しあたりにこのプロトコルが送信するデータ量の上限を指定します。
 
Result StartReceive (void *pBuffer, uint32_t bufferSize, StationId sourceStationId)
 受信を開始します。
 
Result StartSend (const void *cpData, uint32_t dataSize, Configuration configuration, uint32_t userData=0)
 送信を開始します。
 
virtual void Trace (uint64_t flag) const
 デバッグに有用な情報をプリントします。
 

Static Public 変数

static const uint32_t ThroughputLimitMax = 0x0FFFFFFF
 SetThroughputLimit() で設定できる値の最大値です。
 

説明

大きなデータを全員に一斉送信するプロトコルです。

列挙型

動作状態を表します。

列挙型の値:
State_Invalid 

セッションに参加していません。

State_Wait 

何も行っていません。

State_Sending 

送信中です。

State_SendSuccess 

送信に成功しました。

State_SendFailure 

送信に失敗しました。

State_Receiving 

受信中です。

State_ReceiveSuccess 

受信に成功しました。

State_ReceiveFailure 

受信に失敗しました。

関数

Result nn::pia::transport::ReliableBroadcastProtocol::Cancel ( )

送受信を中断します。

State_Sending 中にこの関数を呼ぶと、その後の common::Scheduler::Dispatch() でキャンセル処理を行った後、通常は State_SendFailure に遷移します。 ただし、タイミングによっては State_SendSuccess に遷移する場合もあります。 受信側のステーションも State_ReceiveFailure (または State_ReceiveSuccess )に遷移します。

State_Receiving 中にこの関数を呼ぶと、その後の common::Scheduler::Dispatch() でキャンセル処理を行った後、通常は State_ReceiveFailure に遷移します。 ただし、タイミングによっては State_ReceiveSuccess に遷移する場合もあり、その場合は受信したデータを参照できます。 Configuration::IsFailIfRejected() が true となる設定で動作させている場合は、その送信自体が中断されます。

戻り値
成功すれば、 IsSuccess() が true を返す Result が返されます。この関数がエラーを返さないようにアプリケーションを実装する必要があります。
返るエラーの一覧:
ResultInvalidState 送受信中ではありません。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
参照
StartSend, StartReceive
void nn::pia::transport::ReliableBroadcastProtocol::Finalize ( )

終了処理を行います。

参照
Initialize
Result nn::pia::transport::ReliableBroadcastProtocol::FinishSendEndless ( )

Configuration::IsSendEndless() が true となる設定で実行している送信を終了させます。 動作の詳細は Configuration::IsSendEndless() を参照してください。

戻り値
成功すれば、 IsSuccess() が true を返す Result が返されます。この関数がエラーを返さないようにアプリケーションを実装する必要があります。
返るエラーの一覧:
ResultInvalidState 送信実行中ではないか、Configuration::IsSendEndless() が true となる設定ではありません。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
参照
Configuration::IsSendEndless
const TransferSetting* nn::pia::transport::ReliableBroadcastProtocol::GetCurrentTransferSetting ( ) const

現在のデータ転送の設定情報を取得します。

戻り値
送信中および送信後ならその送信の設定が、受信中および受信後ならその受信の設定が取得できます。 受信要求が来る前に受信開始した時や、その状態のまま Cancel() した時など、データを全く受け取っていない場合は NULL を返します。
uint32_t nn::pia::transport::ReliableBroadcastProtocol::GetProgress ( ) const

送受信の進捗状況を取得します。

送信中の進捗は、送信対象となるステーションの増減によって途中で値が小さくなる場合がありますので注意してください。

戻り値
送受信が完了したデータサイズ(バイト)です。 送信中、送信後は送信対象としているステーションに対して送信したデータサイズの平均値が取得できます。 受信中、受信後は自分が受け取ったデータサイズが取得できます。
const TransferSetting* nn::pia::transport::ReliableBroadcastProtocol::GetRequest ( ) const

届いている受信要求を取得します。

このデータを受け取る場合は必要なサイズのバッファを用意して StartReceive() を行う必要があります。 このデータを受け取らない場合は RejectRequest() を呼ぶ必要があります。 複数の受信要求が届いている場合は、最も優先度の高い( Configuration::IsMediateRequest() の値に関係なく、送信者の StationIndex が小さい)受信要求が取得できます。

戻り値
受信要求のポインタです。 受信要求が届いてない場合は NULL が返されます。
参照
StartReceive, RejectRequest
const TransferSetting* nn::pia::transport::ReliableBroadcastProtocol::GetRequest ( StationId  stationId) const

特定のステーションからの受信要求を取得します。

このデータを受け取る場合は必要なサイズのバッファを用意して StartReceive() を行う必要があります。

引数
[in]stationId取得したい受信要求の StationId です。
戻り値
受信要求のポインタです。 受信要求が届いてない場合は NULL が返されます。
参照
StartReceive, RejectRequest
uint32_t nn::pia::transport::ReliableBroadcastProtocol::GetSendProgress ( StationId  stationId) const

特定の送信先への送信の進捗状況を取得します。

引数
[in]stationId進捗状況を調べたいステーションの StationId です。
戻り値
指定したステーションに送信が完了したデータサイズ(バイト)です。 送信中、送信後でないときや無効な StationId が指定された場合は 0 を返します。
State nn::pia::transport::ReliableBroadcastProtocol::GetState ( ) const
inline

現在の動作状態を取得します。

戻り値
現在の動作状態です。
uint32_t nn::pia::transport::ReliableBroadcastProtocol::GetThroughputLimit ( ) const
inline

common::Scheduler::Dispatch の 1 回の呼び出しあたりにこのプロトコルが送信するデータ量の上限を取得します。

戻り値
common::Scheduler::Dispatch の 1 回の呼び出しあたりにこのプロトコルが送信するデータ量です。
参照
SetThroughputLimit
Result nn::pia::transport::ReliableBroadcastProtocol::Initialize ( )

インスタンスを初期化します。 BeginSetup()EndSetup() 間で呼び出す必要があります。

戻り値
成功すれば、 IsSuccess() が true を返す Result が返されます。この関数がエラーを返さないようにアプリケーションを実装する必要があります。
返るエラーの一覧:
ResultAlreadyInitialized 既に初期化されています。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
参照
Finalize
bool nn::pia::transport::ReliableBroadcastProtocol::IsRunning ( ) const
inline

送受信の非同期処理実行中かどうかを取得します。

GetState() が State_Sending または State_Receiving を返す時に true になります。

戻り値
送受信の非同期処理実行中なら true を返します。
参照
GetState
bool nn::pia::transport::ReliableBroadcastProtocol::IsSendTarget ( StationId  stationId) const

指定したステーションが現在の送信の送信対象とされているかどうかを取得します。

通常はセッションに参加している自分以外の全てのステーションが送信対象になります。 Configuration::IsSendToNewcomer() が false の場合は、送信開始以降にセッションに参加したステーションは送信対象になりません。 Configuration::IsFailIfRejected() が false の場合は、その送信に対して受信拒否したり受信を中断したステーションは送信対象から外されます。

引数
[in]stationId送信対象かどうか調べたいステーションの StationId です。
戻り値
指定したステーションが送信対象なら true を、そうでなければ false を返します。 送信中、送信後でないときは false を返します。
Result nn::pia::transport::ReliableBroadcastProtocol::RejectRequest ( )

GetRequest() で取得される受信要求を拒否します。

この受信要求の動作方式が Configuration::IsFailIfRejected() が true となる設定の場合は、その送信自体が中断されます。 現在受信中の受信要求に対してこの関数を呼んだ場合は Cancel() と同等の処理を行います。

戻り値
成功すれば、 IsSuccess() が true を返す Result が返されます。この関数がエラーを返さないようにアプリケーションを実装する必要があります。
返るエラーの一覧:
ResultInvalidState GetRequest() が NULL を返しています。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
参照
GetRequest
Result nn::pia::transport::ReliableBroadcastProtocol::RejectRequest ( StationId  stationId)

GetRequest ( nn::pia::StationId ) で取得される受信要求を拒否します。

この受信要求の動作方式が Configuration::IsFailIfRejected() が true となる設定の場合は、その送信自体が中断されます。 現在受信中の受信要求に対してこの関数を呼んだ場合は Cancel() と同等の処理を行います。

引数
[in]stationId拒否したい受信要求の StationId です。
戻り値
成功すれば、 IsSuccess() が true を返す Result が返されます。この関数がエラーを返さないようにアプリケーションを実装する必要があります。
返るエラーの一覧:
ResultInvalidState GetRequest ( nn::pia::StationId ) が NULL を返しています。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
参照
GetRequest
Result nn::pia::transport::ReliableBroadcastProtocol::Reset ( )

送受信結果の情報を破棄して State_Wait に戻ります。

送受信実行中は失敗しますので、その状態で呼び出したい場合は先に Cancel() して送受信を中断させてからこの関数を呼ぶ必要があります。 この関数は必ずしも使用する必要は無く、 State_SendSuccess, State_SendFailure, State_ReceiveSuccess, State_ReceiveFailure の状態から 直接次の送受信を開始することも可能です。

戻り値
成功すれば、 IsSuccess() が true を返す Result が返されます。この関数がエラーを返さないようにアプリケーションを実装する必要があります。
返るエラーの一覧:
ResultInvalidState セッションに参加していないか、送受信を実行中です。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
void nn::pia::transport::ReliableBroadcastProtocol::SetThroughputLimit ( uint32_t  throughputLimit)

common::Scheduler::Dispatch の 1 回の呼び出しあたりにこのプロトコルが送信するデータ量の上限を指定します。

このプロトコルが common::Scheduler::Dispatch の 1 回あたりに送信するデータ量の平均値が この関数で設定した値以下になるように制限されます。 瞬間的にはここで設定した値以上のサイズの送信が行われることもあります。

この関数に 0 を指定することでこのプロトコルはデータ送信を行わなくなりますので、 送信を一時停止させたい場合は、送信側で 0 を指定する必要があります。 その後送信を再開させる場合は、改めて正の値を設定する必要があります。 一時停止したまま Cancel() で中断したい場合でも、0 を指定したままだと中断することの通知も行えず、 中断処理が完了しなくなってしまいますので、注意してください。 一方、受信側も応答パケットなど若干のデータの送信が行われますので、 受信側で 0 を指定しても処理が進まなくなってしまう点に注意してください。

設定できる値の最大値は ThroughputLimitMax です。これより大きな値を設定した場合は、ThroughputLimitMax を設定したものと扱います。

デフォルト値は ThroughputLimitMax です。 セッション作成時や参加時にデフォルト値にリセットされますので、その後に設定する必要があります。

通信環境によっては、上限を適切に設定した方が、ThroughputLimitMax を設定した場合よりもスループットが高くなる可能性があります。 特に CTR でのインターネット通信時には、アプリケーションで想定するステーション数や通信環境等に合わせて上限値を調整することを推奨します。

引数
[in]throughputLimit設定する送信データ量のサイズ(バイト)です。
参照
GetThroughputLimit
Result nn::pia::transport::ReliableBroadcastProtocol::StartReceive ( void *  pBuffer,
uint32_t  bufferSize,
StationId  sourceStationId 
)

受信を開始します。

GetRequest() を受けてそのデータを受信する場合はその設定に合わせた引数を指定して呼び出す必要があります。 アプリケーションのシーケンスなどによりどういう受信をするかあらかじめ分かっている場合は、 受信要求が来る前にこの関数を呼んでおくと、受信要求を待つ場合に比べて無駄なく受信が開始できます。 この関数が成功すると State_Receiving に遷移します。 ResultInvalidArgument で失敗した場合は Reset() されます。

ジョイントセッション処理をまたいでデータを受信することはできません。

引数
[out]pBuffer受信データを受け取るバッファです。 State_Receiving の間( IsRunning() が true の間)はまだデータを参照できません。 データの先頭から順に受信される保証はありませんので、先頭から GetProgress() バイトは参照できるという事もありません。
[in]bufferSize受信バッファのサイズです。 受信要求のデータサイズがこの値より大きい場合は、この関数は成功しますが State_ReceiveFailure に遷移します。
[in]sourceStationIdこの送信者からのデータを受信します。
戻り値
成功すれば、 IsSuccess() が true を返す Result が返されます。この関数がエラーを返さないようにアプリケーションを実装する必要があります。
返るエラーの一覧:

ResultInvalidState セッションに参加していないか、他の送受信を実行中です。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。

ResultInvalidArgument 引数が誤っています。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。

ResultTemporaryUnavailable セッション移行処理中のため、一時的に API を利用できない状態です。ジョイントセッション機能使用時にのみ返ります。アプリケーションで適切にハンドリングしてください。

参照
GetRequest
Result nn::pia::transport::ReliableBroadcastProtocol::StartSend ( const void *  cpData,
uint32_t  dataSize,
Configuration  configuration,
uint32_t  userData = 0 
)

送信を開始します。

この関数に成功すれば State_Sending に遷移します。 ResultInvalidArgument で失敗した場合は Reset() されます。

ジョイントセッション処理をまたいでデータを送信することはできません。

引数
[in]cpData送信するデータへのポインタです。 State_Sending の間( IsRunning() が true の間)は指定したバッファを保持しておく必要があります。 データの先頭から順に送信される保証はありませんので、先頭から GetProgress() バイトは書き換えて大丈夫という事もありません。
[in]dataSize送信するデータのサイズです。
[in]configurationこのデータ転送における動作方式を指定します。
[in]userData送信データに付ける付加情報です。 受信側のアプリケーションが受信開始前に参照することができ、データを識別するためなどに使用できます。
戻り値
成功すれば、 IsSuccess() が true を返す Result が返されます。この関数がエラーを返さないようにアプリケーションを実装する必要があります。
返るエラーの一覧:

ResultInvalidState セッションに参加していないか、他の送受信を実行中です。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。

ResultInvalidArgument 引数が誤っています。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。

ResultTemporaryUnavailable セッション移行処理中のため、一時的に API を利用できない状態です。ジョイントセッション機能使用時にのみ返ります。アプリケーションで適切にハンドリングしてください。

virtual void nn::pia::transport::ReliableBroadcastProtocol::Trace ( uint64_t  flag) const
virtual

デバッグに有用な情報をプリントします。

引数
[in]flagトレースフラグの論理和。詳細は TraceFlag 型を参照してください。

nn::pia::transport::Protocolを再定義しています。