Cafe SDK  Version 2.13
API References for nn Library Modules
 All Data Structures Namespaces Functions Variables Typedefs Enumerations Enumerator Groups Pages
Modules | Namespaces
Reliable Local Communication (RDT) Library

A library for reliable local communication. More...

Modules

 Reliable Local Communication (RDT) API
 This is a list of Reliable Local Communication (RDT) library API members. (Includes only C++ API members.)
 
 Reliable Local Communication (RDT) Results
 A list of Results used in the Reliable Local Communication (RDT) library.
 

Namespaces

namespace  nn::rdt
 Namespace for the Reliable Local Communication (RDT) Library.
 

Detailed Description

A library for reliable local communication.

Overview

The RDT library uses features of the UDS library to implement reliable communication of data (in which the data is not corrupted or dropped).

(Only Receiver knows whether all data was received. For more information, see the note later in this section.) The RDT library for Cafe can communicate with the RDT library for CTR. Programming using RDT is the same as for CTR. In addition to this API reference, see the CTR Programming Manual: Wireless Communication provided for the CTR.

RDT was designed to send and receive relatively large amounts of data (more than a few dozen kilobytes).

It does not perform very well, however, in situations where small chunks of data (under 1 KB) are frequently being sent and received.

<tt>Sender</tt> Class

nn::rdt::Sender
Class that represents a device sending data. Sends data to the Receiver class described later. The Sender class implements retransmission and other features that ensure that data that is sent is always received, even if errors like packet loss occur during communication.

<tt>Receiver</tt> Class

nn::rdt::Receiver
Class that represents a device receiving data. Receives the data sent from the Sender class described earlier. The application is guaranteed to receive bytes in the order sent because the receiver rebuilds the data in the correct order while sending the appropriate response codes as data is being received.

UDS Setup

Before an application can use RDT, it must first set up UDS. In other words, the application must first form the network, connect to it, and enable UDS communication, before initializing the RDT library.

Setting up UDS communication is the responsibility of the application. The same is true for freeing the network that is created.

Features

The RDT class library involves a unidirectional flow of raw data from the Sender to the Receiver. To transfer data in both directions, you must create another Sender/Receiver pair.

Non-blocking Operations

Function calls in the RDT class library do not block. The nn::rdt::Sender::Open, nn::rdt::Receiver::Wait, nn::rdt::Sender::Send, and nn::rdt::Receiver::Receive functions return immediately when called. The functions that actually send and receive data are called by the Process function provided in both classes.

The <tt>Process</tt> Function

Even when running in background mode, applications must always call this function at least every game frame (always less than 50 ms) until the nn::rdt::Sender::Finalize and nn::rdt::Receiver::Finalize functions are called.

If Process is not called periodically, no actual communication or state transitions occur. (Although a few functions, including Cancel, are exceptions to that rule.) You can sometimes improve performance of sending and receiving data by calling the Process function several times in a row.

Memory Allocation

The RDT library does not allocate memory dynamically. Applications provide any memory required by the library when calling the nn::rdt::Initialize function. Note: When providing this memory, pay attention to its alignment.

Cautions

Only Receiver knows whether all data was received. Only when Receiver is in a state of having completed receiving data (RECEIVER_STATE_WAITING_FINISHED or RECEIVER_STATE_FINISHED) can all data be considered received. There is no guarantee that Receiver has received data even if Sender enters the send complete status (SENDER_STATE_CLOSING or SENDER_STATE_CLOSED). In addition to a Sender and Receiver, a session for controlling the transfer of data is required to reliably send and receive data with the RDT library. For more information, see the sample demos.

The RDT library implicitly consumes two nn::uds::EndpointDescriptor objects per each Sender or Receiver instance.