CTR-Pia
5.4.3
Game Communication Engine
|
データ同期通信を行うためのプロトコルです。
サポート対象のネットワークトポロジーはフルメッシュ型のみです。スター型、リレーメッシュ型はサポート対象外ですので注意してください。
[詳細]
構成 | |
struct | Setting |
初期化時に指定する設定構造体です。 [詳細] | |
Public 型 | |
enum | EndReason { EndReason_Nothing = 0, EndReason_End, EndReason_OtherStation, EndReason_ChangeConnection, EndReason_Timeout, EndReason_EndAlone } |
同期通信が終了した際の終了理由を表します。 [詳細] | |
enum | State { State_NotSynchronized = 0, State_Waiting, State_Starting, State_Synchronized, State_Ending, State_EndedAlone } |
同期通信の進行状態を表します。 [詳細] | |
Public メソッド | |
uint32_t | CalcMaxSyncDataSizeSentInOnePacket (uint32_t delay, uint32_t dataIdNum) |
送信する同期データを 1 パケットに収めるための、各データ ID のデータサイズの合計の最大値を求めます。 | |
bool | CanGetData () const |
受信した同期データを取得できるかどうかを取得します。 | |
bool | CheckEntry (StationId stationId) const |
指定したステーションが同期通信に参加しているかどうかを取得します。 | |
Result | End () |
同期通信を終了します。 | |
Result | EndAlone () |
自分だけ単独で同期通信を終了します。 | |
void | Finalize () |
終了処理です。 | |
Result | GetData (StationId stationId, uint32_t dataId, void *pBuffer) const |
同期通信で受信した同期データを取得します。 | |
const void * | GetDataPtr (StationId stationId, uint32_t dataId) const |
同期通信で受信した同期データへのポインタを取得します。 | |
uint32_t | GetDataSize (uint32_t dataId) const |
SyncProtocol::Initialize で指定したデータ ID の同期データのサイズを取得します。 | |
uint32_t | GetDataUnitSizeMax () const |
同期データ 1 単位のサイズとして設定できる最大値(バイト数)を取得します。 | |
uint32_t | GetDelay () const |
実際に設定されている入力遅延の値を取得します。 | |
Result | GetEndFrameNo (StationId stationId, uint32_t *endFrameNo) const |
指定したステーションが終了するフレームを取得します。 | |
uint32_t | GetFrameNo () const |
SyncProtocol::State_Synchronized となってからのフレーム数を取得します。 | |
Result | GetIsNoDataFrame (bool *isNoDataFrame) const |
同期データを取得できないフレームかどうかを取得します。 | |
EndReason | GetLastEndReason () const |
同期通信が終了した際の終了理由を取得します。 | |
uint32_t | GetMaxDelay () const |
SyncProtocol::Initialize で指定した入力遅延の最大値を取得します。 | |
uint32_t | GetSendPeriod () const |
SyncProtocol::Start や SyncProtocol::SetSendPeriod で指定した送信間隔の設定値を取得します。 | |
State | GetState () const |
同期通信の進行状態を取得します。 | |
uint32_t | GetTimeoutFrame () const |
SyncProtocol::Initialize で指定したタイムアウトの設定値を取得します。 | |
uint32_t | GetUsingDataIdBitmap (StationId stationId) const |
指定したステーションが送信しているデータ ID のリストをビットフラグで取得します。 | |
Result | Initialize (const Setting &setting) |
インスタンスを初期化します。sync::BeginSetup() ~ sync::EndSetup() 間で呼び出す必要があります。 | |
bool | NeedsSetData () const |
送信する同期データを設定する必要があるかどうかを取得します。 | |
bool | NeedsSetData (uint32_t dataId) const |
特定のデータ ID の同期データを設定する必要があるかどうかを取得します。 | |
Result | RequestToChangeDelay (uint32_t newDelay) |
入力遅延の変更依頼を同期データとして設定します。 | |
Result | SetData (uint32_t dataId, const void *cpData) |
同期通信で送信する同期データを設定します。 | |
Result | SetSendPeriod (uint32_t sendPeriod) |
送信間隔を設定します。 | |
Result | Start (uint32_t usingDataIdBitmap, uint32_t delay, uint32_t sendPeriod) |
同期通信を開始します。 | |
Result | Step () |
同期通信を 1 フレーム進めます。 | |
virtual void | Trace (uint64_t flag) const |
デバッグに有用な情報をプリントします。 | |
Static Public 変数 | |
static const uint32_t | CompressionLevelHigh = 9 |
SyncProtocol::Setting::dataCompressionLevel で指定する同期データの圧縮レベル(圧縮率重視)です。 | |
static const uint32_t | CompressionLevelLow = 1 |
SyncProtocol::Setting::dataCompressionLevel で指定する同期データの圧縮レベル(速度重視)です。 | |
static const uint32_t | CompressionLevelMiddle = 5 |
SyncProtocol::Setting::dataCompressionLevel で指定する同期データの圧縮レベルです。 | |
static const uint32_t | CompressionLevelNone = 0 |
SyncProtocol::Setting::dataCompressionLevel で指定する同期データの圧縮レベル(圧縮なし)です。 | |
static const uint32_t | DataIdNum = 16 |
データ ID の設定可能個数です。 | |
static const uint8_t | FrameDelayMax = 32 |
SyncProtocol::Setting::maxDelay で指定する入力遅延の最大値で、単位はフレームです。 | |
データ同期通信を行うためのプロトコルです。
サポート対象のネットワークトポロジーはフルメッシュ型のみです。スター型、リレーメッシュ型はサポート対象外ですので注意してください。
同期通信が終了した際の終了理由を表します。
EndReason_Nothing |
同期通信は終了していません。 |
EndReason_End |
このステーションで SyncProtocol::End が呼ばれたために終了しました。 |
EndReason_OtherStation |
他のステーションが同期通信を終了したために終了しました。 |
EndReason_ChangeConnection |
セッションに参加しているステーションに変更があったため終了しました。 |
EndReason_Timeout |
SyncProtocol::Setting::timeoutFrame フレーム間同期データが届かなかったため終了しました。 |
EndReason_EndAlone |
このステーションで SyncProtocol::EndAlone が呼ばれたために終了しました。 |
uint32_t nn::pia::sync::SyncProtocol::CalcMaxSyncDataSizeSentInOnePacket | ( | uint32_t | delay, |
uint32_t | dataIdNum | ||
) |
送信する同期データを 1 パケットに収めるための、各データ ID のデータサイズの合計の最大値を求めます。
この関数で求められる値は、送信間隔 1 のときに、送信や再送により送信する同期データサイズが最大となった場合を想定した値です。
[in] | delay | 入力遅延の値です。 |
[in] | dataIdNum | 使用するデータ ID の数です。 |
bool nn::pia::sync::SyncProtocol::CanGetData | ( | ) | const |
受信した同期データを取得できるかどうかを取得します。
SyncProtocol::State_Synchronized の間は同期データを取得できます。 ただし、同期通信中の入力遅延変更機能を使用している場合は、この関数が true を返しても 同期データを取得できないフレームがあるので、SyncProtocol::GetIsNoDataFrame でデータを取得できないフレームかを確認する必要があります。
bool nn::pia::sync::SyncProtocol::CheckEntry | ( | StationId | stationId | ) | const |
指定したステーションが同期通信に参加しているかどうかを取得します。
[in] | stationId | 調べたいステーションの StationId です。 |
Result nn::pia::sync::SyncProtocol::End | ( | ) |
同期通信を終了します。
SyncProtocol::State_Waiting, SyncProtocol::State_Starting, SyncProtocol::State_Synchronized の間に呼ぶことができ、成功すると SyncProtocol::State_Ending に遷移します。 その後、通信相手に終了することを通知したのち、SyncProtocol::State_NotSynchronized に遷移します。 この関数で同期通信を終了させた場合、通常は終了の理由が、このステーションでは SyncProtocol::EndReason_End に、 他のステーションでは、SyncProtocol::EndReason_OtherStation になります。 ただし、同時に他の要因で終了する事になった場合はこの限りではありません。
この関数を呼んだ直後の段階では SyncProtocol::State_Ending ですので、再び SyncProtocol::Start を呼ぶには、SyncProtocol::State_NotSynchronized になるまで 数フレームの間 SyncProtocol::Step を呼ぶ必要があります。
Result nn::pia::sync::SyncProtocol::EndAlone | ( | ) |
自分だけ単独で同期通信を終了します。
SyncProtocol::State_Synchronized の間に呼ぶことができます。
この関数を呼び出したフレームの同期データは取得できますが、 呼び出し後に他のステーションが単独同期終了を行ったことが通知された場合、 そのステーションが送信した同期データは取得できなくなり、同期ずれの原因となりますので、 この関数の呼び出しは、受信した同期データを取得後に行う必要があります。
終了フレームは、既に同期データを設定済みのフレームの内、最後のフレームとなります。 通信相手に終了フレームを通知し、全ての通信相手が終了フレームに達したことを確認した後、 SyncProtocol::State_EndedAlone に遷移します。 この関数を呼び出し成功後、SyncProtocol::State_Synchronized の間は SyncProtocol::Step に失敗し、 フレームを進めることができなくなるため、自分は終了フレームに達しない点に注意してください。 しかし、この場合でも SyncProtocol::Step は内部処理進行のために毎フレーム呼ぶ必要があります。
この関数で同期通信を終了した場合、通常はこのステーションの終了の理由は、SyncProtocol::EndReason_EndAlone になります。 ただし、同時に他の要因で終了する事になった場合はこの限りではありません。
SyncProtocol::State_EndedAlone の状態で、全ての通信相手が同期通信を終了すると、 SyncProtocol::State_NotSynchronized に遷移します。 また、SyncProtocol::State_EndedAlone の状態、または、その後 SyncProtocol::State_NotSynchronized に遷移した状態で 自分がセッションから離脱しても、他のステーションは同期通信を維持することができます。 ただし、SyncProtocol::State_EndedAlone に遷移後に新規ステーションが接続し、 自分以外のステーションが再度同期通信を開始しようとして SyncProtocol::State_Waiting になっているときに自分が切断すると、 自分以外のステーションは同期通信を終了し、SyncProtocol::State_NotSynchronized に遷移します。 また、SyncProtocol::State_EndedAlone で終了したステーションは SyncProtocol::State_NotSynchronized に遷移後、 再度同期通信を開始することができますが、再度同期通信を開始、または、セッションからの離脱を行わなければ、 自分以外のステーションは同期通信中の状態になることができません。
void nn::pia::sync::SyncProtocol::Finalize | ( | ) |
終了処理です。
|
inline |
同期通信で受信した同期データを取得します。
SyncProtocol::CanGetData が true の時は、SyncProtocol::CheckEntry が true となるステーションから、SyncProtocol::GetUsingDataIdBitmap でビットが立っているデータ ID の同期データを取得できます。 同期通信中の入力遅延変更機能を使用している場合は、同期データを取得できないフレームがあり、そのフレームでは ResultInvalidState を返します。 同期データを取得できないフレームかどうかは、SyncProtocol::GetIsNoDataFrame で確認する必要があります。
[in] | stationId | 取得する同期データを送信するステーションの StationId です。 |
[in] | dataId | 取得する同期データのデータ ID です。 |
[out] | pBuffer | 同期データを格納するバッファのポインタです。必要なサイズは SyncProtocol::Initialize で指定したサイズです。 |
ResultInvalidState この関数を呼び出せる SyncProtocol::State ではありません。または、同期データを取得できないフレームです。または、通信中ではありません。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
ResultInvalidArgument 引数の指定が不正です。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
const void* nn::pia::sync::SyncProtocol::GetDataPtr | ( | StationId | stationId, |
uint32_t | dataId | ||
) | const |
同期通信で受信した同期データへのポインタを取得します。
SyncProtocol::CanGetData が true の時は、SyncProtocol::CheckEntry が true となるステーションから、SyncProtocol::GetUsingDataIdBitmap でビットが立っているデータ ID の同期データを取得できます。 取得したポインタは、次に SyncProtocol::Step を呼ぶまで有効です。 同期データのサイズは SyncProtocol::Initialize で指定したサイズです。
[in] | stationId | 取得する同期データを送信するステーションの StationId です。 |
[in] | dataId | 取得する同期データのデータ ID です。 |
uint32_t nn::pia::sync::SyncProtocol::GetDataSize | ( | uint32_t | dataId | ) | const |
SyncProtocol::Initialize で指定したデータ ID の同期データのサイズを取得します。
[in] | dataId | 調べたい同期データのデータ ID です。 |
uint32_t nn::pia::sync::SyncProtocol::GetDataUnitSizeMax | ( | ) | const |
同期データ 1 単位のサイズとして設定できる最大値(バイト数)を取得します。
transport::Transport の初期化時に設定するパラメータによって、取得される値は異なります。
|
inline |
実際に設定されている入力遅延の値を取得します。
Result nn::pia::sync::SyncProtocol::GetEndFrameNo | ( | StationId | stationId, |
uint32_t * | endFrameNo | ||
) | const |
指定したステーションが終了するフレームを取得します。
SyncProtocol::State_NotSynchronized, SyncProtocol::State_Waiting 以外の状態のときに呼ぶことができます。 SyncProtocol::State_Synchronized になる前に終了する場合、endFrameNo は 0 になりますが、 実際にはその前に終了しますので注意してください。 また、終了するステーション自身は、このフレームに達する前に終了することもある点に注意してください。
ResultInvalidArgument 引数の指定が不正です。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
ResultInvalidState この関数を呼び出せる SyncProtocol::State ではありません。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
ResultNoData 終了するフレームが設定されていません。アプリケーションで適切にハンドリングしてください。
uint32_t nn::pia::sync::SyncProtocol::GetFrameNo | ( | ) | const |
SyncProtocol::State_Synchronized となってからのフレーム数を取得します。
SyncProtocol::State_Synchronized の間、SyncProtocol::Step に成功すると 1 進みます。
|
inline |
同期データを取得できないフレームかどうかを取得します。
同期通信中の入力遅延変更機能を使用している場合は、同期データを取得できないフレームがあるため、この関数で同期データを取得できないフレームかを確認する必要があります。 同期通信中の入力遅延変更機能を使用していない場合は、この関数を使用する必要はありません。
[out] | isNoDataFrame | 同期データを取得できないフレームであるかです。 |
ResultInvalidState 呼び出し状態が不正です。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
ResultInvalidArgument 引数の指定が不正です。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
EndReason nn::pia::sync::SyncProtocol::GetLastEndReason | ( | ) | const |
|
inline |
SyncProtocol::Initialize で指定した入力遅延の最大値を取得します。
|
inline |
SyncProtocol::Start や SyncProtocol::SetSendPeriod で指定した送信間隔の設定値を取得します。
|
inline |
同期通信の進行状態を取得します。
|
inline |
SyncProtocol::Initialize で指定したタイムアウトの設定値を取得します。
uint32_t nn::pia::sync::SyncProtocol::GetUsingDataIdBitmap | ( | StationId | stationId | ) | const |
指定したステーションが送信しているデータ ID のリストをビットフラグで取得します。
[in] | stationId | 調べたいステーションの StationId です。 |
インスタンスを初期化します。sync::BeginSetup() ~ sync::EndSetup() 間で呼び出す必要があります。
[in] | setting | 各種設定情報です。 同期通信をするすべてのステーション間で、同じ値を設定する必要があります。異なる値を設定した場合の動作は不定です。 |
ResultAlreadyInitialized 既に初期化されています。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
ResultInvalidArgument 引数が不正です。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
bool nn::pia::sync::SyncProtocol::NeedsSetData | ( | ) | const |
送信する同期データを設定する必要があるかどうかを取得します。
SyncProtocol::State_Starting, SyncProtocol::State_Synchronized の間は送信する同期データを設定する必要があります。 ただし、SyncProtocol::RequestToChangeDelay による同期通信中の入力遅延変更機能を使用している場合や、 SyncProtocol::EndAlone による同期通信の単独終了を行った場合には、 これらの SyncProtocol::State であっても同期データを設定する必要がない場合があります。 SyncProtocol::Step を呼び出した時の返り値が失敗だった場合、フレームは進んでいないので、 次の SyncProtocol::Step 呼び出し前に同期データを設定しなおす必要はありません。
bool nn::pia::sync::SyncProtocol::NeedsSetData | ( | uint32_t | dataId | ) | const |
特定のデータ ID の同期データを設定する必要があるかどうかを取得します。
SyncProtocol::State_Starting, SyncProtocol::State_Synchronized の間は同期データを設定する必要があります。 ただし、SyncProtocol::RequestToChangeDelay による同期通信中の入力遅延変更機能を使用している場合や、 SyncProtocol::EndAlone による同期通信の単独終了を行った場合には、 これらの SyncProtocol::State であっても同期データを設定する必要がない場合があります。 SyncProtocol::Step を呼び出した時の返り値が失敗だった場合はフレームは進んでいないので、 次の SyncProtocol::Step 呼び出し前に同期データを設定しなおす必要はありません。
[in] | dataId | 同期データを設定する必要があるかどうかを調べたいデータ ID です。 |
Result nn::pia::sync::SyncProtocol::RequestToChangeDelay | ( | uint32_t | newDelay | ) |
入力遅延の変更依頼を同期データとして設定します。
依頼する入力遅延は、初期化時に SyncProtocol::Setting::maxDelay で指定した最大入力遅延以下の値である必要があります。 依頼する入力遅延として 0 を指定した場合は、変更依頼を行わないものとして扱われます。 この関数が成功しても、依頼した入力遅延の値に変更されることは保証されません。 同じフレームで複数の依頼を受け取った場合は、依頼された入力遅延の値の最大値が優先されます。 入力遅延の変更依頼を同期データとして受け取った時点で、すでに他の依頼による入力遅延の変更中であった場合は、依頼は無視されます。
[in] | newDelay | 依頼する入力遅延の値です。 |
ResultInvalidState 呼び出し状態が不正です。または、通信中ではありません。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
ResultInvalidArgument 引数の指定が不正です。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
ResultAlreadyExists 既に設定されています。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
Result nn::pia::sync::SyncProtocol::SetData | ( | uint32_t | dataId, |
const void * | cpData | ||
) |
同期通信で送信する同期データを設定します。
SyncProtocol::NeedsSetData が true の時は、SyncProtocol::Step を呼ぶ前に、同期データを設定する必要があります。 SyncProtocol::State_Synchronized のとき、設定する同期データは、(SyncProtocol::GetFrameNo + SyncProtocol::GetDelay) フレーム用のデータとなります。
[in] | dataId | 設定する同期データのデータ ID です。 |
[in] | cpData | 設定する同期データです。サイズは SyncProtocol::Initialize で指定したものになります。 |
ResultInvalidState この関数を呼び出せる SyncProtocol::State ではありません。または、通信中ではありません。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
ResultInvalidArgument 引数の指定が不正です。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
ResultAlreadyExists 同期データは既に設定されています。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
Result nn::pia::sync::SyncProtocol::SetSendPeriod | ( | uint32_t | sendPeriod | ) |
送信間隔を設定します。
[in] | sendPeriod | 設定した同期データの送信、再送信処理の間隔を指定します。 ここで指定した回数 SyncProtocol::Step() が呼び出されるたびに、common::Scheduler::Dispatch() 呼び出し時に送信、再送信処理が行われます。 1 以上の値を指定する必要があります。 |
Result nn::pia::sync::SyncProtocol::Start | ( | uint32_t | usingDataIdBitmap, |
uint32_t | delay, | ||
uint32_t | sendPeriod | ||
) |
同期通信を開始します。
SyncProtocol::State_NotSynchronized の間に呼ぶことができ、成功すると SyncProtocol::State_Waiting に遷移します。 その後、通信相手でも同期通信が開始されると、SyncProtocol::State_Starting, SyncProtocol::State_Synchronized と遷移していきます。
[in] | usingDataIdBitmap | SyncProtocol::Initialize() で指定したデータ ID のうち、今回の同期通信でこのステーションから送信するデータ ID のリストをビットフラグで指定します。 ビットの下位から順に、データ ID の 0 から対応します。 ステーション毎に別々の値を指定できます。 |
[in] | delay | このステーションが設定を希望する入力遅延を指定できます。 実際に設定される入力遅延は、各ステーションが希望した入力遅延の値の中の最大値となります。 初期化時に SyncProtocol::Setting::maxDelay で指定した最大入力遅延以下の値である必要があります。 |
[in] | sendPeriod | 設定した同期データの送信、再送信処理の間隔を指定します。 ここで指定した回数 SyncProtocol::Step() が呼び出されるたびに、common::Scheduler::Dispatch() 呼び出し時に送信、再送信処理が行われます。 1 以上の値を指定する必要があります。 |
ResultInvalidState この関数を呼び出せる SyncProtocol::State ではありません。または、通信中ではありません。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
ResultInvalidArgument 引数の指定が不正です。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
Result nn::pia::sync::SyncProtocol::Step | ( | ) |
同期通信を 1 フレーム進めます。
SyncProtocol::State_NotSynchronized 以外の間は毎フレーム呼び出す必要があります。フレーム毎の処理の先頭で実行することを推奨します。 SyncProtocol::NeedsSetData が true の時は、この関数を呼ぶ前に SyncProtocol::SetData で送信する同期データを設定してください。 SyncProtocol::State_NotSynchronized の時にこの関数を呼んでも問題ありません。
SyncProtocol::EndAlone 呼び出し成功後の単独同期終了処理中は本関数が失敗しますが、 内部処理を進行させるために毎フレーム呼び出す必要がある点に注意してください。
ResultInvalidState 通信中ではありません。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
ResultDataIsNotArrivedYet 同期データが他のステーションから届いていないためフレームを進めることができませんでした。 common::Scheduler::Dispatch() を呼んだあと再度この関数を呼ぶ必要があります。アプリケーションで適切にハンドリングしてください。
ResultDataIsNotSet 自分が送信する同期データがまだ設定されていません。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
ResultTemporaryUnavailable 単独同期終了処理中です。
|
virtual |
デバッグに有用な情報をプリントします。
[in] | flag | トレースフラグの論理和。詳細は TraceFlag 型を参照してください。 |
nn::pia::transport::Protocolを再定義しています。