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

Provides core functionality of the transport module. More...

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

Classes

struct  DebugSetting
 Structure that collects the parameters to pass to the SetDebugSetting function. More...
 
struct  Setting
 Stores parameters passed to the CreateInstance function. More...
 

Public Member Functions

nn::Result CheckConnectionError (void) const
 Gets the connection status of the transport module. More...
 
nn::Result CheckTransportStatus () const
 Checks the state of Transport, and determines whether sending and receiving processes can be executed in that state. More...
 
nn::Result ConvertToStationId (StationId *pId, StationIndex idx) const
 Converts a nn::pia::StationId to a StationId. More...
 
nn::Result ConvertToStationIndex (StationIndex *pIdx, StationId id) const
 */ More...
 
template<typename T >
u32 CreateProtocol (u16 port=0)
 Generates an instance of a protocol of type T. More...
 
void DestroyProtocol (u32 protocolHandle)
 Destroys the protocol instance. More...
 
void DisableKeepAlive (void)
 Disables the keep-alive process. More...
 
void EnableKeepAlive (void)
 Enables the keep-alive process. More...
 
nn::Result GetHostStationConnectionInfo (StationConnectionInfo *pInfoOut)
 Gets the address of the session host (StationConnectionInfo). More...
 
s32 GetKeepAliveInterval (void) const
 Gets the interval at which to send keep-alive packets. More...
 
nn::Result GetLocalStationConnectionInfo (StationConnectionInfo *pInfoOut)
 Gets the address of the local device (StationConnectionInfo). More...
 
size_t GetMaxStationNum (void) const
 Gets the maximum number of connections (Station instances) set when CreateInstance was called. More...
 
template<typename T >
T * GetProtocol (u32 protocolHandle)
 Gets an instance of a protocol of type T. More...
 
bool IsKeepAliveEnabled (void) const
 Gets whether the keep-alive process is enabled. More...
 
virtual void Trace (u64 flag) const
 Prints information that is useful for debugging. More...
 

Static Public Member Functions

static nn::Result CreateInstance (const Transport::Setting &setting)
 Creates a Transport class instance (singleton pattern). More...
 
static void DestroyInstance (void)
 Destroys the Transport class instance (singleton pattern). If no instances exist, this function does nothing. More...
 
static TransportGetInstance (void)
 Gets the Transport class instance (singleton pattern). This function returns a NULL pointer if the instance has not yet been created using the CreateInstance() function. This function is thread-safe. More...
 
static nn::Result SetDebugSetting (const struct DebugSetting &setting)
 Enables debugging features. More...
 

Detailed Description

Provides core functionality of the transport module.


Revision History:

2015-04-24 Fixed an error in the description of the arguments passed to ConvertToStationId.

2015-04-24 Noted that the ConvertToStationIndex and ConvertToStationId functions have different behavior when used with the Session API and the Mesh API.

2014-11-05 Renamed the GetConnectionStatus function to CheckConnectionError.

2014-09-18 Changed the specifications so that ResultAlreadyExists is returned if you call CreateInstance when an instance already exists.

2014-07-17 Added the new CheckTransportStatus function.

2014-06-26 Added the new ConvertToStationId and ConvertToStationIndex functions.

2014-04-08 Provided the DebugSetting structure as the default constructor, and made it initialize all member variables with the default values.

2014-04-03 Renamed the GetMasterStationConnectionInfo function to GetHostStationConnectionInfo.

2014-04-02 Added the new SetDebugSetting function. Use this function to make debugging settings for things like latency emulation.

2014-04-02 Removed the members related to latency emulation from the Transport::Setting structure.

2013-11-22 Added the analysisInterval member variable to the Transport::Setting structure and made it possible to automatically print measurement results from the transport analysis feature.

2013-05-24 Made the SetKeepAliveInterval function private. Specify with the Session::Startup function.

2013-04-01 Removed the maxPacketCreatorBufferNum and maxPacketParserBufferNum members from the Transport::Setting struct.

2012-12-03 The Transport::GetConnectionStatus function can now return ResultInvalidState.

2012-11-30 Removed the Transport::MAX_SIGNATURE_KEY_SIZE constant.

2012-11-30 Removed signature-related parameters from the version of the Transport::Setting struct constructor with parameters.

2012-11-30 Removed signature-related member variables from the Transport::Setting struct.

2012-11-27 Changed the specifications of the Transport::CreateInstance function. The function now returns an error Result value if the signature feature is not enabled on networks where signed packets are recommended.

2012-07-25 Added Transport::GetLocalStationConnectionInfo and Transport::GetMasterStationConnectionInfo.

2012-07-18 Added error handling for the Transport::GetConnectionStatus function.

2012-07-05 Prepared a constructor for the Transport::Setting structure.

2012-07-05 Added member variables for latency emulation to the Setting structure.

2012-07-04 Updated descriptions of Setting structure members.

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

2012-06-15 Added the Transport::GetConnectionStatus function.

2012-06-15 Made the following functions private: Transport::Startup, Transport::Cleanup, and Transport::Dispatch.

2012-06-01 Added the Transport::Startup and Transport::Cleanup functions.

2012-05-25 Changed the Result values that the Transport::Dispatch function can return.

2012-05-09 Extended the Transport::Setting struct to add the ability to sign packets.

2012-04-28 Noted that the Transport::Dispatch function can return ResultInvalidState.

2012-04-28 Revised the description of the Transport::Dispatch function.

2012-04-25 Described memory settings using the Transport::Setting struct.

2012-04-21 Revised the description of the Transport::Dispatch function.

2012-04-18 The size of internal buffers can now be specified in the Transport::CreateInstance function.

2012-04-12 Added functions related to keep-alive processing.

2012-04-06 Initial version.

Member Function Documentation

nn::Result nn::pia::transport::Transport::CheckConnectionError ( void  ) const
inline

Gets the connection status of the transport module.

This function is thread-safe.

Returns
Returns a Result value for which the IsSuccess value returns true if there are no problems with the network connection.
Error Return Values:
ResultInvalidState Specifies that the application may not have called an appropriate initialization or setup function. This Result is returned, for example, if you attempt to connect to the Internet when the socket library has not been initialized. Programming error. Fix your program so that this error is not returned.
Error Return Values:
ResultNetworkConnectionIsLost Indicates that the network connection was lost. The wireless switch may be turned off or there may be a problem with the access point. If this error is returned in a local connection environment, reinitialize PiaLocal and the higher-level modules. If this error is returned in an Internet connection environment, connect to the Internet again (nn::ac::Connect). You could also reinitialize, as with a local connection environment. Handle appropriately in the application.
See also
util::NetworkErrorCodeConverter::Convert
nn::Result nn::pia::transport::Transport::CheckTransportStatus ( ) const
inline

Checks the state of Transport, and determines whether sending and receiving processes can be executed in that state.

Returns
Returns a Result value for which IsSuccess() returns true if the session module is finished being set up and the various API functions can be called without issue.
Error Return Values:

ResultInvalidState The setup of the session module is not complete. Programming error. Fix your program so that this error is not returned.

ResultTemporaryUnavailable The API function is temporarily unavailable because the joint session process is in progress. Handle appropriately in the application.

See also
ConvertToStationIndex, ConvertToStationId
nn::Result nn::pia::transport::Transport::ConvertToStationId ( StationId pId,
StationIndex  idx 
) const

Converts a nn::pia::StationId to a StationId.

The function returns a failure Result if the local station is not participating in the session or the function is called during a joint session.

This function can be called inside the session state-change event callback to which the EVENT_JOIN and EVENT_LEAVE events are reported.

This function works differently depending on whether it is used with the Session API or the Mesh API. When used with the Mesh API, the conversion succeeds even if a StationIndex that is not a mesh participant is specified.

Parameters
[out]pIdPointer to where the converted StationId is stored.
[in]idxThe StationIndex to convert.
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. Programming error. Fix your program so that this error is not returned.

ResultInvalidState Not in a state where the conversion process can be run. The setup for session might not have been completed. Programming error. Fix your program so that this error is not returned.

ResultNotFound Indicates that the station specified in the StationIndex is not participating in the session. 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
ConvertToStationIndex, session::Session::SessionEventCallback
nn::Result nn::pia::transport::Transport::ConvertToStationIndex ( StationIndex pIdx,
StationId  id 
) const

*/

*/ */ */

Converts a StationId to a StationIndex.

The function returns a failure Result if the local station is not participating in the session or the function is called during a joint session.

This function can be called inside the session state-change event callback to which the EVENT_JOIN and EVENT_LEAVE events are reported.

This function works differently depending on whether it is used with the Session API or the Mesh API. When used with the Mesh API, the conversion succeeds even if a StationId that is not a mesh participant is specified.

Parameters
[out]pIdxA pointer to where the converted StationIndex is stored.
[in]idThe StationId to convert.
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. Programming error. Fix your program so that this error is not returned.

ResultInvalidState Not in a state where the conversion process can be run. The setup for session might not have been completed. Programming error. Fix your program so that this error is not returned.

ResultNotFound Indicates that the station specified in the StationId is not participating in the session. 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
ConvertToStationId, session::Session::SessionEventCallback
static nn::Result nn::pia::transport::Transport::CreateInstance ( const Transport::Setting setting)
static

Creates a Transport class instance (singleton pattern).

Parameters
[in]settingSpecifies the Setting struct that parameters are stored in.
Returns
Returns a Result value that indicates success if the instance is created successfully. You must make sure that the implementation of this function in your application does not return any errors.
Error Return Values:

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

ResultInvalidState Specifies that the timing at which the CreateInstance function was called is incorrect. Make this call between the BeginSetup and EndSetup functions. Programming error. Fix your program so that this error is not returned.

ResultAlreadyExists Indicates that an instance has already been created. Programming error. Fix your program so that this error is not returned.

ResultInvalidArgument Specifies that an argument is invalid. Programming error. Fix your program so that this error is not returned.

ResultAllocationFailed Specifies that the function failed to allocate memory. You must either increase the memory provided to Pia with the common::Initialize function or try setting parameters that do not consume as much memory. Programming error. Fix your program so that this error is not returned.

See also
DestroyInstance, GetInstance, Setting
template<typename T >
u32 nn::pia::transport::Transport::CreateProtocol ( u16  port = 0)
inline

Generates an instance of a protocol of type T.

Template Parameters
TSpecifies the protocol type.
Parameters
[in]portSpecifies the value of the protocol port.
Returns
Returns a handle to the generated protocol. If the same protocol ID already exists, 0 is returned.
See also
DestroyProtocol, GetProtocol
static void nn::pia::transport::Transport::DestroyInstance ( void  )
static

Destroys the Transport class instance (singleton pattern). If no instances exist, this function does nothing.

See also
CreateInstance, GetInstance
void nn::pia::transport::Transport::DestroyProtocol ( u32  protocolHandle)
inline

Destroys the protocol instance.

Parameters
[in]protocolHandleSpecifies the handle for the protocol to delete.
See also
CreateProtocol, GetProtocol
void nn::pia::transport::Transport::DisableKeepAlive ( void  )

Disables the keep-alive process.

See also
EnableKeepAlive, IsKeepAliveEnabled
void nn::pia::transport::Transport::EnableKeepAlive ( void  )

Enables the keep-alive process.

See also
DisableKeepAlive, IsKeepAliveEnabled
nn::Result nn::pia::transport::Transport::GetHostStationConnectionInfo ( StationConnectionInfo pInfoOut)

Gets the address of the session host (StationConnectionInfo).

The address that is obtained when you are not connected to the network is undefined.

Parameters
[out]pInfoOutSpecifies a pointer to the object that holds the address obtained for the session host.
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:
ResultInvalidArgument Specifies that one or more arguments are invalid. Programming error. Fix your program so that this error is not returned.
See also
GetLocalStationConnectionInfo
static Transport* nn::pia::transport::Transport::GetInstance ( void  )
inlinestatic

Gets the Transport class instance (singleton pattern). This function returns a NULL pointer if the instance has not yet been created using the CreateInstance() function. This function is thread-safe.

Returns
Returns a pointer to a Transport instance.
See also
CreateInstance, DestroyInstance
s32 nn::pia::transport::Transport::GetKeepAliveInterval ( void  ) const

Gets the interval at which to send keep-alive packets.

This function is thread-safe.

Returns
Returns the sending interval for keep-alive packets. The value is in milliseconds.
See also
SetKeepAliveInterval
nn::Result nn::pia::transport::Transport::GetLocalStationConnectionInfo ( StationConnectionInfo pInfoOut)

Gets the address of the local device (StationConnectionInfo).

The address that is obtained when you are not connected to the network is undefined.

Parameters
[out]pInfoOutSpecifies a pointer to the object that holds the local address.
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:
ResultInvalidArgument Specifies that one or more arguments are invalid. Programming error. Fix your program so that this error is not returned.
See also
GetHostStationConnectionInfo
size_t nn::pia::transport::Transport::GetMaxStationNum ( void  ) const
inline

Gets the maximum number of connections (Station instances) set when CreateInstance was called.

This function is thread-safe.

Returns
Returns the maximum number of stations that can be connected to.
See also
CreateInstance
template<typename T >
T* nn::pia::transport::Transport::GetProtocol ( u32  protocolHandle)
inline

Gets an instance of a protocol of type T.

Template Parameters
TSpecifies the protocol type.
Parameters
[in]protocolHandleSpecifies the handle for the protocol to get.
Returns
Returns the address of the protocol instance. Returns NULL if the protocol for the specified handle does not exist or is not of type T.
See also
CreateProtocol, DestroyProtocol
bool nn::pia::transport::Transport::IsKeepAliveEnabled ( void  ) const

Gets whether the keep-alive process is enabled.

This function is thread-safe.

Returns
Returns true if it is enabled, and false if it is disabled.
See also
EnableKeepAlive, DisableKeepAlive
static nn::Result nn::pia::transport::Transport::SetDebugSetting ( const struct DebugSetting setting)
static

Enables debugging features.

Enables debugging features based on the content set in the arguments. Never call this API function in a product ROM.

When you use this API function, you must call it before calling the Transport::CreateInstance function.

Returns
Returns a Result value for which the IsSuccess function returns true if execution succeeds.
Error Return Values:
ResultInvalidState Returned if this function is called at the wrong time. Programming error. Fix your program so that this error is not returned.
virtual void nn::pia::transport::Transport::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.