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

Function Blocking

With the exception of the GetLinkLevel function, all of the UDS library functions can be blocked by several milliseconds, depending on the situation. (Stated in the Function Reference that if the block time is greater than 100 ms it is the reference value.)

Note that this can cause problems such as unstable frame rates when these functions are called within the main thread.

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 the destination. 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 the destination.

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. When the packets are addressed to BROADCAST_NODE_ID or certain nodes, the order in which they 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.

Specification for TemporaryID with UDS Communication

When a device builds a network and operates as the master, usually a random number is generated and used as the TemporaryID for that network so the network can be distinguished from a network built by the same device and on which local communications have taken place, but on which communications have been broken and resumed.

However, if a TemporaryID is generated every single time a network is built, consider what happens when you implement an algorithm like the one shown below in order to build networks without the end user being aware of whether they are master or client:

1: Become a master (build a network).
2: If cannot find peer to connect with after set period of time, destroy the network.
3: Search for nearby networks, and if a network for the same application exists, connect to that network as a client.
4. If cannot find peer to connect with, repeat these steps.

With this kind of algorithm, devices try to connect based on their search results, but because a TemporaryID is generated every single time a network is built, there are frequent times when peers cannot connect because the master device has rebuilt its network. The upshot is that the implementer is not able to realize the expected behavior.

UDS communication provides for the following exception:

Do not update the TemporaryID when rebuilding the network if no clients are connected and communication between devices has not been established.
(However, if it has been a long time since the network was rebuilt, assume the network being built has no relation to the previous network and go ahead and update the TemporaryID.)


Contact Nintendo if there is a problem implementing this specification in your application.

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. If the Master application is not intentionally prohibiting connection, the corresponding error may also occur when the connection cannot be made due to poor signal quality conditions.
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 the system entered wireless-disabled mode after the UDS library was initialized.
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::ResultMisalignedAddress Indicates that the address alignment is invalid.
nn::uds::CTR::ResultMisalignedSize Indicates that the size alignment is invalid.
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.
nn::uds::CTR::ResultInvalidData Indicates that the data that was received was invalid.

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).

Constants

Transmission Data Sizes
NET_DESC_APPDATA_SIZE_MAX const u8 Maximum size of optional data that can be set for the beacon.
UDS_PACKET_PAYLOAD_MAX_SIZE const u16 Maximum size of the data that can be sent in a single call to nn::uds::CTR::SendTo.
ATTACH_BUFFER_SIZE_MIN const size_t Minimum size of the receive buffer specified in a call to the Attach function. This value is the sum of the UDS_PACKET_PAYLOAD_MAX_SIZE and the system management region.
ATTACH_BUFFER_SIZE_DEFAULT const size_t Default size of the receive buffer specified in a call to the Attach function.
Passphrase String Length
UDS_PASSPHRASE_LENGTH_MIN const size_t Minimum size of the passphrase for generating the encrypted key used in communication.
UDS_PASSPHRASE_LENGTH_MAX const size_t Maximum size of the passphrase for generating the encrypted key used in communication.
Send/Receive Options
NO_WAIT const bit8 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 const bit8 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.
Other
BROADCAST_NODE_ID const u16 Node ID indicating the broadcast address for the network. Even spectators can receive data sent to BROADCAST_NODE_ID.
NODE_MAX const u8 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 const u8 The maximum number of endpoints that can be created. This value is subject to change.
S SCRAMBLED_LOCAL_FRIEND_CODE_SIZE const size_t 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.

This function is thread-safe.
DisallowToConnect Disallows client nodes to connect to the network. Does not affect 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
GetConnectionStatus Returns the current connection status.
GetLinkLevel Gets the current link level.
GetChannel Gets the current channel.

This function is thread-safe.
GetNodeInformation Gets information about the specified node.

This function is thread-safe.
SetApplicationDataToBeacon Sets optional data in the beacon.
GetApplicationDataFromBeacon Gets the data set to the beacon.

Revision History

2012/04/02
Added a result for ResultInvalidData.
2012/03/13
Added description of time before re-issuing ID to the specification for the TemporaryId.
2012/02/13
Added a specification for TemporaryId.
2012/01/20
Added thread safe and unsafe information for each function.
2011/01/25
Added description that almost all library functions can block.
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