nn::nex::NgsFacade::Login Member Function

Syntax

qResult Login(
     ProtocolCallContext * pContext,
     qUnsignedInt32 gameServerId,
     const qChar * pAccessKey,
     TimeInterval uiTimeout = 30000,
     PrincipalID principalId = INVALID_PRINCIPALID
);

Parameters

Name Description
in pContext The call context. Do not use this call context to set or cancel a timeout.
in gameServerId Game server ID.
in pAccessKey Access key for the game server.
in uiTimeout Timeout (in milliseconds). The default value is 30 seconds.
in principalId Specify either INVALID_PRINCIPALID (the default) or the principal ID of the local system.

Return Values

Returns the processing result.

Value Description
QSUCCESS(Core,Success) Successfully started the login process.
QERROR(Core,Timeout) A timeout occurred.
QERROR(Core,InvalidArgument) Invalid argument.
QERROR(Core,OperationAborted) Either the system is currently logging in, logging out, or terminating, or the system is currently online.
QERROR(FPD,NotInitialized) The friend library is not initialized.
QERROR(FPD,NotConnected) Not logged in to NFS.
QERROR(FPD,InvalidPrincipalID) The principalId passed in the argument is neither INVALID_PRINCIPALID nor the principal ID of the system.

Description

Logs in.

Logs in to the NGS (Nintendo Game Server).

To log in to the NGS, you must first have successfully logged in to the NFS (Nintendo Friend Server). For information about logging in to NFS, see the nn::friends function reference.

This function logs in to the NGS after authenticating the game to the authentication server.

In this function, do not use the ProtocolCallContext::SetTimeout or ProtocolCallContext::Cancel functions to control asynchronous processing. Use the argument to specify the timeout time, and if you want to cancel the login process, use the NgsFacade::Terminate function to do so.

Use the CallContext::GetOutcome function to determine whether the asynchronous process succeeded or failed. If it failed, use the GetLastLoginErrorCode function to get the network error code.

After login succeeds, the NEX library sends a keep-alive to the game server once every five seconds. If 30 seconds elapse without a keep-alive response from the game server, the library's internal status automatically transitions to offline. When this happens, perform finalization in the application and call the NgsFacade::Logout or NgsFacade::Terminate function. Get the library's internal status with the IsConnected function.

On the game server side, if 30 seconds elapse without receiving a keep-alive packet from a client, that client is treated as logged out.

Revision History

2014/04/16
Changed the notation of the QRESULT_SUCCESS and QRESULT_ERROR return values to QSUCCESS and QERROR.
2013/11/05
Explained how to determined whether a timeout has occurred during authentication.
2013/03/07
Explained the error code when a timeout has occurred.
2012/10/31
Changed gameId to gameServerId.
2012/06/06
Reworked the internal process when logging in so that it now requires less time on the second and subsequent times.
2012/03/09
Changed the send interval for the keep-alive packet with the game server to five seconds, and changed the period of non-communication before automatically transitioning to the logout state to 30 seconds.
2012/01/26
Initial version.

CONFIDENTIAL