6.17. Advanced Features - Session Password Settings

When using Internet communication, you can set a password on a session. Two types of passwords can be set.

 

Reference:

The session password feature is not supported during local communication.

 

User password

You can create a session configured with a user password by specifying a user-defined password in the SetSessionUserPassword() function of the inet::NexCreateSessionSetting object used when creating the session.

The maximum length of a user password is inet::SESSION_USER_PASSWORD_LENGTH characters.

Code 6-40. Configuring the User Password
// Store the user-defined password and its length in the following variables.
const wchar_t userPassword[inet::SESSION_USER_PASSWORD_LENGTH];
size_t userPasswordSize;

// Set the user password in the session to be created.
nn::pia::inet::NexCreateSessionSetting createSessionSetting;
createSessionSetting.SetSessionUserPassword(userPassword, userPasswordSize);

// Create the session configured with a user password.
nn::Result result = nn::pia::session::Session::GetInstance()->CreateSessionAsync(&createSessionSetting);

A session configured with a user password is no longer matched in random matchmaking. Also, the session can only be matched by the browse matchmaking feature when a search is run with the SetExcludeUserPasswordSet() option of inet::NexSessionSearchCriteria set to false. Use the nn::pia::inet::NexSessionInfo::IsRestrictedByUserPassword() function to determine whether there are any sessions with user passwords among the obtained search results.

To join a session configured with a user password, set the correct password in the SetSessionUserPassword() function of the inet::NexJoinSessionSetting object and run the session joining process. If an incorrect password is set, the session joining process fails and the asynchronous process returns session::ResultSessionUserPasswordUnmatch.

Code 6-41. Searching and Joining Sessions With User Passwords
// The following setting is required to search for sessions configured with user passwords.
nn::pia::inet::NexSessionSearchCriteria searchCriteria;
searchCriteria.SetExcludeUserPasswordSet(false);

// Run a search that also includes sessions configured with user passwords.
nn::Result result = nn::pia::session::Session::GetInstance()->BrowseSessionAsync(&searchCriteria);

// After the asynchronous search process completes, set the session configured with a user password.
nn::pia::inet::NexJoinSessionSetting joinSessionSetting;
pTargetSessionInfo = GetSessionInfoOfUserPasswordSet(nn::pia::session::Session::GetInstance()->GetBrowsedSessionInfoList());
joinSessionSetting.SetSessionInfoPtr(pTargetSessionInfo);

// Store the user-defined password and its length in the following variables.
const wchar_t userPassword[inet::SESSION_USER_PASSWORD_LENGTH];
size_t userPasswordSize;

// Set the user password in the settings to use when joining.
joinSessionSetting.SetSessionUserPassword(userPassword, userPasswordSize);

// If the configured user password matches, the join process succeeds.
nn::Result result = nn::pia::session::Session::GetInstance()->JoinSessionAsync(pJoinSessionSetting);

System Password

The application can store a system password and session ID generated by the server. This enables stations with the password information to rejoin the session if they are disconnected.

The host can configure the current session with a server-generated system password by calling session::Session::GenerateSessionSystemPasswordAsync().

When a system password is set, all stations participating in the session receive a session::Session::EVENT_SET_SESSION_SYSTEM_PASSWORD event in the callback registered with session::Session::RegisterSessionEventCallback(). You can get the system password by calling the session::Session::GetSessionSystemPassword() function inside the callback function. If a station calls the session::Session::GenerateSessionSystemPasswordAsync() function, when the asynchronous process completes, the system password is saved to the buffer that was passed as an argument.

The system password can be retrieved from the time the session::Session::EVENT_SET_SESSION_SYSTEM_PASSWORD event is triggered until the session::Session::EVENT_CLEAR_SESSION_SYSTEM_PASSWORD event is triggered. The password is also no longer available after Session::Cleanup() is called.

The system password length is inet::SESSION_SYSTEM_PASSWORD_LENGTH characters. You must prepare a buffer to store the system password in the application.

Code 6-42. Generating and Retrieving a System Password
// Store the system password and session ID.
// This information can no longer be retrieved after the Pia cleanup process runs, so you must prepare a buffer in the application.
u32 sessionId;
wchar_t systemPassword[nn::pia::inet::SESSION_SYSTEM_PASSWORD_LENGTH];

// Session state change event callback function.
void sampleSessionCallback(nn::pia::session::Session::SessionEventType eventType, nn::pia::StationId stationId)
{
    // The eventType argument is an enumerated type that indicates the content of the state change that occurs.
    switch (eventType)
    {
    // All stations participating in the session are notified when a system password is generated.
    case nn::pia::session::Session::EVENT_SET_SESSION_SYSTEM_PASSWORD:
        // Record the session ID and system password.
        sessionId = nn::pia::session::Session::GetInstance()->GetSessionId();
        nn::pia::session::Session::GetInstance()->GetSessionSystemPassword(systemPassword);
        break;
    }
}

// Generate a system password at any time while participating in a session.
nn::Result result = nn::pia::session::Session::GetInstance()->GenerateSessionSystemPasswordAsync(systemPassword);

A session configured with a system password is no longer matched by the random matchmaking feature and the browse matchmaking feature. To join a session configured with a system password, set the session ID and system password recorded to the inet::NexJoinSessionSetting object and run the session joining process. If an incorrect password is set, the session joining process fails and the asynchronous process returns session::ResultSessionSystemPasswordUnmatch.

Code 6-43. Joining a Session With a System Password
// Store the system password and session ID.
u32 sessionId;
wchar_t systemPassword[nn::pia::inet::SESSION_SYSTEM_PASSWORD_LENGTH];

// Set the ID of the session to join and the system password.
nn::pia::inet::NexJoinSessionSetting joinSessionSetting;
joinSessionSetting.SetSessionId(sessionId);
joinSessionSetting.SetSessionSystemPassword(systemPassword, nn::pia::inet::SESSION_SYSTEM_PASSWORD_LENGTH);

// The join process succeeds if the specified session ID still exists and the set system password matches.
nn::Result result = nn::pia::session::Session::GetInstance()->JoinSessionAsync(pJoinSessionSetting);

The host can clear the configured system password of the current session by calling session::Session::ClearSessionSystemPasswordAsync(). When the system password is cleared, all stations participating in the session receive a session::Session::EVENT_CLEAR_SESSION_SYSTEM_PASSWORD event in the callback registered with session::Session::RegisterSessionEventCallback(). After the system password is cleared, the session can be searched for and joined like a standard session.

Code 6-44. Clearing the System Password
// Session state change event callback function.
void sampleSessionCallback(nn::pia::session::Session::SessionEventType eventType, nn::pia::StationId stationId)
{
    // The eventType argument is an enumerated type that indicates the content of the state change that occurs.
    switch (eventType)
    {
    // All stations participating in the session are notified when a system password is generated.
    case nn::pia::session::Session::EVENT_CLEAR_SESSION_SYSTEM_PASSWORD:
        // The system password was cleared.
        break;
    }
}

// Clear the system password at any time while participating in a session.
nn::Result result = nn::pia::session::Session::GetInstance()->ClearSessionSystemPasswordAsync();