nn::uds::CTR Namespace

Description

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

This library is used to run UDS communication, Nintendo's unique local wireless communication. For details on UDS communication, see the programming manuals.

Notes

Sleep Mode During UDS Communication

Sleep Mode Is Prohibited During Initialize

Do not enter Sleep Mode while the Initialize function is running. The process of transitioning the communication system to UDS mode may conflict with background communication processing when the system enters Sleep Mode, resulting in incorrect behavior.

Sleep Mode Transitions During Communication

Because the system cannot maintain UDS communication during Sleep Mode, applications must shut down the UDS library before allowing the system to enter Sleep Mode.

If the system enters Sleep Mode without shutting down the UDS library, the UDS library forces all communication in progress to end immediately before the entire system enters Sleep Mode, resulting in an internal state of STATE_ERROR. Once the library has fallen into this state, all functions except for a few (such as Finalize and GetConnectionStatus) return an error.

Guaranteeing Packet Arrival

The UDS library itself does not guarantee that packets have actually been sent to communication peers. A packet loss of approximately 1-2% is normal and in some cases may be 10%. Do not use code that assumes the packets you send will always reach your communication peer.

Packet Order

As long as packets are sent to the same node with the same options specified, they are guaranteed to be sent in the same order. The order in which packets addressed to BROADCAST_NODE_ID and packets addressed to a specific node are sent and received may be swapped. Similarly, the order in which they are sent and received may also be swapped when you switch between using the FORCE_DIRECT_BC and FORCE_UNICAST options.

Classes

Handling the Results of the Scan Function
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.
Result
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 when the node attempts to send a packet to itself or when the connection target disconnects 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 Indicates that a transition to wireless OFF mode occurred after initializing the UDS library.
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::ResultMiscellaneousSystemError A temporary failure resulting from something on the system side. Normally, if you retry with the same arguments, the function will succeed.
nn::uds::CTR::ResultNotImplemented Indicates that although a function has been prepared, its operation has not yet been implemented.
nn::uds::CTR::ResultMalformedData Indicates that the data is not appropriate and that there is a possibility that the received data may have been tampered with.

Structures

nn::uds::CTR::ConnectionStatus Structure indicating the UDS connection status.
nn::uds::CTR::ScrambledLocalFriendCode This structure stores information that can be converted to a local friend code using the friends library.
nn::uds::CTR::NodeInformation Structure that stores user information about nodes connected to the network.
nn::uds::CTR::EndpointDescriptor Endpoint descriptor. This corresponds to a socket descriptor.

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 functions, the wireless transmission ends immediately, even if no data has been received.
FORCE_DIRECT_BC When SendTo has been specified, sends using Direct Broadcast without asking for a recipient. Among clients, Unicast communication takes place without the use of a master. As a result you can have low latency communication, but the hidden node problem arises.
FORCE_UNICAST When SendTo has been specified, the client sends a packet always via a master. There is no need to consider the hidden node problem, but the latency of the client's send becomes higher.
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. In the future, we plan to support communication for 16 devices, but as of CTR-SDK 0.14 we cannot confirm sufficient operations with that many devices, so communications with 13 or more devices exceeds the guaranteed range of operations.
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.
S SCRAMBLED_LOCAL_FRIEND_CODE_SIZE The byte length of ScrambledLocalFriendCode.

Functions

Initialization & Shutdown
Initialize Initializes the UDS library. Initialization fails if any other communication features are already in use.
Finalize Finalizes the UDS library. After executing, other communication features become usable.
Networks (Creating, Destroying, Connecting, and Disconnecting)
CreateLocalCommunicationId A local communication ID is generated from a unique ID.
CreateNetwork Creates a new 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.
DisallowToConnect Disallows client nodes to connect to the network. Does not effect clients currently connected.
AllowToConnect Allows client nodes to connect to the network.
EjectSpectator Kicks all the connected spectators off of the network.
AllowToSpectate Allows Spectator nodes to connect to the network.
DestroyNetwork Destroys the network.
DisconnectNetwork Disconnects a given node from the network to which it is currently connected.
Sending and Receiving Data
CreateEndpoint Creates a network endpoint and returns the corresponding descriptor.
SetMaxSendDelay Specifies the maximum send delay time.
SendTo Sends data to the specified port on the specified partner's system.
Attach Makes the endpoint into a packet-receivable state.
Receive Receives data. (There is no way to obtain the address of the sender.)
ReceiveFrom Receives data.
DestroyEndpoint Destroys an endpoint.
Other
GetMacAddress Gets the MAC address of the local host. (Used in debugging)
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 has not yet been implemented.)
SetApplicationDataToBeacon Sets optional data in the beacon.
GetApplicationDataFromBeacon Gets the data set to the beacon.

Revision History

2010/12/15
Added information to Description and Notes.
2010/10/22
Updated the members of the nn::uds::NodeInformation structure.
2010/10/15
Added as a reference to the functions that return nn::Result information on what values are returned. Deleted the not-yet-implemented function, SetNetworkAttribute. Added a new function, SetMaxSendDelay, which configures the maximum send delay time. Added a new ResultMalformedData error. Added a new ResultMiscellaneousSystemError error. Added a function to cut off a connection to a network, DisallowToConnect, and a function to re-allow a connection, AllowToConnect.
2010/06/14
Initial version.

CONFIDENTIAL