CTR Pia
4.11.3
Game Communication Engine
|
This protocol is used for synchronized communication.
Full mesh is the only network topology type that is supported. Note that star and relay mesh types are not supported.
.
More...
Classes | |
struct | Setting |
Stores settings specified during initialization. More... | |
Public Types |
Public Member Functions | |
size_t | CalcMaxSyncDataSizeSentInOnePacket (u32 delay, u32 dataIdNum) |
Calculates the maximum total size of data that can be sent as a single packet of synchronization data, given the specified number of data IDs. More... | |
bool | CanGetData () const |
Gets whether received data can be retrieved. More... | |
bool | CheckEntry (StationId stationId) const |
Gets whether the specified station has joined synchronization. More... | |
nn::Result | End () |
Ends synchronized communication. More... | |
nn::Result | EndAlone () |
Unilaterally ends synchronization for only the local station. More... | |
void | Finalize () |
Finalizes the instance. More... | |
nn::Result | GetData (StationId stationId, u32 dataId, void *pBuffer) const |
Gets the data received during synchronization. More... | |
const void * | GetDataPtr (StationId stationId, u32 dataId) const |
Gets a pointer to the data received during synchronization. More... | |
size_t | GetDataSize (u32 dataId) const |
Gets the size of data having the data ID specified to the Initialize function. More... | |
size_t | GetDataUnitSizeMax () const |
Gets the maximum number of bytes that can be sent in one data unit. More... | |
u32 | GetDelay () const |
Gets the input delay actually specified. More... | |
nn::Result | GetEndFrameNo (StationId stationId, u32 *endFrameNo) const |
Gets the end frame for the specified station. More... | |
u32 | GetFrameNo () const |
Gets the number of frames since synchronization started. More... | |
nn::Result | GetIsNoDataFrame (bool *isNoDataFrame) const |
Gets whether synchronization data cannot be retrieved for this frame. More... | |
EndReason | GetLastEndReason () const |
Gets the reason why synchronization was ended. More... | |
u32 | GetMaxDelay () const |
Gets the maximum input delay specified to the Initialize function. More... | |
u32 | GetSendPeriod () const |
Gets the send interval specified to the Start function. More... | |
State | GetState () const |
Gets the current state of synchronization. More... | |
u32 | GetTimeoutFrame () const |
Gets the timeout setting specified in the Initialize function. More... | |
bit32 | GetUsingDataIdBitmap (StationId stationId) const |
Gets a bit flag representing the list of data IDs that the specified station is sending. More... | |
nn::Result | Initialize (const Setting &setting) |
Initializes the instance. Make this call between the BeginSetup and EndSetup functions. More... | |
bool | NeedSetData () const |
Gets whether it is necessary to set the data to send. More... | |
bool | NeedSetData (u32 dataId) const |
Gets whether it is necessary to set the data to send for the specified data ID. More... | |
nn::Result | RequestToChangeDelay (u32 newDelay) |
Sets a change delay request as synchronization data. More... | |
nn::Result | SetData (u32 dataId, const void *cpData) |
Sets data to send during synchronization. More... | |
nn::Result | SetSendPeriod (u32 sendPeriod) |
Sets the send interval. More... | |
nn::Result | Start (bit32 usingDataIdBitmap, u32 delay, u32 sendPeriod) |
Starts synchronization. More... | |
nn::Result | Step () |
Advances synchronization by one frame. More... | |
virtual void | Trace (u64 flag) const |
Prints information that is useful for debugging. More... | |
Static Public Attributes | |
static const u32 | COMPRESSION_LEVEL_HIGH = 9 |
Specifies the compression level (compression rate emphasized) for the synchronization data specified in Setting::m_DataCompressionLevel . | |
static const u32 | COMPRESSION_LEVEL_LOW = 1 |
Specifies the compression level (speed emphasized) for the synchronization data specified in Setting::m_DataCompressionLevel . | |
static const u32 | COMPRESSION_LEVEL_MIDDLE = 5 |
Specifies the compression level for the synchronization data specified in Setting::m_DataCompressionLevel . | |
static const u32 | COMPRESSION_LEVEL_NONE = 0 |
Specifies the compression level (no compression) for the synchronization data specified in Setting::m_DataCompressionLevel . | |
static const u32 | DATA_ID_NUM = 16 |
Defines the number of data IDs that can be set. | |
static const u8 | FRAME_DELAY_MAX = 32 |
Defines the maximum input latency specified that can be specified for Setting::m_MaxDelay , as a number of frames. | |
static const u32 | RESERVED_DATA_ID_NUM = 1 |
Defines the reserved data ID. | |
This protocol is used for synchronized communication.
Full mesh is the only network topology type that is supported. Note that star and relay mesh types are not supported.
.
2014-01-30 Added constants to specify the compression level of synchronization data, and made any other compression levels unsupported.
2013-11-22 Changed internal processes and reduced the amount of synchronization data sent.
2013-11-22 Enabled a skip feature when sending synchronized data on the same frame by default and removed the configuration parameter (Setting::m_SendSkipMax
).
2013-10-25 Added the EndAlone
function for unilaterally ending synchronization.
2013-10-25 Added a feature for compressing synchronized data.
2013-10-25 Added a skip feature when sending synchronized data on the same frame.
2013-08-30 Changed the message headers. This breaks backward compatibility.
2013-08-26 Removed the Session::m_SendPeriod
function. Set the same parameters by calling Start
.
2013-08-26 Removed Start(bit32 usingDataIdBitmap)
and Start(bit32 usingDataIdBitmap, u32 delay)
. Use Start(bit32 usingDataIdBitmap, u32 delay, u32 sendPeriod)
when synchronized communication starts.
2013-05-20 Promoted the feature to change delay during synchronization to the officially supported version.
2013-04-12 Added a function to calculate the maximum data size that would fit into a single packet of synchronization data to be sent.
2013-04-12 Added a feature to change the delay after initialization. (The feature to change the delay during synchronization is still in beta.)
2013-04-12 Changed the type of the Setting
member.
2013-04-12 Changed the number of Data IDs that can be configured.
2013-02-19 Renamed STATE_READY
to STATE_WAITING
.
2013-02-15 Added a function to get the settings specified in the Initialize
function.
2013-02-15 Changed the type of the Setting
member.
2013-01-18 Greatly revised the state transitions, and changed the operations of each function.
2013-01-18 It is now possible to send large files.
2012-12-25 Initial version.
2012-12-25 Renamed the existing SyncProtocol
class to SyncProtocolOld
.
Represents the reason why synchronization was ended.
Enumerator | |
---|---|
END_REASON_NOTHING |
Synchronization has not ended. |
END_REASON_END |
Communication ended because of a call to the |
END_REASON_OTHER_STATION |
Communication ended because another station ended synchronization. |
END_REASON_CHANGE_CONNECTION |
Communication ended because there was a change in the stations in the session. |
END_REASON_TIMEOUT |
Communication ended because no data was received for |
END_REASON_END_ALONE |
Communication ended because of a call to the |
Represents the current state of synchronization.
size_t nn::pia::sync::SyncProtocol::CalcMaxSyncDataSizeSentInOnePacket | ( | u32 | delay, |
u32 | dataIdNum | ||
) |
Calculates the maximum total size of data that can be sent as a single packet of synchronization data, given the specified number of data IDs.
This function calculates the maximum amount of synchronization data that can be sent. This maximum amount of data is the value to use when you need to send (delay * 2) frames of synchronization data.
[in] | delay | Specifies the delay value. |
[in] | dataIdNum | Specifies the number of data IDs that you are using. |
bool nn::pia::sync::SyncProtocol::CanGetData | ( | ) | const |
Gets whether received data can be retrieved.
Received data can be retrieved while the state is STATE_SYNCHRONIZED
. However, when you are using the feature to change the delay while communication is synchronized, use GetIsNoDataFrame
to check whether data can be retrieved during the current frame. During some frames you cannot retrieve data even if this function returns true
.
true
if received data can be retrieved. bool nn::pia::sync::SyncProtocol::CheckEntry | ( | StationId | stationId | ) | const |
Gets whether the specified station has joined synchronization.
[in] | stationId | Specifies the StationId of the station being checked. |
true
if the specified station has joined synchronization. nn::Result nn::pia::sync::SyncProtocol::End | ( | ) |
Ends synchronized communication.
If this function can be called when the state is STATE_WAITING
, STATE_STARTING
, or STATE_SYNCHRONIZED
, and the function succeeds, the state transitions to STATE_ENDING
. When network nodes are subsequently notified that communication has ended, the state transitions to STATE_NOT_SYNCHRONIZED
. If you use this function to end synchronization, normally the reason for the end of communication is END_REASON_END
for the local station and END_REASON_OTHER_STATION
for other stations. However, these are not necessarily the values if communication is simultaneously terminated by different nodes for different reasons. Immediately after this function is called, you must call the Step
function for several frames until STATE_NOT_SYNCHRONIZED
results before calling the Start
function again.
Result
value for which the IsSuccess
function returns true
if execution succeeds. You must make sure that the implementation of this function in your application does not return any errors.ResultInvalidState
Indicates that this function cannot be called in the current State
. Alternatively, it indicates that stations are not communicating. Programming error. Fix your program so that this error is not returned. nn::Result nn::pia::sync::SyncProtocol::EndAlone | ( | ) |
Unilaterally ends synchronization for only the local station.
This function can be called while the state is STATE_SYNCHRONIZED
.
This function can get the synchronization data for each frame. If there is a notification that an individual synchronization finalization has been done on another station after this function has been called, however, the synchronization data that station sent cannot be obtained. This can lead to the data getting out of sync, so make sure to call this function after getting the received synchronization data. The end frame is set to the last frame for which send data has already been set. The peers are notified of the end frame and the local station transitions to the STATE_ENDED_ALONE
state after confirming that all peers have reached the end frame. After this function is called successfully, Step
fails while the state is STATE_SYNCHRONIZED
. Note that the frame can no longer advance when this happens, so the local station never reaches the end frame. Nonetheless, the Step
function must still be called in every frame to advance internal processes. If you use this function to end synchronization, normally the reason for the end of communication is END_REASON_END_ALONE
for the local station. However, these are not necessarily the values if communication is simultaneously terminated by different nodes for different reasons. Once synchronization ends with all peers while in the STATE_ENDED_ALONE
state, the state transitions to STATE_NOT_SYNCHRONIZED
. Also, the other stations can maintain synchronization even if the local station leaves the session in the STATE_ENDED_ALONE
state, or after transitioning to the subsequent STATE_NOT_SYNCHRONIZED
state. However, if the local station disconnects in the STATE_WAITING
state because a new station connected after the transition to the STATE_ENDED_ALONE
state and the other stations attempted synchronization again, the other stations end synchronization and transition to the STATE_NOT_SYNCHRONIZED
state. Also, stations that ended in the STATE_ENDED_ALONE
state can restart synchronization after transitioning to the STATE_NOT_SYNCHRONIZED
state, but if those stations restart synchronization or leave the session, the stations other than the local station cannot be synchronized.
Result
value for which the IsSuccess
function returns true
if execution succeeds. You must make sure that the implementation of this function in your application does not return any errors.ResultInvalidState
Indicates that this function cannot be called in the current State
. or that the end frame has already been set. Alternatively, it indicates that stations are not communicating. Programming error. Fix your program so that this error is not returned.void nn::pia::sync::SyncProtocol::Finalize | ( | ) |
Finalizes the instance.
|
inline |
Gets the data received during synchronization.
If the CanGetData
and CheckEntry
functions return true
for a station, it can retrieve data for data IDs that have bits set in the bitmap returned from the GetUsingDataIdBitmap
function. If you use the feature to change the delay while communication is synchronized, data cannot be retrieved in some frames. The function returns ResultInvalidState
in these frames. Use the GetIsNoDataFrame
function to determine whether data can be retrieved in this frame.
[in] | stationId | Specifies the StationId of the station that is sending the data to retrieve. |
[in] | dataId | Specifies the data ID of the data to retrieve. |
[out] | pBuffer | Specifies a pointer to a buffer to store the data. It must be the size specified in the Initialize function. |
Result
value for which the IsSuccess
function returns true
if execution succeeds. You must make sure that the implementation of this function in your application does not return any errors.ResultInvalidState
Indicates that this function cannot be called in the current State
. Alternatively, it could indicate that data cannot be retrieved in this frame. Alternatively, it indicates that stations are not communicating. Programming error. Fix your program so that this error is not returned.
ResultInvalidArgument
Indicates that an argument is invalid. Programming error. Fix your program so that this error is not returned.
const void* nn::pia::sync::SyncProtocol::GetDataPtr | ( | StationId | stationId, |
u32 | dataId | ||
) | const |
Gets a pointer to the data received during synchronization.
If the CanGetData
and CheckEntry
functions return true
for a station, it can retrieve data for data IDs that have bits set in the bitmap returned from the GetUsingDataIdBitmap
function. The retrieved pointer is valid until the next call to the Step
function. It has the size specified in the Initialize
function.
[in] | stationId | Specifies the StationId of the station that is sending the data to retrieve. |
[in] | dataId | Specifies the data ID of the data to retrieve. |
NULL
if there is no available data. size_t nn::pia::sync::SyncProtocol::GetDataSize | ( | u32 | dataId | ) | const |
Gets the size of data having the data ID specified to the Initialize
function.
[in] | dataId | Specifies the data ID of the data being checked. |
size_t nn::pia::sync::SyncProtocol::GetDataUnitSizeMax | ( | ) | const |
Gets the maximum number of bytes that can be sent in one data unit.
The value obtained depends on the parameter specified when initializing the transport::Transport
instance.
|
inline |
Gets the input delay actually specified.
nn::Result nn::pia::sync::SyncProtocol::GetEndFrameNo | ( | StationId | stationId, |
u32 * | endFrameNo | ||
) | const |
Gets the end frame for the specified station.
This function can be called when the state is something other than STATE_NOT_SYNCHRONIZED
or STATE_WAITING
. If synchronization ends before the STATE_SYNCHRONIZED
state is reached, endFrame
becomes 0
, but note that synchronization actually ends before that. Also note that the station ending synchronization may end before reaching this frame.
Result
value for which the IsSuccess
function returns true
if execution succeeds.ResultInvalidArgument
Indicates that an argument is invalid. Programming error. Fix your program so that this error is not returned.
ResultInvalidState
Indicates that this function cannot be called in the current State
. Programming error. Fix your program so that this error is not returned.
ResultNoData
Indicates that the end frame is not set. Handle appropriately in the application.
u32 nn::pia::sync::SyncProtocol::GetFrameNo | ( | ) | const |
Gets the number of frames since synchronization started.
While the state is STATE_SYNCHRONIZED
, every successful call to the Step
function advances one frame.
0
if synchronization is not active, and also returns 0
on the first frame when synchronization starts.
|
inline |
Gets whether synchronization data cannot be retrieved for this frame.
If you are using the feature to change the delay while communication is synchronized, use this function to check whether data can be retrieved in the current frame. Data cannot be retrieved for some frames when you use this feature. You are not required to use this function if you are not using the function for changing the delay while communication is synchronized.
[out] | isNoDataFrame | Specifies whether synchronization data is available in this frame. |
Result
value for which the IsSuccess
function returns true
if execution succeeds. ResultInvalidState
Indicates that the function was called in an invalid state. Programming error. Fix your program so that this error is not returned.
ResultInvalidArgument
Indicates that an argument is invalid. Programming error. Fix your program so that this error is not returned.
EndReason nn::pia::sync::SyncProtocol::GetLastEndReason | ( | ) | const |
Gets the reason why synchronization was ended.
This value is reset if the Start
function is called to start synchronization again.
|
inline |
Gets the maximum input delay specified to the Initialize
function.
|
inline |
Gets the send interval specified to the Start
function.
|
inline |
Gets the current state of synchronization.
|
inline |
Gets the timeout setting specified in the Initialize
function.
bit32 nn::pia::sync::SyncProtocol::GetUsingDataIdBitmap | ( | StationId | stationId | ) | const |
Gets a bit flag representing the list of data IDs that the specified station is sending.
[in] | stationId | Specifies the StationId of the station being checked. |
0
is returned for stations not engaging in synchronization (stations for which CheckEntry
returns false
). nn::Result nn::pia::sync::SyncProtocol::Initialize | ( | const Setting & | setting | ) |
Initializes the instance. Make this call between the BeginSetup
and EndSetup
functions.
[in] | setting | Specifies various settings. Specify the same values on all stations using data synchronization. Operations are undefined when different values are specified. |
Result
value for which the IsSuccess
function returns true
if execution succeeds. You must make sure that the implementation of this function in your application does not return any errors. ResultAlreadyInitialized
Indicates that the instance is already initialized. Programming error. Fix your program so that this error is not returned.
ResultInvalidArgument
Indicates that an argument is invalid. Programming error. Fix your program so that this error is not returned.
bool nn::pia::sync::SyncProtocol::NeedSetData | ( | ) | const |
Gets whether it is necessary to set the data to send.
You must set the data to send during STATE_STARTING
and STATE_SYNCHRONIZED
. If the return value of a call to Step
indicates that execution failed, there is no need to reconfigure send data before the next call to Step
because the frame has not advanced.
true
if any of the required data IDs are not set. Returns false
if it is not necessary to set send data, or the data to send has already been set. bool nn::pia::sync::SyncProtocol::NeedSetData | ( | u32 | dataId | ) | const |
Gets whether it is necessary to set the data to send for the specified data ID.
You must set the data to send during STATE_STARTING
and STATE_SYNCHRONIZED
. When the return value of a call to Step
indicates that execution failed, you do not need to reconfigure send data before the next call to Step
because the frame has not advanced.
[in] | dataId | Specifies the data ID to check whether it is necessary to send data for. |
true
when send data needs to be set for the specified data ID. Returns false
if it is not necessary to set send data, or the data to send has already been set. nn::Result nn::pia::sync::SyncProtocol::RequestToChangeDelay | ( | u32 | newDelay | ) |
Sets a change delay request as synchronization data.
The requested delay must be no larger than the delay specified at initialization. If you request a delay of zero, the library assumes that you have not requested a change. Even if this function succeeds, the delay is not guaranteed to change to the requested value. If more than one request is received in the same frame, the largest requested delay value gets precedence. If the delay is already being changed in response to a request when another delay-change request arrives as synchronization data, the newly arrived request is ignored.
[in] | newDelay | Specifies the requested delay value. |
Result
value for which the IsSuccess
function returns true
if execution succeeds. ResultInvalidState
Indicates that the function was called in an invalid state. Alternatively, it indicates that stations are not communicating. Programming error. Fix your program so that this error is not returned.
ResultInvalidArgument
Indicates that an argument is invalid. Programming error. Fix your program so that this error is not returned.
ResultAlreadyExists
Indicates that the data has already been set. Programming error. Fix your program so that this error is not returned.
nn::Result nn::pia::sync::SyncProtocol::SetData | ( | u32 | dataId, |
const void * | cpData | ||
) |
Sets data to send during synchronization.
If the NeedSetData
function returns true
, you must set data before calling the Step
function.
[in] | dataId | Specifies the data ID of data being set. |
[in] | cpData | Specifies the data being set. The size is specified in the call to the Initialize function. |
Result
value for which the IsSuccess
function returns true
if execution succeeds. You must make sure that the implementation of this function in your application does not return any errors.ResultInvalidState
Indicates that this function cannot be called in the current State
. Alternatively, it indicates that stations are not communicating. Programming error. Fix your program so that this error is not returned.
ResultInvalidArgument
Indicates that an argument is invalid. Programming error. Fix your program so that this error is not returned.
ResultAlreadyExists
Indicates that the data has already been set. Programming error. Fix your program so that this error is not returned.
nn::Result nn::pia::sync::SyncProtocol::SetSendPeriod | ( | u32 | sendPeriod | ) |
Sets the send interval.
Result
value for which the IsSuccess
function returns true
if execution succeeds. ResultInvalidArgument
Indicates that an argument is invalid. Programming error. Fix your program so that this error is not returned.nn::Result nn::pia::sync::SyncProtocol::Start | ( | bit32 | usingDataIdBitmap, |
u32 | delay, | ||
u32 | sendPeriod | ||
) |
Starts synchronization.
If this function is successfully called when the state is STATE_NOT_SYNCHRONIZED
, the state transitions to STATE_WAITING
. If a network node starts synchronization after this function is called, the state transitions to STATE_STARTING
and STATE_SYNCHRONIZED
.
[in] | usingDataIdBitmap | Specifies a bit flag representing the data IDs (among those specified by Initialize ) to send from this station during this round of synchronized communication. Bits are ordered from low to high, with the lowest-order bit corresponding to data ID 0. You can specify separate values for each station. |
[in] | delay | Specifies the delay requested by this station. The largest delay value among stations that specify a delay is actually used. This delay value must be less than or equal to the delay specified during initialization. |
[in] | sendPeriod | Specifies the send/resend interval for the configured data. Each time that SyncProtocol::Step is called the number of times specified by this parameter, send/resend is executed when common::Scheduler::Dispatch is called. Specify a value of 1 or greater. |
Result
value for which the IsSuccess
function returns true
if execution succeeds. You must make sure that the implementation of this function in your application does not return any errors.ResultInvalidState
Indicates that this function cannot be called in the current State
. Alternatively, it indicates that stations are not communicating. Programming error. Fix your program so that this error is not returned.
ResultInvalidArgument
Indicates that an argument is invalid. Programming error. Fix your program so that this error is not returned.
nn::Result nn::pia::sync::SyncProtocol::Step | ( | ) |
Advances synchronization by one frame.
Call this function during each frame when the state is other than STATE_NOT_SYNCHRONIZED
. Call this function at the beginning of each frame. When NeedSetData
returns true
, specify the data to send to the SetData
function before calling this function. This function can also be called when the state is STATE_NOT_SYNCHRONIZED
. EndAlone After being called successfully, this function fails when called during individual synchronization finalization processes. It must be called every frame to keep the internal processing going.
Result
value for which the IsSuccess
function returns true
if execution succeeds. ResultInvalidState
Indicates that communication is not active. Programming error. Fix your program so that this error is not returned.
ResultDataIsNotArrivedYet
Indicates that the frame was not advanced because the data being synchronized has not arrived from other stations. Try calling this function again after calling the common::Scheduler::Dispatch
function. Handle appropriately in the application.
ResultDataIsNotSet
Indicates that the local station has not yet set the data to send. Programming error. Fix your program so that this error is not returned.
ResultTemporaryUnavailable
An individual synchronization finalization process is in progress.
|
virtual |
Prints information that is useful for debugging.
[in] | flag | Specifies the bitwise OR of trace flags. For more information, see the TraceFlag type. |
Reimplemented from nn::pia::transport::Protocol.