CTR Pia  4.11.3
Game Communication Engine
nn::pia::sync::SyncProtocol Class Reference

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...

+ Inheritance diagram for nn::pia::sync::SyncProtocol:

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.
 

Detailed Description

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.
.

Revision History:

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.

Member Enumeration Documentation

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 function by the station.

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 Setting::m_TimeoutFrame frames.

END_REASON_END_ALONE 

Communication ended because of a call to the EndAlone function by the station.

Represents the current state of synchronization.

Enumerator
STATE_NOT_SYNCHRONIZED 

Synchronization is not active.

STATE_WAITING 

Start synchronization and wait for other stations to start synchronization.

STATE_STARTING 

Synchronization is starting. Although the data to send must be set, it cannot yet be retrieved.

STATE_SYNCHRONIZED 

Synchronization is active. The data to send must be set, and it can be retrieved.

STATE_ENDING 

Synchronization is ending.

STATE_ENDED_ALONE 

The local station unilaterally ended synchronization.

Member Function Documentation

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.

Parameters
[in]delaySpecifies the delay value.
[in]dataIdNumSpecifies the number of data IDs that you are using.
Returns
Returns the maximum total size of data that can be sent as a single packet of synchronization data, given the specified number of data IDs.
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.

Returns
Returns true if received data can be retrieved.
See also
GetData
bool nn::pia::sync::SyncProtocol::CheckEntry ( StationId  stationId) const

Gets whether the specified station has joined synchronization.

Parameters
[in]stationIdSpecifies the StationId of the station being checked.
Returns
Returns 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.

Returns
Returns a 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.
Error Return Values:
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.
See also
Start
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.

Returns
Returns a 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.
Error Return Values:
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.

See also
Initialize
nn::Result nn::pia::sync::SyncProtocol::GetData ( StationId  stationId,
u32  dataId,
void *  pBuffer 
) const
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.

Parameters
[in]stationIdSpecifies the StationId of the station that is sending the data to retrieve.
[in]dataIdSpecifies the data ID of the data to retrieve.
[out]pBufferSpecifies a pointer to a buffer to store the data. It must be the size specified in the Initialize function.
Returns
Returns a 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.
Error Return Values:

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.

Parameters
[in]stationIdSpecifies the StationId of the station that is sending the data to retrieve.
[in]dataIdSpecifies the data ID of the data to retrieve.
Returns
Returns a pointer to data received during synchronization. This function returns 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.

Parameters
[in]dataIdSpecifies the data ID of the data being checked.
Returns
Returns the size of the specified data.
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.

See also
Returns the maximum number of bytes that can be sent in one data unit.
Setting::m_DataUnitSize
u32 nn::pia::sync::SyncProtocol::GetDelay ( ) const
inline

Gets the input delay actually specified.

Returns
Returns the number of input delay frames.
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.

Returns
Returns a Result value for which the IsSuccess function returns true if execution succeeds.
Error Return Values:

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.

Returns
Returns the number of frames since synchronization started. Note: This function returns 0 if synchronization is not active, and also returns 0 on the first frame when synchronization starts.
nn::Result nn::pia::sync::SyncProtocol::GetIsNoDataFrame ( bool *  isNoDataFrame) const
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.

Parameters
[out]isNoDataFrameSpecifies whether synchronization data is available in this frame.
Returns
Returns a Result value for which the IsSuccess function returns true if execution succeeds.
Error Return Values:

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.

Returns
Returns the reason why synchronization ended.
u32 nn::pia::sync::SyncProtocol::GetMaxDelay ( ) const
inline

Gets the maximum input delay specified to the Initialize function.

Returns
Returns the maximum number of frames to delay input.
u32 nn::pia::sync::SyncProtocol::GetSendPeriod ( ) const
inline

Gets the send interval specified to the Start function.

Returns
Returns the send interval.
State nn::pia::sync::SyncProtocol::GetState ( ) const
inline

Gets the current state of synchronization.

Returns
Returns the current state of synchronization.
u32 nn::pia::sync::SyncProtocol::GetTimeoutFrame ( ) const
inline

Gets the timeout setting specified in the Initialize function.

Returns
Returns the timeout setting.
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.

Parameters
[in]stationIdSpecifies the StationId of the station being checked.
Returns
Returns a list of data IDs that the specified station is sending. 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.

Parameters
[in]settingSpecifies various settings. Specify the same values on all stations using data synchronization. Operations are undefined when different values are specified.
Returns
Returns a 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.
Error Return Values:

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.

See also
Finalize
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.

Returns
Returns 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.
See also
SetData
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.

Parameters
[in]dataIdSpecifies the data ID to check whether it is necessary to send data for.
Returns
Returns 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.
See also
SetData
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.

Parameters
[in]newDelaySpecifies the requested delay value.
Returns
Returns a Result value for which the IsSuccess function returns true if execution succeeds.
Error Return Values:

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.

Parameters
[in]dataIdSpecifies the data ID of data being set.
[in]cpDataSpecifies the data being set. The size is specified in the call to the Initialize function.
Returns
Returns a 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.
Error Return Values:

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.

See also
NeedSetData, Step
nn::Result nn::pia::sync::SyncProtocol::SetSendPeriod ( u32  sendPeriod)

Sets the send interval.

Returns
Returns a Result value for which the IsSuccess function returns true if execution succeeds.
Error Return Values:
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.

Parameters
[in]usingDataIdBitmapSpecifies 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]delaySpecifies 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]sendPeriodSpecifies 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.
Returns
Returns a 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.
Error Return Values:

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.

See also
End
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.

Returns
Returns a Result value for which the IsSuccess function returns true if execution succeeds.
Error Return Values:

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.

See also
SetData
virtual void nn::pia::sync::SyncProtocol::Trace ( u64  flag) const
virtual

Prints information that is useful for debugging.

Parameters
[in]flagSpecifies the bitwise OR of trace flags. For more information, see the TraceFlag type.

Reimplemented from nn::pia::transport::Protocol.