CTR Pia
4.11.3
Game Communication Engine
|
This protocol sends transmissions that are guaranteed to arrive. More...
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... | |
This protocol sends transmissions that are guaranteed to arrive.
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.
void nn::pia::transport::ReliableProtocol::Finalize | ( | ) |
Finalizes.
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
)
[in] | sendBufferSize | Specifies 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] | receiveBufferSize | Specifies 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. |
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.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.
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.
[in] | stationId | Returns the StationId of the peer. |
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.
[out] | pSourceStationId | Specifies a pointer to a buffer containing the StationId of the sender of the data that was received. |
[out] | pBuffer | Specifies a pointer to a buffer for holding the received data. |
[out] | pDataSize | Specifies a pointer to a buffer for holding the size of the received data. |
[in] | bufferSize | Specifies the size of the buffer (in bytes) for holding the received data. |
Result
value for which the IsSuccess()
function returns true
if execution succeeds.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.
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.
[in] | destinationStationId | Specifies the StationId of the recipient. Specify STATION_ID_ALL to send to all currently connected peers. |
[in] | pData | Specifies the address of the data to send. |
[in] | dataSize | Specifies the length, in bytes, of the data to send. |
Result
value for which the IsSuccess()
function returns true
if execution succeeds.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.
|
virtual |
Prints information that is useful for debugging.
[in] | flag | Specifies the bitwise OR of trace flags. For more information, see the TraceFlag reference. |
Reimplemented from nn::pia::transport::Protocol.