CTR Pia  4.11.3
Game Communication Engine
transport_ReliableProtocol.h
1 /*---------------------------------------------------------------------------*
2  Project: Pia
3  File: transport_ReliableProtocol.h
4 
5  Copyright 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 
14 
15 #pragma once
16 
17 #include <pia/transport/transport_definitions.h>
18 
19 #include <pia/common/common_types.h>
20 #include <pia/transport/transport_Protocol.h>
21 
22 #include <pia/transport/transport_ProtocolEvent.h>
23 
24 namespace nn
25 {
26 namespace pia
27 {
28 namespace transport
29 {
30 
31 class ReliableSlidingWindow;
32 
33 /*!
34  @brief This protocol sends transmissions that are guaranteed to arrive.
35 
36  @date 2014-07-17 Changed the specifications so that <tt>ResultNotFound</tt> is returned when the destination <tt>StationId</tt> specified in the <tt>Send()</tt> function is not found.
37  @date 2014-07-16 Changed the specifications so that <tt>ResultTemporaryUnavailable</tt> is returned when <tt>Send()</tt> is called while state transitions between sessions or joint sessions are in progress.
38  @date 2014-03-24 Added a formula to the <tt>Initialize()</tt> API Reference for determining the approximate amount of memory it consumes.
39  @date 2012-12-14 Improved the method of tuning the resend interval.
40  @date 2012-10-29 It now automatically tunes the resend interval.
41  @date 2012-07-17 Added <tt>ResultNotInCommunication</tt> to the return values of the <tt>Send()</tt> and <tt>Receive()</tt> functions.
42  @date 2012-07-09 You are no longer required to set the maximum number of connections in the <tt>Initialize()</tt> function.
43  @date 2012-07-05 Added descriptions of the send and receive operations and buffer usage.
44  @date 2012-04-24 You can now send to all members by specifying the recipient as <tt>STATION_INDEX_ALL</tt> in the <tt>Send()</tt> function.
45  @date 2012-04-06 Initial version.
46 */
48 {
49 public:
50 /*!
51  @cond PRIVATE
52  @brief Instantiates an object with default parameters (default constructor).
53 
54  @details Do not call this constructor directly from applications.
55  Use the <tt>@ref Transport::CreateProtocol</tt> function to create an instance.
56 */
57  ReliableProtocol(void);
58  //! @endcond
59 
60 
61 /*!
62  @cond PRIVATE
63  @brief The destructor.
64 
65  @details Do not call this destructor directly from applications.
66  Use the <tt>@ref Transport::DestroyProtocol</tt> function to destroy an instance.
67 */
68  virtual ~ReliableProtocol(void);
69  //! @endcond
70 
71 
72  PIA_PROTOCOL_TYPE_INFO(PROTOCOL_TYPE_RELIABLE);
73 
74 
75 /*!
76  @brief Initializes the instance. Call between the <tt>BeginSetup()</tt> and <tt>EndSetup()</tt> functions.
77 
78  @details You can measure the actual number of send/receive buffers used by specifying
79  <tt>@ref common::WatermarkManager::KEY_RELIABLE_PROTOCOL_SEND_BUFFER_NUM</tt> or
80  <tt>@ref common::WatermarkManager::KEY_RELIABLE_PROTOCOL_RECEIVE_BUFFER_NUM</tt> in
81  <tt>@ref common::WatermarkManager</tt>.
82  @details Use the following formula to calculate the approximate amount of memory consumed by <tt>ReliableProtocol</tt>.
83  (<tt><var>sendBufferSize</var></tt> * <tt>1500</tt> + <tt><var>receiveBufferSize</var></tt> * <tt>1500</tt>) * (<tt>Transport::Setting::maxStationNum</tt> - <tt>1</tt>)
84 
85  @param[in] sendBufferSize Specifies the size of the send buffer. Specify a value of <tt>1</tt> or greater.
86  Send buffers are used to hold data sent using the <tt>Send()</tt> function until the sender can confirm that it has arrived to the recipient.
87  @param[in] receiveBufferSize Specifies the size of the receive buffer. Specify a value of <tt>1</tt> or greater.
88  Receive buffers are used to hold received data until the <tt>Receive()</tt> function is called.
89 
90  @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess()</tt> function returns <tt>true</tt> if execution succeeds. You must make sure that the implementation of this function in your application does not return any errors.
91 
92  @retval ResultInvalidArgument Indicates that an argument is invalid. Programming error. Fix your program so that this error is not returned.
93  @retval ResultAlreadyInitialized Indicates that the instance is already initialized. Programming error. Fix your program so that this error is not returned.
94 
95  @see Finalize
96 */
97  nn::Result Initialize(u32 sendBufferSize, u32 receiveBufferSize);
98 
99 
100 /*!
101  @brief Finalizes.
102 
103  @see Initialize
104 */
105  void Finalize();
106 
107 
108 /*!
109  @cond PRIVATE
110  @brief Starts communication.
111 
112  @param[in] myStationIndex Specifies the <tt>StationIndex</tt> value of the local station. Specify a value in the range from <tt>STATION_INDEX_1</tt> to <tt><var>maxConnections</var></tt>.
113 
114  @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess()</tt> function returns <tt>true</tt> if execution succeeds.
115 
116  @retval ResultNotInitialized Indicates that the instance is not initialized. Programming error. Fix your program so that this error is not returned.
117  @retval ResultInvalidState Indicates that stations are already communicating. Programming error. Fix your program so that this error is not returned.
118  @retval ResultInvalidArgument Indicates that an argument is invalid. Programming error. Fix your program so that this error is not returned.
119 */
120  virtual nn::Result Startup(StationIndex myStationIndex);
121  //! @endcond
122 
123 
124 /*!
125  @cond PRIVATE
126  @brief Ends communication.
127 */
128  virtual void Cleanup();
129  //! @endcond
130 
131 
132 /*!
133  @cond PRIVATE
134  @brief The main process.
135 
136  @return Returns <tt>nn::ResultSuccess</tt>.
137 */
138  virtual nn::Result Dispatch();
139  //! @endcond
140 
141 
142 /*!
143  @cond PRIVATE
144  @brief Switches the connection status.
145 
146  @param[in] event Specifies the event representing the operation.
147 
148  @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess()</tt> function returns <tt>true</tt> if execution succeeds.
149 
150  @retval ResultInvalidState Indicates that the function was called in an invalid state. Programming error. Fix your program so that this error is not returned.
151  @retval ResultInvalidArgument Indicates that an argument is invalid. Programming error. Fix your program so that this error is not returned.
152 */
153  virtual nn::Result UpdateProtocolEvent(const transport::ProtocolEvent& event);
154  //! @endcond
155 
156 
157 /*!
158  @brief Sends data.
159 
160  @details The function divides the send data that is set with this function into packet-sized chunks and stores the chunks in buffers.
161  Next, the <tt>@ref common::Scheduler::Dispatch()</tt> function creates packets from the data consecutively, and sends them.
162  If the library cannot confirm that a packet has arrived after waiting for a reasonable time, it resends it.
163  The time until a resent is adjusted automatically, based on the round-trip time (RTT).
164  After the library confirms that a packet has arrived, it deletes the data from the buffer. At this point, the buffer can be reused for sending additional data.
165 
166  @param[in] destinationStationId Specifies the <tt>@ref StationId</tt> of the recipient. Specify <tt>STATION_ID_ALL</tt> to send to all currently connected peers.
167  @param[in] pData Specifies the address of the data to send.
168  @param[in] dataSize Specifies the length, in bytes, of the data to send.
169 
170  @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess()</tt> function returns <tt>true</tt> if execution succeeds.
171 
172  @retval ResultInvalidState <tt>ReliableProtocol</tt> might not have been initialized, or the session setup might not have been completed. Programming error. Fix your program so that this error is not returned.
173  @retval ResultInvalidArgument Indicates that an argument is invalid. Programming error. Fix your program so that this error is not returned.
174  @retval ResultNotInCommunication Indicates that the local station is not connected to the specified recipient. The specified peer is not in this session. Handle appropriately in the application.
175  @retval ResultBufferIsFull Indicates that there is not enough space in the send buffer. If this happens frequently, consider increasing the send buffer size specified in the <tt>Initialize()</tt> function. Handle appropriately in the application.
176  @retval ResultTemporaryUnavailable The API function is temporarily unavailable because the joint session process is in progress. Handle appropriately in the application.
177  @retval ResultNotFound Indicates that the specified destination was not found. Handle appropriately in the application.
178 
179  @see Receive
180 */
181  nn::Result Send(StationId destinationStationId, const void* pData, size_t dataSize);
182 
183 
184 /*!
185  @cond PRIVATE
186  @brief Sends data.
187 */
188  nn::Result Send(StationIndex destinationStationIndex, const void* pData, size_t dataSize);
189  //! @endcond
190 
191 
192 /*!
193  @brief Receives data.
194 
195  @details The library parses received packets when the <tt>@ref common::Scheduler::Dispatch()</tt> function is called, and accumulates them in buffers.
196  When the library can confirm that all the data chunks created by the <tt>Send()</tt> function have been received, it joins them together with this function. You can then retrieve the data using this function.
197  The library then frees the storage buffer, and it can be used for the next receive operation.
198 
199  @param[out] pSourceStationId Specifies a pointer to a buffer containing the <tt>@ref StationId</tt> of the sender of the data that was received.
200  @param[out] pBuffer Specifies a pointer to a buffer for holding the received data.
201  @param[out] pDataSize Specifies a pointer to a buffer for holding the size of the received data.
202  @param[in] bufferSize Specifies the size of the buffer (in bytes) for holding the received data.
203 
204  @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess()</tt> function returns <tt>true</tt> if execution succeeds.
205 
206  @retval ResultInvalidState Indicates that the instance is not initialized. Programming error. Fix your program so that this error is not returned.
207  @retval ResultInvalidArgument Indicates that an argument is invalid. Programming error. Fix your program so that this error is not returned.
208  @retval ResultNotInCommunication Indicates that the station is not actively communicating. The peer is not in the current session. Handle appropriately in the application.
209  @retval ResultNoData Indicates that no data was received. Handle appropriately in the application.
210  @retval ResultBrokenData Indicates that the received data is too large to fit in the receive buffer or cannot all be written to the buffer passed into the function. Start over from the session startup step.
211  This result could be returned because of invalid data from the sender, such as cheats, requiring handling at run time.
212  If the sender's behavior is valid, the program must be fixed so that this result is not returned. Handle appropriately in the application.
213 
214  @see Send
215 */
216  nn::Result Receive(StationId* pSourceStationId, void* pBuffer, size_t* pDataSize, size_t bufferSize);
217 
218 
219 /*!
220  @cond PRIVATE
221  @brief Receives data.
222 */
223  nn::Result Receive(StationIndex* pSourceStationIndex, void* pBuffer, size_t* pDataSize, size_t bufferSize);
224  //! @endcond
225 
226 
227 /*!
228  @brief Gets whether the specified node is communicating.
229 
230  @details If the specified peer is in the same session as the local station, <tt>true</tt> will be returned.
231 
232  @param[in] stationId Returns the <tt>@ref StationId</tt> of the peer.
233 
234  @return Returns <tt>true</tt> if the node is communicating.
235 */
236  bool IsInCommunication(StationId stationId) const;
237 
238 
239 /*!
240  @cond PRIVATE
241  @brief Gets whether the specified node is communicating.
242 */
243  bool IsInCommunication(StationIndex stationId) const;
244  //! @endcond
245 
246 
247  // Resend time calculation callback type.
248  // <tt>rtt</tt> takes the round-trip time (RTT) in milliseconds. <tt>resendCount</tt> takes the number of times the data has been resent.
249  // The callback's return value is the resend time. The value is in milliseconds.
250  typedef s32 (*ResendTimeCallback)(s32 rtt, size_t resendCount);
251 
252 
253 /*!
254  @cond PRIVATE
255  @brief Registers a callback function that calculates the resend time.
256  No callback function is registered by default.
257 
258  @return Returns a pointer to the callback function held until just before the call.
259 */
260  static ResendTimeCallback RegisterResendTimeCallback(ResendTimeCallback cb);
261  //! @endcond
262 
263 
264 /*!
265  @brief Prints information that is useful for debugging.
266 
267  @param[in] flag Specifies the bitwise OR of trace flags. For more information, see the <tt>TraceFlag</tt> reference.
268 */
269  virtual void Trace(u64 flag) const;
270 
271 #if NN_PIA_EXPERIMENT_RELIABLE_DETAIL_INFO
272  void PrintDebugInfo(void) const;
273  void ClearAllResendCount(void);
274  u32 GetAllResendCount(void) const;
275 #endif
276 
277 private:
278  ReliableSlidingWindow* GetSlidingWindow(StationIndex stationId);
279  const ReliableSlidingWindow* GetSlidingWindow(StationIndex stationId) const;
280 
281  nn::Result ReceiveImpl(StationIndex* pSourceStationIndex, void* pBuffer, size_t* pDataSize, size_t bufferSize, bool bCheckStationIdTable);
282 
283 private:
284  StationIndex m_LocalStationIndex;
285  u32 m_MaxConnections;
286  ReliableSlidingWindow* m_paSlidingWindow;
287  u32 m_DispatchSlidingWindowIdx;
288 
289  static ResendTimeCallback s_pfResendTimeCallback; // Resend time calculation callback.
290 };
291 }
292 }
293 } // End of namespace nn::pia::transport.
virtual void Trace(u64 flag) const
Prints information that is useful for debugging.
StationIndex
Enumerates StationIndex values.
Definition: platformCtr.h:44
Definition of the StationId identifying the station within the session.
Definition: types.h:33
Definition: assert.h:115
nn::Result Receive(StationId *pSourceStationId, void *pBuffer, size_t *pDataSize, size_t bufferSize)
Receives data.
bool IsInCommunication(StationId stationId) const
Gets whether the specified node is communicating.
Protocol base class.
Definition: transport_Protocol.h:44
nn::Result Send(StationId destinationStationId, const void *pData, size_t dataSize)
Sends data.
nn::Result Initialize(u32 sendBufferSize, u32 receiveBufferSize)
Initializes the instance. Call between the BeginSetup() and EndSetup() functions. ...
This protocol sends transmissions that are guaranteed to arrive.
Definition: transport_ReliableProtocol.h:47