CTR Pia  4.11.3
Game Communication Engine
transport_UnreliableProtocol.h
1 /*---------------------------------------------------------------------------*
2  Project: Pia
3  File: transport_UnreliableProtocol.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/transport/transport_Protocol.h>
20 #include <pia/common/common_PacketDefine.h>
21 
22 
23 // Forward declaration.
24 namespace nn
25 {
26 namespace pia
27 {
28 namespace transport
29 {
30 class ReceivedDataContainer;
31 }
32 }
33 }
34 
35 
36 namespace nn
37 {
38 namespace pia
39 {
40 namespace transport
41 {
42 
43 
44 /*!
45 @brief Represents the unreliable protocol class, with which data may be lost.
46 <tt>UnreliableProtocol</tt> does not guarantee that data arrives in the order it was sent.
47 It may not be possible to receive data with the <tt>Receive</tt> function in the same order it was sent with the <tt>Send</tt> function.
48 @date 2014-09-10 Corrected incorrect information about when the <tt>GetDataSizeLimit</tt> function can be called.
49 @date 2014-07-17 Changed the specifications so that <tt>ResultTemporaryUnavailable</tt> is returned when <tt>SendToAll</tt> is called while state transitions between sessions or joint sessions are in progress.
50 @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.
51 @date 2014-07-16 Changed the specifications so that <tt>ResultTemporaryUnavailable</tt> is returned when the <tt>Send</tt>/<tt>Receive</tt> function is called while state transitions between sessions or joint sessions are in progress.
52 @date 2014-03-10 Added information about when the <tt>GetDataSizeLimit</tt> function can be called.
53 @date 2014-03-10 Fixed errors in the description of the <tt>MAX_DATA_SIZE</tt> value. The correct value is <tt>1430</tt>.
54 @date 2013-07-05 Modified the <tt>Initialize</tt> function. <tt>Initialize</tt> now succeeds when called between calls to <tt>BeginSetup</tt> and <tt>EndSetup</tt> of another module.
55 @date 2013-05-14 Fixed the documentation of the <tt>Finalize</tt> function.
56 @date 2013-04-12 Changed the specifications of <tt>Send</tt> and <tt>SendToAll</tt> so that a <tt>ResultBufferIsFull</tt> object is never returned.
57 @date 2013-04-05 Made <tt>GetDataSizeLimit</tt> into a non-static member function.
58 @date 2013-04-01 Changed the specifications of the <tt>Receive</tt> function. Reordered the dummy parameters.
59 @date 2013-04-01 Changed the specifications of the <tt>Initialize</tt> function. If the <tt>Initialize</tt> function is called when the object has already been initialized with a call to <tt>Initialize</tt>, the function now returns <tt>ResultAlreadyInitialized</tt>.
60 @date 2013-04-01 Changed the specifications of the <tt>Initialize</tt> function. You can now specify the number of receive buffers in the function arguments.
61 @date 2013-03-19 Made major changes to the internal implementation of the <tt>UnreliableProtocol</tt> class, due to changes to the <tt>transport</tt> implementation.
62 @date 2013-02-04 Fixed a bug where data received in the old session would remain in the buffer after the session ended, and could be retrieved in a new session.
63 @date 2012-07-17 Changed the <tt>Send</tt>, <tt>SendToAll</tt>, and <tt>Receive</tt> functions. Made it so that <tt>ResultNotInCommunication</tt> is returned when communication is not possible.
64 @date 2012-07-17 Added the <tt>IsInCommunication</tt> function.
65 @date 2012-07-04 Added a description of detailed operations of the <tt>Receive</tt>, <tt>Send</tt> and <tt>SendToAll</tt> functions.
66 @date 2012-06-28 Clearly indicated which functions are thread-safe.
67 @date 2012-05-31 Changed the functionality of the <tt>Receive</tt> function. When the size of the read buffer is insufficient, <tt>ResultBufferShortage</tt> is now returned.
68 @date 2012-05-30 Changed the functionality of the <tt>Send</tt> and <tt>SendToAll</tt> functions. You can no longer send data in excess of the value of the <tt>GetDataSizeLimit</tt> function.
69 @date 2012-05-30 Added the <tt>GetDataSizeLimit</tt> function. This function gets the maximum transmission unit.
70 @date 2012-04-28 It was mistakenly indicated that the <tt>Initialize</tt> function would return <tt>ResultInvalidArgument</tt>. This statement was deleted.
71 @date 2012-04-28 Specifications changed so that the <tt>Send</tt> and <tt>SendToAll</tt> functions return <tt>ResultInvalidState</tt> when <tt>UnreliableProtocol</tt> is not initialized.
72 @date 2012-04-28 Fixed a bug where <tt>ResultInvalidState</tt> was left out of the list of return values for the <tt>Receive</tt> function.
73 @date 2012-04-06 Initial version.
74 */
76 {
77 public:
78 /*!
79 @brief Defines the maximum data size that can be sent and received at one time using <tt>UnreliableProtocol</tt>. This value is in bytes.
80 
81 @details The value of this constant is <tt>1430</tt>, but if the application sets a smaller MTU value, the amount of data that can actually be sent or received is smaller than this value.
82 
83 */
84  static const size_t MAX_DATA_SIZE = common::PROTOCOL_MESSGAE_PAYLOAD_SIZE_MAX;
85 
86 
87 /*!
88 @brief Gets the maximum size of data that can be sent in one transmission. This value is in bytes.
89 
90 @details The value returned by this function is affected by the MTU value set by the application and by whether packets are signed.
91 This function is thread-safe.
92 @details If your application uses mesh networks, call this function after the mesh startup process completes.
93 The correct value is not returned if the function is called sooner.
94 @details If your application uses sessions, call this function after joining a session.
95 The correct value is not returned if this function is called sooner.
96 
97 @return Returns the maximum amount of data that can be sent at one time per call to the <tt>Send</tt> or <tt>SendToAll</tt> functions. This value is in bytes.
98 
99 @see Send, SendToAll
100 
101 
102 */
103  size_t GetDataSizeLimit(void);
104 
105 
106 /*!
107 @cond PRIVATE
108 @brief Instantiates the object with default parameters (default constructor).
109 
110 @details Do not call this constructor directly from applications.
111 Use the <tt>@ref Transport::CreateProtocol</tt> function to create an instance.
112 */
113  UnreliableProtocol(void);
114  //! @endcond
115 
116 
117 /*!
118 @cond PRIVATE
119 @brief Destroys the object.
120 
121 @details Do not call this destructor directly from applications.
122 Use the <tt>@ref Transport::DestroyProtocol</tt> function to destroy an instance.
123 */
124  virtual ~UnreliableProtocol(void);
125  //! @endcond
126 
127 
128 /*!
129 @cond PRIVATE
130 @brief This is a dispatch function.
131 
132 @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess</tt> function returns <tt>true</tt> if execution succeeds.
133 @retval ResultInvalidState Indicates that the <tt>UnreliableProtocol::Initialize</tt> function may not have been called. Programming error. Fix your program so that this error is not returned.
134 */
135  virtual nn::Result Dispatch(void);
136  //! @endcond
137 
138 
139  virtual nn::Result UpdateProtocolEvent(const ProtocolEvent& event);
140 
141 
142  PIA_PROTOCOL_TYPE_INFO(PROTOCOL_TYPE_UNRELIABLE);
143 
144 
145 /*!
146 @brief Initializes the instance.
147 
148 @details Call between the <tt>BeginSetup</tt> and <tt>EndSetup</tt> functions.
149 
150 
151 @param[in] recvBufNum Specifies the number of receive buffers. Each receive buffer uses about 1,500 bytes of memory.
152 @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.
153 @retval ResultNotInitialized Indicates that the <tt>transport</tt> module is not initialized. Programming error. Fix your program so that this error is not returned.
154 @retval ResultAllocationFailed Indicates that the function failed to allocate memory. Consider providing more memory when calling the <tt>common::Initialize</tt> function. Programming error. Fix your program so that this error is not returned.
155 @retval ResultAlreadyInitialized Indicates that the <tt>UnreliableProtocol</tt> instance is already initialized. Programming error. Fix your program so that this error is not returned.
156 @retval ResultInvalidArgument Indicates that an argument is invalid. One cause of this error is when <tt>recvBufNum</tt> is set to zero. Programming error. Fix your program so that this error is not returned.
157 @retval ResultInvalidState Indicates that the function was not called between the <tt>BeginSetup</tt> and <tt>EndSetup</tt> functions. Programming error. Fix your program so that this error is not returned.
158 @see Finalize
159 */
160  nn::Result Initialize(size_t recvBufNum = 32);
161 
162 
163 /*!
164 @brief Finalizes the instance.
165 
166 @details This function returns without doing anything if it is called before the <tt>Initialize</tt> function has been called.
167 
168 @see Initialize
169 */
170  void Finalize(void);
171 
172 
173 /*!
174 @cond PRIVATE
175 @brief Starts communication.
176 
177 @param[in] myStationIndex Specifies the local <tt>StationIndex</tt>.
178 @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess</tt> function returns <tt>true</tt> if execution succeeds.
179 @retval ResultInvalidArgument Indicates that one or more arguments are invalid. Programming error. Fix your program so that this error is not returned.
180 @retval ResultInvalidState Indicates that the <tt>Startup</tt> function has already been called. Programming error. Fix your program so that this error is not returned.
181 
182 */
183  virtual nn::Result Startup(StationIndex myStationIndex);
184  //! @endcond
185 
186 
187 /*!
188 @cond PRIVATE
189 @brief Ends communication.
190 */
191  virtual void Cleanup(void);
192  //! @endcond
193 
194 
195 /*!
196 @brief Loads received data into a buffer.
197 
198 @details Receives data. However, calling this function does not trigger a receive operation in the wireless module.
199 A receiving thread in the Pia library periodically receives packets from the wireless module.
200 The packets received by the receiving thread are then copied to a packet analysis process buffer that restores the data when the <tt>PiaTransport</tt> dispatch runs.
201 This function copies that copy of the data restored in this way into a buffer provided by the application.
202 
203 @param[out] pSrcId Specifies a pointer to the <tt>StationId</tt> of the station the data was received from.
204 @param[out] pRecvBuf Specifies a pointer to the buffer that data is read into.
205 @param[out] pRecvDataSize Specifies a pointer to the size of data actually read. This value is in bytes.
206 @param[in] recvBuffSize Specifies the size of the buffer that receives the data. This value is in bytes.
207 
208 @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess</tt> function returns <tt>true</tt> if execution succeeds.
209 @retval ResultInvalidArgument Indicates that one or more arguments are invalid. Programming error. Fix your program so that this error is not returned.
210 @retval ResultInvalidState Indicates that the <tt>UnreliableProtocol::Initialize</tt> function may not have been called, or that the <tt>session</tt> setup might not have been completed. Programming error. Fix your program so that this error is not returned.
211 @retval ResultBufferShortage Indicates that the receiving buffer is too small. Returned when the amount of incoming data is larger than the size specified by the <var>recvBuffSize</var> parameter. Programming error. Fix your program so that this error is not returned.
212 @retval ResultNoData Indicates that the receiving buffer is empty and no data could be read. Handle appropriately in the application.
213 @retval ResultNotInCommunication Indicates that communication is not possible. Handle appropriately in the application.
214 @retval ResultTemporaryUnavailable The API function is temporarily unavailable because the joint session process is in progress. Handle appropriately in the application.
215 @see Send, SendToAll, MAX_DATA_SIZE
216 
217 
218 */
219  nn::Result Receive(StationId* pSrcId, bit8* pRecvBuf, size_t* pRecvDataSize, size_t recvBuffSize);
220 
221 
222 /*!
223 @cond PRIVATE
224 @brief Loads received data into a buffer.
225 */
226  nn::Result Receive(StationIndex* pSrcId, bit8* pRecvBuf, size_t* pRecvDataSize, size_t recvBuffSize);
227  //! @endcond
228 
229 
230 /*!
231 @brief Sends data to a specific station.
232 
233 @details Sends data. However, calling this function alone does not actually cause the data to be sent.
234 This function copies the data passed in by the application into a buffer that the Pia library uses to generate packets.
235 The data copied into the packet generation buffer is packaged into packets, and passed to the Pia internal transmit thread by running the Pia dispatch process afterwards. The actual send process periodically passes packets from the send thread to the wireless module.
236 
237 @param[in] destId Specifies the <tt>StationId</tt> of the recipient.
238 @param[in] pData Specifies a pointer to the start of the data to send.
239 @param[in] dataSize Specifies the size of the data to send. This value is in bytes. This size must not be greater than the value returned by the <tt>GetDataSizeLimit</tt> function.
240 @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess</tt> function returns <tt>true</tt> if execution succeeds.
241 @retval ResultInvalidArgument Indicates that one or more arguments are invalid. This error is also returned when the size of the data to send is too large. Programming error. Fix your program so that this error is not returned.
242 @retval ResultInvalidState Indicates that the <tt>UnreliableProtocol::Initialize</tt> function may not have been called, or that the <tt>session</tt> setup might not have been completed. Programming error. Fix your program so that this error is not returned.
243 @retval ResultNotInCommunication Indicates that communication is not possible. Handle appropriately in the application.
244 @retval ResultTemporaryUnavailable The API function is temporarily unavailable because the joint session process is in progress. Handle appropriately in the application.
245 @retval ResultNotFound Indicates that the specified destination was not found.
246 @see SendToAll, Receive, MAX_DATA_SIZE, GetDataSizeLimit, IsInCommunication
247 
248 
249 */
250  nn::Result Send(StationId destId, const bit8* pData, size_t dataSize);
251 
252 
253 /*!
254 @cond PRIVATE
255 @brief Sends data to a specific station.
256 */
257  nn::Result Send(StationIndex destId, const bit8* pData, size_t dataSize);
258  //! @endcond
259 
260 
261 /*!
262 @brief Sends data to all stations.
263 
264 @details Sends data. However, calling this function alone does not actually cause the data to be sent.
265 This function copies the data passed in by the application into a buffer that the Pia library uses to generate packets.
266 The data copied into the packet generation buffer is packaged into packets, and passed to the Pia internal transmit thread by running the Pia dispatch process afterwards. The actual send process periodically passes packets from the send thread to the wireless module.
267 
268 @param[in] pData Specifies a pointer to the start of the data to send.
269 @param[in] dataSize Specifies the size of the data to send. This value is in bytes. This size must not be greater than the value returned by the <tt>GetDataSizeLimit</tt> function.
270 @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess</tt> function returns <tt>true</tt> if execution succeeds.
271 @retval ResultInvalidArgument Indicates that one or more arguments are invalid. This error is also returned when the size of the data to send is too large. Programming error. Fix your program so that this error is not returned.
272 @retval ResultInvalidState Indicates that the <tt>UnreliableProtocol::Initialize</tt> function may not have been called. Programming error. Fix your program so that this error is not returned.
273 @retval ResultNotInCommunication Indicates that communication is not possible. Handle appropriately in the application.
274 @retval ResultTemporaryUnavailable The API function is temporarily unavailable because the joint session process is in progress. Handle appropriately in the application.
275 @see Send, Receive, MAX_DATA_SIZE, GetDataSizeLimit, IsInCommunication
276 
277 
278 */
279  nn::Result SendToAll(const bit8* pData, size_t dataSize);
280 
281 
282 /*!
283 @cond PRIVATE
284 @brief Sends data to multiple stations.
285 */
286  nn::Result SendToMulti(u32 stationBitmap, const bit8* pData, size_t dataSize);
287  //! @endcond
288 
289 
290 /*!
291 @brief Determines whether communication is possible.
292 
293 @return Returns <tt>true</tt> if communication is possible; returns <tt>false</tt> otherwise.
294 */
295  bool IsInCommunication(void) const;
296 
297 
298 /*!
299 @brief Prints information that is useful for debugging.
300 
301 @param[in] flag Specifies the bitwise OR of trace flags. For more information, see the <tt>@ref TraceFlag</tt> type.
302 */
303  virtual void Trace(u64 flag) const;
304 
305 
306 private:
307  nn::Result sendImpl(StationIndex destId, const bit8* pData, size_t dataSize);
308 
309 protected:
310  void* m_pRawBuffer; // Raw memory passed to <tt>m_pReceiveBuffer</tt>.
311  ReceivedDataContainer* m_pReceiveBuffer;
312 
313  StationIndex m_LocalStationIndex;
314 };
315 }
316 }
317 } // end of namespace nn::pia::transport
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
virtual void Trace(u64 flag) const
Prints information that is useful for debugging.
void Finalize(void)
Initializes the transport module. This function does nothing and returns if it is called before the I...
Represents the unreliable protocol class, with which data may be lost. UnreliableProtocol does not gu...
Definition: transport_UnreliableProtocol.h:75
Protocol base class.
Definition: transport_Protocol.h:44
nn::Result Initialize(void)
Initializes the transport module.