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

Represents a station. A station refers to a machine participating in a Pia session. More...

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

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...
 
SequenceIdControllerGetSequenceIdController (void)
 Gets a pointer to the SequenceIdController instance (non-const version). This function is thread-safe. More...
 
const SequenceIdControllerGetSequenceIdController (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::StationAddressGetStationAddress (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.
 

Detailed Description

Represents a station. A station refers to a machine participating in a Pia session.


Revision History:

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.

Member Enumeration Documentation

Enumerates Station states.

Enumerator
STATE_INVALID 

Indicates an invalid StationState.

STATE_INITIAL 

Indicates that this station has already been initialized.

STATE_CREATING_SESSION 

Indicates a state in which a request has been made to connect to this station, and that the connection process has started.

STATE_JOINING_SESSION 

Indicates a state in which a request to connect from this station has been received, and that the connection process has started.

STATE_WAITING_CONNECTION 

Indicates a state of waiting for communication with this station to be established.

STATE_PARTICIPATING 

Indicates a state in which communication with this station is possible.

STATE_LEAVING 

Indicates a state in which communication with this station is being disconnected.

STATE_MAX 

This is a sentinel value indicating the maximum value of StationState.

Member Function Documentation

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.

Parameters
[out]pTokenSpecifies the ID token of the Station if it was successfully retrieved.
Returns
Returns a 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.
Error Return Values:

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 s32 nn::pia::transport::Station::GetInitialRttPulseInterval ( void  )
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.

Returns
Returns the specified interval for sending pulses. The value is in milliseconds.
See also
SetInitialRttPulseInterval, GetRtt, SetRttPulseInterval, GetRttPulseInterval, GetRttSamplingNum
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.

Parameters
[out]pNameSpecifies the name of the Station if successfully retrieved.
Returns
Returns a 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.
Error Return Values:

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.

Parameters
[out]pPrincipalIdSpecifies the principal ID of the Station if successfully retrieved.
Returns
Returns a 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.
Error Return Values:

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.

Returns
Returns the RTT value. The value is in milliseconds.
Error Return Values:
INVALID_RTT Specifies a negative value that indicates that the RTT value cannot be obtained in this state.
See also
SetRttPulseInterval, GetRttPulseInterval, SetInitialRttPulseInterval, GetInitialRttPulseInterval, GetRttSamplingNum
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.

Parameters
[in]samplingNumSpecifies the number of most recent samples to use in calculating the RTT.
Returns
Returns the RTT value. The value is in milliseconds.
Error Return Values:
INVALID_RTT Specifies a negative value that indicates that the RTT value cannot be obtained in this state.
See also
SetRttPulseInterval, GetRttPulseInterval, SetInitialRttPulseInterval, GetInitialRttPulseInterval, GetRttSamplingNum
static s32 nn::pia::transport::Station::GetRttPulseInterval ( void  )
static

Gets the interval for sending pulses for RTT calculation.

Returns
Returns the specified interval for sending pulses. The value is in milliseconds.
See also
SetRttPulseInterval, GetRtt, SetInitialRttPulseInterval, GetInitialRttPulseInterval, GetRttSamplingNum
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.

Returns
Returns the number of samples held by the system.
Error Return Values:
0 A value of 0 specifies a state in which the RTT value could not be obtained.
See also
GetRtt, SetRttPulseInterval, GetRttPulseInterval, SetInitialRttPulseInterval, GetInitialRttPulseInterval
SequenceIdController* nn::pia::transport::Station::GetSequenceIdController ( void  )
inline

Gets a pointer to the SequenceIdController instance (non-const version). This function is thread-safe.

Returns
Returns a pointer to the SequenceIdController instance.
const SequenceIdController* nn::pia::transport::Station::GetSequenceIdController ( void  ) const
inline

Gets a pointer to the SequenceIdController instance (const version). This function is thread-safe.

Returns
Returns a const pointer to the SequenceIdController instance.
StationState nn::pia::transport::Station::GetState ( void  ) const
inline

Gets the state of the Station instance.

This function is thread-safe.

Returns
Returns the state of the Station.
const common::StationAddress& nn::pia::transport::Station::GetStationAddress ( void  ) const
inline

Gets the station address.

Returns
Returns a const reference for the StationAddress that is set.
StationId nn::pia::transport::Station::GetStationId ( void  ) const
inline

Gets the StationId.

Returns
Returns the StationId corresponding to the Station instance.
StationIndex nn::pia::transport::Station::GetStationIndex ( void  ) const
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.

Returns
Returns the StationIndex set in the instance.
static nn::Result nn::pia::transport::Station::SetInitialRttPulseInterval ( s32  msec)
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.

Parameters
[in]msecSpecifies the interval at which to send pulses initially. The value is in milliseconds.
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. Returned if a non-positive integer is specified. Programming error. Fix your program so that this error is not returned.
See also
GetInitialRttPulseInterval, GetRtt, SetRttPulseInterval, GetRttPulseInterval, GetRttSamplingNum
static nn::Result nn::pia::transport::Station::SetRttPulseInterval ( s32  msec)
static

Sets the interval for sending pulses for RTT calculation.

Parameters
[in]msecSpecifies the interval at which to send pulses. The value is in milliseconds.
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. Returned if a non-positive integer is specified. Programming error. Fix your program so that this error is not returned.
See also
GetRttPulseInterval, GetRtt, SetInitialRttPulseInterval, GetInitialRttPulseInterval, GetRttSamplingNum
virtual void nn::pia::transport::Station::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.