CTR Pia
4.11.3
Game Communication Engine
|
Represents the NEX library facade (interface wrapper) class. More...
Classes | |
struct | LoginInfo |
Information about the NEX game server that was logged in to. More... | |
Public Types |
Public Member Functions | |
virtual nn::Result | Bind (LoginInfo *pLoginInfo) |
Registers information for the game server that was logged in to. More... | |
virtual nn::Result | CancelStartNatSessionAsync () |
Cancels StartNatSessionAsync asynchronous processes. This function can only be called when directly manipulated by the session::Mesh class. More... | |
virtual void | Cleanup () |
Cleans up the NexFacade function. This function can only be called when directly manipulated by the session::Mesh class. More... | |
Filtering | GetNatPropertyFiltering () |
Gets the local NAT filtering type. More... | |
u16 | GetNatPropertyInterfacePort () |
Gets the LAN port for the local NAT. More... | |
Mapping | GetNatPropertyMapping () |
Gets the local NAT port mapping type. More... | |
u32 | GetNatPropertyPortIncrement () |
Gets the local NAT port increment. More... | |
u16 | GetNatPropertyPublicPort () |
Gets the Internet port for the local NAT. More... | |
Result | GetRetrieveNotificationDataResult () const |
Gets the result of the RetrieveNotificationDataAsync asynchronous process. More... | |
virtual nn::Result | GetStartNatSessionResult () const |
Gets the result of StartNatSessionAsync asynchronous processing. This function can only be called when directly manipulated by the session::Mesh class. More... | |
Result | GetUpdateNotificationDataResult () const |
Gets the result of the UpdateNotificationDataAsync asynchronous process. More... | |
bool | IsCompletedRetrieveNotificationData () const |
Checks for completion of the RetrieveNotificationDataAsync asynchronous process. More... | |
virtual bool | IsCompletedStartNatSession () const |
Checks the completion of StartNatSessionAsync asynchronous processing. This function can only be called when directly manipulated by the session::Mesh class. More... | |
bool | IsCompletedUpdateNotificationData () const |
Checks for completion of asynchronous processing by UpdateNotificationDataAsync . More... | |
bool | IsStartedNatSession () |
Checks whether the NAT session (P2P communication) has started. More... | |
bool | IsStartedUp () |
Checks whether the NexFacade feature is in a started state. More... | |
Result | RetrieveNotificationDataAsync (u8 gameNotificationTypeBitMask, nn::nex::qList< nn::nex::NotificationEvent > *pRetrievedEventList) |
Gets the game-specific events that were sent as notifications to the game server. More... | |
virtual nn::Result | StartNatSessionAsync () |
Starts a NAT session (P2P communication). This function can only be called when directly manipulated by the session::Mesh class. More... | |
virtual nn::Result | Startup () |
Starts the NexFacade function. This function can only be called when directly manipulated by the session::Mesh class. More... | |
virtual void | StopNatSession () |
Stops a NAT session (P2P communication). This function can only be called when directly manipulated by the session::Mesh class. More... | |
virtual void | Trace (u64 flag) const |
Prints information that is useful for debugging. More... | |
virtual void | Unbind () |
Deletes the information on the registered game server. More... | |
void | UpdateGatheringID (nn::nex::GatheringID gatheringID) |
Updates the GatheringID of the matchmaking session managed by NexFacade . This function can only be called when directly manipulated by the session::Mesh class. More... | |
Result | UpdateNotificationDataAsync (nn::nex::NotificationEvents::NotificationEvents gameNotificationType, u32 param1, u32 param2, const wchar_t *strParam, size_t strParamLength) |
Notifies the game server of game-specific events. More... | |
Static Public Member Functions | |
static nn::Result | ConvertNexSignatureKeyToSignatureSetting (const nn::nex::qVector< nn::nex::qByte > &nexSignatureKey, nn::pia::common::SignatureSetting *pSignatureSetting) |
Converts an nn::nex::qVector<nn::nex::qByte> shared session key to an nn::pia::common::SignatureSetting instance. More... | |
static nn::Result | ConvertNexStationUrlToStationConnectionInfo (const nn::nex::qList< nn::nex::StationURL > &nexStationUrlList, nn::pia::transport::StationConnectionInfo *pStationConnectionInfo) |
Converts nn::nex::StationURL to nn::pia::transport::StationConnectionInfo . More... | |
static void | ConvertNexStationUrlToStationLocation (const nn::nex::StationURL &url, transport::StationLocation *pLocation) |
Converts a NEX StationURL instance to a PiaTransport StationLocation instance. More... | |
static nn::Result | CreateInstance (void) |
Creates an instance (singleton pattern). More... | |
static void | DestroyInstance (void) |
Destroys the instance (singleton pattern). More... | |
static NexFacade * | GetInstance (void) |
Gets the pointer to the NexFacade instance (singleton pattern). More... | |
Represents the NEX library facade (interface wrapper) class.
This is not the facade for the nn::pia::inet::Nex*
classes, but for the NEX library classes.
2014-09-18 Changed the specifications so that ResultAlreadyExists
is returned if you call CreateInstance()
when an instance already exists.
2014-04-01 Added the Bind()
and Unbind()
functions and LoginInfo
. In conjunction with that, modified the arguments for the Startup()
function.
2014-03-25 Deleted the GetNatProperty()
function. Added the GetNatPropertyMapping()
, GetNatPropertyFiltering()
, GetNatPropertyPortIncrement()
, GetNatPropertyPublicPort()
, and GetNatPropertyInterfacePort()
functions.
2014-03-18 Deleted the ConvertNexStationURLToStationConnectionInfo()
function. Made the ConvertNexInetAddressToInetAddress()
, ConvertInetAddressToNexInetAddress()
, and ConvertStationLocationToNexStationUrl()
functions private.
2014-01-15 Made changes so that the name resolution process that was being done in the StartNatSessionAsync()
function now uses the socket library directly.
2013-12-18 Added the StartNatSessionAsync()
, IsCompletedStartNatSession()
, GetStartNatSessionResult()
, and CancelStartNatSessionAsync()
functions.
2013-11-27 Deleted ResultDnsFailed
from the StartNatSession()
return values and added it to the Result
values that could be returned through CallContext
when asynchronous processes fail.
2013-09-18 Added the game server ID as the third parameter of the Startup()
function.
2013-09-05 Added the fact that the NEX allocator is called inside the Startup()
function.
2013-07-02 Changed the first argument of the Startup()
function from nn::nex::Credentials*
to nn::nex::NgsFacade*
.
2012-12-03 Added ConvertNexSignatureKeyToSignatureSetting
.
2012-12-03 Added ConvertNexStationUrlToStationConnectionInfo
.
2012-12-03 Deprecated ConvertNexStationURLToStationConnectionInfo
.
2012-12-03 Renamed the ConvertStationLocationToNexStationURL()
function to ConvertStationLocationToNexStationUrl()
.
2012-12-03 Renamed the ConvertNexStationURLToStationLocation()
function to ConvertNexStationUrlToStationLocation()
.
2012-11-29 Moved the parts of the nn::pia::transport::StationLocation
function that bring in a dependency on NEX here.
2012-11-21 Added the ConvertStationLocationToNexStationURL()
and ConvertNexStationURLToStationLocation()
functions.
2012-11-21 Added the ConvertNexInetAddressToInetAddress()
and ConvertInetAddressToNexInetAddress()
functions.
2012-05-17 Added the NexFacade::UpdateGatheringID
function to get the GatheringID
of the matchmaking session from the application.
2012-05-16 Added parameters to the NexFacade::Startup function
.
2012-04-06 Initial version.
|
virtual |
Registers information for the game server that was logged in to.
This function registers the game server ID, and an instance of the nn::nex::NgsFacade
class when a login to the NEX game server succeeds with the Pia library. Call it in the interval between logging in to the NEX game server and calling the NexFacade::Startup
function.
[in] | pLoginInfo | Specifies a pointer to the NEX game server information LoginInfo . |
Result
values is returned. You must make sure that the implementation of this function in your application does not return any errors. nn::pia::ResultInvalidArgument
Indicates that one or more arguments are invalid. Programming error. Fix your program so that this error is not returned.
|
virtual |
Cancels StartNatSessionAsync
asynchronous processes. This function can only be called when directly manipulated by the session::Mesh
class.
This function cancels asynchronous processing after StartNatSessionAsync
is called. The cancel process advances by periodically calling the nn::pia::common::Scheduler::Dispatch
function. The library quickly acts to cancel the asynchronous process after this function is called, but check using the IsCompletedStartNatSession()
function that the cancellation has completed.
StartNatSessionAsync
asynchronous processing. If this function call fails, one or more of the following Result
values is returned. nn::pia::ResultInvalidState
Returned when no StartNatSessionAsync
asynchronous processing is being performed at the time this function is called. Programming error. Fix your program so that this error is not returned.
|
virtual |
Cleans up the NexFacade
function. This function can only be called when directly manipulated by the session::Mesh
class.
Call before logging out from the NEX game server.
|
static |
Converts an nn::nex::qVector<nn::nex::qByte>
shared session key to an nn::pia::common::SignatureSetting
instance.
Converts the shared session key obtained from the game server during matchmaking into a key for the class used to configure the packet-signing feature. Either configure the converted nn::pia::common::SignatureSetting
instance with a buffer for the key beforehand, or use the nn::pia::common::SignatureSettingWithKeyBuffer
class. The converted packet-signing settings are required by the nn::pia::session::Mesh::Startup
function.
[in] | nexSignatureKey | Specifies the nn::nex::qVector<nn::nex::qByte> instance to convert from. |
[out] | pSignatureSetting | Specifies the nn::pia::common::SignatureSetting instance to convert to. |
Result
values is returned. You must make sure that the implementation of this function in your application does not return any errors. nn::pia::ResultInvalidArgument
Indicates that one or more arguments are invalid. Make sure that the buffer in the nn::pia::common::SignatureSetting
instance is at least as large as the original data. Programming error. Fix your program so that this error is not returned.
|
static |
Converts nn::nex::StationURL
to nn::pia::transport::StationConnectionInfo
.
Converts the connection point information obtained from nn::nex::MatchmakeExtensionClient::GetMeshURLs
to Pia station connection information. The converted station connection information can be used with nn::pia::session::Mesh::JoinMeshAsync
.
[in] | nexStationUrlList | Specifies the connection to convert. There must be one or two elements. |
[in] | pStationConnectionInfo | Specifies the station connection to convert to. |
Result
values is returned. You must make sure that the implementation of this function in your application does not return any errors. nn::pia::ResultInvalidArgument
Indicates that one or more arguments are invalid. Programming error. Fix your program so that this error is not returned.
|
static |
Converts a NEX
StationURL
instance to a PiaTransport
StationLocation
instance.
[in] | url | Specifies the NEX StationURL instance. |
[out] | pLocation | Specifies the StationLocation instance of PiaTransport . |
|
static |
Creates an instance (singleton pattern).
Result
values is returned. You must make sure that the implementation of this function in your application does not return any errors. nn::pia::ResultNotInitialized
Indicates that the inet
module is not initialized. Programming error. Fix your program so that this error is not returned.
nn::pia::ResultInvalidState
Indicates that the function was called at the wrong time. Programming error. Fix your program so that this error is not returned.
nn::pia::ResultAlreadyExists
Indicates that an instance has already been created. Programming error. Fix your program so that this error is not returned.
|
static |
Destroys the instance (singleton pattern).
This function does nothing and returns if called when an instance has not been created. Returns from the function without doing anything.
|
inlinestatic |
Gets the pointer to the NexFacade
instance (singleton pattern).
Filtering nn::pia::inet::NexFacade::GetNatPropertyFiltering | ( | ) |
Gets the local NAT filtering type.
Gets the local NAT filtering type. A correct value is available after the asynchronous process for NexFacade::StartNatSessionAsync
completes.
u16 nn::pia::inet::NexFacade::GetNatPropertyInterfacePort | ( | ) |
Gets the LAN port for the local NAT.
Gets the LAN port for the local NAT. A correct value is available after the asynchronous process for NexFacade::StartNatSessionAsync
completes.
Mapping nn::pia::inet::NexFacade::GetNatPropertyMapping | ( | ) |
Gets the local NAT port mapping type.
Gets the local NAT port mapping type. A correct value is available after the asynchronous process for NexFacade::StartNatSessionAsync
completes.
u32 nn::pia::inet::NexFacade::GetNatPropertyPortIncrement | ( | ) |
Gets the local NAT port increment.
Gets the local NAT port increment. A correct value is available after the asynchronous process for NexFacade::StartNatSessionAsync
completes.
u16 nn::pia::inet::NexFacade::GetNatPropertyPublicPort | ( | ) |
Gets the Internet port for the local NAT.
Gets the Internet port for the local NAT. A correct value is available after the asynchronous process for NexFacade::StartNatSessionAsync
completes.
Result nn::pia::inet::NexFacade::GetRetrieveNotificationDataResult | ( | ) | const |
Gets the result of the RetrieveNotificationDataAsync
asynchronous process.
This function gets the result after RetrieveNotificationDataAsync
has been called, and IsCompletedRetrieveNotificationData
has confirmed that the process is complete.
RetrieveNotificationDataAsync
asynchronous processing. The following results are returned when the process ends. ResultSuccess
The asynchronous process succeeded.
nn::pia::ResultInvalidState
Indicates that the RetrieveNotificationDataAsync
function was called at the wrong time, or that the asynchronous process has not completed. Programming error. Fix your program so that this error is not returned.
nn::pia::ResultNexInternalError
This is an internal NEX error. The nn::pia::util::NetworkErrorCodeConverter::Convert
function gets a NEX network error code. Check the NEX section of the network error code list. After logging out, reinitialize Pia and NEX. If this error occurs during Internet communication, convert to a network error code and display in the error viewer applet/EULA applet. However, during local communication, do not display it as an error with error code in the error viewer applet/EULA applet. Handle appropriately in the application.
|
virtual |
Gets the result of StartNatSessionAsync
asynchronous processing. This function can only be called when directly manipulated by the session::Mesh
class.
This function gets the results after StartNatSessionAsync
is called and IsCompletedStartNatSession
confirms that the process has completed.
StartNatSessionAsync
asynchronous processing. The following results are returned when the process ends. nn::ResultSuccess
The asynchronous process succeeded.
nn::pia::ResultCancelled
The asynchronous process was canceled. Perform cleanup.
nn::pia::ResultInvalidState
The StartNatSessionAsync
function was called at the wrong time, or the asynchronous process has not completed. Programming error. Fix your program so that this error is not returned.
nn::pia::ResultNetworkConnectionIsLost
The network is not available. The wireless switch may be turned off or there may be a problem with the access point. Reconnect to AC.
nn::pia::ResultNatCheckFailed
The NAT check failed. If this error occurs during Internet communication, convert to a network error code and display in the error viewer applet/EULA applet. However, during local communication, do not display it as an error with error code in the error viewer applet/EULA applet. Perform cleanup.
nn::pia::ResultDnsFailed
DNS resolution failed. If this error occurs during Internet communication, convert to a network error code and display in the error viewer applet/EULA applet. However, during local communication, do not display it as an error with error code in the error viewer applet/EULA applet. Perform cleanup.
Result nn::pia::inet::NexFacade::GetUpdateNotificationDataResult | ( | ) | const |
Gets the result of the UpdateNotificationDataAsync
asynchronous process.
This function gets the result after UpdateNotificationDataAsync
has been called, and IsCompletedUpdateNotificationData
has confirmed that the process is complete.
UpdateNotificationDataAsync
asynchronous process. The following results are returned when the process ends. ResultSuccess
The asynchronous process succeeded.
nn::pia::ResultInvalidState
Indicates that the UpdateNotificationDataAsync
function was called at the wrong time, or the asynchronous process has not completed. Programming error. Fix your program so that this error is not returned.
nn::pia::ResultNexInternalError
This is an internal NEX error. The nn::pia::util::NetworkErrorCodeConverter::Convert
function gets a NEX network error code. Check the NEX section of the network error code list. After logging out, reinitialize Pia and NEX. If this error occurs during Internet communication, convert to a network error code and display in the error viewer applet/EULA applet. However, during local communication, do not display it as an error with error code in the error viewer applet/EULA applet. Handle appropriately in the application.
bool nn::pia::inet::NexFacade::IsCompletedRetrieveNotificationData | ( | ) | const |
Checks for completion of the RetrieveNotificationDataAsync
asynchronous process.
After calling RetrieveNotificationDataAsync
, use this function to check the completion of the asynchronous process.
true
if the asynchronous process has completed, or false
otherwise.
|
virtual |
Checks the completion of StartNatSessionAsync
asynchronous processing. This function can only be called when directly manipulated by the session::Mesh
class.
This function checks the completion of asynchronous processing after StartNatSessionAsync
is called.
true
if the asynchronous process has completed, or false
otherwise. bool nn::pia::inet::NexFacade::IsCompletedUpdateNotificationData | ( | ) | const |
Checks for completion of asynchronous processing by UpdateNotificationDataAsync
.
After UpdateNotificationDataAsync
has been called, this function checks the completion of the asynchronous process.
true
if the asynchronous process has completed, or false
otherwise.
|
inline |
Checks whether the NAT session (P2P communication) has started.
true
if started.
|
inline |
Checks whether the NexFacade
feature is in a started state.
true
when started up. Result nn::pia::inet::NexFacade::RetrieveNotificationDataAsync | ( | u8 | gameNotificationTypeBitMask, |
nn::nex::qList< nn::nex::NotificationEvent > * | pRetrievedEventList | ||
) |
Gets the game-specific events that were sent as notifications to the game server.
Gets events, uniquely defined by the game, that friends logged in to the same game server have sent as notifications. Log in to the gamer server and call this function in the interval between the calls to Bind
and Unbind
. You normally get events using an event handler. Use this function to get events only during a login.
[in] | gameNotificationTypeBitMask | Specify the bitmask that represents the game-defined event type to acquire. The nth bit corresponds to nn::nex::NotificationEvents::GameNotificationEventN . |
[out] | pRetrievedEventList | Specifies the location for storing the acquired event list. Maintain an instance for the specified list until asynchronous processing completes. |
Result
values is returned. You must make sure that the implementation of this function in your application does not return any errors. nn::pia::ResultInvalidArgument
Indicates that one or more arguments are invalid. Programming error. Fix your program so that this error is not returned.
nn::pia::ResultInvalidState
Indicates that the function was called at the wrong time. Programming error. Fix your program so that this error is not returned.
|
virtual |
Starts a NAT session (P2P communication). This function can only be called when directly manipulated by the session::Mesh
class.
Starts a NAT session and performs the necessary preprocessing for P2P communication. If calling this function, do so before calling the nn::pia::session::Mesh::Startup
function. The port number used for P2P communication changes every time this function is run.
The started process advances by periodically calling the nn::pia::common::Scheduler::Dispatch
function. Use IsCompletedStartNatSession
to check whether the process has completed and GetStartNatSessionResult
to check the result.
This function performs DNS name resolution on the server for NAT-type detection, but only the first time it is called after the application starts. The name resolution process runs in a background thread during asynchronous processes. The name resolution process uses the nn::socket::GetAddrInfo()
function of the socket library. Memory is allocated from the working memory specified using the nn::socket::Initialize()
function when the name resolution process is run. That memory is later freed when the name resolution process ends.
If the WAN cable of the router is unplugged before name resolution finishes, it might take 30 or more seconds for this asynchronous process to complete because it needs to wait for the name resolution process timeout. This process may take over 30 seconds to complete. The name resolution process cannot be canceled.
The following results may be returned by the GetStartNatSessionResult
instance when the asynchronous process completes.
nn::ResultSuccess
: The asynchronous process succeeded.nn::pia::ResultCancelled
: The asynchronous process was canceled. Perform cleanup.nn::pia::ResultInvalidState
: Called at the wrong time. Programming error. Fix your program so that this error is not returned.nn::pia::ResultNetworkConnectionIsLost
: The network is not available. The wireless switch may be turned off or there may be a problem with the access point. Reconnect to AC.nn::pia::ResultNatCheckFailed
: The NAT check failed. If this error occurs during Internet communication, convert to a network error code and display in the error viewer applet/EULA applet. However, during local communication, do not display it as an error with error code in the error viewer applet/EULA applet. Perform cleanup.nn::pia::ResultDnsFailed
: DNS resolution failed. If this error occurs during Internet communication, convert to a network error code and display in the error viewer applet/EULA applet. However, during local communication, do not display it as an error with error code in the error viewer applet/EULA applet. Perform cleanup.Result
values is returned. nn::pia::ResultInvalidArgument
Indicates that one or more arguments are invalid. Programming error. Fix your program so that this error is not returned.
nn::pia::ResultInvalidState
Indicates that the function was called at the wrong time. Programming error. Fix your program so that this error is not returned.
|
virtual |
Starts the NexFacade
function. This function can only be called when directly manipulated by the session::Mesh
class.
Call this function after logging in to the NEX game server and running the Bind
function. Use the NEX allocator to create instances of classes used for internal processing inside this function. These instances are managed with the NEX library and are destroyed when the nn::nex::NgsFacade
instance is destroyed. A new instance is not created if an instance of this class is already being managed by NEX.
Result
values is returned. You must make sure that the implementation of this function in your application does not return any errors. nn::pia::ResultInvalidArgument
Indicates that one or more arguments are invalid. Programming error. Fix your program so that this error is not returned.
nn::pia::ResultInvalidState
Indicates that the function was called at the wrong time or that the NEX thread mode is not supported by Pia. (The Pia library only supports unsafe transport buffer thread mode or unsafe user thread mode. We recommend using unsafe transport buffer thread mode with 3.x versions of NEX. Programming error. Fix your program so that this error is not returned.
|
virtual |
Stops a NAT session (P2P communication). This function can only be called when directly manipulated by the session::Mesh
class.
Call this function before calling the nn::pia::session::Mesh::Cleanup
function.
|
virtual |
Prints information that is useful for debugging.
[in] | flag | Specifies the trace flag. For more information, see the TraceFlag API reference. |
|
virtual |
Deletes the information on the registered game server.
This function deletes the game server ID's registration information, and an instance of the nn::nex::NgsFacade
class from the Pia library when a login to the NEX game server succeeds. Call this function in the interval between the call to the NexFacade::Cleanup
function and logging out from the NEX game server.
void nn::pia::inet::NexFacade::UpdateGatheringID | ( | nn::nex::GatheringID | gatheringID | ) |
Updates the GatheringID
of the matchmaking session managed by NexFacade
. This function can only be called when directly manipulated by the session::Mesh
class.
Any GatheringID
updated by this function can be used by features such as host migration.
[in] | gatheringID | Specify the GatheringID of the matchmaking session you are in. |
Result nn::pia::inet::NexFacade::UpdateNotificationDataAsync | ( | nn::nex::NotificationEvents::NotificationEvents | gameNotificationType, |
u32 | param1, | ||
u32 | param2, | ||
const wchar_t * | strParam, | ||
size_t | strParamLength | ||
) |
Notifies the game server of game-specific events.
Notifies friends logged in to the same game server of events that have been uniquely defined in the game. Log in to the gamer server and call this function in the interval between the calls to Bind
and Unbind
. Limit the frequency of event notifications so there are no more than 10 notifications in any minute.
[in] | gameNotificationType | The game-defined event type (nn::nex::NotificationEvents::GameNotificationEvent1 through nn::nex::NotificationEvents::GameNotificationEvent8 ). |
[in] | param1 | Specifies an event parameter. |
[in] | param2 | Specifies an event parameter. |
[in] | strParam | Specifies an event parameter string. Limit the string to no longer than 256 characters. |
[in] | strParamLength | The length of the event parameter string. Limit the string to no longer than 256 characters. |
Result
values is returned. You must make sure that the implementation of this function in your application does not return any errors. nn::pia::ResultInvalidArgument
Indicates that one or more arguments are invalid. Programming error. Fix your program so that this error is not returned.
nn::pia::ResultInvalidState
Indicates that the function was called at the wrong time. Programming error. Fix your program so that this error is not returned.