6.6. Basic Features - Processing During Session Participation

This section explains processing during session participation.

Sending and Receiving

During session participation, PiaTransport is used, so the sending and receiving of data between stations is possible. For more information about sending and receiving, see 5. PiaTransport Guide and the API reference.

Checking the Network Connection Status

You can check whether the local station is connected to a session by calling the function in the Session class that checks the connection status. Connections can sometimes be disconnected for external reasons, such as when the session host destroys the session or when communication cannot be maintained.

With Internet communication, there are two types of disconnection, those caused by being disconnected from the session and those caused by being disconnected from the network. The process for restarting the session differs in each case.

Code 6-11. Checking the Network Connection Status
// Get and check the connection status.
nn::Result sessionConnectionStatusResult = nn::pia::session::Session::GetInstance()->CheckConnectionError();
if ( sessionConnectionStatusResult == nn::pia::session::ResultSessionConnectionIsLost() )
{
    // Disconnected from mesh (P2P session).
    // Be sure to clean up after the end of the Session::LeaveSessionAsync asynchronous process.
}
// The following check is also necessary for Internet communication.
if ( sessionConnectionStatusResult == nn::pia::ResultNetworkConnectionIsLost() )
{
    // Disconnected from the network.
    // After performing cleanup operations, finalize PiaSession and reconnect to the Internet.
}

Checking Stations Participating in the Session

You can get information such as the number of stations and whether a particular StationId exists in the session.

Code 6-12. Analyzing the Session You Are Participating In
// The number of valid stations.
u16 stationNum = nn::pia::session::Session::GetInstance()->GetStationNum();
 
// The session host's StationId
nn::pia::StationId hostStationId = nn::pia::session::Session::GetInstance()->GetHostStationId();
// The local station's StationId
nn::pia::StationId localStationId = nn::pia::session::Session::GetInstance()->GetLocalStationId();
 
// Check whether a particular StationId exists in the session.
nn::pia::StationId targetStationId; // The target StationId exists.
bool isValid = nn::pia::session::Session::GetInstance()->CheckStationIdIsValid( targetStationId );

Handling Session State Change Events

When a session state has changed, you can know about the state change by registering a callback function in advance. When the session state changes while the callback function is registered until it is unregistered, the callback function is called. State change event notifications are issued when a station joins or leaves the session.

Warning:

Do not include any processes that would block for a long time within the callback function. This can negatively affect system processes.

The processes that connect a station that is joining a session with stations that are already in the session occur in parallel with the session join process. As a result, the EVENT_JOIN event (which indicates that a new station has joined the session) may occur at a different time for each of the stations that have already joined the session. Also, depending on how far the connection process has progressed, the EVENT_JOIN event may not actually occur for all of the stations that are already in the session if the joining station fails to join the session for any reason (such as if it fails to connect with one of the other stations in the session). (In this case, the stations where an EVENT_JOIN occurred experience an EVENT_LEAVE a short time later.)

StationId values included in the EVENT_JOIN notification can be converted into the corresponding StationIndex values (and converted back from StationIndex values to StationId values) until the EVENT_LEAVE notification, which indicates that the station is leaving the session.

Make sure that you register callback functions prior to starting a session and unregister them after cleaning up after a session.

Code 6-13. Registering and Unregistering the Session State Change Event Callback Function and the Event Callback Function
// Example of a session state change event callback function.
void sampleSessionCallback(nn::pia::session::Session::SessionEventType eventType, nn::pia::StationId stationId)
{
    // The eventType parameter is an enum type representing the details of the change in state event.
    switch (eventType)
    {
    case nn::pia::session::Session::EVENT_JOIN:
        // The station assigned StationId: stationId has joined the session.
        break;
    case nn::pia::session::Session::EVENT_LEAVE:
        // The station assigned StationId: stationId has left the session.
        break;
    case nn::pia::session::Session::EVENT_SESSION_HOST_CHANGED:
        // The station StationId: stationId has become the session host.
        break;
    case nn::pia::session::Session::EVENT_HOST_MIGRATION_FAILED:
        // Host migration failed.
        break;
    }
}
 
// Register the event callback function.
nn::pia::session::Session::GetInstance()->RegisterSessionEventCallback(sampleSessionCallback);

// Do not start the session until after the event callback function has been registered.
// This callback function will be called if the session state stages while it is registered until it is unregistered.

// Be sure to clean up the session before unregistering the event callback function.
 
// Unregister the event callback function.
nn::pia::session::Session::GetInstance()->UnregisterSessionEventCallback();

Changing Session Settings

The session host can modify a variety of session settings while the session is in progress.

Changing Session Attributes

Calling the ModifyAttributeAsync() function starts the asynchronous process. The end of that process can be detected with the IsCompletedModifyAttribute() function. GetModifyAttributeResult() returns a result of true for IsSuccess() when the process is successful. You can set an index from 0 through 5 for session attributes.

Code 6-14. Changing Session Attributes
nn::Result result = nn::pia::session::Session::GetInstance()->ModifyAttributeAsync(MATCHMAKE_ATTR_INDEX, 10);
if( result.IsFailure() )
{
    // Error processing
}

// If the asynchronous process has started successfully, you must call the dispatch function periodically and wait for the asynchronous process to proceed.
while(nn::pia::session::Session::GetInstance()->IsCompletedModifyAttribute() == false)
{
    if ( networkType == INTERNET )
    {
        // If you are using Internet communication, you must call the NEX Scheduler::Dispatch function for keep-alive communications with the server.
        nn::nex::Scheduler::GetInstance()->DispatchAll();
    }
    nn::pia::common::Scheduler::GetInstance()->Dispatch();
}

// Check the result of the asynchronous process.
result = nn::pia::session::Session::GetInstance()->GetModifyAttributeResult();
if( result.IsFailure() )
{
    //Error processing.
}

Application-defined data

Calling the UpdateApplicationDataAsync() function starts the asynchronous process to change application-defined data. The end of that process can be detected with the IsCompletedUpdateApplicationData() function. The GetUpdateApplicationDataResult() function returns a result of true for IsSuccess() when the process is successful.

Matchmaking Priority

To change matchmaking priority, call the UpdateSelectionPriority() function. Updating to a value other than 0 or nn::pia::inet::SESSION_MAX_SELECTION_PRIORITY requires you to wait 30 seconds from the prior call.

Use the IsUpdatableSelectionPriority() function to determine whether a call is possible.

Code 6-15. Changing the Matchmaking Priority
u8 priority = 0;
u8 temporaryPriority = 1 - priority;
// Check whether the value planned to be changed is updatable.
if (nn::pia::session::Session::GetInstance()->IsUpdatableSelectionPriority(temporaryPriority))
{
    priority = temporaryPriority;
    nn::pia::session::Session::GetInstance()->UpdateSelectionPriority(priority);
}

Batch-Updating Session Settings

Multiple items can be updated all at the same time.

Calling the UpdateSessionSettingAsync() function starts the asynchronous process for the session settings batch update process. The end of that process can be detected with the IsCompletedUpdateSessionSetting() function. The GetUpdateSessionSettingResult() function returns a result of true for IsSuccess() when the process is successful.

Only set the items you want to update for NexUpdateSessionSetting.

The following items can be updated.

  • Session type
  • Minimum number of participants
  • Maximum number of participants.
  • Session attributes
  • Matchmaking session's invite for participation status
  • Matchmaking priority
  • User password
  • Application-defined data
  • Session's description string

The session type can only be updated from inet::SESSION_TYPE_FRIEND to inet::SESSION_TYPE_ANYBODY. The idea is that you would open up matchmaking to random players after gathering friends together.

You can also update the following items used for matchmaking that selects sessions based on scoring. These items are used when updating to the new host information when host migration is enabled.

  • Rating value.
  • Disconnection rate
  • Violation rate
  • IP address used as the standard when determining distance on the Internet
  • Country code