/*---------------------------------------------------------------------------*
  Project:  Horizon
  File:     rdt.h

  Copyright (C) Nintendo.  All rights reserved.

  These coded instructions, statements, and computer programs contain
  proprietary information of Nintendo of America Inc. and/or Nintendo
  Company Ltd., and are protected by Federal copyright law.  They may
  not be disclosed to third parties or copied or duplicated in any form,
  in whole or in part, without the prior written consent of Nintendo.

  $Rev: 54504 $
 *---------------------------------------------------------------------------*/

#ifdef _WIN32
#include <stdafx.h>
#endif

#ifndef NN_RDT_H_
#define NN_RDT_H_

/*!
    @defgroup nn_rdt  Reliable Local Communication (RDT) Library
    @brief  A library for reliable local communication.

@section nn_rdt_overview  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 <tt>Receiver</tt> 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 <i>CTR Programming Manual: Wireless Communication</i> 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.


@subsection nn_rdt_sender  <tt>Sender</tt> Class
nn::rdt::Sender<br />
Class that represents a device sending data. Sends data to the <tt>Receiver</tt> class described later.
The <tt>Sender</tt> 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.



@subsection nn_rdt_receiver  <tt>Receiver</tt> Class
nn::rdt::Receiver<br />
Class that represents a device receiving data. Receives the data sent from the <tt>Sender</tt> 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.



@subsection nn_rdt_uds_setup  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.


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


@subsection nn_rdt_non_blocking_ops  Non-blocking Operations
Function calls in the RDT class library do not block.
The <tt>nn::rdt::Sender::Open</tt>, <tt>nn::rdt::Receiver::Wait</tt>, <tt>nn::rdt::Sender::Send</tt>, and <tt>nn::rdt::Receiver::Receive</tt> functions return immediately when called. 
The functions that actually send and receive data are called by the <tt>Process</tt> function provided in both classes.


@subsection nn_rdt_process  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 <tt>nn::rdt::Sender::Finalize</tt> and <tt>nn::rdt::Receiver::Finalize</tt> functions are called.

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

@subsection nn_rdt_memory_alloc  Memory Allocation
The RDT library does not allocate memory dynamically.
Applications provide any memory required by the library when calling the <tt>nn::rdt::Initialize</tt> function. 
<b>Note:</b> When providing this memory, pay attention to its alignment.


@section nn_rdt_cautions  Cautions
Only <tt>Receiver</tt> knows whether all data was received.
Only when <tt>Receiver</tt> is in a state of having completed receiving data (<tt>RECEIVER_STATE_WAITING_FINISHED</tt> or <tt>RECEIVER_STATE_FINISHED</tt>) can all data be considered received.
There is no guarantee that <tt>Receiver</tt> has received data even if <tt>Sender</tt> enters the send complete status (<tt>SENDER_STATE_CLOSING</tt> or <tt>SENDER_STATE_CLOSED</tt>).
In addition to a <tt>Sender</tt> and <tt>Receiver</tt>, 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 <tt>nn::uds::EndpointDescriptor</tt> objects per each <tt>Sender</tt> or <tt>Receiver</tt> instance.


*/
/*!
    @ingroup  nn_rdt
    @namespace  nn::rdt
    @brief  Namespace for the Reliable Local Communication (RDT) Library.
*/

#include <nn/rdt/rdt_define.h>
#include <nn/rdt/rdt_Sender.h>
#include <nn/rdt/rdt_Receiver.h>
#include <nn/rdt/rdt_Result.h>
#include <nn/rdt/rdt_Misc.h>

namespace nn
{
namespace rdt
{
using namespace nn::rdt;
}
}


#endif  // end of NN_RDT_H_