CTR Pia
4.11.3
Game Communication Engine
|
Represents a protocol for sending a large volume of data to all stations. More...
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 TransferSetting * | GetCurrentTransferSetting () const |
Gets the current data transfer settings. More... | |
size_t | GetProgress () const |
Gets the progress status of the send/receive operation. More... | |
const TransferSetting * | GetRequest () const |
Gets receive requests that have been delivered. More... | |
const TransferSetting * | GetRequest (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... | |
Represents a protocol for sending a large volume of data to all stations.
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.
Enumerates the operational states.
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
.
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 data is not currently being sent/received. Programming error. Fix your program so that this error is not returned.void nn::pia::transport::ReliableBroadcastProtocol::Finalize | ( | ) |
Finalizes the class instance.
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.
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
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.const TransferSetting* nn::pia::transport::ReliableBroadcastProtocol::GetCurrentTransferSetting | ( | ) | const |
Gets the current data transfer settings.
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.
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).
NULL
if a receive request has not been delivered.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.
[in] | stationId | Specifies the StationId of the station you want to get a receive request from. |
NULL
if a receive request has not been delivered.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.
[in] | stationId | Specifies the StationId of the station receiving the data. |
0
is returned if there is no send operation in progress or completed, or if an invalid StationId
was specified.
|
inline |
Gets the current operational state.
|
inline |
Gets the maximum amount of data that this protocol can send per call to the common::Scheduler::Dispatch
function.
common::Scheduler::Dispatch
function.nn::Result nn::pia::transport::ReliableBroadcastProtocol::Initialize | ( | ) |
Initializes the instance. Make this call between the BeginSetup
and EndSetup
functions.
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.
|
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
.
true
if asynchronous processing of send and receive operations is in progress. 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.
[in] | stationId | Specifies the StationId of the station that you are checking to determine whether it is a receiving station. |
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.
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 the GetRequest
function has returned NULL
. Programming error. Fix your program so that this error is not returned.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.
[in] | stationId | Specifies the StationId of the station you want to reject a receive request from. |
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 the GetRequest ( nn::pia::StationId )
function has returned NULL
. Programming error. Fix your program so that this error is not returned.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
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 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.
|
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.
[in] | throughputLimit | Specifies the amount of send data to configure (in bytes). |
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.
[out] | pBuffer | Specifies 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] | bufferSize | Specifies 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] | sourceStationId | Specifies the station the data is being received from. |
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 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.
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.
[in] | cpData | Specifies 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] | dataSize | Specifies the size of the data to send. |
[in] | configuration | Specifies operations during data transfer. |
[in] | userData | Specifies 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. |
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 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 |
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.