This section describes procedures and important information for when you use mesh networks for PiaLocal local communications.
When using PiaLocal, initialize the modules in the following order.
For more information about each of these processes, see the appropriate pages of the programming manual.
Alternatively, you can perform the initialization in steps 3 and 4 after step 6.
When using PiaLocal, finalize the modules in the following order.
For more information about each of these processes, see the appropriate pages of the programming manual.
Alternatively, you can perform the finalizations in steps 6 and 7 before step 4.
The session communication may be restarted without finalizing the module by first disconnecting from the network in step 4, cleaning up using the process in step 5, and finally restarting from step 5 of the initialization order.
PiaLocal must be restarted when the wireless switch has been turned off. Perform through step 5 of the finalization order, and then restart from step 5 of the initialization order.
If you intend to act again to create or join a session after destroying or leaving a session, you must first perform all finalization processes through step 5 (clean up PiaLocal). (Steps 6 and beyond in the finalization order are unnecessary.) After you have finished performing these processes, resume the corresponding initialization processes.
Initialize PiaLocal as follows.
nn::Result result;
// Initialize the local module. result = nn::pia::local::Initialize(); PIA_ASSERT(result.IsSuccess()); // Start setup of the local module. result = nn::pia::local::BeginSetup(); PIA_ASSERT(result.IsSuccess()); // Create an instance of LocalNetwork. result = nn::pia::local::LocalNetwork::CreateInstance(); PIA_ASSERT(result.IsSuccess()); // Prepare settings to pass to Initialize. nn::pia::local::UdsNetworkSetting setting; setting.m_ReceiveBufferSize = UDS_RECEIVE_BUFFER_SIZE; setting.m_ScanBufferSize = UDS_SCAN_BUFFER_SIZE; setting.m_SendOption = UDS_SEND_OPTION; setting.m_ReceiveOption = UDS_RECEIVE_OPTION; setting.m_IsEnableHostMigration = ENABLE_HOST_MIGRATION; // Initialize LocalNetwork. result = nn::pia::local::LocalNetwork::GetInstance()->Initialize(setting); PIA_SAMPLE_ASSERT_RESULT_IS_SUCCESS(result); // Create an instance of LocalFacade. result = nn::pia::local::LocalFacade::CreateInstance(); PIA_ASSERT(result.IsSuccess()); // End the setup of the local module. result = nn::pia::local::EndSetup(); PIA_ASSERT(result.IsSuccess()); |
Start PiaLocal as follows.
// LocalNetwork startup.
result = nn::pia::local::LocalNetwork::GetInstance()->Startup(); if (result.IsFailure()) { if (result == nn::pia::ResultInvalidConnection()) { // Initialization failed because wireless is off. } else { // Initialization failed for some other reason. } } |
This section describes how to create a network. This procedure uses an asynchronous process. Advance the process by calling the common::Scheduler::Dispatch() function. The station that succeeds in creating the network becomes the local network host. After the network is successfully created, run the startup processes and then create the session.
nn::Result result;
// Prepare settings to pass to CreateNetworkAsync. nn::pia::local::UdsCreateNetworkSetting createNetworkSetting; createNetworkSetting.m_SubId = SUB_ID; createNetworkSetting.m_MaxEntry = MAX_ENTRY; createNetworkSetting.m_LocalCommunicationId = nn::pia::local::LocalNetwork::GetInstance()->CreateLocalCommunicationId(TITLE_ID); memcpy(createNetworkSetting.m_Passphrase, PASSPHRASE, sizeof(PASSPHRASE)); createNetworkSetting.m_PassphraseLength = sizeof(PASSPHRASE); createNetworkSetting.m_Channel = CHANNEL; memcpy(createNetworkSetting.m_ApplicationData, APPLICATION_DATA, sizeof(APPLICATION_DATA)); createNetworkSetting.m_ApplicationDataSize = sizeof(APPLICATION_DATA); // Start to create the network. result = nn::pia::local::LocalNetwork::GetInstance()->CreateNetworkAsync(&createNetworkSetting); if (result.IsFailure()) { // Error handling. } // Wait for creation of the network to complete. while (nn::pia::local::LocalNetwork::GetInstance()->IsCompletedCreateNetwork() == false) { nn::pia::common::Scheduler::GetInstance()->Dispatch(); } // Get the result of network creation. result = nn::pia::local::LocalNetwork::GetInstance()->GetCreateNetworkResult(); if (result.IsSuccess()) { // Creation of the network succeeded. } else { // Creation of the network failed. } |
This section shows how to search for networks that have been created. This procedure uses an asynchronous process. Advance the process by calling the common::Scheduler::Dispatch() function.
nn::Result result;
// Start searching for networks. u32 communicationId = nn::pia::local::LocalNetwork::GetInstance()->CreateLocalCommunicationId(TITLE_ID); result = nn::pia::local::LocalNetwork::GetInstance()->ScanNetworkAsync(communicationId, SUB_ID); if (result.IsFailure()) { // Error handling. } // Wait for the network search to complete. while (nn::pia::local::LocalNetwork::GetInstance()->IsCompletedScanNetwork() == false) { nn::pia::common::Scheduler::GetInstance()->Dispatch(); } // Get the results of the network search. result = nn::pia::local::LocalNetwork::GetInstance()->GetScanNetworkResult(); if (result.IsSuccess()) { // The search for networks succeeded. // Get the discovered networks. nn::pia::local::UdsNetworkDescription networkDescriptionList[GATHERING_LIST_MAX]; u32 foundNum = 0; result = nn::pia::local::LocalNetwork::GetInstance()->GetNetworkDescriptionList(networkDescriptionList, &foundNum, GATHERING_LIST_MAX); if (result.IsSuccess()) { // Successfully obtained the discovered networks. nn::pia::local::UdsStationInfo stationInfoList[MAX_ENTRY]; for (u32 i = 0; i < foundNum; ++i) { // Get the information for the stations participating in the network. result = nn::pia::local::LocalNetwork::GetInstance()->GetStationInfoList(stationInfoList, MAX_ENTRY, i); if (result.IsSuccess()) { for (u32 j = 0; j < MAX_ENTRY; ++j) { if (stationInfoList[j].m_Role != nn::pia::local::LocalStationInfo::STATION_INFO_ROLE_NONE) { // Get the user names. nn::cfg::CTR::UserName userName = stationInfoList[j].m_UserName; } } } } } else { // Failed to get the discovered networks. } } else { // The network search failed. } |
This section describes how to connect to a network found by a search. This procedure uses an asynchronous process. Advance the process by calling the common::Scheduler::Dispatch() function. The station successfully connecting to a network becomes the local network client. After successfully connecting to the network, run the startup processes and then join the session.
nn::Result result;
// Prepare the settings to pass to ConnectNetworkAsync. nn::pia::local::UdsConnectNetworkSetting connectNetworkSetting; memcpy(connectNetworkSetting.m_Passphrase, PASSPHRASE, sizeof(PASSPHRASE)); connectNetworkSetting.m_PassphraseLength = sizeof(PASSPHRASE); connectNetworkSetting.m_pLocalNetworkDescription = &(networkDescriptionList[targetSession]); // Start connecting to the network. result = nn::pia::local::LocalNetwork::GetInstance()->ConnectNetworkAsync(&connectNetworkSetting); if (result.IsFailure()) { // Error handling. } // Wait for the process of connecting to the network to complete. while (nn::pia::local::LocalNetwork::GetInstance()->IsCompletedConnectNetwork() == false) { nn::pia::common::Scheduler::GetInstance()->Dispatch(); } // Get the result of connecting to the network. result = nn::pia::local::LocalNetwork::GetInstance()->GetConnectNetworkResult(); if (result.IsSuccess()) { // Successfully connected to the network. } else { // Failed to connect to the network. } |
This section describes how to disconnect a station from the network to which it is currently connected. This procedure uses an asynchronous process. Advance the process by calling the common::Scheduler::Dispatch() function. If the local network host runs this process, it only succeeds if host migration is enabled and the local network host runs the host migration process manually.
nn::Result result;
// Start the process of disconnecting from the network. result = nn::pia::local::LocalNetwork::GetInstance()->DisconnectNetworkAsync(); if (result.IsFailure()) { // Error handling. } // Wait for the process of disconnecting from the network to complete. while (nn::pia::local::LocalNetwork::GetInstance()->IsCompletedDisconnectNetwork() == false) { nn::pia::common::Scheduler::GetInstance()->Dispatch(); } // Get the result of disconnecting from the network. result = nn::pia::local::LocalNetwork::GetInstance()->GetDisconnectNetworkResult(); if (result.IsSuccess()) { // Successfully disconnected from the network. } else { // Failed to disconnect from the network. } |
This section shows how to destroy the currently joined network. This procedure uses an asynchronous process. Advance the process by calling the common::Scheduler::Dispatch() function. This process only succeeds on the local network host.
nn::Result result;
// Start the process of destroying the network. result = nn::pia::local::LocalNetwork::GetInstance()->DestroyNetworkAsync(); if (result.IsFailure()) { // Error handling. } // Wait for the process of destroying the network to complete. while (nn::pia::local::LocalNetwork::GetInstance()->IsCompletedDestroyNetwork() == false) { nn::pia::common::Scheduler::GetInstance()->Dispatch(); } // Get the result of destroying the network. result = nn::pia::local::LocalNetwork::GetInstance()->GetDestroyNetworkResult(); if (result.IsSuccess()) { // Successfully destroyed the network. } else { // Failed to destroy the network. } |
Clean up PiaLocal as follows.
// The LocalNetwork cleanup process.
nn::pia::local::LocalNetwork::GetInstance()->Cleanup(); |
When you have finished using PiaLocal, finalize it.
// Destroy the instance of LocalFacade.
nn::pia::local::LocalFacade::DestroyInstance(); // Finalize LocalNetwork. nn::pia::local::LocalNetwork::GetInstance()->Finalize(); // Destroy the instance of LocalNetwork. nn::pia::local::LocalNetwork::DestroyInstance(); // Finalize the local module. nn::pia::local::Finalize(); |