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

Represents the unreliable protocol class, with which data may be lost. UnreliableProtocol does not guarantee that data arrives in the order it was sent. It may not be possible to receive data with the Receive function in the same order it was sent with the Send function.
. More...

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

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...
 
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

Represents the unreliable protocol class, with which data may be lost. UnreliableProtocol does not guarantee that data arrives in the order it was sent. It may not be possible to receive data with the Receive function in the same order it was sent with the Send function.
.

Revision History:

2014-09-10 Corrected incorrect information about when the GetDataSizeLimit function can be called.

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

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 the Send/Receive function is called while state transitions between sessions or joint sessions are in progress.

2014-03-10 Added information about when the GetDataSizeLimit function can be called.

2014-03-10 Fixed errors in the description of the MAX_DATA_SIZE value. The correct value is 1430.

2013-07-05 Modified the Initialize function. Initialize now succeeds when called between calls to BeginSetup and EndSetup of another module.

2013-05-14 Fixed the documentation of the Finalize function.

2013-04-12 Changed the specifications of Send and SendToAll so that a ResultBufferIsFull object is never returned.

2013-04-05 Made GetDataSizeLimit into a non-static member function.

2013-04-01 Changed the specifications of the Receive function. Reordered the dummy parameters.

2013-04-01 Changed the specifications of the Initialize function. If the Initialize function is called when the object has already been initialized with a call to Initialize, the function now returns ResultAlreadyInitialized.

2013-04-01 Changed the specifications of the Initialize function. You can now specify the number of receive buffers in the function arguments.

2013-03-19 Made major changes to the internal implementation of the UnreliableProtocol class, due to changes to the transport implementation.

2013-02-04 Fixed a bug where data received in the old session would remain in the buffer after the session ended, and could be retrieved in a new session.

2012-07-17 Changed the Send, SendToAll, and Receive functions. Made it so that ResultNotInCommunication is returned when communication is not possible.

2012-07-17 Added the IsInCommunication function.

2012-07-04 Added a description of detailed operations of the Receive, Send and SendToAll functions.

2012-06-28 Clearly indicated which functions are thread-safe.

2012-05-31 Changed the functionality of the Receive function. When the size of the read buffer is insufficient, ResultBufferShortage is now returned.

2012-05-30 Changed the functionality of the Send and SendToAll functions. You can no longer send data in excess of the value of the GetDataSizeLimit function.

2012-05-30 Added the GetDataSizeLimit function. This function gets the maximum transmission unit.

2012-04-28 It was mistakenly indicated that the Initialize function would return ResultInvalidArgument. This statement was deleted.

2012-04-28 Specifications changed so that the Send and SendToAll functions return ResultInvalidState when UnreliableProtocol is not initialized.

2012-04-28 Fixed a bug where ResultInvalidState was left out of the list of return values for the Receive function.

2012-04-06 Initial version.

Member Function Documentation

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

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  )

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)

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

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 
)

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 
)

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 
)

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

Reimplemented in nn::pia::transport::RoundRobinUnreliableProtocol.

Member Data Documentation

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

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.