CTR Pia  4.11.3
Game Communication Engine
nn::pia::transport::ReliableBroadcastProtocol Class Reference

Represents a protocol for sending a large volume of data to all stations. More...

+ Inheritance diagram for nn::pia::transport::ReliableBroadcastProtocol:

Classes

class  Configuration
 Represents methods used to transfer data. More...
 
struct  TransferSetting
 Stores data transfer settings. More...
 

Public Types

Public Member Functions

nn::Result Cancel ()
 Stops sending or receiving data. More...
 
void Finalize ()
 Finalizes the class instance. More...
 
nn::Result FinishSendEndless ()
 Stops sending data sent using any configuration for which the Configuration::IsSendEndless function returns true. For more information about operations, see the Configuration::IsSendEndless function. More...
 
const TransferSettingGetCurrentTransferSetting () const
 Gets the current data transfer settings. More...
 
size_t GetProgress () const
 Gets the progress status of the send/receive operation. More...
 
const TransferSettingGetRequest () const
 Gets receive requests that have been delivered. More...
 
const TransferSettingGetRequest (nn::pia::StationId stationId) const
 Gets receive requests from a particular station. More...
 
size_t GetSendProgress (nn::pia::StationId stationId) const
 Gets the progress status of data being sent to a particular receiving station. More...
 
State GetState () const
 Gets the current operational state. More...
 
u32 GetThroughputLimit () const
 Gets the maximum amount of data that this protocol can send per call to the common::Scheduler::Dispatch function. More...
 
nn::Result Initialize ()
 Initializes the instance. Make this call between the BeginSetup and EndSetup functions. More...
 
bool IsRunning () const
 Gets whether asynchronous send and receive operations are currently executing. More...
 
bool IsSendTarget (nn::pia::StationId stationId) const
 Gets information about whether the specified station is to receive data currently being sent. More...
 
nn::Result RejectRequest ()
 Rejects receive requests retrieved with the GetRequest function. More...
 
nn::Result RejectRequest (nn::pia::StationId stationId)
 Rejects receive requests retrieved with the GetRequest ( nn::pia::StationId ) function. More...
 
nn::Result Reset ()
 Discards information about the result of sending and receiving data and returns to the STATE_WAIT state. More...
 
void SetThroughputLimit (u32 throughputLimit)
 Sets the maximum amount of data that this protocol sends per call to the common::Scheduler::Dispatch function. More...
 
nn::Result StartReceive (void *pBuffer, size_t bufferSize, StationId sourceStationId)
 Starts receiving data. More...
 
nn::Result StartSend (const void *cpData, size_t dataSize, Configuration configuration, u32 userData=0)
 Starts sending data. More...
 
virtual void Trace (u64 flag) const
 Prints information that is useful for debugging. More...
 

Detailed Description

Represents a protocol for sending a large volume of data to all stations.


Revision History:

2014-07-16 Changed the specifications so that ResultTemporaryUnavailable is returned when the StartSend or StartReceive function is called during joint sessions or during state transitions between sessions.

2014-07-10 Fixed broken links in the API reference.

2014-07-01 Changed the specifications of TransferSetting. Use TransferSetting::GetSourceStationId to get the sender's StationId.

2014-04-02 Revised the documentation for the IsXXXX functions in the Configuration class.

2013-05-27 Fixed an incorrect return value sometimes returned from the Cancel function.

2013-04-25 Refactored code. This breaks backward compatibility.

2012-03-29 The value specified in the SetThroughputLimit function is now set as the default value when communication starts.

2012-10-29 Improved throughput by tuning the way that data is sent.

2012-10-17 Fixed a bug where the GetProgress function might halt on an assertion.

2012-09-18 Added the SetThroughputLimit and GetThroughputLimit functions.

2012-09-10 Tuned throughput.

2012-08-21 Initial version.

Member Enumeration Documentation

Enumerates the operational states.

Enumerator
STATE_INVALID 

Indicates not participating in a session.

STATE_WAIT 

Indicates currently doing nothing.

STATE_SENDING 

Indicates sending.

STATE_SEND_SUCCESS 

Indicates that sending was successful.

STATE_SEND_FAILURE 

Indicates failure to send.

STATE_RECEIVING 

Indicates receiving.

STATE_RECEIVE_SUCCESS 

Indicates that receiving was successful.

STATE_RECEIVE_FAILURE 

Indicates failure to receive.

Member Function Documentation

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

Stops sending or receiving data.

If this function is called when the state is STATE_SENDING and the action is then canceled in the common::Scheduler::Dispatch function, the station ordinarily goes to STATE_SEND_FAILURE. However, the station may also enter STATE_SEND_SUCCESS, depending on the timing. The receiving station also transitions to STATE_RECEIVE_FAILURE (or STATE_RECEIVE_SUCCESS).

If this function is called when the state is STATE_RECEIVING and the action is then canceled in the common::Scheduler::Dispatch function, the station ordinarily goes to STATE_RECEIVE_FAILURE. However, the station may also enter STATE_RECEIVE_SUCCESS, depending on the timing. If this happens, you can access received data. Sending itself is suspended if the station is not configured to run in a way that the Configuration::IsFailIfRejected( function returns true.

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 data is not currently being sent/received. Programming error. Fix your program so that this error is not returned.
See also
StartSend, StartReceive
void nn::pia::transport::ReliableBroadcastProtocol::Finalize ( )

Finalizes the class instance.

See also
Initialize
nn::Result nn::pia::transport::ReliableBroadcastProtocol::FinishSendEndless ( )

Stops sending data sent using any configuration for which the Configuration::IsSendEndless function returns true. For more information about operations, see the Configuration::IsSendEndless 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 Not currently sending data, or not configured for the Configuration::IsSendEndless function to return true. Programming error. Fix your program so that this error is not returned.
See also
Configuration::IsSendEndless
const TransferSetting* nn::pia::transport::ReliableBroadcastProtocol::GetCurrentTransferSetting ( ) const

Gets the current data transfer settings.

Returns
Retrieves send settings if the function is executed during or after a send operation, or the receive settings if it is during or after a receive operation. Returns NULL if no data has been received, such as when the receive starts before a receive request comes in, or when the Cancel function is executed in that state.
size_t nn::pia::transport::ReliableBroadcastProtocol::GetProgress ( ) const

Gets the progress status of the send/receive operation.

The value representing progress of a send operation can decrease while sending data because if the number of receiving stations changes.

Returns
Returns the amount of data (in bytes) that has been sent and received. You can retrieve the average amount of data sent to receiving stations during or after a send operation. You can get the amount of the data received by the local station while or after receiving it.
const TransferSetting* nn::pia::transport::ReliableBroadcastProtocol::GetRequest ( ) const

Gets receive requests that have been delivered.

To get this data, prepare a buffer of the required size and call the StartReceive function. Call the RejectRequest function if you do not want to receive the data. When multiple receive requests have arrived, you can get the receive request with the highest priority (the request from the sender with the lowest StationIndex, regardless of the value of the Configuration::IsMediateRequest function).

Returns
Returns a pointer to the receive request. This function returns NULL if a receive request has not been delivered.
See also
StartReceive, RejectRequest
const TransferSetting* nn::pia::transport::ReliableBroadcastProtocol::GetRequest ( nn::pia::StationId  stationId) const

Gets receive requests from a particular station.

To get this data, prepare a buffer of the required size and call the StartReceive function.

Parameters
[in]stationIdSpecifies the StationId of the station you want to get a receive request from.
Returns
Returns a pointer to the receive request. This function returns NULL if a receive request has not been delivered.
See also
StartReceive, RejectRequest
size_t nn::pia::transport::ReliableBroadcastProtocol::GetSendProgress ( nn::pia::StationId  stationId) const

Gets the progress status of data being sent to a particular receiving station.

Parameters
[in]stationIdSpecifies the StationId of the station receiving the data.
Returns
Returns the amount of data (in bytes) that has been sent to the specified station. 0 is returned if there is no send operation in progress or completed, or if an invalid StationId was specified.
State nn::pia::transport::ReliableBroadcastProtocol::GetState ( ) const
inline

Gets the current operational state.

Returns
Returns the current operational state.
u32 nn::pia::transport::ReliableBroadcastProtocol::GetThroughputLimit ( ) const
inline

Gets the maximum amount of data that this protocol can send per call to the common::Scheduler::Dispatch function.

Returns
Returns the amount of data that the protocol sends per call to the common::Scheduler::Dispatch function.
See also
SetThroughputLimit
nn::Result nn::pia::transport::ReliableBroadcastProtocol::Initialize ( )

Initializes the instance. Make this call between the BeginSetup and EndSetup functions.

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.
See also
Finalize
bool nn::pia::transport::ReliableBroadcastProtocol::IsRunning ( ) const
inline

Gets whether asynchronous send and receive operations are currently executing.

This function returns true if the GetState function returns STATE_SENDING or STATE_RECEIVING.

Returns
Returns true if asynchronous processing of send and receive operations is in progress.
See also
GetState
bool nn::pia::transport::ReliableBroadcastProtocol::IsSendTarget ( nn::pia::StationId  stationId) const

Gets information about whether the specified station is to receive data currently being sent.

Normally, all other stations participating in the session receive data. If Configuration::IsSendToNewcomer is false, stations that joined the session after the start of the transmissions are excluded as recipients. If Configuration::IsFailIfRejected is false, stations that rejected the transmission or for which reception failed are excluded as recipients.

Parameters
[in]stationIdSpecifies the StationId of the station that you are checking to determine whether it is a receiving station.
Returns
Returns true if the specified station is a receiving station, and false otherwise. Returns false if the local station is currently sending data and the operation has not completed.
nn::Result nn::pia::transport::ReliableBroadcastProtocol::RejectRequest ( )

Rejects receive requests retrieved with the GetRequest function.

The send operation itself is suspended when the transfer protocol is configured such that the Configuration::IsFailIfRejected function returns true. Calling this function on a receive request currently being received is equivalent to calling the Cancel 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 the GetRequest function has returned NULL. Programming error. Fix your program so that this error is not returned.
See also
GetRequest
nn::Result nn::pia::transport::ReliableBroadcastProtocol::RejectRequest ( nn::pia::StationId  stationId)

Rejects receive requests retrieved with the GetRequest ( nn::pia::StationId ) function.

The send operation itself is suspended when the transfer protocol is configured such that the Configuration::IsFailIfRejected function returns true. Calling this function on a receive request currently being received is equivalent to calling the Cancel function.

Parameters
[in]stationIdSpecifies the StationId of the station you want to reject a receive request from.
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 the GetRequest ( nn::pia::StationId ) function has returned NULL. Programming error. Fix your program so that this error is not returned.
See also
GetRequest
nn::Result nn::pia::transport::ReliableBroadcastProtocol::Reset ( )

Discards information about the result of sending and receiving data and returns to the STATE_WAIT state.

This function fails if data is currently being sent or received. To call the function at such times, first call the Cancel function to suspend the send or receive operation, and then call this function. Rather than always using this function, you can also start sending and receiving data directly from the following states: STATE_SEND_SUCCESS, STATE_SEND_FAILURE, STATE_RECEIVE_SUCCESS, and STATE_RECEIVE_FAILURE

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 the station has not joined in the session or is currently sending or receiving data. Programming error. Fix your program so that this error is not returned.
void nn::pia::transport::ReliableBroadcastProtocol::SetThroughputLimit ( u32  throughputLimit)
inline

Sets the maximum amount of data that this protocol sends per call to the common::Scheduler::Dispatch function.

The average amount of data sent by this protocol per call to the common::Scheduler::Dispatch function is kept under the value specified to this function. Data may still momentarily be sent at rates greater than specified.

To temporarily stop sending data, a sender must specify 0 in this function. Setting a value of 0 completely stops this protocol from sending data. Change the setting to a positive value if you want to start sending data again. If you try to cancel data transfer by calling the Cancel function while sending is paused, the cancellation does not complete and notification of the cancellation is not sent while 0 is specified for this value. Conversely, the data transfer does not proceed if a receiving station sets this value to 0, because the receiving station also sends small amounts of data (such as acknowledgement packets).

Use the default value for the best performance. The default is six packets worth of data. This value is not constant because the size of a single packet can vary depending on the MTU and other settings.

Set this value after communication starts, because the default value is reset when communication starts.

Parameters
[in]throughputLimitSpecifies the amount of send data to configure (in bytes).
See also
GetThroughputLimit
nn::Result nn::pia::transport::ReliableBroadcastProtocol::StartReceive ( void *  pBuffer,
size_t  bufferSize,
StationId  sourceStationId 
)

Starts receiving data.

To start receiving data on the local station in response to a GetRequest call, call this function with arguments specified in accordance with the settings for receiving data. If you know in advance what to expect (because of the application's sequence, for example), you can call this function before the receive request comes so that you waste less time receiving the data than if you were to wait for the receive request to arrive. If this function call succeeds, the local station enters STATE_RECEIVING state. If the call fails with a return value of ResultInvalidArgument, the Reset function is called.

Data cannot be received across joint session processes.

Parameters
[out]pBufferSpecifies the buffer that receives the data. Data cannot be accessed while the local station's state is STATE_RECEIVING (while IsRunning returns true). Data is not guaranteed to be in order. You may not be able to access the first number of bytes given by GetProgress.
[in]bufferSizeSpecifies the size of the receive buffer. If the size of the requested data is larger than this value, this function succeeds, but the station enters STATE_RECEIVE_FAILURE state.
[in]sourceStationIdSpecifies the station the data is being received from.
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 the station has not joined the session or that another send/receive operation is in progress. 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.

ResultTemporaryUnavailable The API function is temporarily unavailable because the joint session process is in progress. Handle appropriately in the application.

See also
GetRequest
nn::Result nn::pia::transport::ReliableBroadcastProtocol::StartSend ( const void *  cpData,
size_t  dataSize,
Configuration  configuration,
u32  userData = 0 
)

Starts sending data.

If this function call succeeds, the state of the station changes to STATE_SENDING. If the call fails with a return value of ResultInvalidArgument, the Reset function is called.

Data cannot be sent across joint session processes.

Parameters
[in]cpDataSpecifies a pointer to the data being sent. You must maintain the specified buffer while the state is STATE_SENDING (while IsRunning returns true). There is no guarantee that data will be sent in order. You cannot just rewrite the first GetProgress() bytes of data in the buffer.
[in]dataSizeSpecifies the size of the data to send.
[in]configurationSpecifies operations during data transfer.
[in]userDataSpecifies additional information included in the data to send. Applications running on the receiving station can view this information before receiving the data, and use it for purposes such as identifying the data.
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 the station has not joined the session or that another send/receive operation is in progress. 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.

ResultTemporaryUnavailable The API function is temporarily unavailable because the joint session process is in progress. Handle appropriately in the application.

virtual void nn::pia::transport::ReliableBroadcastProtocol::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.