CTR Pia
4.11.3
Game Communication Engine
|
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...
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... | |
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.
.
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.
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.
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.
Send
or SendToAll
functions. This value is in bytes.nn::Result nn::pia::transport::UnreliableProtocol::Initialize | ( | size_t | recvBufNum = 32 | ) |
Initializes the instance.
Call between the BeginSetup
and EndSetup
functions.
[in] | recvBufNum | Specifies the number of receive buffers. Each receive buffer uses about 1,500 bytes of memory. |
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. 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.
bool nn::pia::transport::UnreliableProtocol::IsInCommunication | ( | void | ) | const |
Determines whether communication is possible.
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.
[out] | pSrcId | Specifies a pointer to the StationId of the station the data was received from. |
[out] | pRecvBuf | Specifies a pointer to the buffer that data is read into. |
[out] | pRecvDataSize | Specifies a pointer to the size of data actually read. This value is in bytes. |
[in] | recvBuffSize | Specifies the size of the buffer that receives the data. This value is in bytes. |
Result
value for which the IsSuccess
function returns true
if execution succeeds. 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.
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.
[in] | destId | Specifies the StationId of the recipient. |
[in] | pData | Specifies a pointer to the start of the data to send. |
[in] | dataSize | Specifies 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. |
Result
value for which the IsSuccess
function returns true
if execution succeeds. 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.
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.
[in] | pData | Specifies a pointer to the start of the data to send. |
[in] | dataSize | Specifies 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. |
Result
value for which the IsSuccess
function returns true
if execution succeeds. 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.
|
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.
Reimplemented in nn::pia::transport::RoundRobinUnreliableProtocol.
|
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.