CTR Pia  4.11.3
Game Communication Engine
local_LocalNetwork.h
1 /*---------------------------------------------------------------------------*
2  Project: Pia
3  File: local_LocalNetwork.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/local/local_LocalNetworkSetting.h>
18 
19 #include <pia/common/common_RootObject.h>
20 #include <pia/common/common_CallContext.h>
21 #include <pia/common/common_CriticalSection.h>
22 
23 namespace nn
24 {
25 namespace pia
26 {
27 namespace common
28 {
29 
30 class StationAddress;
31 }
32 }
33 } // end of namespace nn::pia::local
34 
35 namespace nn
36 {
37 namespace pia
38 {
39 namespace local
40 {
41 
42 // Forward declarations.
43 class LocalNetworkManager;
44 class LocalMigrationManager;
45 class LocalAroundNetworkSearchManager;
46 class LocalCreateNetworkJob;
47 class LocalDestroyNetworkJob;
48 class LocalScanNetworkJob;
49 class LocalConnectNetworkJob;
50 class LocalDisconnectNetworkJob;
51 class LocalForceDisconnectNetworkJob;
52 class LocalBackgroundProcessJob;
53 class LocalNetworkSetting;
54 class UdsNetworkSetting;
55 class LocalNetworkDescription;
56 class UdsNetworkDescription;
57 class LocalCreateNetworkSetting;
58 class LocalConnectNetworkSetting;
59 class LocalScanNetworkSetting;
60 
61 /*!
62 @brief Class for handling the local network.
63 
64 @date 2014-10-23 The <tt>Initialize</tt> function now stops on an assert if device memory is passed to Pia.
65 @date 2014-03-03 Initial version.
66 
67 */
69 {
70 public:
71 /*!
72 @brief Creates the <tt>LocalNetwork</tt> class instance (singleton pattern).
73 
74 @return Returns a <tt>Result</tt> value that indicates success if the instance is created successfully.
75 
76 @retval ResultNotInitialized Indicates that the <tt>local</tt> module is not initialized.
77 @retval ResultInvalidState Indicates that the instance was created at the wrong time.
78 @retval ResultAlreadyExists Indicates that an instance has already been created.
79 */
80  static nn::Result CreateInstance();
81 
82 
83 /*!
84 @brief Destroys the <tt>LocalNetwork</tt> class instance (singleton pattern).
85 */
86  static void DestroyInstance();
87 
88 /*!
89 @brief Gets the <tt>LocalNetwork</tt> class instance (singleton pattern).
90 
91 @details Returns a <tt>NULL</tt> pointer if the instance has not yet been created using the <tt>@ref Initialize</tt> function.
92 
93 @return Returns a pointer to the <tt>LocalNetwork</tt> instance.
94 
95 */
97  {
98  return s_pInstance;
99  }
100 
101 private:
102  LocalNetwork();
103  virtual ~LocalNetwork();
104 /*!
105 @brief This copy constructor is private.
106 */
107  LocalNetwork(const LocalNetwork&);
108 
109 /*!
110 @brief This assignment operator is private.
111 */
112  LocalNetwork& operator=(const LocalNetwork&);
113 
114 public:
115 /*!
116 @brief Initializes the instance. Make this call between the <tt>BeginSetup</tt> and <tt>EndSetup</tt> functions.
117 
118 @attention Device memory cannot be used as the <tt>LocalNetwork</tt> receive buffer, so <tt>common::Initialize</tt> stops on an assert if device memory is passed.
119 
120 @param[in] setting Specifies various settings.
121 
122 @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.
123 
124 @retval ResultAlreadyInitialized Indicates that the instance is already initialized. Programming error. Fix your program so that this error is not returned.
125 @retval ResultInvalidArgument Indicates that an argument is invalid. Programming error. Fix your program so that this error is not returned.
126 
127 @see Finalize
128 
129 */
130  nn::Result Initialize(const LocalNetworkSetting& setting);
131 
132 
133 /*!
134 @brief Finalizes the instance.
135 
136 @see Initialize
137 */
138  void Finalize();
139 
140 
141 /*!
142 @brief Startup process.
143 
144 @attention Do not transition to sleep mode during a call to this function.
145 
146 @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess</tt> function returns <tt>true</tt> if execution succeeds.
147 
148 @retval ResultInvalidConnection Indicates that the device entered wireless off mode. Perform cleanup.
149 @retval ResultInvalidState Indicates that the function cannot be executed in this state. Programming error. Fix your program so that this error is not returned.
150 
151 @see Cleanup
152 */
153  nn::Result Startup();
154 
155 
156 /*!
157 @brief Cleanup process.
158 
159 @see Startup
160 */
161  void Cleanup();
162 
163 
164 /*!
165 @brief Enumerates the reason for the disconnection.
166 */
168  {
169  DISCONNECT_REASON_BEFORE_COMMUNICATION = 0, //!< Communication has not yet started.
170  DISCONNECT_REASON_NETWORK_IS_AVAILABLE, //!< Connection being maintained.
171  DISCONNECT_REASON_REQUEST_FROM_MYSELF, //!< Disconnected from the network due to local action.
172  DISCONNECT_REASON_REQUEST_FROM_SYSTEM, //!< Disconnected from the network due to a system request (transition to wireless off mode or sleep mode).
173  DISCONNECT_REASON_DISCARDED_FROM_NETWORK, //!< Kicked off the network due to an instruction from the host. Alternatively, the client was disconnected due to degraded connectivity and the host's internal state.
174  DISCONNECT_REASON_CONNECTION_LOST, //!< The connection could not be maintained because a beacon could not be received from the host for a certain period due to degraded connectivity.
175  DISCONNECT_REASON_UNKNOWN //!< Disconnected for an unknown reason.
176  };
177 
178 
179 /*!
180 @brief Represents the state that allows or denies new participants.
181 */
183  {
184  ALLOW_PARTICIPATING_STATE_NONE = 0, //!< Not connected to the network.
185  ALLOW_PARTICIPATING_STATE_ALLOW, //!< New participants are allowed.
186  ALLOW_PARTICIPATING_STATE_DISALLOW, //!< New participants are denied.
187  ALLOW_PARTICIPATING_STATE_ALLOW_ONLY_RECONNECTION //!< Only reconnections are allowed.
188  };
189 
190 
191 /*!
192 @cond PRIVATE
193 */
194  nn::Result CreateNetwork(nn::pia::common::CallContext* pCallContext, const LocalCreateNetworkSetting* pCreateNetworkSetting);
195  //! @endcond
196 
197 /*!
198 @brief Creates the local network.
199 
200 @details Receives the network settings and starts the asynchronous process that creates the local network.
201 The device that creates the network becomes the local network host.
202 The started process advances by periodically calling the <tt>@ref nn::pia::common::Scheduler::Dispatch</tt> function.
203 Use <tt>@ref IsCompletedCreateNetwork</tt> to check whether the process has completed and <tt>@ref GetCreateNetworkResult</tt> to check the result.
204 
205 @param[in] pCreateNetworkSetting Settings for the network to create.
206 
207 @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess</tt> function returns <tt>true</tt> if the process is successfully started.
208 
209 @retval ResultNotInitialized Indicates that the <tt>LocalNetwork</tt> is not initialized. Programming error. Fix your program so that this error is not returned.
210 @retval ResultInvalidArgument Indicates that an argument is invalid. Programming error. Fix your program so that this error is not returned.
211 @retval ResultInvalidState Indicates that processes are already running. Alternatively, another asynchronous process is running. Or, the station is already connected. Programming error. Fix your program so that this error is not returned.
212 @retval ResultErrorOccurred Indicates that an internal error occurred. Perform cleanup.
213 
214 @see IsCompletedCreateNetwork, GetCreateNetworkResult
215 */
216  nn::Result CreateNetworkAsync(const LocalCreateNetworkSetting* pCreateNetworkSetting);
217 
218 /*!
219 @brief Checks the completion of <tt>CreateNetworkAsync</tt> asynchronous processing.
220 
221 @details This function checks the completion of asynchronous processes started with <tt>@ref CreateNetworkAsync</tt>.
222 
223 @return Returns <tt>true</tt> if the asynchronous process has completed; <tt>false</tt> otherwise. Returns <tt>false</tt> if the asynchronous process has not started or if another asynchronous process has been started.
224 
225 @see CreateNetworkAsync, GetCreateNetworkResult
226 */
227  bool IsCompletedCreateNetwork();
228 
229 /*!
230 @brief Gets the result of <tt>CreateNetworkAsync</tt> asynchronous processing.
231 
232 @details This function gets the results after an asynchronous process started by <tt>@ref CreateNetworkAsync</tt> ends.
233 
234 @return Returns the result of <tt>CreateNetworkAsync</tt> asynchronous processing. On success, 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.
235 @retval ResultNotInitialized Indicates that the communication library is not initialized. Programming error. Fix your program so that this error is not returned.
236 @retval ResultInvalidState Indicates that the function cannot be executed in this state. Alternatively, results cannot be obtained in this state. Programming error. Fix your program so that this error is not returned.
237 @retval ResultInvalidConnection Indicates that the device entered wireless off mode. Perform cleanup.
238 @retval ResultTimeOut Timed out. Perform cleanup.
239 @retval ResultCancelled Canceled. Perform cleanup.
240 @retval ResultErrorOccurred Indicates that an internal error occurred. Perform cleanup.
241 
242 @see CreateNetworkAsync, IsCompletedCreateNetwork
243 */
244  nn::Result GetCreateNetworkResult();
245 
246 
247 /*!
248 @cond PRIVATE
249 */
250  nn::Result DestroyNetwork(nn::pia::common::CallContext* pCallContext);
251  //! @endcond
252 
253 /*!
254 @brief Destroys the local network.
255 
256 @details Starts an asynchronous process that destroys the local network.
257 The started process advances by periodically calling the <tt>@ref nn::pia::common::Scheduler::Dispatch</tt> function.
258 Use <tt>@ref IsCompletedDestroyNetwork</tt> to check whether the process has completed and <tt>@ref GetDestroyNetworkResult</tt> to check the result.
259 After the process is completed, clean up <tt>LocalNetwork</tt>.
260 
261 @attention This function can only be called by the local network host.
262 
263 @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess</tt> function returns <tt>true</tt> if the process is successfully started.
264 
265 @retval ResultNotInitialized Indicates that the <tt>LocalNetwork</tt> is not initialized. Programming error. Fix your program so that this error is not returned.
266 @retval ResultInvalidState Indicates that processes are already running. Alternatively, another asynchronous process is running. Alternatively, the device is not the local network host. Programming error. Fix your program so that this error is not returned.
267 
268 @see IsCompletedDestroyNetwork, GetDestroyNetworkResult
269 */
270  nn::Result DestroyNetworkAsync();
271 
272 /*!
273 @brief Checks the completion of <tt>DestroyNetworkAsync</tt> asynchronous processing.
274 
275 @details This function checks the completion of asynchronous processes started with <tt>@ref DestroyNetworkAsync</tt>.
276 
277 @return Returns <tt>true</tt> if the asynchronous process has completed; <tt>false</tt> otherwise. Returns <tt>false</tt> if the asynchronous process has not started or if another asynchronous process has been started.
278 
279 @see DestroyNetworkAsync, GetDestroyNetworkResult
280 */
281  bool IsCompletedDestroyNetwork();
282 
283 /*!
284 @brief Gets the result of <tt>DestroyNetworkAsync</tt> asynchronous processing.
285 
286 @details This function gets the results after an asynchronous process started by <tt>@ref DestroyNetworkAsync</tt> ends.
287 
288 @return Returns the result of <tt>DestroyNetworkAsync</tt> asynchronous processing. On success, 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.
289 @retval ResultNotInitialized Indicates that the communication library is not initialized. Programming error. Fix your program so that this error is not returned.
290 @retval ResultInvalidState Indicates that the function cannot be executed in this state. Alternatively, results cannot be obtained in this state. Programming error. Fix your program so that this error is not returned.
291 @retval ResultInvalidConnection Indicates that the device entered wireless off mode. Perform cleanup.
292 @retval ResultCancelled Canceled. Perform cleanup.
293 @retval ResultErrorOccurred Indicates that an internal error occurred. Perform cleanup.
294 
295 @see DestroyNetworkAsync, IsCompletedDestroyNetwork
296 */
297  nn::Result GetDestroyNetworkResult();
298 
299 
300 /*!
301 @cond PRIVATE
302 */
303  nn::Result ConnectNetwork(nn::pia::common::CallContext* pCallContext, const LocalConnectNetworkSetting* pConnectNetworkSetting);
304  //! @endcond
305 
306 /*!
307 @brief Connects to the local network.
308 
309 @details Starts an asynchronous process that connects to the local network. The device that connects becomes a local host client.
310 The started process advances by periodically calling the <tt>@ref nn::pia::common::Scheduler::Dispatch</tt> function.
311 Use <tt>@ref IsCompletedConnectNetwork</tt> to check whether the process has completed and <tt>@ref GetConnectNetworkResult</tt> to check the result.
312 You can also cancel the process by calling the <tt>@ref CancelConnectNetworkAsync</tt> function during the process.
313 Even if you cancel the process, wait until you confirm the process completion using <tt>@ref IsCompletedConnectNetwork</tt>.
314 If you get results that indicate that the process failed (or was canceled), clean up <tt>LocalNetwork</tt> and start it again.
315 
316 @param[in] pConnectNetworkSetting Settings for the network to connect to.
317 
318 @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess</tt> function returns <tt>true</tt> if the process is successfully started.
319 
320 @retval ResultNotInitialized Indicates that the <tt>LocalNetwork</tt> is not initialized. Programming error. Fix your program so that this error is not returned.
321 @retval ResultInvalidArgument Indicates that an argument is invalid. Programming error. Fix your program so that this error is not returned.
322 @retval ResultInvalidState Indicates that processes are already running. Alternatively, another asynchronous process is running. Or, the station is already connected. Programming error. Fix your program so that this error is not returned.
323 @retval ResultDifferentVersion Indicates a different application version or the local network version of the target network. Perform cleanup.
324 
325 @see IsCompletedConnectNetwork, GetConnectNetworkResult, CancelConnectNetworkAsync
326 */
327  nn::Result ConnectNetworkAsync(const LocalConnectNetworkSetting* pConnectNetworkSetting);
328 
329 /*!
330 @brief Checks the completion of <tt>ConnectNetworkAsync</tt> asynchronous processing.
331 
332 @details This function checks the completion of asynchronous processes started with <tt>@ref ConnectNetworkAsync</tt>.
333 
334 @return Returns <tt>true</tt> if the asynchronous process has completed; <tt>false</tt> otherwise. Returns <tt>false</tt> if the asynchronous process has not started or if another asynchronous process has been started.
335 
336 @see ConnectNetworkAsync, GetConnectNetworkResult, CancelConnectNetworkAsync
337 */
338  bool IsCompletedConnectNetwork();
339 
340 /*!
341 @brief Gets the result of <tt>ConnectNetworkAsync</tt> asynchronous processing.
342 
343 @details This function gets the results after an asynchronous process started by <tt>@ref ConnectNetworkAsync</tt> ends.
344 
345 @return Returns the result of <tt>ConnectNetworkAsync</tt> asynchronous processing. On success, 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.
346 @retval ResultNotInitialized Indicates that the communication library is not initialized. Programming error. Fix your program so that this error is not returned.
347 @retval ResultInvalidState Indicates that the function cannot be executed in this state. Alternatively, results cannot be obtained in this state. Programming error. Fix your program so that this error is not returned.
348 @retval ResultInvalidNetwork Indicates that the connection target network was not found. Perform cleanup.
349 @retval ResultNetworkIsFull The maximum number of connections has already been exceeded. Perform cleanup.
350 @retval ResultJoinRequestDenied The host denied the attempt to join. Perform cleanup. Handle appropriately in the application. When an error occurs in Internet communication, 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. Do not use the error/EULA applet (CTR) for local communication errors.
351 @retval ResultInvalidConnection Indicates that the device entered wireless off mode. Perform cleanup.
352 @retval ResultTimeOut Timed out.
353 It could also be returned when <tt>@ref nn::pia::local::UdsConnectNetworkSetting::m_Passphrase</tt> is incorrect. Perform cleanup.
354 @retval ResultCancelled Canceled. Perform cleanup.
355 @retval ResultErrorOccurred Indicates that an internal error occurred. Perform cleanup.
356 
357 @see ConnectNetworkAsync, IsCompletedConnectNetwork, CancelConnectNetworkAsync
358 */
359  nn::Result GetConnectNetworkResult();
360 
361 /*!
362 @brief Cancels <tt>ConnectNetworkAsync</tt> asynchronous processes.
363 
364 @details This function cancels asynchronous processes started by <tt>ConnectNetworkAsync</tt>.
365 The cancel process advances by periodically calling the <tt>@ref nn::pia::common::Scheduler::Dispatch</tt> function.
366 The library promptly cancels asynchronous processes after this function is called, but use the <tt>@ref IsCompletedConnectNetwork</tt> function to check whether the cancellation has completed.
367 
368 @return Returns the result of canceling <tt>ConnectNetworkAsync</tt> asynchronous processing. On success, 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.
369 @retval ResultInvalidState Returned when no <tt>ConnectNetworkAsync</tt> asynchronous processing is being performed. Programming error. Fix your program so that this error is not returned.
370 
371 @see ConnectNetworkAsync, IsCompletedConnectNetwork, GetConnectNetworkResult
372 
373 */
374  nn::Result CancelConnectNetworkAsync();
375 
376 
377 /*!
378 @cond PRIVATE
379 */
380  nn::Result DisconnectNetwork(nn::pia::common::CallContext* pCallContext);
381  //! @endcond
382 
383 /*!
384 @brief Disconnects from the local network.
385 
386 @details Starts an asynchronous process that disconnects from the local network.
387 When the local device is the local network host, this function succeeds if host migration is enabled, and the manual host migration process starts.
388 The started process advances by periodically calling the <tt>@ref nn::pia::common::Scheduler::Dispatch</tt> function.
389 Use <tt>@ref IsCompletedDisconnectNetwork</tt> to check whether the process has completed and <tt>@ref GetDisconnectNetworkResult</tt> to check the result.
390 After the process is completed, clean up <tt>LocalNetwork</tt>.
391 
392 @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess</tt> function returns <tt>true</tt> if the process is successfully started.
393 
394 @retval ResultNotInitialized Indicates that the <tt>LocalNetwork</tt> is not initialized. Programming error. Fix your program so that this error is not returned.
395 @retval ResultInvalidState Indicates that processes are already running. Alternatively, another asynchronous process is running.
396 Alternatively, the local device is the local network host, but host migration is disabled. Programming error. Fix your program so that this error is not returned.
397 
398 @see IsCompletedDisconnectNetwork, GetDisconnectNetworkResult
399 */
400  nn::Result DisconnectNetworkAsync();
401 
402 /*!
403 @brief Checks the completion of <tt>DisconnectNetworkAsync</tt> asynchronous processing.
404 
405 @details This function checks the completion of asynchronous processes started with <tt>@ref DisconnectNetworkAsync</tt>.
406 
407 @return Returns <tt>true</tt> if the asynchronous process has completed; <tt>false</tt> otherwise. Returns <tt>false</tt> if the asynchronous process has not started or if another asynchronous process has been started.
408 
409 @see DisconnectNetworkAsync, GetDisconnectNetworkResult
410 */
411  bool IsCompletedDisconnectNetwork();
412 
413 /*!
414 @brief Gets the result of <tt>DisconnectNetworkAsync</tt> asynchronous processing.
415 
416 @details This function gets the results after an asynchronous process started by <tt>@ref DisconnectNetworkAsync</tt> ends.
417 
418 @return Returns the result of <tt>DisconnectNetworkAsync</tt> asynchronous processing. On success, 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.
419 @retval ResultNotInitialized Indicates that the communication library is not initialized. Programming error. Fix your program so that this error is not returned.
420 @retval ResultInvalidState Indicates that the function cannot be executed in this state. Alternatively, results cannot be obtained in this state. Programming error. Fix your program so that this error is not returned.
421 @retval ResultInvalidConnection Indicates that the device entered wireless off mode. Perform cleanup.
422 @retval ResultCancelled Canceled. Perform cleanup.
423 @retval ResultErrorOccurred Indicates that an internal error occurred. Perform cleanup.
424 
425 @see DisconnectNetworkAsync, IsCompletedDisconnectNetwork
426 */
427  nn::Result GetDisconnectNetworkResult();
428 
429 
430 /*!
431 @cond PRIVATE
432 */
433  nn::Result ScanNetwork(nn::pia::common::CallContext* pCallContext, u32 localCommunicationId, u8 subId);
434  //! @endcond
435 
436 /*!
437 @brief Scans for nearby local networks.
438 
439 @details Starts an asynchronous process that scans for nearby local networks. Fails if called while connecting to a network.
440 The started process advances by periodically calling the <tt>@ref nn::pia::common::Scheduler::Dispatch</tt> function.
441 Use <tt>@ref IsCompletedScanNetwork</tt> to check whether the process has completed and <tt>@ref GetScanNetworkResult</tt> to check the result.
442 You can also cancel the process by calling the <tt>@ref CancelScanNetworkAsync</tt> function during the process.
443 Even if you cancel the process, wait until you can confirm the process completion using <tt>@ref IsCompletedScanNetwork</tt>.
444 Use <tt>@ref GetNetworkDescriptionList</tt> and <tt>@ref GetNetworkDescription</tt> to get information on the local networks that were found through scanning.
445 Use <tt>@ref GetStationInfoList</tt> to get information on the connected stations that were found through scanning.
446 Get the strength of the signal sent from the network by calling <tt>@ref GetRadioStrength</tt>.
447 These items of information become available after the network scanning ends successfully. If scanning starts again, they can no longer be obtained.
448 The information is also no longer available when you begin the process of creating or connecting to a network.
449 
450 @param[in] localCommunicationId Specifies the local communication ID. Specify the value generated by <tt>@ref CreateLocalCommunicationId</tt>.
451 @param[in] subId Specifies the ID for identifying the communication mode. The application can set any arbitrary value for this parameter.
452 To search all IDs, specify <tt>0xff</tt>.
453 
454 @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess</tt> function returns <tt>true</tt> if the process is successfully started.
455 
456 @retval ResultNotInitialized Indicates that the <tt>LocalNetwork</tt> is not initialized. Programming error. Fix your program so that this error is not returned.
457 @retval ResultInvalidState Indicates that processes are already running. Alternatively, another asynchronous process is running. Alternatively, the system is already connected to the network. Programming error. Fix your program so that this error is not returned.
458 
459 @see IsCompletedScanNetwork, GetScanNetworkResult, CancelScanNetworkAsync
460 
461 
462 */
463  nn::Result ScanNetworkAsync(u32 localCommunicationId, u8 subId);
464 
465 /*!
466 @brief Checks the completion of <tt>ScanNetworkAsync</tt> asynchronous processing.
467 
468 @details This function checks the completion of asynchronous processes started with <tt>@ref ScanNetworkAsync</tt>.
469 
470 @return Returns <tt>true</tt> if the asynchronous process has completed; <tt>false</tt> otherwise. Returns <tt>false</tt> if the asynchronous process has not started or if another asynchronous process has been started.
471 
472 @see ScanNetworkAsync, GetScanNetworkResult, CancelScanNetworkAsync
473 */
474  bool IsCompletedScanNetwork();
475 
476 /*!
477 @brief Gets the result of <tt>ScanNetworkAsync</tt> asynchronous processing.
478 
479 @details This function gets the results after an asynchronous process started by <tt>@ref ScanNetworkAsync</tt> ends.
480 
481 @return Returns the result of <tt>ScanNetworkAsync</tt> asynchronous processing. On success, 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.
482 @retval ResultNotInitialized Indicates that the communication library is not initialized. Programming error. Fix your program so that this error is not returned.
483 @retval ResultInvalidState Indicates that the function cannot be executed in this state. Alternatively, results cannot be obtained in this state. Programming error. Fix your program so that this error is not returned.
484 @retval ResultInvalidConnection Indicates that the device entered wireless off mode. Perform cleanup.
485 @retval ResultNegligibleFault Canceled.
486 @retval ResultErrorOccurred Indicates that an internal error occurred. Perform cleanup.
487 
488 @see ScanNetworkAsync, IsCompletedScanNetwork, CancelScanNetworkAsync
489 */
490  nn::Result GetScanNetworkResult();
491 
492 /*!
493 @brief Cancels <tt>ScanNetworkAsync</tt> asynchronous processes.
494 
495 @details This function cancels asynchronous processes started by <tt>ScanNetworkAsync</tt>.
496 The cancel process advances by periodically calling the <tt>@ref nn::pia::common::Scheduler::Dispatch</tt> function.
497 The library promptly cancels asynchronous functions after this function is called, but use the <tt>@ref IsCompletedScanNetwork</tt> function to check whether the cancellation has completed.
498 
499 @return Returns the result of canceling <tt>ScanNetworkAsync</tt> asynchronous processing. On success, 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.
500 @retval ResultInvalidState Returned when no <tt>ConnectNetworkAsync</tt> asynchronous processing is being performed. Programming error. Fix your program so that this error is not returned.
501 
502 @see ScanNetworkAsync, IsCompletedScanNetwork, GetScanNetworkResult
503 
504 */
505  nn::Result CancelScanNetworkAsync();
506 
507 
508 /*!
509 @brief Creates a local communication ID from a unique ID.
510 
511 @details This function generates a 32-bit value (the <I>local communication ID</I>) to use for local communication from the 20-bit unique ID (the title-specific ID) assigned by the Nintendo Licensing department.
512 If you have not been assigned a unique ID by the Nintendo Licensing department, use one of the unique IDs for game software prototypes (<tt>0xFF000</tt> through <tt>0xFF3FF</tt>).
513 
514 @attention However, for your retail product, be sure to get a unique ID from the Nintendo Licensing department.
515 
516 @param[in] uniqueId Specifies a unique ID. To communicate more than one title, specify the unique ID of any of the titles.
517 @param[in] isTrial Specifies the flag for handling cases where the same unique ID is shared by both the final product and trial version. If you do not want the final product and trial version to communicate with each other, specify a value of <tt>true</tt> for trial versions. <b>Note:</b> Always set this flag to <tt>false</tt> in retail products.
518 
519 @return Returns the created local communication ID.
520 */
521  u32 CreateLocalCommunicationId(u32 uniqueId, bool isTrial = false) const;
522 
523 
524 /*!
525 @brief Gets the beacon data set by the application.
526 
527 @param[out] pBuffer Buffer that stores the data obtained.
528 @param[out] pDataSize Specifies the size of the data obtained.
529 @param[in] bufferSize The size of the buffer that stores the data obtained.
530 @param[in] pNetworkDescription The information for the network whose data you want to get.
531 
532 @return Returns a <tt>Result</tt> value indicating success if data was successfully obtained from the network.
533 
534 @retval ResultNotInitialized Indicates that the <tt>LocalNetwork</tt> is not initialized. Programming error. Fix your program so that this error is not returned.
535 @retval ResultInvalidArgument Indicates that an argument is invalid. Programming error. Fix your program so that this error is not returned.
536 @retval ResultNoData There was no data to get.
537 */
538  nn::Result GetApplicationData(void* pBuffer, size_t* pDataSize, size_t bufferSize, const LocalNetworkDescription* pNetworkDescription) const;
539 
540 /*!
541 @brief Gets the size of the beacon data set by the application.
542 
543 @param[out] pDataSize Specifies the size of the beacon data set by the application.
544 @param[in] pNetworkDescription The information for the network whose beacon data size you want to get.
545 
546 @return Returns a <tt>Result</tt> value indicating success if data was successfully obtained from the network.
547 
548 @retval ResultNotInitialized Indicates that the <tt>LocalNetwork</tt> is not initialized. Programming error. Fix your program so that this error is not returned.
549 @retval ResultInvalidArgument Indicates that an argument is invalid. Programming error. Fix your program so that this error is not returned.
550 @retval ResultNoData There was no data to get.
551 */
552  nn::Result GetApplicationDataSize(size_t* pDataSize, const LocalNetworkDescription* pNetworkDescription) const;
553 
554 /*!
555 @brief Gets the data set in the beacon.
556 
557 @attention This function is intended to be called by a device connected to a local network.
558 
559 @attention This function may not return correct results if called during local host migration.
560 Do not call it during host migration (while the <tt>@ref LocalNetwork::IsDuringHostMigration</tt> function returns <tt>true</tt>).
561 
562 @param[out] pBuffer Specifies the buffer to write data to.
563 @param[out] pDataSize Specifies the length of the retrieved data.
564 @param[in] bufferSize Specifies the size of the buffer to write data to.
565 
566 @return Returns a <tt>Result</tt> value indicating success on successful completion.
567 
568 @retval ResultNotInitialized Indicates that the instance is not initialized. Programming error. Fix your program so that this error is not returned.
569 @retval ResultInvalidState Indicates that the function cannot be executed in this state. Programming error. Fix your program so that this error is not returned.
570 @retval ResultInvalidArgument Indicates that an argument is invalid. Programming error. Fix your program so that this error is not returned.
571 @retval ResultInvalidConnection Indicates that the device entered wireless off mode. Perform cleanup.
572 @retval ResultNotInCommunication In a state where communication is not possible. Either a disconnect will shortly be detected, or host migration is about to begin. The function may succeed if called after host migration completes.
573 */
574  nn::Result GetApplicationDataFromBeacon(void* pBuffer, size_t* pDataSize, size_t bufferSize) const;
575 
576 /*!
577 @brief Gets the size of the data set in the beacon.
578 
579 @attention This function is intended to be called by a device connected to a local network.
580 
581 @attention This function may not return correct results if called during local host migration.
582 Do not call it during host migration (while the <tt>@ref LocalNetwork::IsDuringHostMigration</tt> function returns <tt>true</tt>).
583 
584 @param[out] pDataSize The size of the data set in the beacon.
585 
586 @return Returns a <tt>Result</tt> value indicating success on successful completion.
587 
588 @retval ResultNotInitialized Indicates that the instance is not initialized. Programming error. Fix your program so that this error is not returned.
589 @retval ResultInvalidState Indicates that the function cannot be executed in this state. Programming error. Fix your program so that this error is not returned.
590 @retval ResultInvalidArgument Indicates that an argument is invalid. Programming error. Fix your program so that this error is not returned.
591 @retval ResultInvalidConnection Indicates that the device entered wireless off mode. Perform cleanup.
592 @retval ResultNotInCommunication In a state where communication is not possible. Either a disconnect will shortly be detected, or host migration is about to begin. The function may succeed if called after host migration completes.
593 */
594  nn::Result GetApplicationDataSizeFromBeacon(size_t* pDataSize) const;
595 
596 /*!
597 @brief Sets data in the beacon.
598 
599 @details Only the local network host can execute this function.
600 
601 @attention This function may not return correct results if called during local host migration.
602 Do not call it during host migration (while the <tt>@ref LocalNetwork::IsDuringHostMigration</tt> function returns <tt>true</tt>).
603 
604 @param[in] pData Specifies a pointer to the data to set.
605 @param[in] dataSize Specifies the size of the data to set. The size must be no greater than the value that can be obtained with <tt>@ref GetBeaconApplicationDataSizeMax</tt>.
606 
607 @return Returns a <tt>Result</tt> value indicating success on successful completion.
608 
609 @retval ResultNotInitialized Indicates that the instance is not initialized. Programming error. Fix your program so that this error is not returned.
610 @retval ResultInvalidState Indicates that the function cannot be executed in this state. Programming error. Fix your program so that this error is not returned.
611 @retval ResultInvalidArgument Indicates that an argument is invalid. Programming error. Fix your program so that this error is not returned.
612 @retval ResultInvalidConnection Indicates that the device entered wireless off mode. Or, it was disconnected from the local network. Perform cleanup.
613 */
614  nn::Result SetApplicationDataToBeacon(const void* pData, size_t dataSize);
615 
616 /*!
617 @brief Gets the local network information.
618 
619 @details Gets a list of the local network information discovered by the <tt>@ref ScanNetworkAsync</tt> function.
620 
621 @param[out] paLocalNetworkDescriptionList Specifies the buffer that stores the obtained network information.
622 @param[out] pValidNetworkNum The number of networks for which network information was obtained.
623 @param[in] networkDescriptionListSize The size of the buffer that stores the obtained network information.
624 
625 @return Returns a <tt>Result</tt> value indicating success if information was successfully obtained.
626 
627 @retval ResultNotInitialized Indicates that the <tt>LocalNetwork</tt> is not initialized. Programming error. Fix your program so that this error is not returned.
628 @retval ResultInvalidArgument Indicates that an argument is invalid. Programming error. Fix your program so that this error is not returned.
629 @retval ResultInvalidState Not in a state where data can be retrieved. Programming error. Fix your program so that this error is not returned.
630 */
631  nn::Result GetNetworkDescriptionList(LocalNetworkDescription* paLocalNetworkDescriptionList, u32* pValidNetworkNum, size_t networkDescriptionListSize);
632 
633 /*!
634 @brief Gets the local network information.
635 
636 @details Gets the local network information discovered by the <tt>@ref ScanNetworkAsync</tt> function.
637 
638 @param[out] pLocalNetworkDescription Specifies the buffer that stores the network information obtained.
639 @param[in] networkDescriptionIndex The index of the network information you want to get.
640 
641 @return Returns a <tt>Result</tt> value indicating success if information was successfully obtained.
642 
643 @retval ResultNotInitialized Indicates that the <tt>LocalNetwork</tt> is not initialized. Programming error. Fix your program so that this error is not returned.
644 @retval ResultInvalidArgument Indicates that an argument is invalid. Programming error. Fix your program so that this error is not returned.
645 @retval ResultInvalidState Not in a state where data can be retrieved. Programming error. Fix your program so that this error is not returned.
646 */
647  nn::Result GetNetworkDescription(LocalNetworkDescription* pLocalNetworkDescription, u32 networkDescriptionIndex);
648 
649 
650 /*!
651 @brief Gets information about the specified station.
652 
653 @param[out] pLocalStationInfo Specifies the buffer that stores the station information obtained.
654 @param[in] address The address of the station whose information you want to get.
655 
656 @return Returns a <tt>Result</tt> value indicating success if information was successfully obtained.
657 
658 @retval ResultNotInitialized Indicates <tt>LocalNetwork</tt> has not been started. Programming error. Fix your program so that this error is not returned.
659 @retval ResultInvalidArgument Indicates that an argument is invalid. Programming error. Fix your program so that this error is not returned.
660 @retval ResultNotFound The target station was not found. You might have been disconnected.
661 @retval ResultInvalidConnection Indicates that the device entered wireless off mode. Perform cleanup.
662 */
663  nn::Result GetStationInfo(LocalStationInfo* pLocalStationInfo, const common::StationAddress& address) const;
664 
665 /*!
666 @brief Gets a list of information about the stations participating in the specified network.
667 
668 @param[out] paLocalStationInfoList Specifies the buffer that stores the list of station information obtained. The array length must be equal to or greater than the maximum number of stations that can connect to the specified network.
669 @param[in] listLength Specifies the length of the <var>paLocalStationInfoList</var> array. This must be equal to or greater than the maximum number of stations that can connect to the specified network.
670 @param[in] networkListIndex The index of the network whose information you want to get.
671 
672 @return Returns a <tt>Result</tt> value indicating success if information was successfully obtained.
673 
674 @retval ResultInvalidArgument Indicates that an argument is invalid. Programming error. Fix your program so that this error is not returned.
675 @retval ResultInvalidState Indicates that no networks are found. Alternatively, data cannot be obtained in this state. Programming error. Fix your program so that this error is not returned.
676 @retval ResultNoData Indicates that information could not be obtained.
677 @retval ResultInvalidConnection Indicates that the device entered wireless off mode. Perform cleanup.
678 */
679  nn::Result GetStationInfoList(LocalStationInfo* paLocalStationInfoList, u8 listLength, u32 networkListIndex) const;
680 
681 
682 /*!
683 @brief Gets the largest size of data the application can set in the beacon.
684 
685 @return Returns the largest size of data the application can set in the beacon.
686 */
687  size_t GetBeaconApplicationDataSizeMax() const;
688 
689 /*!
690 @brief Gets the number of networks discovered.
691 
692 @return Returns the number of networks discovered.
693 */
694  u32 GetFoundNetworkNum() const
695  {
696  return m_FoundNetworkNum;
697  }
698 
699 
700 /*!
701 @brief Gets whether the local device is the local network host.
702 
703 @return Returns whether the local device is the local network host.
704 */
705  bool IsHost() const;
706 
707 
708 /*!
709 @brief Gets whether the local device is a local network client.
710 
711 @return Returns whether the local device is a local network client.
712 */
713  bool IsClient() const;
714 
715 
716 /*!
717 @brief Gets whether there is a connection to the network.
718 
719 @attention Note that <tt>false</tt> could be returned during host migration (while the <tt>@ref LocalNetwork::IsDuringHostMigration</tt> function returns <tt>true</tt>).
720 
721 @return Returns whether there is a connection to the network.
722 
723 */
724  bool IsConnected() const
725  {
726  return IsHost() || IsClient();
727  }
728 
729 
730 /*!
731 @brief Gets whether local host migration is in progress.
732 
733 @return Returns whether local host migration is in progress.
734 */
735  bool IsDuringHostMigration() const;
736 
737 
738 /*!
739 @brief Gets whether local host migration is enabled.
740 
741 @return Returns whether local host migration is enabled.
742 */
743  bool IsEnableHostMigration() const;
744 
745 
746 /*!
747 @brief Gets the link level.
748 
749 @details There are four link levels, from <tt>0</tt> through <tt>3</tt>. <tt>0</tt>: Communication quality is extremely poor, or communication has not been established. <tt>1</tt>: Communication quality is poor. <tt>2</tt>: Communication quality is not very good. <tt>3</tt>: Communication quality is good.
750 
751 @attention This function may not return correct results if called during local host migration.
752 Do not call it during host migration (while the <tt>@ref LocalNetwork::IsDuringHostMigration</tt> function returns <tt>true</tt>).
753 
754 @return Returns the communication quality of the network currently connected to. If not connected, <tt>0</tt> is returned.
755 
756 */
757  u8 GetLinkLevel() const;
758 
759 
760 /*!
761 @brief Parses a network and gets the signal strength sent from that network.
762 
763 @details There are four levels of signal strength, from <tt>0</tt> through <tt>3</tt>. <tt>0</tt>: Communication quality is extremely poor, or communication has not been established. <tt>1</tt>: Communication quality is poor. <tt>2</tt>: Communication quality is not very good. <tt>3</tt>: Communication quality is good.
764 
765 @attention The link level retrieved corresponds to the local network information stored when <tt>@ref ScanNetworkAsync</tt> is executed.
766 To get the saved local network information list, use the <tt>@ref GetNetworkDescriptionList</tt> function.
767 
768 @param[out] pRadioStrength Specifies a pointer to the variable that records the signal strength. The data is stored only if the network can be analyzed correctly.
769 @param[in] descriptionListIndex Specifies the variable for specifying the network to parse. Specify the network number you want to analyze by index, starting from <tt>0</tt> for the first entry in the local network information list.
770 
771 @return Returns a <tt>Result</tt> value indicating success on successful completion.
772 
773 @retval ResultInvalidState No information is stored in the local network information list. Alternatively, data cannot be obtained in this state. Programming error. Fix your program so that this error is not returned.
774 @retval ResultInvalidArgument Indicates that an argument is invalid. Programming error. Fix your program so that this error is not returned.
775 
776 */
777  nn::Result GetRadioStrength(u8* pRadioStrength, u32 descriptionListIndex) const;
778 
779 
780 /*!
781 @brief Gets the IEEE 802.11b/g wireless channel in use.
782 
783 @attention This function may not return correct results if called during local host migration.
784 Do not call it during host migration (while the <tt>@ref LocalNetwork::IsDuringHostMigration</tt> function returns <tt>true</tt>).
785 
786 @return Returns the current channel. If not connected or if the attempt to get the channel fails, <tt>0</tt> is returned.
787 */
788  u8 GetNetworkChannel() const;
789 
790 /*!
791 @brief Disallows new clients from joining the network. This function does not affect clients that are currently connected.
792 
793 @details This feature is intended to deny connections by new clients attempting to connect during interactive gaming.
794 When you want to allow connections again, call the <tt>@ref AllowParticipating</tt> function.
795 
796 @note In some cases, the information set by this function is not carried over to the new network after host migration occurs due to abnormal disconnection of the host.
797 
798 @attention This function can only be called by the local network host.
799 
800 @param[in] isDisallowToReconnect If set to <tt>false</tt>, only the clients that were disconnected after calling this function can reconnect.
801 
802 @return Returns a <tt>Result</tt> value indicating success on successful completion.
803 
804 @retval ResultNotInitialized Indicates that the instance is not initialized. Programming error. Fix your program so that this error is not returned.
805 @retval ResultInvalidState Indicates that the function cannot be executed in this state. Programming error. Fix your program so that this error is not returned.
806 @retval ResultInvalidConnection Indicates that the device entered wireless off mode. Or, it was disconnected from the local network. Perform cleanup.
807 */
808  nn::Result DisallowParticipating(bool isDisallowToReconnect = true);
809 
810 /*!
811 @brief Allows new clients to join the network.
812 
813 @details This function re-enables connections from new clients that were denied by the <tt>@ref DisallowParticipating</tt> function.
814 
815 @note In some cases, the information set by this function is not carried over to the new network after host migration occurs due to abnormal disconnection of the host.
816 
817 @attention This function can only be called by the local network host.
818 
819 @return Returns a <tt>Result</tt> value indicating success on successful completion.
820 
821 @retval ResultNotInitialized Indicates that the instance is not initialized. Programming error. Fix your program so that this error is not returned.
822 @retval ResultInvalidState Indicates that the function cannot be executed in this state. Programming error. Fix your program so that this error is not returned.
823 @retval ResultInvalidConnection Indicates that the device entered wireless off mode. Or, it was disconnected from the local network. Perform cleanup.
824 */
825  nn::Result AllowParticipating();
826 
827 /*!
828 @cond PRIVATE
829 @brief Kicks the specified client off the network.
830 
831 @attention This function can only be called by the local network host.
832 
833 @param[in] address The <tt>@ref common::StationAddress</tt> for the client to kick off.
834 
835 @return Returns a <tt>Result</tt> value indicating success on successful completion.
836 
837 @retval ResultNotInitialized Indicates that the instance is not initialized. Programming error. Fix your program so that this error is not returned.
838 @retval ResultInvalidState Indicates that the function cannot be executed in this state. Programming error. Fix your program so that this error is not returned.
839 @retval ResultInvalidConnection Indicates that the device entered wireless off mode. Or, it was disconnected from the local network. Perform cleanup.
840 */
841  nn::Result EjectClient(const common::StationAddress& address);
842  //! @endcond
843 
844 /*!
845 @cond PRIVATE
846 @brief Kicks all clients off the network.
847 
848 @attention This function can only be called by the local network host.
849 
850 @return Returns a <tt>Result</tt> value indicating success on successful completion.
851 
852 @retval ResultNotInitialized Indicates that the instance is not initialized. Programming error. Fix your program so that this error is not returned.
853 @retval ResultInvalidState Indicates that the function cannot be executed in this state. Programming error. Fix your program so that this error is not returned.
854 @retval ResultInvalidConnection Indicates that the device entered wireless off mode. Or, it was disconnected from the local network. Perform cleanup.
855 */
856  nn::Result EjectClientAll();
857  //! @endcond
858 
859 /*!
860 @brief Gets the reason for being disconnected from the network.
861 
862 @details Resets to <tt>@ref DISCONNECT_REASON_BEFORE_COMMUNICATION</tt> when <tt>@ref Startup</tt> or <tt>@ref Cleanup</tt> is called.
863 
864 @return Returns the reason for being disconnected from the network.
865 */
867  {
868  return m_DisconnectReason;
869  }
870 
871 /*!
872 @cond PRIVATE
873 */
874  void SetDisconnectReason(DisconnectReason reason)
875  {
876  m_DisconnectReason = reason;
877  }
878  //! @endcond
879 
880 /*!
881 @brief Gets the state that indicates whether new participants are allowed or denied.
882 
883 @return Returns whether new participants are allowed or denied.
884 */
885  AllowParticipatingState GetAllowParticipatingState() const;
886 
887 /*!
888 @cond PRIVATE
889 */
890  void SetAllowParticipatingState(AllowParticipatingState reason)
891  {
892  m_AllowParticipatingState = reason;
893  }
894  //! @endcond
895 
896 /*!
897 @brief Gets whether nearby network search is enabled.
898 
899 @return Returns whether nearby network search is enabled.
900 */
901  bool IsEnableAroundNetworkSearch() const;
902 
903 /*!
904 @brief Begins nearby network search.
905 
906 @details Only the local network host can execute this function.
907 Only succeeds when nearby network search is enabled.
908 After this API is called, start notification is also sent to the clients.
909 
910 @return Returns a <tt>Result</tt> value indicating a successful start to nearby network search.
911 
912 @retval ResultNotInitialized Indicates that the instance is not initialized. Programming error. Fix your program so that this error is not returned.
913 @retval ResultInvalidState Indicates that the function cannot be executed in this state. Programming error. Fix your program so that this error is not returned.
914 */
915  nn::Result StartAroundNetworkSearch();
916 
917 /*!
918 @brief Terminates nearby network search.
919 
920 @details Only the local network host can execute this function.
921 Only succeeds when nearby network search is enabled.
922 After termination, any discovered networks are no longer available.
923 After this API is called, termination notification is also sent to the clients.
924 
925 @return Returns a <tt>Result</tt> value indicating a successful termination to nearby network search.
926 
927 @retval ResultNotInitialized Indicates that the instance is not initialized. Programming error. Fix your program so that this error is not returned.
928 @retval ResultInvalidState Indicates that the function cannot be executed in this state. Programming error. Fix your program so that this error is not returned.
929 */
930  nn::Result StopAroundNetworkSearch();
931 
932 /*!
933 @brief Gets whether nearby network search has begun.
934 
935 @return Returns whether nearby network search has begun.
936 */
937  bool IsAroundNetworkSearchActivated() const;
938 
939 /*!
940 @brief Sets the parameters for nearby network search.
941 
942 @details Settings are not shared with other stations. To do so, configure each and every station.
943 Only succeeds when nearby network search is enabled.
944 
945 @param[in] setting The parameters for nearby network search.
946 
947 @return Returns a <tt>Result</tt> value indicating a successful setting was made.
948 
949 @retval ResultNotInitialized Indicates that the instance is not initialized. Programming error. Fix your program so that this error is not returned.
950 @retval ResultInvalidState Indicates that the function cannot be executed in this state. Programming error. Fix your program so that this error is not returned.
951 */
952  nn::Result SetAroundNetworkSearchSetting(const LocalAroundNetworkSearchSetting& setting);
953 
954 /*!
955 @brief Gets the information for networks discovered during nearby network search.
956 
957 @details Also succeeds if zero networks were discovered.
958 Only succeeds when nearby network search is enabled.
959 
960 @param[out] paLocalAroundNetworkInfoList The buffer storing the obtained network information.
961 @param[out] pValidNetworkNum The number of networks for which network information was obtained.
962 @param[in] networkInfoListSize The size of the buffer storing the obtained network information.
963 
964 @return Returns a <tt>Result</tt> value indicating that information was obtained successfully.
965 
966 @retval ResultNotInitialized Indicates that the instance is not initialized. Programming error. Fix your program so that this error is not returned.
967 @retval ResultInvalidState Indicates that the function cannot be executed in this state. Programming error. Fix your program so that this error is not returned.
968 @retval ResultInvalidArgument Indicates that an argument is invalid. Programming error. Fix your program so that this error is not returned.
969 */
970  nn::Result GetAroundNetworkInfoList(LocalAroundNetworkInfo* paLocalAroundNetworkInfoList, u32* pValidNetworkNum, size_t networkInfoListSize) const;
971 
972 /*!
973 @cond PRIVATE
974 */
975  void SleepBeforeSend();
976  //! @endcond
977 
978 /*!
979 @cond PRIVATE
980 @brief Sets the sleep interval to use before sending data.
981 
982 @param[in] sleepTime The sleep time to use before sending data. The value is in milliseconds.
983 */
984  void SetSleepBeforeSendTime(s64 sleepTime);
985  //! @endcond
986 
987 /*!
988 @brief Prints information that is useful for debugging.
989 
990 @param[in] flag Specifies the bitwise OR of trace flags. For more information, see the <tt>@ref TraceFlag</tt> type.
991 */
992  virtual void Trace(u64 flag) const;
993 
994 
995 /*!
996 @cond PRIVATE
997 */
998  u8 GetTransportId() const;
999  LocalNetworkDescription* GetNetworkDescription(u32 index);
1000  LocalNetworkManager* GetLocalNetworkManager()
1001  {
1002  return m_pLocalNetworkManager;
1003  }
1004  LocalMigrationManager* GetLocalMigrationManager();
1005  LocalAroundNetworkSearchManager* GetLocalAroundNetworkSearchManager();
1006  LocalCreateNetworkJob* GetLocalCreateNetworkJob()
1007  {
1008  return m_pLocalCreateNetworkJob;
1009  }
1010  LocalBackgroundProcessJob* GetLocalBackgroundProcessJob()
1011  {
1012  return m_pLocalBackgroundProcessJob;
1013  }
1014 
1015  void* GetReceiveBuffer()
1016  {
1017  return m_pReceiveBuffer;
1018  }
1019  size_t GetReceiveBufferSize() const
1020  {
1021  return m_ReceiveBufferSize;
1022  }
1023  void* GetScanBuffer()
1024  {
1025  return m_pScanBuffer;
1026  }
1027  const void* GetScanBuffer() const
1028  {
1029  return m_pScanBuffer;
1030  }
1031  size_t GetScanBufferSize() const
1032  {
1033  return m_ScanBufferSize;
1034  }
1035  common::CriticalSection* GetScanBufferLock()
1036  {
1037  return &m_ScanBufferLock;
1038  }
1039 
1040  void RegisterUpdateEventCallback(LocalUpdateEventCallback callback, void* pParam);
1041  void UnregisterUpdateEventCallback();
1042  void ProcessUpdateEventDisconnected(u8 transportId);
1043  void ProcessUpdateEventMigrationStarted();
1044  void SetIsEnableGetScanData(bool isEnable)
1045  {
1046  m_IsEnableGetScanData = isEnable;
1047  }
1048  bool IsEnableGetScanData() const
1049  {
1050  return m_IsEnableGetScanData && !IsDuringHostMigration() && !IsConnected();
1051  }
1052 
1053  u32 GetSessionId() const;
1054  u32 GetSessionIdFromNetworkDescription(const LocalNetworkDescription* pNetworkDescription) const;
1055  bool IsForceDisconnect() const
1056  {
1057  return m_IsForceDisconnect;
1058  }
1059  void SetIsForceDisconnect(bool flag)
1060  {
1061  m_IsForceDisconnect = flag;
1062  }
1063  bool IsExpectDisconnectByKickout() const
1064  {
1065  return m_IsExpectDisconnectByKickout;
1066  }
1067  void SetIsExpectDisconnectByKickout(bool flag)
1068  {
1069  m_IsExpectDisconnectByKickout = flag;
1070  }
1071 
1072  u8 GetNetworkParticipantNum() const;
1073 
1074  bool IsAsyncProcessInProgress() const;
1075  //! @endcond
1076 
1077 private:
1078  nn::Result InitializeCore(const UdsNetworkSetting& setting);
1079  void CreateJobs();
1080  void DestroyJobs();
1081  void CleanupJobs();
1082 
1083  // For asynchronous processing.
1084  enum AsyncProcessingName
1085  {
1086  ASYNC_NOTHING = 0,
1087  ASYNC_CREATE_NETWORK,
1088  ASYNC_DESTROY_NETWORK,
1089  ASYNC_SCAN_NETWORK,
1090  ASYNC_CONNECT_NETWORK,
1091  ASYNC_DISCONNECT_NETWORK
1092  };
1093  void ResetInternalAsyncState();
1094  bool IsCompletedAsyncProcess(AsyncProcessingName processingName);
1095  nn::Result GetAsyncProcessResult(AsyncProcessingName processingName);
1096  nn::Result CancelAsyncProcess(AsyncProcessingName processingName);
1097 
1098 private:
1099  static LocalNetwork* s_pInstance;
1100  static bool s_IsInitialized;
1101 
1102  LocalNetworkType m_LocalNetworkType;
1103  LocalNetworkSetting* m_pLocalNetworkSetting;
1104  LocalNetworkDescription* m_paLocalNetworkDescriptionArray;
1105  u32 m_FoundNetworkNum;
1106 
1107  LocalNetworkManager* m_pLocalNetworkManager;
1108  LocalMigrationManager* m_pLocalMigrationManager;
1109  LocalAroundNetworkSearchManager* m_pLocalAroundNetworkSearchManager;
1110 
1111  LocalCreateNetworkJob* m_pLocalCreateNetworkJob;
1112  LocalDestroyNetworkJob* m_pLocalDestroyNetworkJob;
1113  LocalScanNetworkJob* m_pLocalScanNetworkJob;
1114  LocalConnectNetworkJob* m_pLocalConnectNetworkJob;
1115  LocalDisconnectNetworkJob* m_pLocalDisconnectNetworkJob;
1116  LocalForceDisconnectNetworkJob* m_pLocalForceDisconnectNetworkJob;
1117  LocalBackgroundProcessJob* m_pLocalBackgroundProcessJob;
1118 
1119  void* m_pReceiveBuffer; //!< Specifies the receive buffer. The buffer must be 4096-byte aligned, and its size must be a multiple of 4096.
1120  size_t m_ReceiveBufferSize; //!< Specifies the receive buffer size.
1121  bool m_IsReceiveBufferAllocatedByApplication; //!< Flag that indicates that the receive buffer was specified using a parameter from within the application.
1122  void* m_pScanBuffer; //!< Specifies the scan buffer.
1123  size_t m_ScanBufferSize; //!< Specifies the scan buffer size.
1124  common::CriticalSection m_ScanBufferLock; //!< Scan buffer lock.
1125 
1126  DisconnectReason m_DisconnectReason;
1127 
1128  // For asynchronous processing.
1129  common::CallContext m_InternalContext;
1130  AsyncProcessingName m_CurrentAsyncProcessingName;
1131 
1132  LocalUpdateEventCallback m_pfUpdateEventCallback;
1133  void* m_pUpdateEventCallbackParam;
1134 
1135  // Whether new participants are allowed or denied.
1136  AllowParticipatingState m_AllowParticipatingState;
1137 
1138  // Flag indicating whether scan data can be retrieved.
1139  bool m_IsEnableGetScanData;
1140 
1141  // For sleep prior to sending.
1142  bool m_IsNeedSleepBeforeSend;
1143  s64 m_LastSendTick;
1144  s64 m_SleepBeforeSendTick;
1145 
1146  // Flag for disconnection from the application, and then calling the destructor.
1147  bool m_IsForceDisconnect;
1148  // Flag for anticipating a disconnect due to being kicked out.
1149  bool m_IsExpectDisconnectByKickout;
1150 };
1151 }
1152 }
1153 } // end of namespace nn::pia::local
Disconnected from the network due to a system request (transition to wireless off mode or sleep mode)...
Definition: local_LocalNetwork.h:172
void Finalize(void)
Finalizes the common module.
Class for handling the local network.
Definition: local_LocalNetwork.h:68
New participants are denied.
Definition: local_LocalNetwork.h:186
Definition: assert.h:115
DisconnectReason GetDisconnectReason()
Gets the reason for being disconnected from the network.
Definition: local_LocalNetwork.h:866
The connection could not be maintained because a beacon could not be received from the host for a cer...
Definition: local_LocalNetwork.h:174
Class for configuring a local network.
Definition: local_LocalNetworkSetting.h:73
Class that holds information about the network discovered using nearby network search.
Definition: local_LocalNetworkSetting.h:262
Kicked off the network due to an instruction from the host. Alternatively, the client was disconnecte...
Definition: local_LocalNetwork.h:173
u32 GetFoundNetworkNum() const
Gets the number of networks discovered.
Definition: local_LocalNetwork.h:694
Disconnected from the network due to local action.
Definition: local_LocalNetwork.h:171
AllowParticipatingState
Represents the state that allows or denies new participants.
Definition: local_LocalNetwork.h:182
DisconnectReason
Enumerates the reason for the disconnection.
Definition: local_LocalNetwork.h:167
Represents the calling context.
Definition: common_CallContext.h:43
Represents an address used to uniquely identify stations. .
Definition: common_StationAddress.h:43
Class for configuring the creation of a local network.
Definition: local_LocalNetworkSetting.h:102
nn::Result Initialize(void *pMem, u32 size)
Initializes the common module.
Connection being maintained.
Definition: local_LocalNetwork.h:170
Class that holds information about a local network.
Definition: local_LocalNetworkSetting.h:121
static LocalNetwork * GetInstance()
Gets the LocalNetwork class instance (singleton pattern).
Definition: local_LocalNetwork.h:96
Class for configuring the nearby network search feature.
Definition: local_LocalNetworkSetting.h:275
Class for configuring networks that use the UDS library.
Definition: local_UdsNetworkSetting.h:40
Class for configuring a connection to a local network.
Definition: local_LocalNetworkSetting.h:152
bool IsConnected() const
Gets whether there is a connection to the network.
Definition: local_LocalNetwork.h:724
This is the common base class used inside the Pia library.
Definition: common_RootObject.h:40
Class that holds information about stations connected to a local network.
Definition: local_LocalNetworkSetting.h:230
New participants are allowed.
Definition: local_LocalNetwork.h:185