CTR Pia  4.11.3
Game Communication Engine
nn::pia::local::LocalNetwork Class Reference

Class for handling the local network. More...

+ Inheritance diagram for nn::pia::local::LocalNetwork:

Public Types

Public Member Functions

nn::Result AllowParticipating ()
 Allows new clients to join the network. More...
 
nn::Result CancelConnectNetworkAsync ()
 Cancels ConnectNetworkAsync asynchronous processes. More...
 
nn::Result CancelScanNetworkAsync ()
 Cancels ScanNetworkAsync asynchronous processes. More...
 
void Cleanup ()
 Cleanup process. More...
 
nn::Result ConnectNetworkAsync (const LocalConnectNetworkSetting *pConnectNetworkSetting)
 Connects to the local network. More...
 
u32 CreateLocalCommunicationId (u32 uniqueId, bool isTrial=false) const
 Creates a local communication ID from a unique ID. More...
 
nn::Result CreateNetworkAsync (const LocalCreateNetworkSetting *pCreateNetworkSetting)
 Creates the local network. More...
 
nn::Result DestroyNetworkAsync ()
 Destroys the local network. More...
 
nn::Result DisallowParticipating (bool isDisallowToReconnect=true)
 Disallows new clients from joining the network. This function does not affect clients that are currently connected. More...
 
nn::Result DisconnectNetworkAsync ()
 Disconnects from the local network. More...
 
void Finalize ()
 Finalizes the instance. More...
 
AllowParticipatingState GetAllowParticipatingState () const
 Gets the state that indicates whether new participants are allowed or denied. More...
 
nn::Result GetApplicationData (void *pBuffer, size_t *pDataSize, size_t bufferSize, const LocalNetworkDescription *pNetworkDescription) const
 Gets the beacon data set by the application. More...
 
nn::Result GetApplicationDataFromBeacon (void *pBuffer, size_t *pDataSize, size_t bufferSize) const
 Gets the data set in the beacon. More...
 
nn::Result GetApplicationDataSize (size_t *pDataSize, const LocalNetworkDescription *pNetworkDescription) const
 Gets the size of the beacon data set by the application. More...
 
nn::Result GetApplicationDataSizeFromBeacon (size_t *pDataSize) const
 Gets the size of the data set in the beacon. More...
 
nn::Result GetAroundNetworkInfoList (LocalAroundNetworkInfo *paLocalAroundNetworkInfoList, u32 *pValidNetworkNum, size_t networkInfoListSize) const
 Gets the information for networks discovered during nearby network search. More...
 
size_t GetBeaconApplicationDataSizeMax () const
 Gets the largest size of data the application can set in the beacon. More...
 
nn::Result GetConnectNetworkResult ()
 Gets the result of ConnectNetworkAsync asynchronous processing. More...
 
nn::Result GetCreateNetworkResult ()
 Gets the result of CreateNetworkAsync asynchronous processing. More...
 
nn::Result GetDestroyNetworkResult ()
 Gets the result of DestroyNetworkAsync asynchronous processing. More...
 
nn::Result GetDisconnectNetworkResult ()
 Gets the result of DisconnectNetworkAsync asynchronous processing. More...
 
DisconnectReason GetDisconnectReason ()
 Gets the reason for being disconnected from the network. More...
 
u32 GetFoundNetworkNum () const
 Gets the number of networks discovered. More...
 
u8 GetLinkLevel () const
 Gets the link level. More...
 
u8 GetNetworkChannel () const
 Gets the IEEE 802.11b/g wireless channel in use. More...
 
nn::Result GetNetworkDescription (LocalNetworkDescription *pLocalNetworkDescription, u32 networkDescriptionIndex)
 Gets the local network information. More...
 
nn::Result GetNetworkDescriptionList (LocalNetworkDescription *paLocalNetworkDescriptionList, u32 *pValidNetworkNum, size_t networkDescriptionListSize)
 Gets the local network information. More...
 
nn::Result GetRadioStrength (u8 *pRadioStrength, u32 descriptionListIndex) const
 Parses a network and gets the signal strength sent from that network. More...
 
nn::Result GetScanNetworkResult ()
 Gets the result of ScanNetworkAsync asynchronous processing. More...
 
nn::Result GetStationInfo (LocalStationInfo *pLocalStationInfo, const common::StationAddress &address) const
 Gets information about the specified station. More...
 
nn::Result GetStationInfoList (LocalStationInfo *paLocalStationInfoList, u8 listLength, u32 networkListIndex) const
 Gets a list of information about the stations participating in the specified network. More...
 
nn::Result Initialize (const LocalNetworkSetting &setting)
 Initializes the instance. Make this call between the BeginSetup and EndSetup functions. More...
 
bool IsAroundNetworkSearchActivated () const
 Gets whether nearby network search has begun. More...
 
bool IsClient () const
 Gets whether the local device is a local network client. More...
 
bool IsCompletedConnectNetwork ()
 Checks the completion of ConnectNetworkAsync asynchronous processing. More...
 
bool IsCompletedCreateNetwork ()
 Checks the completion of CreateNetworkAsync asynchronous processing. More...
 
bool IsCompletedDestroyNetwork ()
 Checks the completion of DestroyNetworkAsync asynchronous processing. More...
 
bool IsCompletedDisconnectNetwork ()
 Checks the completion of DisconnectNetworkAsync asynchronous processing. More...
 
bool IsCompletedScanNetwork ()
 Checks the completion of ScanNetworkAsync asynchronous processing. More...
 
bool IsConnected () const
 Gets whether there is a connection to the network. More...
 
bool IsDuringHostMigration () const
 Gets whether local host migration is in progress. More...
 
bool IsEnableAroundNetworkSearch () const
 Gets whether nearby network search is enabled. More...
 
bool IsEnableHostMigration () const
 Gets whether local host migration is enabled. More...
 
bool IsHost () const
 Gets whether the local device is the local network host. More...
 
nn::Result ScanNetworkAsync (u32 localCommunicationId, u8 subId)
 Scans for nearby local networks. More...
 
nn::Result SetApplicationDataToBeacon (const void *pData, size_t dataSize)
 Sets data in the beacon. More...
 
nn::Result SetAroundNetworkSearchSetting (const LocalAroundNetworkSearchSetting &setting)
 Sets the parameters for nearby network search. More...
 
nn::Result StartAroundNetworkSearch ()
 Begins nearby network search. More...
 
nn::Result Startup ()
 Startup process. More...
 
nn::Result StopAroundNetworkSearch ()
 Terminates nearby network search. More...
 
virtual void Trace (u64 flag) const
 Prints information that is useful for debugging. More...
 

Static Public Member Functions

static nn::Result CreateInstance ()
 Creates the LocalNetwork class instance (singleton pattern). More...
 
static void DestroyInstance ()
 Destroys the LocalNetwork class instance (singleton pattern).
 
static LocalNetworkGetInstance ()
 Gets the LocalNetwork class instance (singleton pattern). More...
 

Detailed Description

Class for handling the local network.


Revision History:

2014-10-23 The Initialize function now stops on an assert if device memory is passed to Pia.

2014-03-03 Initial version.

Member Enumeration Documentation

Represents the state that allows or denies new participants.

Enumerator
ALLOW_PARTICIPATING_STATE_NONE 

Not connected to the network.

ALLOW_PARTICIPATING_STATE_ALLOW 

New participants are allowed.

ALLOW_PARTICIPATING_STATE_DISALLOW 

New participants are denied.

ALLOW_PARTICIPATING_STATE_ALLOW_ONLY_RECONNECTION 

Only reconnections are allowed.

Enumerates the reason for the disconnection.

Enumerator
DISCONNECT_REASON_BEFORE_COMMUNICATION 

Communication has not yet started.

DISCONNECT_REASON_NETWORK_IS_AVAILABLE 

Connection being maintained.

DISCONNECT_REASON_REQUEST_FROM_MYSELF 

Disconnected from the network due to local action.

DISCONNECT_REASON_REQUEST_FROM_SYSTEM 

Disconnected from the network due to a system request (transition to wireless off mode or sleep mode).

DISCONNECT_REASON_DISCARDED_FROM_NETWORK 

Kicked off the network due to an instruction from the host. Alternatively, the client was disconnected due to degraded connectivity and the host's internal state.

DISCONNECT_REASON_CONNECTION_LOST 

The connection could not be maintained because a beacon could not be received from the host for a certain period due to degraded connectivity.

DISCONNECT_REASON_UNKNOWN 

Disconnected for an unknown reason.

Member Function Documentation

nn::Result nn::pia::local::LocalNetwork::AllowParticipating ( )

Allows new clients to join the network.

This function re-enables connections from new clients that were denied by the DisallowParticipating function.

Note
In some cases, the information set by this function is not carried over to the new network after host migration occurs due to abnormal disconnection of the host.
Attention
This function can only be called by the local network host.
Returns
Returns a Result value indicating success on successful completion.
Error Return Values:

ResultNotInitialized Indicates that the instance is not initialized. Programming error. Fix your program so that this error is not returned.

ResultInvalidState Indicates that the function cannot be executed in this state. Programming error. Fix your program so that this error is not returned.

ResultInvalidConnection Indicates that the device entered wireless off mode. Or, it was disconnected from the local network. Perform cleanup.

nn::Result nn::pia::local::LocalNetwork::CancelConnectNetworkAsync ( )

Cancels ConnectNetworkAsync asynchronous processes.

This function cancels asynchronous processes started by ConnectNetworkAsync. The cancel process advances by periodically calling the nn::pia::common::Scheduler::Dispatch function. The library promptly cancels asynchronous processes after this function is called, but use the IsCompletedConnectNetwork function to check whether the cancellation has completed.

Returns
Returns the result of canceling ConnectNetworkAsync asynchronous processing. On success, returns a Result value for which the IsSuccess function returns true. If this function call fails, one or more of the following Result values is returned.
Error Return Values:
ResultInvalidState Returned when no ConnectNetworkAsync asynchronous processing is being performed. Programming error. Fix your program so that this error is not returned.
See also
ConnectNetworkAsync, IsCompletedConnectNetwork, GetConnectNetworkResult
nn::Result nn::pia::local::LocalNetwork::CancelScanNetworkAsync ( )

Cancels ScanNetworkAsync asynchronous processes.

This function cancels asynchronous processes started by ScanNetworkAsync. The cancel process advances by periodically calling the nn::pia::common::Scheduler::Dispatch function. The library promptly cancels asynchronous functions after this function is called, but use the IsCompletedScanNetwork function to check whether the cancellation has completed.

Returns
Returns the result of canceling ScanNetworkAsync asynchronous processing. On success, returns a Result value for which the IsSuccess function returns true. If this function call fails, one or more of the following Result values is returned.
Error Return Values:
ResultInvalidState Returned when no ConnectNetworkAsync asynchronous processing is being performed. Programming error. Fix your program so that this error is not returned.
See also
ScanNetworkAsync, IsCompletedScanNetwork, GetScanNetworkResult
void nn::pia::local::LocalNetwork::Cleanup ( )

Cleanup process.

See also
Startup
nn::Result nn::pia::local::LocalNetwork::ConnectNetworkAsync ( const LocalConnectNetworkSetting pConnectNetworkSetting)

Connects to the local network.

Starts an asynchronous process that connects to the local network. The device that connects becomes a local host client. The started process advances by periodically calling the nn::pia::common::Scheduler::Dispatch function. Use IsCompletedConnectNetwork to check whether the process has completed and GetConnectNetworkResult to check the result. You can also cancel the process by calling the CancelConnectNetworkAsync function during the process. Even if you cancel the process, wait until you confirm the process completion using IsCompletedConnectNetwork. If you get results that indicate that the process failed (or was canceled), clean up LocalNetwork and start it again.

Parameters
[in]pConnectNetworkSettingSettings for the network to connect to.
Returns
Returns a Result value for which the IsSuccess function returns true if the process is successfully started.
Error Return Values:

ResultNotInitialized Indicates that the LocalNetwork is not initialized. Programming error. Fix your program so that this error is not returned.

ResultInvalidArgument Indicates that an argument is invalid. Programming error. Fix your program so that this error is not returned.

ResultInvalidState Indicates that processes are already running. Alternatively, another asynchronous process is running. Or, the station is already connected. Programming error. Fix your program so that this error is not returned.

ResultDifferentVersion Indicates a different application version or the local network version of the target network. Perform cleanup.

See also
IsCompletedConnectNetwork, GetConnectNetworkResult, CancelConnectNetworkAsync
static nn::Result nn::pia::local::LocalNetwork::CreateInstance ( )
static

Creates the LocalNetwork class instance (singleton pattern).

Returns
Returns a Result value that indicates success if the instance is created successfully.
Error Return Values:

ResultNotInitialized Indicates that the local module is not initialized.

ResultInvalidState Indicates that the instance was created at the wrong time.

ResultAlreadyExists Indicates that an instance has already been created.

u32 nn::pia::local::LocalNetwork::CreateLocalCommunicationId ( u32  uniqueId,
bool  isTrial = false 
) const

Creates a local communication ID from a unique ID.

This function generates a 32-bit value (the local communication ID) to use for local communication from the 20-bit unique ID (the title-specific ID) assigned by the Nintendo Licensing department. If you have not been assigned a unique ID by the Nintendo Licensing department, use one of the unique IDs for game software prototypes (0xFF000 through 0xFF3FF).

Attention
However, for your retail product, be sure to get a unique ID from the Nintendo Licensing department.
Parameters
[in]uniqueIdSpecifies a unique ID. To communicate more than one title, specify the unique ID of any of the titles.
[in]isTrialSpecifies the flag for handling cases where the same unique ID is shared by both the final product and trial version. If you do not want the final product and trial version to communicate with each other, specify a value of true for trial versions. Note: Always set this flag to false in retail products.
Returns
Returns the created local communication ID.
nn::Result nn::pia::local::LocalNetwork::CreateNetworkAsync ( const LocalCreateNetworkSetting pCreateNetworkSetting)

Creates the local network.

Receives the network settings and starts the asynchronous process that creates the local network. The device that creates the network becomes the local network host. The started process advances by periodically calling the nn::pia::common::Scheduler::Dispatch function. Use IsCompletedCreateNetwork to check whether the process has completed and GetCreateNetworkResult to check the result.

Parameters
[in]pCreateNetworkSettingSettings for the network to create.
Returns
Returns a Result value for which the IsSuccess function returns true if the process is successfully started.
Error Return Values:

ResultNotInitialized Indicates that the LocalNetwork is not initialized. Programming error. Fix your program so that this error is not returned.

ResultInvalidArgument Indicates that an argument is invalid. Programming error. Fix your program so that this error is not returned.

ResultInvalidState Indicates that processes are already running. Alternatively, another asynchronous process is running. Or, the station is already connected. Programming error. Fix your program so that this error is not returned.

ResultErrorOccurred Indicates that an internal error occurred. Perform cleanup.

See also
IsCompletedCreateNetwork, GetCreateNetworkResult
nn::Result nn::pia::local::LocalNetwork::DestroyNetworkAsync ( )

Destroys the local network.

Starts an asynchronous process that destroys the local network. The started process advances by periodically calling the nn::pia::common::Scheduler::Dispatch function. Use IsCompletedDestroyNetwork to check whether the process has completed and GetDestroyNetworkResult to check the result. After the process is completed, clean up LocalNetwork.

Attention
This function can only be called by the local network host.
Returns
Returns a Result value for which the IsSuccess function returns true if the process is successfully started.
Error Return Values:

ResultNotInitialized Indicates that the LocalNetwork is not initialized. Programming error. Fix your program so that this error is not returned.

ResultInvalidState Indicates that processes are already running. Alternatively, another asynchronous process is running. Alternatively, the device is not the local network host. Programming error. Fix your program so that this error is not returned.

See also
IsCompletedDestroyNetwork, GetDestroyNetworkResult
nn::Result nn::pia::local::LocalNetwork::DisallowParticipating ( bool  isDisallowToReconnect = true)

Disallows new clients from joining the network. This function does not affect clients that are currently connected.

This feature is intended to deny connections by new clients attempting to connect during interactive gaming. When you want to allow connections again, call the AllowParticipating function.

Note
In some cases, the information set by this function is not carried over to the new network after host migration occurs due to abnormal disconnection of the host.
Attention
This function can only be called by the local network host.
Parameters
[in]isDisallowToReconnectIf set to false, only the clients that were disconnected after calling this function can reconnect.
Returns
Returns a Result value indicating success on successful completion.
Error Return Values:

ResultNotInitialized Indicates that the instance is not initialized. Programming error. Fix your program so that this error is not returned.

ResultInvalidState Indicates that the function cannot be executed in this state. Programming error. Fix your program so that this error is not returned.

ResultInvalidConnection Indicates that the device entered wireless off mode. Or, it was disconnected from the local network. Perform cleanup.

nn::Result nn::pia::local::LocalNetwork::DisconnectNetworkAsync ( )

Disconnects from the local network.

Starts an asynchronous process that disconnects from the local network. When the local device is the local network host, this function succeeds if host migration is enabled, and the manual host migration process starts. The started process advances by periodically calling the nn::pia::common::Scheduler::Dispatch function. Use IsCompletedDisconnectNetwork to check whether the process has completed and GetDisconnectNetworkResult to check the result. After the process is completed, clean up LocalNetwork.

Returns
Returns a Result value for which the IsSuccess function returns true if the process is successfully started.
Error Return Values:

ResultNotInitialized Indicates that the LocalNetwork is not initialized. Programming error. Fix your program so that this error is not returned.

ResultInvalidState Indicates that processes are already running. Alternatively, another asynchronous process is running. Alternatively, the local device is the local network host, but host migration is disabled. Programming error. Fix your program so that this error is not returned.

See also
IsCompletedDisconnectNetwork, GetDisconnectNetworkResult
void nn::pia::local::LocalNetwork::Finalize ( )

Finalizes the instance.

See also
Initialize
AllowParticipatingState nn::pia::local::LocalNetwork::GetAllowParticipatingState ( ) const

Gets the state that indicates whether new participants are allowed or denied.

Returns
Returns whether new participants are allowed or denied.
nn::Result nn::pia::local::LocalNetwork::GetApplicationData ( void *  pBuffer,
size_t *  pDataSize,
size_t  bufferSize,
const LocalNetworkDescription pNetworkDescription 
) const

Gets the beacon data set by the application.

Parameters
[out]pBufferBuffer that stores the data obtained.
[out]pDataSizeSpecifies the size of the data obtained.
[in]bufferSizeThe size of the buffer that stores the data obtained.
[in]pNetworkDescriptionThe information for the network whose data you want to get.
Returns
Returns a Result value indicating success if data was successfully obtained from the network.
Error Return Values:

ResultNotInitialized Indicates that the LocalNetwork is not initialized. Programming error. Fix your program so that this error is not returned.

ResultInvalidArgument Indicates that an argument is invalid. Programming error. Fix your program so that this error is not returned.

ResultNoData There was no data to get.

nn::Result nn::pia::local::LocalNetwork::GetApplicationDataFromBeacon ( void *  pBuffer,
size_t *  pDataSize,
size_t  bufferSize 
) const

Gets the data set in the beacon.

Attention
This function is intended to be called by a device connected to a local network.
This function may not return correct results if called during local host migration. Do not call it during host migration (while the LocalNetwork::IsDuringHostMigration function returns true).
Parameters
[out]pBufferSpecifies the buffer to write data to.
[out]pDataSizeSpecifies the length of the retrieved data.
[in]bufferSizeSpecifies the size of the buffer to write data to.
Returns
Returns a Result value indicating success on successful completion.
Error Return Values:

ResultNotInitialized Indicates that the instance is not initialized. Programming error. Fix your program so that this error is not returned.

ResultInvalidState Indicates that the function cannot be executed in this state. Programming error. Fix your program so that this error is not returned.

ResultInvalidArgument Indicates that an argument is invalid. Programming error. Fix your program so that this error is not returned.

ResultInvalidConnection Indicates that the device entered wireless off mode. Perform cleanup.

ResultNotInCommunication In a state where communication is not possible. Either a disconnect will shortly be detected, or host migration is about to begin. The function may succeed if called after host migration completes.

nn::Result nn::pia::local::LocalNetwork::GetApplicationDataSize ( size_t *  pDataSize,
const LocalNetworkDescription pNetworkDescription 
) const

Gets the size of the beacon data set by the application.

Parameters
[out]pDataSizeSpecifies the size of the beacon data set by the application.
[in]pNetworkDescriptionThe information for the network whose beacon data size you want to get.
Returns
Returns a Result value indicating success if data was successfully obtained from the network.
Error Return Values:

ResultNotInitialized Indicates that the LocalNetwork is not initialized. Programming error. Fix your program so that this error is not returned.

ResultInvalidArgument Indicates that an argument is invalid. Programming error. Fix your program so that this error is not returned.

ResultNoData There was no data to get.

nn::Result nn::pia::local::LocalNetwork::GetApplicationDataSizeFromBeacon ( size_t *  pDataSize) const

Gets the size of the data set in the beacon.

Attention
This function is intended to be called by a device connected to a local network.
This function may not return correct results if called during local host migration. Do not call it during host migration (while the LocalNetwork::IsDuringHostMigration function returns true).
Parameters
[out]pDataSizeThe size of the data set in the beacon.
Returns
Returns a Result value indicating success on successful completion.
Error Return Values:

ResultNotInitialized Indicates that the instance is not initialized. Programming error. Fix your program so that this error is not returned.

ResultInvalidState Indicates that the function cannot be executed in this state. Programming error. Fix your program so that this error is not returned.

ResultInvalidArgument Indicates that an argument is invalid. Programming error. Fix your program so that this error is not returned.

ResultInvalidConnection Indicates that the device entered wireless off mode. Perform cleanup.

ResultNotInCommunication In a state where communication is not possible. Either a disconnect will shortly be detected, or host migration is about to begin. The function may succeed if called after host migration completes.

nn::Result nn::pia::local::LocalNetwork::GetAroundNetworkInfoList ( LocalAroundNetworkInfo paLocalAroundNetworkInfoList,
u32 *  pValidNetworkNum,
size_t  networkInfoListSize 
) const

Gets the information for networks discovered during nearby network search.

Also succeeds if zero networks were discovered. Only succeeds when nearby network search is enabled.

Parameters
[out]paLocalAroundNetworkInfoListThe buffer storing the obtained network information.
[out]pValidNetworkNumThe number of networks for which network information was obtained.
[in]networkInfoListSizeThe size of the buffer storing the obtained network information.
Returns
Returns a Result value indicating that information was obtained successfully.
Error Return Values:

ResultNotInitialized Indicates that the instance is not initialized. Programming error. Fix your program so that this error is not returned.

ResultInvalidState Indicates that the function cannot be executed in this state. Programming error. Fix your program so that this error is not returned.

ResultInvalidArgument Indicates that an argument is invalid. Programming error. Fix your program so that this error is not returned.

size_t nn::pia::local::LocalNetwork::GetBeaconApplicationDataSizeMax ( ) const

Gets the largest size of data the application can set in the beacon.

Returns
Returns the largest size of data the application can set in the beacon.
nn::Result nn::pia::local::LocalNetwork::GetConnectNetworkResult ( )

Gets the result of ConnectNetworkAsync asynchronous processing.

This function gets the results after an asynchronous process started by ConnectNetworkAsync ends.

Returns
Returns the result of ConnectNetworkAsync asynchronous processing. On success, returns a Result value for which the IsSuccess function returns true. If this function call fails, one or more of the following Result values is returned.
Error Return Values:

ResultNotInitialized Indicates that the communication library is not initialized. Programming error. Fix your program so that this error is not returned.

ResultInvalidState Indicates that the function cannot be executed in this state. Alternatively, results cannot be obtained in this state. Programming error. Fix your program so that this error is not returned.

ResultInvalidNetwork Indicates that the connection target network was not found. Perform cleanup.

ResultNetworkIsFull The maximum number of connections has already been exceeded. Perform cleanup.

ResultJoinRequestDenied The host denied the attempt to join. Perform cleanup. Handle appropriately in the application. When an error occurs in Internet communication, If this error occurs during Internet communication, convert to a network error code and display in the error viewer applet/EULA applet. However, during local communication, do not display it as an error with error code in the error viewer applet/EULA applet. Do not use the error/EULA applet (CTR) for local communication errors.

ResultInvalidConnection Indicates that the device entered wireless off mode. Perform cleanup.

ResultTimeOut Timed out. It could also be returned when nn::pia::local::UdsConnectNetworkSetting::m_Passphrase is incorrect. Perform cleanup.

ResultCancelled Canceled. Perform cleanup.

ResultErrorOccurred Indicates that an internal error occurred. Perform cleanup.

See also
ConnectNetworkAsync, IsCompletedConnectNetwork, CancelConnectNetworkAsync
nn::Result nn::pia::local::LocalNetwork::GetCreateNetworkResult ( )

Gets the result of CreateNetworkAsync asynchronous processing.

This function gets the results after an asynchronous process started by CreateNetworkAsync ends.

Returns
Returns the result of CreateNetworkAsync asynchronous processing. On success, returns a Result value for which the IsSuccess function returns true. If this function call fails, one or more of the following Result values is returned.
Error Return Values:

ResultNotInitialized Indicates that the communication library is not initialized. Programming error. Fix your program so that this error is not returned.

ResultInvalidState Indicates that the function cannot be executed in this state. Alternatively, results cannot be obtained in this state. Programming error. Fix your program so that this error is not returned.

ResultInvalidConnection Indicates that the device entered wireless off mode. Perform cleanup.

ResultTimeOut Timed out. Perform cleanup.

ResultCancelled Canceled. Perform cleanup.

ResultErrorOccurred Indicates that an internal error occurred. Perform cleanup.

See also
CreateNetworkAsync, IsCompletedCreateNetwork
nn::Result nn::pia::local::LocalNetwork::GetDestroyNetworkResult ( )

Gets the result of DestroyNetworkAsync asynchronous processing.

This function gets the results after an asynchronous process started by DestroyNetworkAsync ends.

Returns
Returns the result of DestroyNetworkAsync asynchronous processing. On success, returns a Result value for which the IsSuccess function returns true. If this function call fails, one or more of the following Result values is returned.
Error Return Values:

ResultNotInitialized Indicates that the communication library is not initialized. Programming error. Fix your program so that this error is not returned.

ResultInvalidState Indicates that the function cannot be executed in this state. Alternatively, results cannot be obtained in this state. Programming error. Fix your program so that this error is not returned.

ResultInvalidConnection Indicates that the device entered wireless off mode. Perform cleanup.

ResultCancelled Canceled. Perform cleanup.

ResultErrorOccurred Indicates that an internal error occurred. Perform cleanup.

See also
DestroyNetworkAsync, IsCompletedDestroyNetwork
nn::Result nn::pia::local::LocalNetwork::GetDisconnectNetworkResult ( )

Gets the result of DisconnectNetworkAsync asynchronous processing.

This function gets the results after an asynchronous process started by DisconnectNetworkAsync ends.

Returns
Returns the result of DisconnectNetworkAsync asynchronous processing. On success, returns a Result value for which the IsSuccess function returns true. If this function call fails, one or more of the following Result values is returned.
Error Return Values:

ResultNotInitialized Indicates that the communication library is not initialized. Programming error. Fix your program so that this error is not returned.

ResultInvalidState Indicates that the function cannot be executed in this state. Alternatively, results cannot be obtained in this state. Programming error. Fix your program so that this error is not returned.

ResultInvalidConnection Indicates that the device entered wireless off mode. Perform cleanup.

ResultCancelled Canceled. Perform cleanup.

ResultErrorOccurred Indicates that an internal error occurred. Perform cleanup.

See also
DisconnectNetworkAsync, IsCompletedDisconnectNetwork
DisconnectReason nn::pia::local::LocalNetwork::GetDisconnectReason ( )
inline

Gets the reason for being disconnected from the network.

Resets to DISCONNECT_REASON_BEFORE_COMMUNICATION when Startup or Cleanup is called.

Returns
Returns the reason for being disconnected from the network.
u32 nn::pia::local::LocalNetwork::GetFoundNetworkNum ( ) const
inline

Gets the number of networks discovered.

Returns
Returns the number of networks discovered.
static LocalNetwork* nn::pia::local::LocalNetwork::GetInstance ( void  )
inlinestatic

Gets the LocalNetwork class instance (singleton pattern).

Returns a NULL pointer if the instance has not yet been created using the Initialize function.

Returns
Returns a pointer to the LocalNetwork instance.
u8 nn::pia::local::LocalNetwork::GetLinkLevel ( ) const

Gets the link level.

There are four link levels, from 0 through 3. 0: Communication quality is extremely poor, or communication has not been established. 1: Communication quality is poor. 2: Communication quality is not very good. 3: Communication quality is good.

Attention
This function may not return correct results if called during local host migration. Do not call it during host migration (while the LocalNetwork::IsDuringHostMigration function returns true).
Returns
Returns the communication quality of the network currently connected to. If not connected, 0 is returned.
u8 nn::pia::local::LocalNetwork::GetNetworkChannel ( ) const

Gets the IEEE 802.11b/g wireless channel in use.

Attention
This function may not return correct results if called during local host migration. Do not call it during host migration (while the LocalNetwork::IsDuringHostMigration function returns true).
Returns
Returns the current channel. If not connected or if the attempt to get the channel fails, 0 is returned.
nn::Result nn::pia::local::LocalNetwork::GetNetworkDescription ( LocalNetworkDescription pLocalNetworkDescription,
u32  networkDescriptionIndex 
)

Gets the local network information.

Gets the local network information discovered by the ScanNetworkAsync function.

Parameters
[out]pLocalNetworkDescriptionSpecifies the buffer that stores the network information obtained.
[in]networkDescriptionIndexThe index of the network information you want to get.
Returns
Returns a Result value indicating success if information was successfully obtained.
Error Return Values:

ResultNotInitialized Indicates that the LocalNetwork is not initialized. Programming error. Fix your program so that this error is not returned.

ResultInvalidArgument Indicates that an argument is invalid. Programming error. Fix your program so that this error is not returned.

ResultInvalidState Not in a state where data can be retrieved. Programming error. Fix your program so that this error is not returned.

nn::Result nn::pia::local::LocalNetwork::GetNetworkDescriptionList ( LocalNetworkDescription paLocalNetworkDescriptionList,
u32 *  pValidNetworkNum,
size_t  networkDescriptionListSize 
)

Gets the local network information.

Gets a list of the local network information discovered by the ScanNetworkAsync function.

Parameters
[out]paLocalNetworkDescriptionListSpecifies the buffer that stores the obtained network information.
[out]pValidNetworkNumThe number of networks for which network information was obtained.
[in]networkDescriptionListSizeThe size of the buffer that stores the obtained network information.
Returns
Returns a Result value indicating success if information was successfully obtained.
Error Return Values:

ResultNotInitialized Indicates that the LocalNetwork is not initialized. Programming error. Fix your program so that this error is not returned.

ResultInvalidArgument Indicates that an argument is invalid. Programming error. Fix your program so that this error is not returned.

ResultInvalidState Not in a state where data can be retrieved. Programming error. Fix your program so that this error is not returned.

nn::Result nn::pia::local::LocalNetwork::GetRadioStrength ( u8 *  pRadioStrength,
u32  descriptionListIndex 
) const

Parses a network and gets the signal strength sent from that network.

There are four levels of signal strength, from 0 through 3. 0: Communication quality is extremely poor, or communication has not been established. 1: Communication quality is poor. 2: Communication quality is not very good. 3: Communication quality is good.

Attention
The link level retrieved corresponds to the local network information stored when ScanNetworkAsync is executed. To get the saved local network information list, use the GetNetworkDescriptionList function.
Parameters
[out]pRadioStrengthSpecifies a pointer to the variable that records the signal strength. The data is stored only if the network can be analyzed correctly.
[in]descriptionListIndexSpecifies the variable for specifying the network to parse. Specify the network number you want to analyze by index, starting from 0 for the first entry in the local network information list.
Returns
Returns a Result value indicating success on successful completion.
Error Return Values:

ResultInvalidState No information is stored in the local network information list. Alternatively, data cannot be obtained in this state. Programming error. Fix your program so that this error is not returned.

ResultInvalidArgument Indicates that an argument is invalid. Programming error. Fix your program so that this error is not returned.

nn::Result nn::pia::local::LocalNetwork::GetScanNetworkResult ( )

Gets the result of ScanNetworkAsync asynchronous processing.

This function gets the results after an asynchronous process started by ScanNetworkAsync ends.

Returns
Returns the result of ScanNetworkAsync asynchronous processing. On success, returns a Result value for which the IsSuccess function returns true. If this function call fails, one or more of the following Result values is returned.
Error Return Values:

ResultNotInitialized Indicates that the communication library is not initialized. Programming error. Fix your program so that this error is not returned.

ResultInvalidState Indicates that the function cannot be executed in this state. Alternatively, results cannot be obtained in this state. Programming error. Fix your program so that this error is not returned.

ResultInvalidConnection Indicates that the device entered wireless off mode. Perform cleanup.

ResultNegligibleFault Canceled.

ResultErrorOccurred Indicates that an internal error occurred. Perform cleanup.

See also
ScanNetworkAsync, IsCompletedScanNetwork, CancelScanNetworkAsync
nn::Result nn::pia::local::LocalNetwork::GetStationInfo ( LocalStationInfo pLocalStationInfo,
const common::StationAddress address 
) const

Gets information about the specified station.

Parameters
[out]pLocalStationInfoSpecifies the buffer that stores the station information obtained.
[in]addressThe address of the station whose information you want to get.
Returns
Returns a Result value indicating success if information was successfully obtained.
Error Return Values:

ResultNotInitialized Indicates LocalNetwork has not been started. Programming error. Fix your program so that this error is not returned.

ResultInvalidArgument Indicates that an argument is invalid. Programming error. Fix your program so that this error is not returned.

ResultNotFound The target station was not found. You might have been disconnected.

ResultInvalidConnection Indicates that the device entered wireless off mode. Perform cleanup.

nn::Result nn::pia::local::LocalNetwork::GetStationInfoList ( LocalStationInfo paLocalStationInfoList,
u8  listLength,
u32  networkListIndex 
) const

Gets a list of information about the stations participating in the specified network.

Parameters
[out]paLocalStationInfoListSpecifies the buffer that stores the list of station information obtained. The array length must be equal to or greater than the maximum number of stations that can connect to the specified network.
[in]listLengthSpecifies the length of the paLocalStationInfoList array. This must be equal to or greater than the maximum number of stations that can connect to the specified network.
[in]networkListIndexThe index of the network whose information you want to get.
Returns
Returns a Result value indicating success if information was successfully obtained.
Error Return Values:

ResultInvalidArgument Indicates that an argument is invalid. Programming error. Fix your program so that this error is not returned.

ResultInvalidState Indicates that no networks are found. Alternatively, data cannot be obtained in this state. Programming error. Fix your program so that this error is not returned.

ResultNoData Indicates that information could not be obtained.

ResultInvalidConnection Indicates that the device entered wireless off mode. Perform cleanup.

nn::Result nn::pia::local::LocalNetwork::Initialize ( const LocalNetworkSetting setting)

Initializes the instance. Make this call between the BeginSetup and EndSetup functions.

Attention
Device memory cannot be used as the LocalNetwork receive buffer, so common::Initialize stops on an assert if device memory is passed.
Parameters
[in]settingSpecifies various settings.
Returns
Returns a Result value for which the IsSuccess function returns true if execution succeeds. You must make sure that the implementation of this function in your application does not return any errors.
Error Return Values:

ResultAlreadyInitialized Indicates that the instance is already initialized. Programming error. Fix your program so that this error is not returned.

ResultInvalidArgument Indicates that an argument is invalid. Programming error. Fix your program so that this error is not returned.

See also
Finalize
bool nn::pia::local::LocalNetwork::IsAroundNetworkSearchActivated ( ) const

Gets whether nearby network search has begun.

Returns
Returns whether nearby network search has begun.
bool nn::pia::local::LocalNetwork::IsClient ( ) const

Gets whether the local device is a local network client.

Returns
Returns whether the local device is a local network client.
bool nn::pia::local::LocalNetwork::IsCompletedConnectNetwork ( )

Checks the completion of ConnectNetworkAsync asynchronous processing.

This function checks the completion of asynchronous processes started with ConnectNetworkAsync.

Returns
Returns true if the asynchronous process has completed; false otherwise. Returns false if the asynchronous process has not started or if another asynchronous process has been started.
See also
ConnectNetworkAsync, GetConnectNetworkResult, CancelConnectNetworkAsync
bool nn::pia::local::LocalNetwork::IsCompletedCreateNetwork ( )

Checks the completion of CreateNetworkAsync asynchronous processing.

This function checks the completion of asynchronous processes started with CreateNetworkAsync.

Returns
Returns true if the asynchronous process has completed; false otherwise. Returns false if the asynchronous process has not started or if another asynchronous process has been started.
See also
CreateNetworkAsync, GetCreateNetworkResult
bool nn::pia::local::LocalNetwork::IsCompletedDestroyNetwork ( )

Checks the completion of DestroyNetworkAsync asynchronous processing.

This function checks the completion of asynchronous processes started with DestroyNetworkAsync.

Returns
Returns true if the asynchronous process has completed; false otherwise. Returns false if the asynchronous process has not started or if another asynchronous process has been started.
See also
DestroyNetworkAsync, GetDestroyNetworkResult
bool nn::pia::local::LocalNetwork::IsCompletedDisconnectNetwork ( )

Checks the completion of DisconnectNetworkAsync asynchronous processing.

This function checks the completion of asynchronous processes started with DisconnectNetworkAsync.

Returns
Returns true if the asynchronous process has completed; false otherwise. Returns false if the asynchronous process has not started or if another asynchronous process has been started.
See also
DisconnectNetworkAsync, GetDisconnectNetworkResult
bool nn::pia::local::LocalNetwork::IsCompletedScanNetwork ( )

Checks the completion of ScanNetworkAsync asynchronous processing.

This function checks the completion of asynchronous processes started with ScanNetworkAsync.

Returns
Returns true if the asynchronous process has completed; false otherwise. Returns false if the asynchronous process has not started or if another asynchronous process has been started.
See also
ScanNetworkAsync, GetScanNetworkResult, CancelScanNetworkAsync
bool nn::pia::local::LocalNetwork::IsConnected ( ) const
inline

Gets whether there is a connection to the network.

Attention
Note that false could be returned during host migration (while the LocalNetwork::IsDuringHostMigration function returns true).
Returns
Returns whether there is a connection to the network.
bool nn::pia::local::LocalNetwork::IsDuringHostMigration ( ) const

Gets whether local host migration is in progress.

Returns
Returns whether local host migration is in progress.
bool nn::pia::local::LocalNetwork::IsEnableAroundNetworkSearch ( ) const

Gets whether nearby network search is enabled.

Returns
Returns whether nearby network search is enabled.
bool nn::pia::local::LocalNetwork::IsEnableHostMigration ( ) const

Gets whether local host migration is enabled.

Returns
Returns whether local host migration is enabled.
bool nn::pia::local::LocalNetwork::IsHost ( ) const

Gets whether the local device is the local network host.

Returns
Returns whether the local device is the local network host.
nn::Result nn::pia::local::LocalNetwork::ScanNetworkAsync ( u32  localCommunicationId,
u8  subId 
)

Scans for nearby local networks.

Starts an asynchronous process that scans for nearby local networks. Fails if called while connecting to a network. The started process advances by periodically calling the nn::pia::common::Scheduler::Dispatch function. Use IsCompletedScanNetwork to check whether the process has completed and GetScanNetworkResult to check the result. You can also cancel the process by calling the CancelScanNetworkAsync function during the process. Even if you cancel the process, wait until you can confirm the process completion using IsCompletedScanNetwork. Use GetNetworkDescriptionList and GetNetworkDescription to get information on the local networks that were found through scanning. Use GetStationInfoList to get information on the connected stations that were found through scanning. Get the strength of the signal sent from the network by calling GetRadioStrength. These items of information become available after the network scanning ends successfully. If scanning starts again, they can no longer be obtained. The information is also no longer available when you begin the process of creating or connecting to a network.

Parameters
[in]localCommunicationIdSpecifies the local communication ID. Specify the value generated by CreateLocalCommunicationId.
[in]subIdSpecifies the ID for identifying the communication mode. The application can set any arbitrary value for this parameter. To search all IDs, specify 0xff.
Returns
Returns a Result value for which the IsSuccess function returns true if the process is successfully started.
Error Return Values:

ResultNotInitialized Indicates that the LocalNetwork is not initialized. Programming error. Fix your program so that this error is not returned.

ResultInvalidState Indicates that processes are already running. Alternatively, another asynchronous process is running. Alternatively, the system is already connected to the network. Programming error. Fix your program so that this error is not returned.

See also
IsCompletedScanNetwork, GetScanNetworkResult, CancelScanNetworkAsync
nn::Result nn::pia::local::LocalNetwork::SetApplicationDataToBeacon ( const void *  pData,
size_t  dataSize 
)

Sets data in the beacon.

Only the local network host can execute this function.

Attention
This function may not return correct results if called during local host migration. Do not call it during host migration (while the LocalNetwork::IsDuringHostMigration function returns true).
Parameters
[in]pDataSpecifies a pointer to the data to set.
[in]dataSizeSpecifies the size of the data to set. The size must be no greater than the value that can be obtained with GetBeaconApplicationDataSizeMax.
Returns
Returns a Result value indicating success on successful completion.
Error Return Values:

ResultNotInitialized Indicates that the instance is not initialized. Programming error. Fix your program so that this error is not returned.

ResultInvalidState Indicates that the function cannot be executed in this state. Programming error. Fix your program so that this error is not returned.

ResultInvalidArgument Indicates that an argument is invalid. Programming error. Fix your program so that this error is not returned.

ResultInvalidConnection Indicates that the device entered wireless off mode. Or, it was disconnected from the local network. Perform cleanup.

nn::Result nn::pia::local::LocalNetwork::SetAroundNetworkSearchSetting ( const LocalAroundNetworkSearchSetting setting)

Sets the parameters for nearby network search.

Settings are not shared with other stations. To do so, configure each and every station. Only succeeds when nearby network search is enabled.

Parameters
[in]settingThe parameters for nearby network search.
Returns
Returns a Result value indicating a successful setting was made.
Error Return Values:

ResultNotInitialized Indicates that the instance is not initialized. Programming error. Fix your program so that this error is not returned.

ResultInvalidState Indicates that the function cannot be executed in this state. Programming error. Fix your program so that this error is not returned.

nn::Result nn::pia::local::LocalNetwork::StartAroundNetworkSearch ( )

Begins nearby network search.

Only the local network host can execute this function. Only succeeds when nearby network search is enabled. After this API is called, start notification is also sent to the clients.

Returns
Returns a Result value indicating a successful start to nearby network search.
Error Return Values:

ResultNotInitialized Indicates that the instance is not initialized. Programming error. Fix your program so that this error is not returned.

ResultInvalidState Indicates that the function cannot be executed in this state. Programming error. Fix your program so that this error is not returned.

nn::Result nn::pia::local::LocalNetwork::Startup ( )

Startup process.

Attention
Do not transition to sleep mode during a call to this function.
Returns
Returns a Result value for which the IsSuccess function returns true if execution succeeds.
Error Return Values:

ResultInvalidConnection Indicates that the device entered wireless off mode. Perform cleanup.

ResultInvalidState Indicates that the function cannot be executed in this state. Programming error. Fix your program so that this error is not returned.

See also
Cleanup
nn::Result nn::pia::local::LocalNetwork::StopAroundNetworkSearch ( )

Terminates nearby network search.

Only the local network host can execute this function. Only succeeds when nearby network search is enabled. After termination, any discovered networks are no longer available. After this API is called, termination notification is also sent to the clients.

Returns
Returns a Result value indicating a successful termination to nearby network search.
Error Return Values:

ResultNotInitialized Indicates that the instance is not initialized. Programming error. Fix your program so that this error is not returned.

ResultInvalidState Indicates that the function cannot be executed in this state. Programming error. Fix your program so that this error is not returned.

virtual void nn::pia::local::LocalNetwork::Trace ( u64  flag) const
virtual

Prints information that is useful for debugging.

Parameters
[in]flagSpecifies the bitwise OR of trace flags. For more information, see the TraceFlag type.