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

This protocol sends transmissions that are guaranteed to arrive. More...

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

Public Member Functions

void Finalize ()
 Finalizes. More...
 
nn::Result Initialize (u32 sendBufferSize, u32 receiveBufferSize)
 Initializes the instance. Call between the BeginSetup() and EndSetup() functions. More...
 
bool IsInCommunication (StationId stationId) const
 Gets whether the specified node is communicating. More...
 
nn::Result Receive (StationId *pSourceStationId, void *pBuffer, size_t *pDataSize, size_t bufferSize)
 Receives data. More...
 
nn::Result Send (StationId destinationStationId, const void *pData, size_t dataSize)
 Sends data. More...
 
virtual void Trace (u64 flag) const
 Prints information that is useful for debugging. More...
 

Detailed Description

This protocol sends transmissions that are guaranteed to arrive.


Revision History:

2014-07-17 Changed the specifications so that ResultNotFound is returned when the destination StationId specified in the Send() function is not found.

2014-07-16 Changed the specifications so that ResultTemporaryUnavailable is returned when Send() is called while state transitions between sessions or joint sessions are in progress.

2014-03-24 Added a formula to the Initialize() API Reference for determining the approximate amount of memory it consumes.

2012-12-14 Improved the method of tuning the resend interval.

2012-10-29 It now automatically tunes the resend interval.

2012-07-17 Added ResultNotInCommunication to the return values of the Send() and Receive() functions.

2012-07-09 You are no longer required to set the maximum number of connections in the Initialize() function.

2012-07-05 Added descriptions of the send and receive operations and buffer usage.

2012-04-24 You can now send to all members by specifying the recipient as STATION_INDEX_ALL in the Send() function.

2012-04-06 Initial version.

Member Function Documentation

void nn::pia::transport::ReliableProtocol::Finalize ( )

Finalizes.

See also
Initialize
nn::Result nn::pia::transport::ReliableProtocol::Initialize ( u32  sendBufferSize,
u32  receiveBufferSize 
)

Initializes the instance. Call between the BeginSetup() and EndSetup() functions.

You can measure the actual number of send/receive buffers used by specifying common::WatermarkManager::KEY_RELIABLE_PROTOCOL_SEND_BUFFER_NUM or common::WatermarkManager::KEY_RELIABLE_PROTOCOL_RECEIVE_BUFFER_NUM in common::WatermarkManager.

Use the following formula to calculate the approximate amount of memory consumed by ReliableProtocol. (sendBufferSize * 1500 + receiveBufferSize * 1500) * (Transport::Setting::maxStationNum - 1)

Parameters
[in]sendBufferSizeSpecifies the size of the send buffer. Specify a value of 1 or greater. Send buffers are used to hold data sent using the Send() function until the sender can confirm that it has arrived to the recipient.
[in]receiveBufferSizeSpecifies the size of the receive buffer. Specify a value of 1 or greater. Receive buffers are used to hold received data until the Receive() function is called.
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:

ResultInvalidArgument Indicates that an argument is invalid. Programming error. Fix your program so that this error is not returned.

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::ReliableProtocol::IsInCommunication ( StationId  stationId) const

Gets whether the specified node is communicating.

If the specified peer is in the same session as the local station, true will be returned.

Parameters
[in]stationIdReturns the StationId of the peer.
Returns
Returns true if the node is communicating.
nn::Result nn::pia::transport::ReliableProtocol::Receive ( StationId pSourceStationId,
void *  pBuffer,
size_t *  pDataSize,
size_t  bufferSize 
)

Receives data.

The library parses received packets when the common::Scheduler::Dispatch() function is called, and accumulates them in buffers. When the library can confirm that all the data chunks created by the Send() function have been received, it joins them together with this function. You can then retrieve the data using this function. The library then frees the storage buffer, and it can be used for the next receive operation.

Parameters
[out]pSourceStationIdSpecifies a pointer to a buffer containing the StationId of the sender of the data that was received.
[out]pBufferSpecifies a pointer to a buffer for holding the received data.
[out]pDataSizeSpecifies a pointer to a buffer for holding the size of the received data.
[in]bufferSizeSpecifies the size of the buffer (in bytes) for holding the received data.
Returns
Returns a Result value for which the IsSuccess() function returns true if execution succeeds.
Error Return Values:

ResultInvalidState Indicates that the instance is not 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.

ResultNotInCommunication Indicates that the station is not actively communicating. The peer is not in the current session. Handle appropriately in the application.

ResultNoData Indicates that no data was received. Handle appropriately in the application.

ResultBrokenData Indicates that the received data is too large to fit in the receive buffer or cannot all be written to the buffer passed into the function. Start over from the session startup step. This result could be returned because of invalid data from the sender, such as cheats, requiring handling at run time. If the sender's behavior is valid, the program must be fixed so that this result is not returned. Handle appropriately in the application.

See also
Send
nn::Result nn::pia::transport::ReliableProtocol::Send ( StationId  destinationStationId,
const void *  pData,
size_t  dataSize 
)

Sends data.

The function divides the send data that is set with this function into packet-sized chunks and stores the chunks in buffers. Next, the common::Scheduler::Dispatch() function creates packets from the data consecutively, and sends them. If the library cannot confirm that a packet has arrived after waiting for a reasonable time, it resends it. The time until a resent is adjusted automatically, based on the round-trip time (RTT). After the library confirms that a packet has arrived, it deletes the data from the buffer. At this point, the buffer can be reused for sending additional data.

Parameters
[in]destinationStationIdSpecifies the StationId of the recipient. Specify STATION_ID_ALL to send to all currently connected peers.
[in]pDataSpecifies the address of the data to send.
[in]dataSizeSpecifies the length, in bytes, of the data to send.
Returns
Returns a Result value for which the IsSuccess() function returns true if execution succeeds.
Error Return Values:

ResultInvalidState ReliableProtocol might not have been initialized, or the session setup might not have been completed. 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.

ResultNotInCommunication Indicates that the local station is not connected to the specified recipient. The specified peer is not in this session. Handle appropriately in the application.

ResultBufferIsFull Indicates that there is not enough space in the send buffer. If this happens frequently, consider increasing the send buffer size specified in the Initialize() function. Handle appropriately in the application.

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

ResultNotFound Indicates that the specified destination was not found. Handle appropriately in the application.

See also
Receive
virtual void nn::pia::transport::ReliableProtocol::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 reference.

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