CTR Pia  4.11.3
Game Communication Engine
transport_TransportAnalyzer.h
1 /*---------------------------------------------------------------------------*
2  Project: Pia
3  File: transport_TransportAnalyzer.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_TransportAnalysisData.h>
20 #include <pia/common/common_Time.h>
21 
22 
23 namespace nn
24 {
25 namespace pia
26 {
27 namespace transport
28 {
29 
30 
31 // Forward declaration.
32 class ConnectionAnalyzer;
33 
34 /*!
35 @brief The <tt>TransportAnalyzer</tt> class reports on packet analysis results, RTT, packet loss rates, and so on.
36 @date 2014-09-18 Changed the specifications so that <tt>ResultAlreadyExists</tt> is returned if you call <tt>CreateInstance</tt> when an instance already exists.
37 @date 2014-07-01 Added a feature that lets you pass analysis data as a text string to a user-defined function.
38 @date 2013-11-25 Added the <tt>SetMarker</tt> function.
39 @date 2013-11-14 Made the <tt>CreateInstance</tt>, <tt>DestroyInstance</tt>, <tt>Initialize</tt>, <tt>Finalize</tt>, <tt>Startup</tt>, and <tt>Cleanup</tt> functions private.
40 @date 2013-11-14 Made changes so that instances are implicitly created within <tt>PiaTransport</tt>.
41 @date 2013-10-29 Initial version.
42 
43 
44 */
46 {
47 public:
48 /*!
49 @brief Defines the type of the print callback used for transport analysis data.
50 @details Use this type when you want to pass an output string containing transport analysis data to a user-defined function.
51 @param[in] pStr Takes the transport analysis data as a text string. Does not add a newline character.
52 
53 */
54  typedef void (*AnalysisPrintCallback)(const char* pStr);
55 
56 
57 /*!
58 @cond PRIVATE
59 @brief Creates an instance of the <tt>TransportAnalyzer</tt> class (singleton pattern).
60 @return Returns a <tt>Result</tt> value that indicates success if the instance is created successfully. You must make sure that the implementation of this function in your application does not return any errors.
61 @retval ResultNotInitialized Indicates that the <tt>transport</tt> module is not initialized. Programming error. Fix your program so that this error is not returned.
62 @retval ResultInvalidState Indicates that the timing at which the <tt>CreateInstance</tt> function was called is incorrect. Make this call between the <tt>BeginSetup</tt> and <tt>EndSetup</tt> functions. Programming error. Fix your program so that this error is not returned.
63 @retval ResultAlreadyExists Indicates that an instance has already been created. Programming error. Fix your program so that this error is not returned.
64 @retval ResultAllocationFailed Indicates that the function failed to allocate memory. Allocate more memory to the Pia library in <tt>common::Initialize</tt>. Programming error. Fix your program so that this error is not returned.
65 @see DestroyInstance, GetInstance, Setting
66 @endcond
67 
68 */
69  static nn::Result CreateInstance();
70 
71 
72 /*!
73 @cond PRIVATE
74 @brief Destroys an instance of the <tt>TransportAnalyzer</tt> class (singleton pattern).
75 If no instances exist, this function does nothing.
76 @see CreateInstance, GetInstance
77 @endcond
78 
79 */
80  static void DestroyInstance();
81 
82 
83 /*!
84 @brief Gets the <tt>TransportAnalyzer</tt> class instance (singleton pattern).
85 This function returns a <tt>NULL</tt> pointer if the instance has not yet been created using the <tt>CreateInstance</tt> function.
86 This function is thread-safe.
87 @return Returns a pointer to the <tt>TransportAnalyzer</tt> instance.
88 @see CreateInstance, DestroyInstance
89 
90 
91 */
93  {
94  return s_pInstance;
95  }
96 
97 /*!
98 @cond PRIVATE
99 @brief Executes the initialization procedure.
100 @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess</tt> function returns <tt>true</tt> if initialization was successful. You must make sure that the implementation of this function in your application does not return any errors.
101 @retval ResultAlreadyInitialized Indicates that the <tt>Initialize</tt> function was already run. Programming error. Fix your program so that this error is not returned.
102 @retval ResultAllocationFailed Indicates that the function failed to allocate memory. Allocate more memory to the Pia library in <tt>common::Initialize</tt>. Programming error. Fix your program so that this error is not returned.
103 @endcond
104 
105 */
106  nn::Result Initialize();
107 
108 
109 /*!
110 @cond PRIVATE
111 @brief Executes the finalization procedure.
112 @endcond
113 */
114  void Finalize();
115 
116 
117 /*!
118 @cond PRIVATE
119 @brief Starts analyzing.
120 @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess</tt> function returns <tt>true</tt> if the procedure was successful. You must make sure that the implementation of this function in your application does not return any errors.
121 @retval ResultNotInitialized Indicates that the <tt>TransportAnalyzer</tt> instance is not initialized. Programming error. Fix your program so that this error is not returned.
122 @retval ResultInvalidState Indicates that the function was called at the wrong time. Programming error. Fix your program so that this error is not returned.
123 @endcond
124 
125 */
126  nn::Result Startup();
127 
128 
129 /*!
130 @cond PRIVATE
131 @brief Ends the analysis.
132 @endcond
133 */
134  void Cleanup();
135 
136 
137 /*!
138 @brief Updates the data.
139 @details The application does not need to call this API function if (A) a positive value has been set for the <tt>analysisInterval</tt> member variable in the <tt>Transport::Setting</tt> structure and (B) automatic printing of analysis data is enabled.
140 When the application gets analysis data when the automatic printing feature is disabled and a value of <tt>0</tt> is set for the <tt>analysisInterval</tt> member variable, update the data by calling this API function explicitly.
141 @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess</tt> function returns <tt>true</tt> if the procedure was successful. You must make sure that the implementation of this function in your application does not return any errors.
142 @retval ResultNotInitialized Indicates that the <tt>TransportAnalyzer</tt> instance is not initialized. Programming error. Fix your program so that this error is not returned.
143 @retval ResultInvalidState Indicates that the function was called at the wrong time. Programming error. Fix your program so that this error is not returned.
144 
145 
146 
147 
148 
149 
150 */
151  nn::Result Update();
152 
153 
154 /*!
155 @brief Gets the data.
156 */
158  {
159  return m_Data;
160  }
161 
162 
163 /*!
164 @brief Outputs a string to the console to delimit flags.
165 @param[in] pComment A pointer to the string that is the name of the delimiter line. The string cannot include whitespace characters. Also, <tt>NULL</tt> cannot be specified.
166 @retval ResultInvalidArgument Specifies that an argument is invalid. <tt>NULL</tt> pointers and strings that include whitespace characters cannot be provided as arguments. Programming error. Fix your program so that this error is not returned.
167 @retval ResultInvalidState Indicates that the function was called at the wrong time. Programming error. Fix your program so that this error is not returned.
168 
169 
170 */
171  nn::Result SetMarker(const char* pComment);
172 
173 /*!
174 @brief Registers the print callback.
175 @param[in] pCallback Specifies a pointer to the callback function to register.
176 @return Returns the print callback that was registered before this function was called.
177 
178 
179 */
181 
182 
183  // Constructor.
185 
186 
187  // Destructor.
189 
190 
191 /*!
192 @cond PRIVATE
193 @brief Writes the monitoring data.
194 @endcond
195 */
196  void SetMonitoringData();
197 
198 
199 /*!
200 @brief Prints information that is useful for debugging.
201 @param[in] flag Specifies the bitwise OR of trace flags. For more information, see the <tt>@ref TraceFlag</tt> type.
202 
203 */
204  void Trace(u64 flag) const;
205 
206 private:
207  ConnectionAnalyzer* m_pConnectionAnalyzer;
208  bool m_bStartup;
209  struct TransportAnalysisData m_Data;
210 
211  common::Time m_StartupTime; // The time when the <tt>Startup</tt> function was called.
212 
213  static TransportAnalyzer* s_pInstance;
214 };
215 }
216 }
217 } // end of namespace nn::pia::transport
const struct TransportAnalysisData & GetTransportAnalysisData() const
Gets the data.
Definition: transport_TransportAnalyzer.h:157
Class that represents time.
Definition: common_Time.h:39
Definition: assert.h:115
AnalysisPrintCallback RegisterPrintCallback(AnalysisPrintCallback pCallback)
Registers the print callback.
void Trace(u64 flag) const
Prints information that is useful for debugging.
The TransportAnalyzer class reports on packet analysis results, RTT, packet loss rates, and so on. .
Definition: transport_TransportAnalyzer.h:45
nn::Result Update()
Updates the data.
static TransportAnalyzer * GetInstance()
Gets the TransportAnalyzer class instance (singleton pattern). This function returns a NULL pointer i...
Definition: transport_TransportAnalyzer.h:92
nn::Result SetMarker(const char *pComment)
Outputs a string to the console to delimit flags.
This is the common base class used inside the Pia library.
Definition: common_RootObject.h:40
Contains the results of analyzing send and receive packets, and parameters indicating the quality of ...
Definition: transport_TransportAnalysisData.h:37
void(* AnalysisPrintCallback)(const char *pStr)
Defines the type of the print callback used for transport analysis data.
Definition: transport_TransportAnalyzer.h:54