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

This class inherits the UnreliableProtocol class, and adds features to send data while distributing the load.
. More...

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

Public Member Functions

void Finalize (void)
 Finalizes the instance. More...
 
size_t GetDataSizeLimit (void)
 Gets the maximum size of data that can be sent in one transmission. This value is in bytes. More...
 
nn::Result Initialize (size_t recvBufNum=32)
 Initializes the instance. More...
 
bool IsInCommunication (void) const
 Determines whether communication is possible. More...
 
nn::Result Receive (StationId *pSrcId, bit8 *pRecvBuf, size_t *pRecvDataSize, size_t recvBuffSize)
 Loads received data into a buffer. More...
 
nn::Result Send (StationId destId, const bit8 *pData, size_t dataSize)
 Sends data to a specific station. More...
 
nn::Result SendToAll (const bit8 *pData, size_t dataSize)
 Sends data to all stations. More...
 
nn::Result SendToRoundRobin (const bit8 *pData, size_t dataSize, u32 stationNum)
 Sends data to multiple stations. More...
 
virtual void Trace (u64 flag) const
 Prints information that is useful for debugging. More...
 

Static Public Attributes

static const size_t MAX_DATA_SIZE = common::PROTOCOL_MESSGAE_PAYLOAD_SIZE_MAX
 Defines the maximum data size that can be sent and received at one time using UnreliableProtocol. This value is in bytes. More...
 

Detailed Description

This class inherits the UnreliableProtocol class, and adds features to send data while distributing the load.
.

Revision History:
2013-03-19 Initial version.

Member Function Documentation

void nn::pia::transport::UnreliableProtocol::Finalize ( void  )
inherited

Finalizes the instance.

This function returns without doing anything if it is called before the Initialize function has been called.

See also
Initialize
size_t nn::pia::transport::UnreliableProtocol::GetDataSizeLimit ( void  )
inherited

Gets the maximum size of data that can be sent in one transmission. This value is in bytes.

The value returned by this function is affected by the MTU value set by the application and by whether packets are signed. This function is thread-safe.

If your application uses mesh networks, call this function after the mesh startup process completes. The correct value is not returned if the function is called sooner.

If your application uses sessions, call this function after joining a session. The correct value is not returned if this function is called sooner.

Returns
Returns the maximum amount of data that can be sent at one time per call to the Send or SendToAll functions. This value is in bytes.
See also
Send, SendToAll
nn::Result nn::pia::transport::UnreliableProtocol::Initialize ( size_t  recvBufNum = 32)
inherited

Initializes the instance.

Call between the BeginSetup and EndSetup functions.

Parameters
[in]recvBufNumSpecifies the number of receive buffers. Each receive buffer uses about 1,500 bytes of memory.
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:

ResultNotInitialized Indicates that the transport module is not initialized. Programming error. Fix your program so that this error is not returned.

ResultAllocationFailed Indicates that the function failed to allocate memory. Consider providing more memory when calling the common::Initialize function. Programming error. Fix your program so that this error is not returned.

ResultAlreadyInitialized Indicates that the UnreliableProtocol instance is already initialized. Programming error. Fix your program so that this error is not returned.

ResultInvalidArgument Indicates that an argument is invalid. One cause of this error is when recvBufNum is set to zero. Programming error. Fix your program so that this error is not returned.

ResultInvalidState Indicates that the function was not called between the BeginSetup and EndSetup functions. Programming error. Fix your program so that this error is not returned.

See also
Finalize
bool nn::pia::transport::UnreliableProtocol::IsInCommunication ( void  ) const
inherited

Determines whether communication is possible.

Returns
Returns true if communication is possible; returns false otherwise.
nn::Result nn::pia::transport::UnreliableProtocol::Receive ( StationId pSrcId,
bit8 *  pRecvBuf,
size_t *  pRecvDataSize,
size_t  recvBuffSize 
)
inherited

Loads received data into a buffer.

Receives data. However, calling this function does not trigger a receive operation in the wireless module. A receiving thread in the Pia library periodically receives packets from the wireless module. The packets received by the receiving thread are then copied to a packet analysis process buffer that restores the data when the PiaTransport dispatch runs. This function copies that copy of the data restored in this way into a buffer provided by the application.

Parameters
[out]pSrcIdSpecifies a pointer to the StationId of the station the data was received from.
[out]pRecvBufSpecifies a pointer to the buffer that data is read into.
[out]pRecvDataSizeSpecifies a pointer to the size of data actually read. This value is in bytes.
[in]recvBuffSizeSpecifies the size of the buffer that receives the data. This value is in bytes.
Returns
Returns a Result value for which the IsSuccess function returns true if execution succeeds.
Error Return Values:

ResultInvalidArgument Indicates that one or more arguments are invalid. Programming error. Fix your program so that this error is not returned.

ResultInvalidState Indicates that the UnreliableProtocol::Initialize function may not have been called, or that the session setup might not have been completed. Programming error. Fix your program so that this error is not returned.

ResultBufferShortage Indicates that the receiving buffer is too small. Returned when the amount of incoming data is larger than the size specified by the recvBuffSize parameter. Programming error. Fix your program so that this error is not returned.

ResultNoData Indicates that the receiving buffer is empty and no data could be read. Handle appropriately in the application.

ResultNotInCommunication Indicates that communication is not possible. 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.

See also
Send, SendToAll, MAX_DATA_SIZE
nn::Result nn::pia::transport::UnreliableProtocol::Send ( StationId  destId,
const bit8 *  pData,
size_t  dataSize 
)
inherited

Sends data to a specific station.

Sends data. However, calling this function alone does not actually cause the data to be sent. This function copies the data passed in by the application into a buffer that the Pia library uses to generate packets. The data copied into the packet generation buffer is packaged into packets, and passed to the Pia internal transmit thread by running the Pia dispatch process afterwards. The actual send process periodically passes packets from the send thread to the wireless module.

Parameters
[in]destIdSpecifies the StationId of the recipient.
[in]pDataSpecifies a pointer to the start of the data to send.
[in]dataSizeSpecifies the size of the data to send. This value is in bytes. This size must not be greater than the value returned by the GetDataSizeLimit function.
Returns
Returns a Result value for which the IsSuccess function returns true if execution succeeds.
Error Return Values:

ResultInvalidArgument Indicates that one or more arguments are invalid. This error is also returned when the size of the data to send is too large. Programming error. Fix your program so that this error is not returned.

ResultInvalidState Indicates that the UnreliableProtocol::Initialize function may not have been called, or that the session setup might not have been completed. Programming error. Fix your program so that this error is not returned.

ResultNotInCommunication Indicates that communication is not possible. 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.

See also
SendToAll, Receive, MAX_DATA_SIZE, GetDataSizeLimit, IsInCommunication
nn::Result nn::pia::transport::UnreliableProtocol::SendToAll ( const bit8 *  pData,
size_t  dataSize 
)
inherited

Sends data to all stations.

Sends data. However, calling this function alone does not actually cause the data to be sent. This function copies the data passed in by the application into a buffer that the Pia library uses to generate packets. The data copied into the packet generation buffer is packaged into packets, and passed to the Pia internal transmit thread by running the Pia dispatch process afterwards. The actual send process periodically passes packets from the send thread to the wireless module.

Parameters
[in]pDataSpecifies a pointer to the start of the data to send.
[in]dataSizeSpecifies the size of the data to send. This value is in bytes. This size must not be greater than the value returned by the GetDataSizeLimit function.
Returns
Returns a Result value for which the IsSuccess function returns true if execution succeeds.
Error Return Values:

ResultInvalidArgument Indicates that one or more arguments are invalid. This error is also returned when the size of the data to send is too large. Programming error. Fix your program so that this error is not returned.

ResultInvalidState Indicates that the UnreliableProtocol::Initialize function may not have been called. Programming error. Fix your program so that this error is not returned.

ResultNotInCommunication Indicates that communication is not possible. 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.

See also
Send, Receive, MAX_DATA_SIZE, GetDataSizeLimit, IsInCommunication
nn::Result nn::pia::transport::RoundRobinUnreliableProtocol::SendToRoundRobin ( const bit8 *  pData,
size_t  dataSize,
u32  stationNum 
)

Sends data to multiple stations.

Sends data to the stationNum stations specified. Sends to stations in order of StationIndex, from lowest to highest, starting with the next largest StationIndex after that of the local station. The next time the call is made, the starting point is the last StationIndex that the station sent data to. For example, consider a session in which stations A, B, C, D, E, and F are participating. The local station is F. If SendToRoundRobin is called with a recipient count of 2, data is sent as follows. First call: SendToRoundRobin(Data1) — Data1 is sent to A and B. Second call: SendToRoundRobin(Data2) — Data2 is sent to C and D. Third call: SendToRoundRobin(Data3) — Data3 is sent to E and A. Fourth call: SendToRoundRobin(Data4) — Data4 is sent to B and C. Fifth call: SendToRoundRobin(Data5) — Data5 is sent to D and E.

Calling this function alone does not cause the data to actually be sent. This function copies the data passed in by the application into the Pia library's packet buffer. The Pia library's send thread periodically sends the packets.

Parameters
[in]pDataSpecifies a pointer to the start of the data to send.
[in]dataSizeSpecifies the size of the data to send. The value is in bytes. This size must not be greater than the value returned by the GetDataSizeLimit function.
[in]stationNumSpecifies the number of stations you want to send data to.
Returns
Returns a Result value for which the IsSuccess function returns true if execution succeeds.
Error Return Values:

ResultInvalidArgument Specifies that one or more arguments are invalid. This error is also returned when the size of the data to send is too large. Programming error. Fix your program so that this error is not returned.

ResultInvalidState Indicates that the Initialize function may not have been called. Programming error. Fix your program so that this error is not returned.

ResultNotInCommunication Indicates that communication is not possible. Handle appropriately in the application.

See also
Send, Receive, MAX_DATA_SIZE, GetDataSizeLimit, IsInCommunication
virtual void nn::pia::transport::RoundRobinUnreliableProtocol::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::UnreliableProtocol.

Member Data Documentation

const size_t nn::pia::transport::UnreliableProtocol::MAX_DATA_SIZE = common::PROTOCOL_MESSGAE_PAYLOAD_SIZE_MAX
staticinherited

Defines the maximum data size that can be sent and received at one time using UnreliableProtocol. This value is in bytes.

The value of this constant is 1430, but if the application sets a smaller MTU value, the amount of data that can actually be sent or received is smaller than this value.