CTR Pia
4.11.3
Game Communication Engine
|
Represents a station. A station refers to a machine participating in a Pia session. More...
Classes | |
struct | IdentificationToken |
Stores the ID token associated with a Station . More... | |
struct | PlayerName |
Stores the player name struct associated with a Station . More... | |
Public Types |
Public Member Functions | |
nn::Result | GetIdentificationToken (IdentificationToken *pToken) |
Gets the ID token of the station. More... | |
nn::Result | GetPlayerName (PlayerName *pName) |
Gets the name of the station. More... | |
nn::Result | GetPrincipalId (u32 *pPrincipalId) |
Gets the principal ID of the station. More... | |
s32 | GetRtt (void) const |
Gets the round-trip time (RTT) between the local Station and this Station . More... | |
s32 | GetRtt (size_t samplingNum) const |
Gets the round-trip time (RTT) between the local Station and this Station . You can specify the number of samples to use for calculating RTT. More... | |
size_t | GetRttSamplingNum (void) const |
Gets the number of RTT (Round Trip Time) samples held by the system. More... | |
SequenceIdController * | GetSequenceIdController (void) |
Gets a pointer to the SequenceIdController instance (non-const version). This function is thread-safe. More... | |
const SequenceIdController * | GetSequenceIdController (void) const |
Gets a pointer to the SequenceIdController instance (const version). This function is thread-safe. More... | |
StationState | GetState (void) const |
Gets the state of the Station instance. More... | |
const common::StationAddress & | GetStationAddress (void) const |
Gets the station address. More... | |
StationId | GetStationId (void) const |
Gets the StationId . More... | |
StationIndex | GetStationIndex (void) const |
Gets the StationIndex . More... | |
virtual void | Trace (u64 flag) const |
Prints information that is useful for debugging. More... | |
Static Public Member Functions | |
static s32 | GetInitialRttPulseInterval (void) |
Gets the interval for sending initial pulses for RTT calculation. More... | |
static s32 | GetRttPulseInterval (void) |
Gets the interval for sending pulses for RTT calculation. More... | |
static nn::Result | SetInitialRttPulseInterval (s32 msec) |
Sets the interval for sending the initial pulse for RTT calculation. More... | |
static nn::Result | SetRttPulseInterval (s32 msec) |
Sets the interval for sending pulses for RTT calculation. More... | |
Static Public Attributes | |
static const size_t | IDENTIFICATION_TOKEN_MAX_DATA_SIZE = 32 |
Specifies the maximum data size for an identification token. | |
static const s32 | INVALID_RTT = -1 |
An invalid value that the GetRtt function can return. | |
static const size_t | PLAYER_NAME_MAX_DATA_SIZE = 17 |
Specifies the maximum data size for a player name. The final character is for the terminating null character. | |
Represents a station. A station refers to a machine participating in a Pia session.
2015-02-19 Made the GetStationIndex
function public.
2013-10-16 Added GetRttSamplingNum
to get the number of samples to use for calculating RTT.
2013-08-08 Added SetInitialRttPulseInterval
and GetInitialRttPulseInterval
.
2013-05-01 Added the GetIdentificationToken
, GetPlayerName
, and GetPrincipalId
functions.
2013-03-28 Added definitions for Station::IdentificationInfo
and Station::PlayerName
.
2013-01-22 Added the GetRtt
function that allows users to specify the number of samples to use when calculating RTT.
2013-01-17 Added the SetRttPulseInterval
and GetRttPulseInterval
member functions for setting and getting the pulse interval used when calculating RTT.
2012-06-28 Clearly indicated which functions are thread-safe.
2012-06-21 Made functions and constants, the use of which were not necessary for applications, private.
2012-06-14 Added Station::GetRtt
function and Station::INVALID_RTT
definition.
2012-05-30 Made the send and receive functions private.
2012-05-01 Added a definition for Station::IdentificationToken
.
2012-04-28 Fixed an error in the notation of the return values for the Station::Startup
function.
2012-04-06 Initial version.
Enumerates Station
states.
nn::Result nn::pia::transport::Station::GetIdentificationToken | ( | IdentificationToken * | pToken | ) |
Gets the ID token of the station.
If called by the local station, this function gets the ID token set in the session::Session::Startup
function. If called by a station other than the station, this function gets the ID token shared at time of connection. If no token has been configured, this function succeeds but the obtained ID token data is filled with NULL
values.
The values of the ID token specified as an out parameter never change if the function fails to acquire an ID token.
[out] | pToken | Specifies the ID token of the Station if it was successfully retrieved. |
Result
value for which the IsSuccess
function returns true
if the ID token is successfully retrieved. If this function call fails, one or more of the following Result
values is returned. ResultInvalidState
Specifies that the function cannot be executed in this state. Programming error. Fix your program so that this error is not returned.
ResultInvalidArgument
Specifies that an invalid pointer was specified as an argument. Programming error. Fix your program so that this error is not returned.
ResultNoData
Specifies that the function was not able to obtain the ID token of the specified station. The sharing of the ID token might not have been completed. Handle appropriately in the application.
|
static |
Gets the interval for sending initial pulses for RTT calculation.
The pulse for calculating the RTT is sent starting when the station joins a session. There are not enough samples available to calculate the RTT immediately after a station joins a session. The system sends pulses at a shorter interval than usual until enough samples are available to quickly get the number of samples required. This member function gets the interval at which pulses are set during this initial period.
nn::Result nn::pia::transport::Station::GetPlayerName | ( | PlayerName * | pName | ) |
Gets the name of the station.
For a local station, gets the name set in the session::Session::Startup
function. For a non-local station, gets the name shared on connection.
The value of the name specified as an out parameter never changes if the function fails to acquire a name.
[out] | pName | Specifies the name of the Station if successfully retrieved. |
Result
value for which the IsSuccess
function returns true
if the name is successfully retrieved. If this function call fails, one or more of the following Result
values is returned. ResultInvalidState
Specifies that the function cannot be executed in this state. Programming error. Fix your program so that this error is not returned.
ResultInvalidArgument
Specifies that an invalid pointer was specified as an argument. Programming error. Fix your program so that this error is not returned.
ResultNoData
Specifies that the function was not able to get the name of the specified station. The sharing of the name might not have been completed. Handle appropriately in the application.
nn::Result nn::pia::transport::Station::GetPrincipalId | ( | u32 * | pPrincipalId | ) |
Gets the principal ID of the station.
For a local station, gets the principal ID specified in the nn::nex::Credentials
function. You can get this value after the inet::NexFacade::StartNatSessionAsync
asynchronous process completes.
For a non-local station, gets the principal ID shared on connection.
The value of the principal ID specified as an out parameter never changes if the function fails to acquire the principal ID.
[out] | pPrincipalId | Specifies the principal ID of the Station if successfully retrieved. |
Result
value for which the IsSuccess
function returns true
if the name is successfully retrieved. If this function call fails, one or more of the following Result
values is returned. ResultInvalidState
Specifies that the function cannot be executed in this state. Programming error. Fix your program so that this error is not returned.
ResultInvalidArgument
Specifies that an invalid pointer was specified as an argument. Programming error. Fix your program so that this error is not returned.
ResultNoData
Specifies that the function was not able to obtain the principal ID of the specified station. The sharing of the ID token might not have been completed. Handle appropriately in the application.
s32 nn::pia::transport::Station::GetRtt | ( | void | ) | const |
Gets the round-trip time (RTT) between the local Station
and this Station
.
The system sends pulses to other stations periodically to get the round-trip time (RTT). At particular times, however, the system may have never sent pulses to or received responses from other stations. One example is when it has just connected to the session. At these times, the GetRtt
function returns INVALID_RTT
, but if you call the GetRtt
function after a short time has passed, the correct value is returned. This function returns the median value of multiple samples. The value obtained from this function is relatively stable and not easily affected by minor changes in network environment.
INVALID_RTT
Specifies a negative value that indicates that the RTT value cannot be obtained in this state. s32 nn::pia::transport::Station::GetRtt | ( | size_t | samplingNum | ) | const |
Gets the round-trip time (RTT) between the local Station
and this Station
. You can specify the number of samples to use for calculating RTT.
The system stores several samples obtained from RTT pulse transmissions and responses. The version of the GetRtt
function that does not take arguments returns the median value for all stored sample values. The version that takes an argument returns the median value for the specified number of samples. When specified, the latest samples are used. If you specify a small value, the RTT value strongly reflects the most recent network connection status. However, if the value of the argument is too small, the RTT value is susceptible to fluctuation.
[in] | samplingNum | Specifies the number of most recent samples to use in calculating the RTT. |
INVALID_RTT
Specifies a negative value that indicates that the RTT value cannot be obtained in this state.
|
static |
Gets the interval for sending pulses for RTT calculation.
size_t nn::pia::transport::Station::GetRttSamplingNum | ( | void | ) | const |
Gets the number of RTT (Round Trip Time) samples held by the system.
The system sends pulses to other stations periodically to get the round-trip time (RTT), and the time required for the response is saved as an RTT sample. At particular times, however, the system cannot obtain a sufficient number of samples because it has just begun sending pulses and receiving responses. One example is when it has just connected to the session. This function returns the number of samples that are used by functions such as GetRtt
to calculate the RTT value. It gives an idea of the reliability and precision of the RTT value.
0
A value of 0
specifies a state in which the RTT value could not be obtained.
|
inline |
Gets a pointer to the SequenceIdController
instance (non-const
version). This function is thread-safe.
SequenceIdController
instance.
|
inline |
Gets a pointer to the SequenceIdController
instance (const
version). This function is thread-safe.
const
pointer to the SequenceIdController
instance.
|
inline |
|
inline |
Gets the station address.
StationAddress
that is set.
|
inline |
|
inline |
Gets the StationIndex
.
This function is thread-safe.
Don't call this function when the application is using the joint session feature. This results in undefined operations.
StationIndex
set in the instance.
|
static |
Sets the interval for sending the initial pulse for RTT calculation.
The pulse for calculating the RTT is sent starting when the station joins a session. There are not enough samples available to calculate the RTT immediately after a station joins a session. The system sends pulses at a shorter interval than usual until enough samples are available to quickly get the number of samples required. This member function sets the interval at which pulses are set during this initial period.
[in] | msec | Specifies the interval at which to send pulses initially. The value is in milliseconds. |
Result
value for which the IsSuccess
function returns true
if execution succeeds. ResultInvalidArgument
Specifies that one or more arguments are invalid. Returned if a non-positive integer is specified. Programming error. Fix your program so that this error is not returned.
|
static |
Sets the interval for sending pulses for RTT calculation.
[in] | msec | Specifies the interval at which to send pulses. The value is in milliseconds. |
Result
value for which the IsSuccess
function returns true
if execution succeeds. ResultInvalidArgument
Specifies that one or more arguments are invalid. Returned if a non-positive integer is specified. Programming error. Fix your program so that this error is not returned.
|
virtual |
Prints information that is useful for debugging.
[in] | flag | Specifies the bitwise OR of trace flags. For more information, see the TraceFlag type. |