This chapter describes the host migration feature.
You can use the host migration feature with PiaSession to maintain the session when the host leaves. With this feature, when the host leaves the session, authority is transferred to one of the remaining clients, making it the new session host and keeping the session active.
You can change whether host migration is used by setting the bUsingHostMigration member of Session::StartupSetting to true or false.
Two methods are available for selecting the next host in host migration: single-candidate mode and multiple-candidate mode. The features of each mode are as follows.
The next host is selected using single-candidate mode for local communication and multiple-candidate mode for Internet communication.
The host can leave the session without destroying it only when host migration is used. The process for leaving the session is identical to 6.8. Basic Features - Leaving Sessions.
When the host calls the function for leaving the session, the remaining clients start host migration and determine the next host.
When using host migration, events occur that notify the results of the host migration process. The notifications are: "Change of host due to host migration" and "Host migration failure."
// Sample state change event callback function.
void sampleSessionEventCallback( nn::pia::session::Session::EventType eventType, nn::pia::StationId id ) { // The eventType argument is an enumerated type that indicates the content of the state change that occurred. // The id argument is the StationId that indicates the target of the state change that occurred. switch( eventType ) { case nn::pia::session::Session::EVENT_JOIN: { // When the station assigned the id joined. }break; case nn::pia::session::Session::EVENT_LEAVE: { // When the station assigned the id left. }break; case nn::pia::session::Session::EVENT_SESSION_HOST_CHANGED: // Note: Event only used for host migration. { // When the id station becomes the new session host due to host migration. }break; case nn::pia::session::Session::EVENT_HOST_MIGRATION_FAILED: // Note: Event only used for host migration. { // When the host migration process fails. // For this event, the id argument becomes STATION_ID_INVALID. }break; } } |