1 /*---------------------------------------------------------------------------* 2 3 Copyright (C) Nintendo. All rights reserved. 4 5 These coded instructions, statements, and computer programs contain 6 proprietary information of Nintendo of America Inc. and/or Nintendo 7 Company Ltd., and are protected by Federal copyright law. They may 8 not be disclosed to third parties or copied or duplicated in any form, 9 in whole or in part, without the prior written consent of Nintendo. 10 11 *---------------------------------------------------------------------------*/ 12 #ifndef NN_AC_AC_API_H_ 13 #define NN_AC_AC_API_H_ 14 15 #include <nn/ac/ac_Types.h> 16 #include <nn/ac/ac_Result.h> 17 18 #ifdef __cplusplus 19 20 namespace nn { 21 namespace ac { 22 23 //! @addtogroup nn_ac 24 //! @{ 25 26 //! @defgroup nn_ac_api_cpp Automatic Connection (AC) API (C++) 27 //! @brief This is a list of Automatic Connection (AC) library C++ members. 28 //! @{ 29 30 //! @name Initializing and Finalizing the Library 31 //! @{ 32 33 /*! 34 @brief Initializes the Automatic Connection (AC) library. 35 This function must be called before calling any functions in the <tt>nn::ac</tt> namespace. 36 Returns <tt>nn::ResultSuccess</tt> on success. 37 If this function has already been called, it does nothing and returns, but the count is recorded internally. 38 @return Returns the execution result of the function. The following values are returned. 39 @retval nn::ResultSuccess Indicates success. 40 @retval nn::ac::ResultAlreadyInitialized Indicates that the connection process is over. (This result should not occur.) 41 42 43 44 */ 45 nn::Result Initialize(); 46 47 /*! 48 @brief Finalizes the AC library. 49 If using the AC library again after calling this function, perform the initialization again with the <tt>nn::ac::Initialize</tt> function. 50 If the connection was established using the <tt>nn::ac::Connect</tt> or <tt>nn::ac::ConnectAsync</tt> functions, close the connection with the <tt>nn::ac::Close</tt> function before calling this function. 51 If no connection has been established, you may call this function at any time because the <tt>nn::ac::Close</tt> function does not need to be called. 52 This function asserts if called more times than the <tt>nn::ac::Initialize</tt> function. 53 @return None. 54 55 56 57 58 */ 59 void Finalize(); 60 61 //! @} 62 63 //! @name Connecting and Disconnecting 64 //! @{ 65 66 /*! 67 @brief Creates a network connection synchronously. 68 Attempts to connect according to the default profile, among the network settings profiles saved in advance in the system. 69 None of the other profiles are referenced. 70 Use the <tt>nn::ac::GetLastErrorCode</tt> function to get the error code if the connection fails. 71 If the application uses the network, have it do so between when the connection is made with this function (or <tt>nn::ac::ConnectAsync</tt>) and when the connection is closed with the <tt>nn::ac::Close</tt> function. 72 @return Returns the execution result of the function. The following values are returned. 73 @retval nn::ResultSuccess Indicates success. 74 @retval nn::ac::ResultNotAcInitialized() Indicates that the function was called before the AC library was initialized with the <tt>nn::ac::Initialize</tt> function. In debug builds, the function asserts before this error is returned. 75 @retval nn::ac::ResultCanceled() Indicates that the connection was canceled. Another process closed the connection. (The error code is not set.) 76 @retval nn::ac::ResultNotFoundAccessPoint() Indicates that the connection could not be completed in time. For WEP, this error also occurs when the security key is incorrect. 77 @retval nn::ac::ResultConflictIpAddress() Indicates an IP address conflict. 78 @retval nn::ac::ResultFailedConnectAp() Indicates that the access point with the specified SSID could not be found, or the signal strength is very poor. 79 @retval nn::ac::ResultInvalidKeyValue() Indicates that the security key is incorrect. 80 @retval nn::ac::ResultNotInitialized() Indicates that the default network settings have not been saved. 81 @retval nn::ac::ResultInvalidData() Indicates incorrect settings in the saved settings. (However, the same check is performed when saving.) 82 @retval nn::ac::ResultAlreadyExclusive() Indicates an attempt to connect in local communication mode. 83 @retval nn::ac::ResultFatal() Indicates that the number of connection tasks that can be registered at one time has been exceeded. 84 85 86 87 88 */ 89 nn::Result Connect(); 90 91 /*! 92 @brief Creates a network connection asynchronously. 93 Attempts to connect according to the default profile, among the network settings profiles saved in advance in the system. 94 None of the other profiles are referenced. 95 96 Use the <tt>nn::ac::GetStatus</tt> or <tt>nn::ac::GetConnectStatus</tt> function to check the status of asynchronous processes. 97 Use the <tt>nn::ac::GetConnectResult</tt> function to get processing results. For failures, use the <tt>nn::ac::GetLastErrorCode</tt> function to get the error code. 98 If the application uses the network, have it do so between when the connection is made with this function (or <tt>nn::ac::Connect</tt>) and when the connection is closed with the <tt>nn::ac::Close</tt> function. 99 @return Returns the execution result of the function. The following values are returned. 100 @retval nn::ResultSuccess Indicates success. However, this result does not mean that the <tt>Connect</tt> process itself was successful. It indicates that the request to the AC for <tt>Connect</tt> processing succeeded. 101 @retval nn::ac::ResultNotAcInitialized() Indicates that the function was called before the AC library was initialized with the <tt>nn::ac::Initialize</tt> function. In debug builds, the function asserts before this error is returned. 102 @retval nn::ac::ResultFatal() Indicates that the number of connection tasks that can be registered at one time has been exceeded. 103 104 105 106 107 */ 108 nn::Result ConnectAsync(); 109 110 /*! 111 @brief Closes a network connection. 112 Closes connections made with the <tt>nn::ac::Connect</tt> or <tt>nn::ac::ConnectAsync</tt> functions. 113 If a connection is from another process, however, the connection is not actually disconnected even if this function is called. 114 The function also returns success in this case. 115 This function is asynchronous. 116 When disconnection instructions are issued to AC, control returns immediately from the function. 117 Use the <tt>nn::ac::GetCloseStatus</tt> function to get the progress of a process. 118 (<tt>nn::ac::GetStatus</tt> is a function that checks the progress of asynchronous connection functions. It cannot get the progress of the disconnection process.) 119 There is no function for getting the result, but there is no need for the application to check it. 120 @return Returns the execution result of the function. The following values are returned. 121 @retval nn::ResultSuccess Indicates success. However, the close operation itself might not be successful. This result indicates that the request to AC for close processing succeeded. 122 @retval nn::ac::ResultNotAcInitialized() Indicates that the function was called before the AC library was initialized with the <tt>nn::ac::Initialize</tt> function. In debug builds, the function asserts before this error is returned. 123 124 125 126 127 128 129 */ 130 nn::Result Close(); 131 132 //! @} 133 134 //! @name Checking the Status of an Asynchronous Process 135 //! @{ 136 137 /*! 138 @brief Gets the processing status of an asynchronous connection function. 139 This function performs the same operation as the <tt>nn::ac::GetConnectStatus</tt> function. 140 See the <tt>nn::ac::GetConnectStatus</tt> function reference. 141 142 */ 143 nn::Result GetStatus( nn::ac::Status* pStatus ); 144 145 /*! 146 @brief Gets the processing status of an asynchronous connection function. 147 Specifically, this function gets the processing progress status of the asynchronous <tt>nn::ac::ConnectAsync</tt> function. 148 (Get the progress of the <tt>nn::ac::Close</tt> function with the <tt>nn::ac::GetCloseStatus</tt> function.) 149 The <tt>nn::ac::GetStatus</tt> and <tt>nn::ac::GetConnectStatus</tt> functions are operationally the same. 150 If successful (<tt>nn::ResultSuccess</tt> is returned), a valid value is stored in <var>pStatus</var>. 151 The meanings of the saved values are as follows. 152 <table> 153 <tr><th>Value</th><th>Meaning</th></tr> 154 <tr><td><tt>nn::ac::STATUS_PROCESSING</tt></td><td>Indicates that the function is still processing. </td></tr> 155 <tr><td><tt>nn::ac::STATUS_OK</tt></td><td>Indicates that the process succeeded. </td></tr> 156 <tr><td><tt>nn::ac::STATUS_FAILED</tt></td><td>Indicates that the process failed. </td></tr> 157 </table> 158 This function is intended to be called after an asynchronous connection process has started. If an asynchronous connection process has never been run, the value that can be obtained by calling this function is undefined. 159 If it results in <tt>nn::ac::STATUS_OK</tt> or <tt>nn::ac::STATUS_FAILED</tt>, the value is maintained until the next asynchronous connection process. 160 When this function returns <tt>nn::ac::STATUS_OK</tt>, the connection state cache for the <tt>nn::ac::IsApplicationConnected</tt> function is destroyed. For more information, see the <tt>nn::ac::IsApplicationConnected</tt> function. 161 @param[out] pStatus The processing status 162 @return Returns the execution result of the function. The following values are returned. 163 @retval nn::ResultSuccess Indicates success. 164 @retval nn::ac::ResultNotAcInitialized() Indicates that the function was called before the AC library was initialized with the <tt>nn::ac::Initialize</tt> function. In debug builds, the function asserts before this error is returned. 165 166 167 168 169 170 171 172 173 */ 174 nn::Result GetConnectStatus( nn::ac::Status* pStatus ); 175 176 /*! 177 @brief Gets the processing status of an asynchronous disconnection function. 178 Specifically, this function gets the processing progress status of the asynchronous <tt>nn::ac::Close</tt> function. 179 (Get the progress of the <tt>nn::ac::ConnectAsync</tt> function with the <tt>nn::ac::GetStatus</tt> or <tt>nn::ac::GetConnectStatus</tt> functions.) 180 If successful (<tt>nn::ResultSuccess</tt> is returned), a valid value is stored in <var>pStatus</var>. 181 The meanings of the saved values are as follows. 182 <table> 183 <tr><th>Value</th><th>Meaning</th></tr> 184 <tr><td><tt>nn::ac::STATUS_PROCESSING</tt></td><td>Indicates that the function is still processing. </td></tr> 185 <tr><td><tt>nn::ac::STATUS_OK</tt></td><td>Indicates that the process succeeded. </td></tr> 186 <tr><td><tt>nn::ac::STATUS_FAILED</tt></td><td>Indicates that the process failed. </td></tr> 187 </table> 188 This function is intended to be called after an asynchronous disconnection process has started. If an asynchronous disconnection process has never been run, the value that can be obtained by calling this function is undefined. 189 If it results in <tt>nn::ac::STATUS_OK</tt> or <tt>nn::ac::STATUS_FAILED</tt>, the value is maintained until the next asynchronous disconnection process. 190 @param[out] pStatus The processing status 191 @return Returns the execution result of the function. The following values are returned. 192 @retval nn::ResultSuccess Indicates success. 193 @retval nn::ac::ResultNotAcInitialized() Indicates that the function was called before the AC library was initialized with the <tt>nn::ac::Initialize</tt> function. In debug builds, the function asserts before this error is returned. 194 195 196 197 198 199 200 */ 201 nn::Result GetCloseStatus( nn::ac::Status* pStatus ); 202 203 /*! 204 @brief Gets the result of an asynchronous connection function. 205 This function gets the result after the <tt>Connect</tt> process running at the request of the asynchronous <tt>nn::ac::ConnectAsync</tt> function ends. 206 The values stored in <var>pResult</var> are the same as the <tt>Result</tt> values for the <tt>nn::ac::Connect</tt> function. 207 @param[out] pResult The result of the <tt>nn::ac::ConnectAsync</tt> connection function. 208 @return Returns the execution result of the function. The following values are returned. 209 @retval nn::ResultSuccess Indicates success. 210 @retval nn::ac::ResultNotAcInitialized() Indicates that the function was called before the AC library was initialized with the <tt>nn::ac::Initialize</tt> function. In debug builds, the function asserts before this error is returned. 211 212 213 214 */ 215 nn::Result GetConnectResult( nn::Result* pResult ); 216 217 //! @} 218 219 //! @name Checking the Connection Status 220 //! @{ 221 222 /*! 223 @brief Gets whether there is a connection to the network. 224 The <var>pIsConnected</var> pointer points to the address that will hold the value of the connection status (<tt>true</tt> for connected or <tt>false</tt> for not connected). 225 If the application's connection status is <tt>true</tt>, it indicates that the status is somewhere between calls to the <tt>nn::ac::Connect</tt> function and the <tt>nn::ac::Close</tt> function. 226 There are cases where an application is physically connected to the network before it calls the <tt>nn::ac::Connect</tt> function. However, from the application's perspective, it can only use the network from the time it requests a connection using the <tt>nn::ac::Connect</tt> function until it closes that connection using the <tt>nn::ac::Close</tt> function. 227 However, even if the application does not call the <tt>nn::ac::Close</tt> function, the connection may be closed by network devices losing power or other processes that disconnect the entire system. 228 In such cases, the connection status of the application is <tt>false</tt>. 229 The AC library automatically reconnects when connectivity is lost. However, even if the application connects this way, its connection status remains <tt>false</tt> because of the previous disconnection until the <tt>nn::ac::Connect</tt> function is called again. 230 This function only gets the connection status. Note that because of the load of other threads or processes, the function may return the actual connection status several milliseconds after it is called. 231 This function caches the connection status for the standard time (1 second), and when this function is called again, it returns the cached value. 232 The function goes into the process for getting the actual connection status if called after the standard time for the cache has been exceeded. 233 Be careful about the load on the system in such cases. 234 However, after the <tt>nn::ac::Connect</tt> function succeeds and the connection is closed with the <tt>nn::ac::CloseAll</tt> function, the connection status cache is destroyed, so this function returns the correct connection status even if it is called immediately afterward. 235 Also, if you open a connection with the asynchronous <tt>nn::ac::ConnectAsync</tt> function and the <tt>nn::ac::GetConnectStatus</tt> function reports that the connection is complete, this function still returns the correct connection status because internally the connection status cache has been destroyed. 236 @param[out] pIsConnected Stores whether there is a connection. If <tt>true</tt>, the application is connected. 237 @return Returns the execution result of the function. The following values are returned. 238 @retval nn::ResultSuccess Indicates success. 239 @retval nn::ac::ResultNotAcInitialized() Indicates that the function was called before the AC library was initialized with the <tt>nn::ac::Initialize</tt> function. In debug builds, the function asserts before this error is returned. 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 */ 263 nn::Result IsApplicationConnected( bool* pIsConnected ); 264 265 //! @} 266 267 //! @name Getting Error Codes 268 //! @{ 269 270 /*! 271 @brief Gets the last error code issued. 272 This error code is for displaying an error on the screen if <tt>Connect</tt> or <tt>Close</tt> processes do not succeed. 273 The function may return <tt>0</tt> if it is not necessary to show an error. 274 Get the error codes after detecting the processing failure and before calling other AC functions. 275 The error codes might be cleared or overwritten by error codes for other processes. 276 Note, however, that the error code does not change regardless of whether you call the <tt>nn::ac::GetConnectResult</tt> function to get a <tt>Result</tt> object; the <tt>nn::ac::GetLastErrorCode</tt> function to get an error code; the <tt>nn::ac::GetStatus</tt>, <tt>nn::ac::GetConnectStatus</tt>, or <tt>nn::ac::GetCloseStatus</tt> functions to get a <tt>Status</tt> object; or the <tt>nn::ac::IsApplicationConnected</tt> function to get the connection status. 277 @param[out] pErrorCode The error code. 278 @return Returns the execution result of the function. The following values are returned. 279 @retval nn::ResultSuccess Indicates success. 280 @retval nn::ac::ResultNotAcInitialized() Indicates that the function was called before the AC library was initialized with the <tt>nn::ac::Initialize</tt> function. In debug builds, the function asserts before this error is returned. 281 282 283 284 285 286 287 288 */ 289 nn::Result GetLastErrorCode( nn::ac::ErrorCode* pErrorCode ); 290 291 //! @} 292 293 //! @name Getting Addresses 294 //! @{ 295 /*! 296 @brief Gets the assigned IP address. 297 @param[out] pAddress The address. 298 @return Returns the execution result of the function. The following values are returned. 299 @retval nn::ResultSuccess Indicates success. 300 @retval nn::ac::ResultNotAcInitialized() Indicates that the function was called before the AC library was initialized with the <tt>nn::ac::Initialize</tt> function. In debug builds, the function asserts before this error is returned. 301 @retval nn::ac::ResultInvalidParameter() Indicates that <tt>NULL</tt> was specified in the obtained region. In debug builds, the function asserts before this error is returned. 302 */ 303 nn::Result GetAssignedAddress( nn::ac::IpAddress *pAddress ); 304 /*! 305 @brief Gets the assigned primary DNS address. 306 @param[out] pAddress The primary DNS address. 307 @return Returns the execution result of the function. The following values are returned. 308 @retval nn::ResultSuccess Indicates success. 309 @retval nn::ac::ResultNotAcInitialized() Indicates that the function was called before the AC library was initialized with the <tt>nn::ac::Initialize</tt> function. In debug builds, the function asserts before this error is returned. 310 @retval nn::ac::ResultInvalidParameter() Indicates that <tt>NULL</tt> was specified in the obtained region. In debug builds, the function asserts before this error is returned. 311 */ 312 nn::Result GetAssignedPreferedDns( nn::ac::IpAddress *pAddress ); 313 /*! 314 @brief Gets the assigned secondary DNS address. 315 @param[out] pAddress The secondary DNS address. 316 @return Returns the execution result of the function. The following values are returned. 317 @retval nn::ResultSuccess Indicates success. 318 @retval nn::ac::ResultNotAcInitialized() Indicates that the function was called before the AC library was initialized with the <tt>nn::ac::Initialize</tt> function. In debug builds, the function asserts before this error is returned. 319 @retval nn::ac::ResultInvalidParameter() Indicates that <tt>NULL</tt> was specified in the obtained region. In debug builds, the function asserts before this error is returned. 320 */ 321 // Gets secondary DNS. 322 nn::Result GetAssignedAlternativeDns( nn::ac::IpAddress *pAddress ); 323 /*! 324 @brief Gets the assigned gateway address. 325 @param[out] pAddress The assigned gateway address. 326 @return Returns the execution result of the function. The following values are returned. 327 @retval nn::ResultSuccess Indicates success. 328 @retval nn::ac::ResultNotAcInitialized() Indicates that the function was called before the AC library was initialized with the <tt>nn::ac::Initialize</tt> function. In debug builds, the function asserts before this error is returned. 329 @retval nn::ac::ResultInvalidParameter() Indicates that <tt>NULL</tt> was specified in the obtained region. In debug builds, the function asserts before this error is returned. 330 */ 331 nn::Result GetAssignedGateway( nn::ac::IpAddress *pAddress ); 332 /*! 333 @brief Gets the assigned subnet mask. 334 @param[out] pAddress The assigned subnet mask. 335 @return Returns the execution result of the function. The following values are returned. 336 @retval nn::ResultSuccess Indicates success. 337 @retval nn::ac::ResultNotAcInitialized() Indicates that the function was called before the AC library was initialized with the <tt>nn::ac::Initialize</tt> function. In debug builds, the function asserts before this error is returned. 338 @retval nn::ac::ResultInvalidParameter() Indicates that <tt>NULL</tt> was specified in the obtained region. In debug builds, the function asserts before this error is returned. 339 */ 340 nn::Result GetAssignedSubnet( nn::ac::IpAddress *pAddress ); 341 342 //! @} 343 344 //! @} 345 //! @} 346 347 } // namespace ac 348 } // namespace nn 349 350 #endif // __cplusplus 351 352 #include <nn/util/detail/util_CLibImpl.h> 353 354 //! @addtogroup nn_ac 355 //! @{ 356 357 //! @defgroup nn_ac_api_c Automatic Connection (AC) API (C) 358 //! @brief This is a list of Automatic Connection (AC) library C members. 359 //! @{ 360 361 //! @name Handling Processing Results 362 //! @{ 363 364 /*! 365 @brief Checks whether the process succeeded. 366 @param[in] result Specifies the processing result. 367 @return Returns whether it was successful. 368 */ 369 NN_EXTERN_C BOOL ACIsSuccess(ACResult result); 370 /*! 371 @brief Checks whether the process failed. 372 @param[in] result Specifies the processing result. 373 @return Returns whether it failed. 374 */ 375 NN_EXTERN_C BOOL ACIsFailure(ACResult result); 376 /*! 377 @brief Checks whether to retry. 378 @param[in] result Specifies the processing result. 379 @return Returns whether to retry. 380 */ 381 NN_EXTERN_C BOOL ACIsRetryRequired(ACResult result); 382 383 //! @} 384 385 //! @name Initializing and Finalizing the Library 386 //! @{ 387 388 /*! 389 @brief See the corresponding C++ function <tt>@ref nn::ac::Initialize</tt>. 390 */ 391 NN_EXTERN_C ACResult ACInitialize( void ); 392 /*! 393 @brief See the corresponding C++ function <tt>@ref nn::ac::Finalize</tt>. 394 */ 395 NN_EXTERN_C void ACFinalize( void ); 396 397 //! @} 398 399 //! @name Connecting and Disconnecting 400 //! @{ 401 402 /*! 403 @brief See the corresponding C++ function <tt>@ref nn::ac::Connect</tt>. 404 */ 405 NN_EXTERN_C ACResult ACConnect( void ); 406 /*! 407 @brief See the corresponding C++ function <tt>@ref nn::ac::ConnectAsync</tt>. 408 */ 409 NN_EXTERN_C ACResult ACConnectAsync( void ); 410 /*! 411 @brief See the corresponding C++ function <tt>@ref nn::ac::Close</tt>. 412 */ 413 NN_EXTERN_C ACResult ACClose( void ); 414 415 //! @} 416 417 //! @name Checking the Status of an Asynchronous Process 418 //! @{ 419 420 /*! 421 @brief See the corresponding C++ function <tt>@ref nn::ac::GetStatus</tt>. 422 */ 423 NN_EXTERN_C ACResult ACGetStatus( ACStatus* pStatus ); 424 /*! 425 @brief See the corresponding C++ function <tt>@ref nn::ac::GetConnectStatus</tt>. 426 */ 427 NN_EXTERN_C ACResult ACGetConnectStatus( ACStatus* pStatus ); 428 /*! 429 @brief See the corresponding C++ function <tt>@ref nn::ac::GetCloseStatus</tt>. 430 */ 431 NN_EXTERN_C ACResult ACGetCloseStatus( ACStatus* pStatus ); 432 433 /*! 434 @brief See the corresponding C++ function <tt>@ref nn::ac::GetConnectResult</tt>. 435 */ 436 NN_EXTERN_C ACResult ACGetConnectResult( ACResult* pResult ); 437 438 //! @} 439 440 //! @name Checking the Connection Status 441 //! @{ 442 443 /*! 444 @brief See the corresponding C++ function <tt>@ref nn::ac::IsApplicationConnected</tt>. 445 */ 446 NN_EXTERN_C ACResult ACIsApplicationConnected( BOOL* pIsConnected ); 447 448 //! @} 449 450 //! @name Getting Error Codes 451 //! @{ 452 453 /*! 454 @brief See the corresponding C++ function <tt>@ref nn::ac::GetLastErrorCode</tt>. 455 */ 456 NN_EXTERN_C ACResult ACGetLastErrorCode( ACErrorCode* pErrorCode ); 457 458 //! @} 459 460 //! @name Getting Addresses 461 //! @{ 462 463 /*! 464 @brief See the corresponding C++ function <tt>@ref nn::ac::GetAssignedAddress</tt>. 465 */ 466 NN_EXTERN_C ACResult ACGetAssignedAddress( ACIpAddress* pAddress ); 467 /*! 468 @brief See the corresponding C++ function <tt>@ref nn::ac::GetAssignedPreferedDns</tt>. 469 */ 470 NN_EXTERN_C ACResult ACGetAssignedPreferedDns( ACIpAddress* pAddress ); 471 /*! 472 @brief See the corresponding C++ function <tt>@ref nn::ac::GetAssignedAlternativeDns</tt>. 473 */ 474 NN_EXTERN_C ACResult ACGetAssignedAlternativeDns( ACIpAddress* pAddress ); 475 /*! 476 @brief See the corresponding C++ function <tt>@ref nn::ac::GetAssignedGateway</tt>. 477 */ 478 NN_EXTERN_C ACResult ACGetAssignedGateway( ACIpAddress* pAddress ); 479 /*! 480 @brief See the corresponding C++ function <tt>@ref nn::ac::GetAssignedSubnet</tt>. 481 */ 482 NN_EXTERN_C ACResult ACGetAssignedSubnet( ACIpAddress* pAddress ); 483 484 //! @} 485 486 //! @} 487 //! @} 488 489 #endif // NN_AC_AC_API_H_ 490