CTR Pia
4.11.3
Game Communication Engine
|
Provides core functionality of the transport
module.
More...
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 Transport * | GetInstance (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... | |
Provides core functionality of the transport
module.
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.
|
inline |
Gets the connection status of the transport
module.
This function is thread-safe.
Result
value for which the IsSuccess
value returns true
if there are no problems with the network connection. 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.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.
|
inline |
Checks the state of Transport
, and determines whether sending and receiving processes can be executed in that state.
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. 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.
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.
[out] | pId | Pointer to where the converted StationId is stored. |
[in] | idx | The StationIndex to convert. |
Result
value for which the IsSuccess
function returns true
if execution succeeds. 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.
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.
[out] | pIdx | A pointer to where the converted StationIndex is stored. |
[in] | id | The StationId to convert. |
Result
value for which the IsSuccess
function returns true
if execution succeeds. 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.
|
static |
Creates a Transport
class instance (singleton pattern).
[in] | setting | Specifies the Setting struct that parameters are stored in. |
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. 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.
|
inline |
Generates an instance of a protocol of type T
.
T | Specifies the protocol type. |
[in] | port | Specifies the value of the protocol port. |
0
is returned.
|
static |
Destroys the Transport
class instance (singleton pattern). If no instances exist, this function does nothing.
|
inline |
Destroys the protocol instance.
[in] | protocolHandle | Specifies the handle for the protocol to delete. |
void nn::pia::transport::Transport::DisableKeepAlive | ( | void | ) |
Disables the keep-alive process.
void nn::pia::transport::Transport::EnableKeepAlive | ( | void | ) |
Enables the keep-alive process.
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.
[out] | pInfoOut | Specifies a pointer to the object that holds the address obtained for the session host. |
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. ResultInvalidArgument
Specifies that one or more arguments are invalid. Programming error. Fix your program so that this error is not returned.
|
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.
Transport
instance. s32 nn::pia::transport::Transport::GetKeepAliveInterval | ( | void | ) | const |
Gets the interval at which to send keep-alive packets.
This function is thread-safe.
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.
[out] | pInfoOut | Specifies a pointer to the object that holds the local address. |
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. ResultInvalidArgument
Specifies that one or more arguments are invalid. Programming error. Fix your program so that this error is not returned.
|
inline |
Gets the maximum number of connections (Station
instances) set when CreateInstance
was called.
This function is thread-safe.
|
inline |
Gets an instance of a protocol of type T
.
T | Specifies the protocol type. |
[in] | protocolHandle | Specifies the handle for the protocol to get. |
NULL
if the protocol for the specified handle does not exist or is not of type T
. bool nn::pia::transport::Transport::IsKeepAliveEnabled | ( | void | ) | const |
Gets whether the keep-alive process is enabled.
This function is thread-safe.
true
if it is enabled, and false
if it is disabled.
|
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.
Result
value for which the IsSuccess
function returns true
if execution succeeds. ResultInvalidState
Returned if this function is called at the wrong time. 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. |