CTR-Pia
5.4.3
Game Communication Engine
|
大きなデータを全員に一斉送信するプロトコルです。 [詳細]
構成 | |
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 TransferSetting * | GetCurrentTransferSetting () const |
現在のデータ転送の設定情報を取得します。 | |
uint32_t | GetProgress () const |
送受信の進捗状況を取得します。 | |
const TransferSetting * | GetRequest () const |
届いている受信要求を取得します。 | |
const TransferSetting * | GetRequest (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() で設定できる値の最大値です。 | |
大きなデータを全員に一斉送信するプロトコルです。
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 となる設定で動作させている場合は、その送信自体が中断されます。
void nn::pia::transport::ReliableBroadcastProtocol::Finalize | ( | ) |
終了処理を行います。
Result nn::pia::transport::ReliableBroadcastProtocol::FinishSendEndless | ( | ) |
Configuration::IsSendEndless() が true となる設定で実行している送信を終了させます。 動作の詳細は Configuration::IsSendEndless() を参照してください。
const TransferSetting* nn::pia::transport::ReliableBroadcastProtocol::GetCurrentTransferSetting | ( | ) | const |
現在のデータ転送の設定情報を取得します。
uint32_t nn::pia::transport::ReliableBroadcastProtocol::GetProgress | ( | ) | const |
送受信の進捗状況を取得します。
送信中の進捗は、送信対象となるステーションの増減によって途中で値が小さくなる場合がありますので注意してください。
const TransferSetting* nn::pia::transport::ReliableBroadcastProtocol::GetRequest | ( | ) | const |
届いている受信要求を取得します。
このデータを受け取る場合は必要なサイズのバッファを用意して StartReceive() を行う必要があります。 このデータを受け取らない場合は RejectRequest() を呼ぶ必要があります。 複数の受信要求が届いている場合は、最も優先度の高い( Configuration::IsMediateRequest() の値に関係なく、送信者の StationIndex が小さい)受信要求が取得できます。
const TransferSetting* nn::pia::transport::ReliableBroadcastProtocol::GetRequest | ( | StationId | stationId | ) | const |
特定のステーションからの受信要求を取得します。
このデータを受け取る場合は必要なサイズのバッファを用意して StartReceive() を行う必要があります。
[in] | stationId | 取得したい受信要求の StationId です。 |
uint32_t nn::pia::transport::ReliableBroadcastProtocol::GetSendProgress | ( | StationId | stationId | ) | const |
特定の送信先への送信の進捗状況を取得します。
[in] | stationId | 進捗状況を調べたいステーションの StationId です。 |
|
inline |
現在の動作状態を取得します。
|
inline |
common::Scheduler::Dispatch の 1 回の呼び出しあたりにこのプロトコルが送信するデータ量の上限を取得します。
Result nn::pia::transport::ReliableBroadcastProtocol::Initialize | ( | ) |
インスタンスを初期化します。 BeginSetup() ~ EndSetup() 間で呼び出す必要があります。
|
inline |
送受信の非同期処理実行中かどうかを取得します。
GetState() が State_Sending または State_Receiving を返す時に true になります。
bool nn::pia::transport::ReliableBroadcastProtocol::IsSendTarget | ( | StationId | stationId | ) | const |
指定したステーションが現在の送信の送信対象とされているかどうかを取得します。
通常はセッションに参加している自分以外の全てのステーションが送信対象になります。 Configuration::IsSendToNewcomer() が false の場合は、送信開始以降にセッションに参加したステーションは送信対象になりません。 Configuration::IsFailIfRejected() が false の場合は、その送信に対して受信拒否したり受信を中断したステーションは送信対象から外されます。
[in] | stationId | 送信対象かどうか調べたいステーションの StationId です。 |
Result nn::pia::transport::ReliableBroadcastProtocol::RejectRequest | ( | ) |
GetRequest() で取得される受信要求を拒否します。
この受信要求の動作方式が Configuration::IsFailIfRejected() が true となる設定の場合は、その送信自体が中断されます。 現在受信中の受信要求に対してこの関数を呼んだ場合は Cancel() と同等の処理を行います。
GetRequest ( nn::pia::StationId ) で取得される受信要求を拒否します。
この受信要求の動作方式が Configuration::IsFailIfRejected() が true となる設定の場合は、その送信自体が中断されます。 現在受信中の受信要求に対してこの関数を呼んだ場合は Cancel() と同等の処理を行います。
[in] | stationId | 拒否したい受信要求の StationId です。 |
Result nn::pia::transport::ReliableBroadcastProtocol::Reset | ( | ) |
送受信結果の情報を破棄して State_Wait に戻ります。
送受信実行中は失敗しますので、その状態で呼び出したい場合は先に Cancel() して送受信を中断させてからこの関数を呼ぶ必要があります。 この関数は必ずしも使用する必要は無く、 State_SendSuccess, State_SendFailure, State_ReceiveSuccess, State_ReceiveFailure の状態から 直接次の送受信を開始することも可能です。
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 | 設定する送信データ量のサイズ(バイト)です。 |
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 | この送信者からのデータを受信します。 |
ResultInvalidState セッションに参加していないか、他の送受信を実行中です。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
ResultInvalidArgument 引数が誤っています。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
ResultTemporaryUnavailable セッション移行処理中のため、一時的に API を利用できない状態です。ジョイントセッション機能使用時にのみ返ります。アプリケーションで適切にハンドリングしてください。
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 | 送信データに付ける付加情報です。 受信側のアプリケーションが受信開始前に参照することができ、データを識別するためなどに使用できます。 |
ResultInvalidState セッションに参加していないか、他の送受信を実行中です。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
ResultInvalidArgument 引数が誤っています。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
ResultTemporaryUnavailable セッション移行処理中のため、一時的に API を利用できない状態です。ジョイントセッション機能使用時にのみ返ります。アプリケーションで適切にハンドリングしてください。
|
virtual |
デバッグに有用な情報をプリントします。
[in] | flag | トレースフラグの論理和。詳細は TraceFlag 型を参照してください。 |
nn::pia::transport::Protocolを再定義しています。