1 /*---------------------------------------------------------------------------* 2 Project: Horizon 3 File: rdt.h 4 5 Copyright (C) 2009-2011 Nintendo. All rights reserved. 6 7 These coded instructions, statements, and computer programs contain 8 proprietary information of Nintendo of America Inc. and/or Nintendo 9 Company Ltd., and are protected by Federal copyright law. They may 10 not be disclosed to third parties or copied or duplicated in any form, 11 in whole or in part, without the prior written consent of Nintendo. 12 13 $Rev: 54504 $ 14 *---------------------------------------------------------------------------*/ 15 16 #ifdef _WIN32 17 #include <stdafx.h> 18 #endif 19 20 #ifndef NN_RDT_H_ 21 #define NN_RDT_H_ 22 23 /*! 24 @defgroup nn_rdt Reliable Local Communication (RDT) Library 25 @brief A library for reliable local communication. 26 27 @section nn_rdt_overview Overview 28 29 The RDT library uses features of the UDS library to implement reliable communication of data (in which the data is not corrupted or dropped). 30 31 (Only <tt>Receiver</tt> knows whether all data was received. For more information, see the note later in this section.) 32 The RDT library for Cafe can communicate with the RDT library for CTR. Programming using RDT is the same as for CTR. 33 In addition to this API reference, see the <i>CTR Programming Manual: Wireless Communication</i> provided for the CTR. 34 35 36 RDT was designed to send and receive relatively large amounts of data (more than a few dozen kilobytes). 37 38 It does not perform very well, however, in situations where small chunks of data (under 1 KB) are frequently being sent and received. 39 40 41 @subsection nn_rdt_sender <tt>Sender</tt> Class 42 nn::rdt::Sender<br /> 43 Class that represents a device sending data. Sends data to the <tt>Receiver</tt> class described later. 44 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. 45 46 47 48 @subsection nn_rdt_receiver <tt>Receiver</tt> Class 49 nn::rdt::Receiver<br /> 50 Class that represents a device receiving data. Receives the data sent from the <tt>Sender</tt> class described earlier. 51 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. 52 53 54 55 @subsection nn_rdt_uds_setup UDS Setup 56 Before an application can use RDT, it must first set up UDS. 57 In other words, the application must first form the network, connect to it, and enable UDS communication, before initializing the RDT library. 58 59 Setting up UDS communication is the responsibility of the application. The same is true for freeing the network that is created. 60 61 62 @subsection nn_rdt_features Features 63 The RDT class library involves a unidirectional flow of raw data from the <tt>Sender</tt> to the <tt>Receiver</tt>. 64 To transfer data in both directions, you must create another <tt>Sender</tt>/<tt>Receiver</tt> pair. 65 66 67 @subsection nn_rdt_non_blocking_ops Non-blocking Operations 68 Function calls in the RDT class library do not block. 69 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. 70 The functions that actually send and receive data are called by the <tt>Process</tt> function provided in both classes. 71 72 73 @subsection nn_rdt_process The <tt>Process</tt> Function 74 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. 75 76 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.) 77 You can sometimes improve performance of sending and receiving data by calling the <tt>Process</tt> function several times in a row. 78 79 @subsection nn_rdt_memory_alloc Memory Allocation 80 The RDT library does not allocate memory dynamically. 81 Applications provide any memory required by the library when calling the <tt>nn::rdt::Initialize</tt> function. 82 <b>Note:</b> When providing this memory, pay attention to its alignment. 83 84 85 @section nn_rdt_cautions Cautions 86 Only <tt>Receiver</tt> knows whether all data was received. 87 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. 88 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>). 89 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. 90 For more information, see the sample demos. 91 92 The RDT library implicitly consumes two <tt>nn::uds::EndpointDescriptor</tt> objects per each <tt>Sender</tt> or <tt>Receiver</tt> instance. 93 94 95 */ 96 /*! 97 @ingroup nn_rdt 98 @namespace nn::rdt 99 @brief Namespace for the Reliable Local Communication (RDT) Library. 100 */ 101 102 #include <nn/rdt/rdt_define.h> 103 #include <nn/rdt/rdt_Sender.h> 104 #include <nn/rdt/rdt_Receiver.h> 105 #include <nn/rdt/rdt_Result.h> 106 #include <nn/rdt/rdt_Misc.h> 107 108 namespace nn 109 { 110 namespace rdt 111 { 112 using namespace nn::rdt; 113 } 114 } 115 116 117 #endif // end of NN_RDT_H_ 118