nn::uds::CTR Namespace

Description

The CTR UDS (local communication) namespace.
(This can also be written without the "::CTR" portion.)

Classes

nn::uds::CTR::NetworkDescription Class indicating network information that can be obtained using nn::uds::CTR::NetworkDescriptionReader.
nn::uds::CTR::NetworkDescriptionReader Class for analyzing all types of network information that can be obtained using nn::uds::CTR::ScanResultReader.
nn::uds::CTR::ScanResultReader Class for analyzing the scan results obtained by nn::uds::CTR::Scan.
nn::uds::CTR::ResultNotFoundNetwork Indicates that the network to which a connection was attempted using ConnectNetwork was not found.
nn::uds::CTR::ResultAlreadyNetworkIsFull Indicates that the network to which a connection was attempted using ConnectNetwork is full (the number of devices connected to that network has already reached the maximum).
nn::uds::CTR::ResultDeniedFromMaster Indicates that the attempt to connect to the network using ConnectNetwork was denied by the master for some reason.
nn::uds::CTR::ResultConnectionTimeout Indicates that the attempted connection to the network made using ConnectNetwork timed out during the connection process.
nn::uds::CTR::ResultInvalidState Indicates that the library is not in a state in which a function could be run. This can also occur if the connection cuts out during communication.
nn::uds::CTR::ResultInvalidNode Indicates that the node with the specified node ID does not exist on the network. This can also occur if the target has been disconnected from the network.
nn::uds::CTR::ResultOutOfResource Indicates that the library is out of resources. This can occur if the total size of the receive buffer specified by the Attach function exceeds that of the buffer specified when the Initialize function was called.
nn::uds::CTR::ResultBufferIsFull This mostly occurs if SendTo is called with high frequency, and send operations get backed up. The data being sent will be lost if an error occurs.
nn::uds::CTR::ResultWirelessOff If the system enters wireless-disabled mode after the UDS library is initialized, all functions other than Initialize and Finalize will return this error.
nn::uds::CTR::ResultNotInitialized Indicates that the library has not been initialized. This error can be resolved by calling the Initialize function.
nn::uds::CTR::ResultAlreadyOccupiedWirelessDevice Indicates that UDS communication cannot be used at the moment because other communication is already in progress.
nn::uds::CTR::ResultOutOfRange Indicates that one or more of the arguments were set to values outside their valid ranges.
nn::uds::CTR::ResultTooLarge Indicates that one or more of the arguments had data that exceeded the maximum size. This occurs for functions that send data.
nn::uds::CTR::ResultNotAuthorized Indicates that one or more of the arguments contain a value that is only permitted in special cases.
nn::uds::CTR::ResultNotImplemented Indicates that although a function has been prepared, its operation has not yet been implemented.

Structures

nn::uds::CTR::ConnectionStatus Structure indicating the UDS connection status.
nn::uds::CTR::NodeInformation Structure indicating user information for connected nodes on the network.
nn::uds::CTR::EndpointDescriptor Endpoint descriptor. This corresponds to a socket descriptor. Currently this only contains an ID, but other fields might be added in the future.

Enumerated Types

State Enumerated type representing UDS states.
DisconnectReason Enumerated type representing the reasons for disconnection.
ConnectType Enumerated type that represents modes used during connection to the network.
PowerSaveMode Enumerated type representing the network's power-saving modes.
LinkLevel Enumerated type that represents the communication quality (link level). The link levels are being adjusted.

Constants

Local Communication ID
TEST_UNIQUE_ID_MASK For a test program, experimental project, or at any other time that an application does not have a unique ID assigned to it, you can use a value between 0xFFF00 and 0xFFFFF as a test ID. These values are also used by SDK samples.
Send/Receive Options
NO_WAIT If this constant is specified as an argument to the SendTo function, wireless transmission occurs immediately without buffering within the UDS library.
If this constant is specified as an argument to either the Receive or ReceiveFrom function, the wireless transmission ends immediately, even if no data has been received.
Other
BROADCAST_NODE_ID Node ID indicating the broadcast address for the network. Even spectators can receive data sent to BROADCAST_NODE_ID.
NODE_MAX Maximum value for the maximum number of network connections. This value is currently being adjusted, so behavior is not guaranteed for communication between 12 or more systems.
ENDPOINT_MAX The maximum number of endpoints that can be created. This value is subject to change.
UDS_PACKET_PAYLOAD_MAX_SIZE Maximum size of the data that can be sent in a single call to nn::uds::CTR::SendTo.
NET_DESC_APPDATA_SIZE_MAX Maximum size of optional data that can be set for the beacon.

Functions

Initialization & Shutdown
Initialize Initializes the UDS library. Initialization fails if any other communication features are already in use. This function may block for a long time because it finalizes communications in the background and the UDS library takes control of the communication device until Finalize is run.
Finalize Finalizes the UDS library. The UDS library uses the the receive buffer specified by the Initialize function until this function completes. The events received by the Initialize function that notify of connection status updates are also finalized here.
Networks (Creating, Destroying, Connecting, and Disconnecting)
CreateLocalCommunicationId Generates a 32-bit value (the local communication ID) to use for UDS communication from the 20-bit unique ID assigned by the Submissions department (submissions@noa.nintendo.com).
CreateNetwork Creates a new local network.
Scan Scans for nearby networks.
ConnectNetwork Connects to an existing network.
EjectClient Kicks the specified node off of the network. Only the master can run this function.
EjectSpectator Kicks all the connected spectators off of the network. New Spectator nodes will be unable to connect after you run this function. To allow Spectator nodes to connect again, call the AllowToSpectate function. Only the master can run this function.
AllowToSpectate Allows Spectator nodes to connect to the network. Because this is allowed by default, use this function after the EjectSpectator function to allow Spectator nodes to connect to the network again. Only the master can run this function.
DestroyNetwork Kicks off all connected clients, then destroys the local network. Only the master can run this function.
DisconnectNetwork Disconnects a given node from the network to which it is currently connected. It is preferable to also run this function before reconnecting after an unintended disconnection. Only clients and spectators can run this function.
Sending and Receiving Data
CreateEndpoint Creates a network endpoint and returns the corresponding descriptor. [Provisional spec] Currently, up to 16 endpoints can be created.
SendTo Sends data to the specified port on the specified partner's system. This function blocks until it has finished sending data.
Attach Attaches the specified port and node ID to the descriptor. When doing so, the system creates a receive buffer for receiving data.
Receive Receives data. (There is no way to obtain the address of the sender.)
ReceiveFrom Receives data. (It is possible to get the address of the sender.)
DestroyEndpoint Destroys an endpoint. At the same time, frees the receive buffer created when Attach was called.
Other
GetMacAddress Gets the MAC address of the local host.
GetConnectionStatus Returns the current connection status.
GetLinkLevel Gets the current link level.
GetNodeInformation Gets information about the specified node.
SetPowerSaveMode Changes the power-saving mode. (This can be changed either before or during communication.) Only a master node can change this setting. Clients and spectators follow the master setting. This function is not yet implemented. It will always fail if run.
SetNetworkAttribute Changes the network attributes. This function is not yet implemented. It will always fail if run.
SetApplicationDataToBeacon Sets optional data for a beacon (up to NET_DESC_APPDATA_SIZE_MAX bytes can be set). Only the master can run this function. Other devices can obtain this data by calling Scan while they are connected as clients or spectators.
GetApplicationDataFromBeacon Retrieves data that is set for a beacon (up to NET_DESC_APPDATA_SIZE_MAX bytes can be retrieved). This can only be run when connected to network.

Note: Applications communicating as clients or spectators will not be notified when data is updated.

Revision History

2010/06/14
Initial version.

CONFIDENTIAL