CTR Pia  4.11.3
Game Communication Engine
inet_NexDebugSession.h
1 /*---------------------------------------------------------------------------*
2  Project: Pia
3  File: inet_NexDebugSession.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/inet/inet_definitions.h>
18 
19 #include <pia/inet/inet_NexSessionTypes.h>
20 #include <pia/inet/inet_NexCreateSessionSetting.h>
21 #include <pia/inet/inet_NexUpdateSessionSetting.h>
22 #include <pia/common/common_CallContext.h>
23 
24 #if NN_PIA_CTR
25 #pragma diag_suppress 1300 //n1769: Pragma for ARMCC.
26 #endif
27 #include <nex.h>
28 #if NN_PIA_CTR
29 #pragma diag_warning 1300 //n1769: Pragma for ARMCC.
30 #endif
31 
32 namespace nn
33 {
34 namespace pia
35 {
36 namespace session
37 {
38 // Forward declarations.
39 class IMatchmakeSession;
40 }
41 }
42 }
43 namespace nn
44 {
45 namespace pia
46 {
47 namespace inet
48 {
49 class NexDebugSessionJob;
50 
51 /*!
52 @brief (For debugging.) This class handles dummy sessions for debugging.
53 */
55 {
56 public:
57 /*!
58  @brief Creates an instance (singleton pattern).
59 
60  @return Returns the result of the function. If this function call fails, one or more of the following <tt>Result</tt> values is returned. You must make sure that the implementation of this function in your application does not return any errors.
61  @retval nn::pia::ResultNotInitialized Indicates that the <tt>inet</tt> module is not initialized. Programming error. Fix your program so that this error is not returned.
62  @retval nn::pia::ResultInvalidState Indicates that the function was called at the wrong time. Programming error. Fix your program so that this error is not returned.
63  @retval nn::pia::ResultAlreadyExists Indicates that an instance has already been created. Programming error. Fix your program so that this error is not returned.
64 */
65  static Result CreateInstance();
66 
67 /*!
68  @brief Destroys the instance (singleton pattern).
69  @details This function does nothing and returns if calledwhen an instance has not been created.
70 */
71  static void DestroyInstance();
72 
73 /*!
74  @brief Gets a pointer to the <tt>NexDebugSession</tt> instance (singleton pattern).
75 
76  @return Returns a <tt>NULL</tt> pointer if the instance cannot be created.
77 */
79  {
80  return s_pInstance;
81  }
82 /*!
83  @brief Starts the <tt>NexDebugSession</tt> function.
84  @details Call this after <tt>NexFacade::Bind</tt>.
85 
86  @return Returns the result of the function. If this function call fails, one or more of the following <tt>Result</tt> values is returned. You must make sure that the implementation of this function in your application does not return any errors.
87  @retval nn::pia::ResultInvalidState Indicates that the function was called at the wrong time. Create a <tt>NexFacade</tt> instance, and verify whether <tt>NexFacade::Bind</tt> is called. Programming error. Fix your program so that this error is not returned.
88 */
89  Result Startup();
90 
91 /*!
92  @brief Cleans up the <tt>NexDebugSession</tt> feature.
93  @details Call before <tt>NexFacade::Unbind</tt>.
94 */
95  void Cleanup();
96 
97 /*!
98  @brief Builds a dummy session.
99  @details This function starts an asynchronous process that creates a dummy session.
100  The local station becomes the host of the created dummy session. The clients cannot participate in a dummy session.
101  The started process advances by periodically calling the <tt>@ref nn::pia::common::Scheduler::Dispatch</tt> function.
102  Use <tt>@ref IsCompletedCreateDummySession</tt> to check whether the process has completed and <tt>@ref GetCreateDummySessionResult</tt> to check the result.
103  You can use <tt>@ref GetCreatedDummySessionId</tt> to get the session ID of the constructed dummy session.
104 
105  @param[in] createSessionSetting Specifies the settings to use when creating the session.
106 
107  @return Returns a <tt>Result</tt> value that indicates success if the asynchronous process starts successfully. If this function call fails, one or more of the following <tt>Result</tt> values is returned.
108  @retval nn::pia::ResultInvalidArgument Indicates that unexpected arguments were passed to the function when starting the asynchronous process. Programming error. Fix your program so that this error is not returned.
109  @retval nn::pia::ResultInvalidState Indicates that the instance was not in a valid state when the function was called. Make sure that no other asynchronous processes are running, that <tt>Startup</tt> has been called, and that <tt>Session::Startup</tt> is not called. Programming error. Fix your program so that this error is not returned.
110 
111  @see IsCompletedCreateDummySession, Checkes the completion of <tt>GetCreateDummySessionResult</tt>, <tt>GetCreatedDummySessionId</tt>,
112 */
113  Result CreateDummySessionAsync(const NexCreateSessionSetting& createSessionSetting);
114 
115 /*!
116  @brief and <tt>CreateDummySessionAsync</tt> asynchronous processing.
117  @details This function checks the completion of asynchronous processes started with <tt>@ref CreateDummySessionAsync</tt>.
118 
119  @return Returns <tt>true</tt> if the asynchronous process has completed, or <tt>false</tt> otherwise. Also returns <tt>false</tt> when there has been no asynchronous processing.
120 
121  @see CreateDummySessionAsync, <tt>GetCreateDummySessionResult</tt>
122 */
123  bool IsCompletedCreateDummySession();
124 
125 /*!
126  @brief Gets the result of <tt>CreateDummySessionAsync</tt> asynchronous processing.
127  @details This function gets the results after an asynchronous process started by <tt>@ref CreateDummySessionAsync</tt> ends.
128 
129  @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess()</tt> function returns <tt>true</tt>. If this function call fails, one or more of the following <tt>Result</tt> values is returned.
130  @retval nn::pia::ResultInvalidArgument Indicates that unexpected arguments were passed to the function when starting the asynchronous process. Programming error. Fix your program so that this error is not returned.
131  @retval nn::pia::ResultInvalidState Attempted to construct 21 or more dummy sessions. Programming error. Fix your program so that this error is not returned.
132  @retval nn::pia::ResultGameServerMaintenance Indicates that the game server is under maintenance. If this error occurs during Internet communication, convert to a network error code and display in the error viewer applet/EULA applet. However, during local communication, do not display it as an error with error code in the error viewer applet/EULA applet. Execute up to the logout process from the NEX server.
133  @retval nn::pia::ResultNexInternalError This is an internal NEX error. The <tt>nn::pia::util::NetworkErrorCodeConverter::Convert</tt> function gets a NEX network error code. Check the NEX section of the network error code list. After logging out, reinitialize Pia and NEX. If this error occurs during Internet communication, convert to a network error code and display in the error viewer applet/EULA applet. However, during local communication, do not display it as an error with error code in the error viewer applet/EULA applet. Handle appropriately in the application.
134 
135  @see CreateDummySessionAsync, <tt>IsCompletedCreateDummySession</tt>
136 */
137  Result GetCreateDummySessionResult() const;
138 
139 /*!
140  @brief Gets the session ID for the dummy session that was created.
141  @return Returns the session ID for the dummy session that was created.
142 */
143  u32 GetCreatedDummySessionId() const;
144 
145 /*!
146  @brief Deletes a dummy session.
147  @details This function starts an asynchronous process that deletes a dummy session.
148  The started process advances by periodically calling the <tt>@ref nn::pia::common::Scheduler::Dispatch</tt> function.
149  Use <tt>@ref IsCompletedDestroyDummySession</tt> to check whether the process has completed and <tt>@ref GetDestroyDummySessionResult</tt> to check the result.
150 
151  @param[in] sessionId The session ID for the dummy session that was deleted.
152 
153  @return Returns a <tt>Result</tt> value that indicates success if the asynchronous process starts successfully. If this function call fails, one or more of the following <tt>Result</tt> values is returned.
154  @retval nn::pia::ResultInvalidState Indicates that the instance was not in a valid state when the function was called. Make sure that no other asynchronous processes are running, that <tt>Startup</tt> has been called, and that <tt>Session::Startup</tt> is not called. Programming error. Fix your program so that this error is not returned.
155 
156  @see IsCompletedDestroyDummySession, <tt>GetDestroyDummySessionResult</tt>
157 */
158  Result DestroyDummySessionAsync(u32 sessionId);
159 
160 /*!
161  @brief Checks the completion of <tt>DestroyDummySessionAsync</tt> asynchronous processing.
162  @details This function checks the completion of asynchronous processes started with <tt>@ref DestroyDummySessionAsync</tt>.
163 
164  @return Returns <tt>true</tt> if the asynchronous process has completed, or <tt>false</tt> otherwise. Also returns <tt>false</tt> when there has been no asynchronous processing.
165 
166  @see DestroyDummySessionAsync, <tt>GetDestroyDummySessionResult</tt>
167 */
168  bool IsCompletedDestroyDummySession();
169 
170 /*!
171  @brief Gets the result of <tt>DestroyDummySessionAsync</tt> asynchronous processing.
172  @details This function gets the results after an asynchronous process started by <tt>@ref DestroyDummySessionAsync</tt> ends.
173 
174  @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess()</tt> function returns <tt>true</tt>. If this function call fails, one or more of the following <tt>Result</tt> values is returned.
175  @retval nn::pia::ResultInvalidState Attempted to delete a session that was not the host. Programming error. Fix your program so that this error is not returned.
176  @retval nn::pia::ResultNotFound The session you tried to delete was not found. Handle appropriately in the application.
177  @retval nn::pia::ResultNexInternalError This is an internal NEX error. The <tt>nn::pia::util::NetworkErrorCodeConverter::Convert</tt> function gets a NEX network error code. Check the NEX section of the network error code list. After logging out, reinitialize Pia and NEX. If this error occurs during Internet communication, convert to a network error code and display in the error viewer applet/EULA applet. However, during local communication, do not display it as an error with error code in the error viewer applet/EULA applet. Handle appropriately in the application.
178 
179  @see DestroyDummySessionAsync, <tt>IsCompletedDestroyDummySession</tt>
180 */
181  Result GetDestroyDummySessionResult() const;
182 
183 /*!
184  @brief Updates dummy session settings.
185  @details Starts asynchronous processing for updating dummy session settings.
186  The started process advances by periodically calling the <tt>@ref nn::pia::common::Scheduler::Dispatch</tt> function.
187  Use <tt>@ref IsCompletedUpdateDummySession</tt> to check whether the process has completed and <tt>@ref GetUpdateDummySessionResult</tt> to check the result.
188 
189  @param[in] sessionId The session ID for the dummy session for which settings are updated.
190  @param[in] updateSessionSetting Update settings for the session.
191 
192  @return Returns a <tt>Result</tt> value that indicates success if the asynchronous process starts successfully. If this function call fails, one or more of the following <tt>Result</tt> values is returned.
193  @retval nn::pia::ResultInvalidState Indicates that the instance was not in a valid state when the function was called. Make sure that no other asynchronous processes are running, that <tt>Startup</tt> has been called, and that <tt>Session::Startup</tt> is not called. Programming error. Fix your program so that this error is not returned.
194 
195  @see IsCompletedUpdateDummySession, <tt>GetUpdateDummySessionResult</tt>
196 */
197  Result UpdateDummySessionAsync(u32 sessionId, const NexUpdateSessionSetting& updateSessionSetting);
198 
199 /*!
200  @brief Checks the completion of <tt>UpdateDummySessionAsync</tt> asynchronous processing.
201  @details This function checks the completion of asynchronous processes started with <tt>@ref UpdateDummySessionAsync</tt>.
202 
203  @return Returns <tt>true</tt> if the asynchronous process has completed, or <tt>false</tt> otherwise. Also returns <tt>false</tt> when there has been no asynchronous processing.
204 
205  @see UpdateDummySessionAsync, <tt>GetUpdateDummySessionResult</tt>
206 */
207  bool IsCompletedUpdateDummySession();
208 
209 /*!
210  @brief Gets the result of <tt>UpdateDummySessionAsync</tt> asynchronous processing.
211  @details This function gets the results after an asynchronous process started by <tt>@ref UpdateDummySessionAsync</tt> ends.
212 
213  @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess()</tt> function returns <tt>true</tt>. If this function call fails, one or more of the following <tt>Result</tt> values is returned.
214  @retval nn::pia::ResultInvalidArgument Indicates that unexpected arguments were passed to the function when starting the asynchronous process. Programming error. Fix your program so that this error is not returned.
215  @retval nn::pia::ResultInvalidState Attempted to update a session that was not the host. Programming error. Fix your program so that this error is not returned.
216  @retval nn::pia::ResultNotFound The session you tried to update was not found. Handle appropriately in the application.
217  @retval nn::pia::ResultNexInternalError This is an internal NEX error. The <tt>nn::pia::util::NetworkErrorCodeConverter::Convert</tt> function gets a NEX network error code. Check the NEX section of the network error code list. After logging out, reinitialize Pia and NEX. If this error occurs during Internet communication, convert to a network error code and display in the error viewer applet/EULA applet. However, during local communication, do not display it as an error with error code in the error viewer applet/EULA applet. Handle appropriately in the application.
218 
219  @see UpdateDummySessionAsync, <tt>IsCompletedUpdateDummySession</tt>
220 */
221  Result GetUpdateDummySessionResult() const;
222 
223 /*!
224  @cond PRIVATE
225 */
226  /// @endcond
227 
228 private:
229  // A pointer to a singleton instance.
230  static NexDebugSession* s_pInstance;
231 
232 /*!
233  @brief This constructor is private because the singleton pattern is used.
234 */
235  NexDebugSession();
236 
237 /*!
238  @brief This destructor is private because the singleton pattern is used.
239 */
240  virtual ~NexDebugSession();
241 
242 /*!
243  @brief This copy constructor is private because the singleton pattern is used.
244 */
246 
247 /*!
248  @brief This assignment operator is private because the singleton pattern is used.
249 */
250  NexDebugSession& operator=(const NexDebugSession&);
251 
252  virtual Result initialize();
253  virtual void finalize();
254 
255  nn::nex::MatchmakeExtensionClient m_MatchMakingClient;
256 
257  NexDebugSessionJob* m_pDebugSessionJob;
258  bool m_IsStartedup;
259  common::AsyncContext m_InternalAsyncContext;
260  u32 m_AsyncProcessType;
261 };
262 }
263 }
264 } // End of namespace nn::pia::inet.
Definition: assert.h:115
Base class that manages information specific to updating session conditions.
Definition: inet_NexUpdateSessionSetting.h:41
Represents the calling context.
Definition: common_CallContext.h:43
Class that manages settings specific to session creation.
Definition: inet_NexCreateSessionSetting.h:35
(For debugging.) This class handles dummy sessions for debugging.
Definition: inet_NexDebugSession.h:54
static NexDebugSession * GetInstance()
Gets a pointer to the NexDebugSession instance (singleton pattern).
Definition: inet_NexDebugSession.h:78
This is the common base class used inside the Pia library.
Definition: common_RootObject.h:40