CTR Pia  4.11.3
Game Communication Engine
transport_RoundRobinUnreliableProtocol.h
1 /*---------------------------------------------------------------------------*
2  Project: Pia
3  File: transport_RoundRobinUnreliableProtocol.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 #include <pia/transport/transport_UnreliableProtocol.h>
19 
20 namespace nn
21 {
22 namespace pia
23 {
24 namespace transport
25 {
26 
27 
28 /*!
29 @brief This class inherits the <tt>UnreliableProtocol</tt> class, and adds features to send data while distributing the load.
30 @date 2013-03-19 Initial version.
31 
32 
33 */
35 {
36 public:
37 /*!
38 @cond PRIVATE
39 @brief Instantiates the object with default parameters (default constructor).
40 @details Applications should not call this constructor directly.
41 Use the <tt>@ref Transport::CreateProtocol</tt> function to create an instance.
42 
43 */
45  //! @endcond
46 
47 
48 /*!
49 @cond PRIVATE
50 @brief Destroys the object.
51 @details Applications should not call this destructor directly.
52 Use the <tt>@ref Transport::DestroyProtocol</tt> function to destroy an instance.
53 
54 */
55  virtual ~RoundRobinUnreliableProtocol(void);
56  //! @endcond
57 
58 
59  PIA_PROTOCOL_TYPE_INFO(PROTOCOL_TYPE_ROUNDROBIN_UNRELIABLE);
60 
61 
62 /*!
63 @cond PRIVATE
64 @brief Starts communication.
65 @param[in] myStationIndex Indicates the local <tt>StationIndex</tt>.
66 @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess</tt> function returns <tt>true</tt> if execution succeeds.
67 @retval ResultInvalidArgument Specifies that one or more arguments are invalid. Programming error. Fix your program so that this error is not returned.
68 @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.
69 
70 
71 */
72  virtual nn::Result Startup(StationIndex myStationIndex);
73  //! @endcond
74 
75 
76 /*!
77 @cond PRIVATE
78 @brief Ends communication.
79 */
80  virtual void Cleanup(void);
81  //! @endcond
82 
83 
84 /*!
85 @brief Sends data to multiple stations.
86 @details Sends data to the <tt>stationNum</tt> stations specified. Sends to stations in order of <tt>StationIndex</tt>, from lowest to highest, starting with the next largest <tt>StationIndex</tt> after that of the local station.
87 The next time the call is made, the starting point is the last <tt>StationIndex</tt> that the station sent data to.
88 For example, consider a session in which stations A, B, C, D, E, and F are participating. The local station is F. If <tt>SendToRoundRobin</tt> is called with a recipient count of 2, data is sent as follows.
89 First call: <tt>SendToRoundRobin(Data1)</tt> — Data1 is sent to A and B.
90 Second call: <tt>SendToRoundRobin(Data2)</tt> — Data2 is sent to C and D.
91 Third call: <tt>SendToRoundRobin(Data3)</tt> — Data3 is sent to E and A.
92 Fourth call: <tt>SendToRoundRobin(Data4)</tt> — Data4 is sent to B and C.
93 Fifth call: <tt>SendToRoundRobin(Data5)</tt> — Data5 is sent to D and E.
94 
95 Calling this function alone does not cause the data to actually be sent.
96 This function copies the data passed in by the application into the Pia library's packet buffer.
97 The Pia library's send thread periodically sends the packets.
98 @param[in] pData Specifies a pointer to the start of the data to send.
99 @param[in] dataSize Specifies the size of the data to send. The value is in bytes. This size must not be greater than the value returned by the <tt>GetDataSizeLimit</tt> function.
100 @param[in] stationNum Specifies the number of stations you want to send data to.
101 @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess</tt> function returns <tt>true</tt> if execution succeeds.
102 @retval ResultInvalidArgument Specifies 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.
103 @retval ResultInvalidState Indicates that the <tt>Initialize</tt> function may not have been called. Programming error. Fix your program so that this error is not returned.
104 @retval ResultNotInCommunication Indicates that communication is not possible. Handle appropriately in the application.
105 @see Send, Receive, MAX_DATA_SIZE, GetDataSizeLimit, IsInCommunication
106 
107 
108 
109 
110 
111 
112 */
113  nn::Result SendToRoundRobin(const bit8* pData, size_t dataSize, u32 stationNum);
114 
115 
116 /*!
117 @brief Prints information that is useful for debugging.
118 @param[in] flag Specifies the bitwise OR of trace flags. For more information, see the <tt>@ref TraceFlag</tt> type.
119 
120 */
121  virtual void Trace(u64 flag) const;
122 
123 
124 private:
125  u32 m_LatestPariticipatingBitmap;
126  StationIndex m_LastSentStationIndex;
127 };
128 }
129 }
130 } // end of namespace nn::pia::transport
nn::Result SendToRoundRobin(const bit8 *pData, size_t dataSize, u32 stationNum)
Sends data to multiple stations.
StationIndex
Enumerates StationIndex values.
Definition: platformCtr.h:44
Definition: assert.h:115
virtual void Trace(u64 flag) const
Prints information that is useful for debugging.
Represents the unreliable protocol class, with which data may be lost. UnreliableProtocol does not gu...
Definition: transport_UnreliableProtocol.h:75
This class inherits the UnreliableProtocol class, and adds features to send data while distributing t...
Definition: transport_RoundRobinUnreliableProtocol.h:34