/*---------------------------------------------------------------------------* Copyright (C) Nintendo. All rights reserved. These coded instructions, statements, and computer programs contain proprietary information of Nintendo of America Inc. and/or Nintendo Company Ltd., and are protected by Federal copyright law. They may not be disclosed to third parties or copied or duplicated in any form, in whole or in part, without the prior written consent of Nintendo. *---------------------------------------------------------------------------*/ #ifndef NN_AC_AC_API_H_ #define NN_AC_AC_API_H_ #include #include #ifdef __cplusplus namespace nn { namespace ac { //! @addtogroup nn_ac //! @{ //! @defgroup nn_ac_api_cpp Automatic Connection (AC) API (C++) //! @brief This is a list of Automatic Connection (AC) library C++ members. //! @{ //! @name Initializing and Finalizing the Library //! @{ /*! @brief Initializes the Automatic Connection (AC) library. This function must be called before calling any functions in the nn::ac namespace. Returns nn::ResultSuccess on success. If this function has already been called, it does nothing and returns, but the count is recorded internally. @return Returns the execution result of the function. The following values are returned. @retval nn::ResultSuccess Indicates success. @retval nn::ac::ResultAlreadyInitialized Indicates that the connection process is over. (This result should not occur.) */ nn::Result Initialize(); /*! @brief Finalizes the AC library. If using the AC library again after calling this function, perform the initialization again with the nn::ac::Initialize function. If the connection was established using the nn::ac::Connect or nn::ac::ConnectAsync functions, close the connection with the nn::ac::Close function before calling this function. If no connection has been established, you may call this function at any time because the nn::ac::Close function does not need to be called. This function asserts if called more times than the nn::ac::Initialize function. @return None. */ void Finalize(); //! @} //! @name Connecting and Disconnecting //! @{ /*! @brief Creates a network connection synchronously. Attempts to connect according to the default profile, among the network settings profiles saved in advance in the system. None of the other profiles are referenced. Use the nn::ac::GetLastErrorCode function to get the error code if the connection fails. If the application uses the network, have it do so between when the connection is made with this function (or nn::ac::ConnectAsync) and when the connection is closed with the nn::ac::Close function. @return Returns the execution result of the function. The following values are returned. @retval nn::ResultSuccess Indicates success. @retval nn::ac::ResultNotAcInitialized() Indicates that the function was called before the AC library was initialized with the nn::ac::Initialize function. In debug builds, the function asserts before this error is returned. @retval nn::ac::ResultCanceled() Indicates that the connection was canceled. Another process closed the connection. (The error code is not set.) @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. @retval nn::ac::ResultConflictIpAddress() Indicates an IP address conflict. @retval nn::ac::ResultFailedConnectAp() Indicates that the access point with the specified SSID could not be found, or the signal strength is very poor. @retval nn::ac::ResultInvalidKeyValue() Indicates that the security key is incorrect. @retval nn::ac::ResultNotInitialized() Indicates that the default network settings have not been saved. @retval nn::ac::ResultInvalidData() Indicates incorrect settings in the saved settings. (However, the same check is performed when saving.) @retval nn::ac::ResultAlreadyExclusive() Indicates an attempt to connect in local communication mode. @retval nn::ac::ResultFatal() Indicates that the number of connection tasks that can be registered at one time has been exceeded. */ nn::Result Connect(); /*! @brief Creates a network connection asynchronously. Attempts to connect according to the default profile, among the network settings profiles saved in advance in the system. None of the other profiles are referenced. Use the nn::ac::GetStatus or nn::ac::GetConnectStatus function to check the status of asynchronous processes. Use the nn::ac::GetConnectResult function to get processing results. For failures, use the nn::ac::GetLastErrorCode function to get the error code. If the application uses the network, have it do so between when the connection is made with this function (or nn::ac::Connect) and when the connection is closed with the nn::ac::Close function. @return Returns the execution result of the function. The following values are returned. @retval nn::ResultSuccess Indicates success. However, this result does not mean that the Connect process itself was successful. It indicates that the request to the AC for Connect processing succeeded. @retval nn::ac::ResultNotAcInitialized() Indicates that the function was called before the AC library was initialized with the nn::ac::Initialize function. In debug builds, the function asserts before this error is returned. @retval nn::ac::ResultFatal() Indicates that the number of connection tasks that can be registered at one time has been exceeded. */ nn::Result ConnectAsync(); /*! @brief Closes a network connection. Closes connections made with the nn::ac::Connect or nn::ac::ConnectAsync functions. If a connection is from another process, however, the connection is not actually disconnected even if this function is called. The function also returns success in this case. This function is asynchronous. When disconnection instructions are issued to AC, control returns immediately from the function. Use the nn::ac::GetCloseStatus function to get the progress of a process. (nn::ac::GetStatus is a function that checks the progress of asynchronous connection functions. It cannot get the progress of the disconnection process.) There is no function for getting the result, but there is no need for the application to check it. @return Returns the execution result of the function. The following values are returned. @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. @retval nn::ac::ResultNotAcInitialized() Indicates that the function was called before the AC library was initialized with the nn::ac::Initialize function. In debug builds, the function asserts before this error is returned. */ nn::Result Close(); //! @} //! @name Checking the Status of an Asynchronous Process //! @{ /*! @brief Gets the processing status of an asynchronous connection function. This function performs the same operation as the nn::ac::GetConnectStatus function. See the nn::ac::GetConnectStatus function reference. */ nn::Result GetStatus( nn::ac::Status* pStatus ); /*! @brief Gets the processing status of an asynchronous connection function. Specifically, this function gets the processing progress status of the asynchronous nn::ac::ConnectAsync function. (Get the progress of the nn::ac::Close function with the nn::ac::GetCloseStatus function.) The nn::ac::GetStatus and nn::ac::GetConnectStatus functions are operationally the same. If successful (nn::ResultSuccess is returned), a valid value is stored in pStatus. The meanings of the saved values are as follows.
ValueMeaning
nn::ac::STATUS_PROCESSINGIndicates that the function is still processing.
nn::ac::STATUS_OKIndicates that the process succeeded.
nn::ac::STATUS_FAILEDIndicates that the process failed.
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. If it results in nn::ac::STATUS_OK or nn::ac::STATUS_FAILED, the value is maintained until the next asynchronous connection process. When this function returns nn::ac::STATUS_OK, the connection state cache for the nn::ac::IsApplicationConnected function is destroyed. For more information, see the nn::ac::IsApplicationConnected function. @param[out] pStatus The processing status @return Returns the execution result of the function. The following values are returned. @retval nn::ResultSuccess Indicates success. @retval nn::ac::ResultNotAcInitialized() Indicates that the function was called before the AC library was initialized with the nn::ac::Initialize function. In debug builds, the function asserts before this error is returned. */ nn::Result GetConnectStatus( nn::ac::Status* pStatus ); /*! @brief Gets the processing status of an asynchronous disconnection function. Specifically, this function gets the processing progress status of the asynchronous nn::ac::Close function. (Get the progress of the nn::ac::ConnectAsync function with the nn::ac::GetStatus or nn::ac::GetConnectStatus functions.) If successful (nn::ResultSuccess is returned), a valid value is stored in pStatus. The meanings of the saved values are as follows.
ValueMeaning
nn::ac::STATUS_PROCESSINGIndicates that the function is still processing.
nn::ac::STATUS_OKIndicates that the process succeeded.
nn::ac::STATUS_FAILEDIndicates that the process failed.
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. If it results in nn::ac::STATUS_OK or nn::ac::STATUS_FAILED, the value is maintained until the next asynchronous disconnection process. @param[out] pStatus The processing status @return Returns the execution result of the function. The following values are returned. @retval nn::ResultSuccess Indicates success. @retval nn::ac::ResultNotAcInitialized() Indicates that the function was called before the AC library was initialized with the nn::ac::Initialize function. In debug builds, the function asserts before this error is returned. */ nn::Result GetCloseStatus( nn::ac::Status* pStatus ); /*! @brief Gets the result of an asynchronous connection function. This function gets the result after the Connect process running at the request of the asynchronous nn::ac::ConnectAsync function ends. The values stored in pResult are the same as the Result values for the nn::ac::Connect function. @param[out] pResult The result of the nn::ac::ConnectAsync connection function. @return Returns the execution result of the function. The following values are returned. @retval nn::ResultSuccess Indicates success. @retval nn::ac::ResultNotAcInitialized() Indicates that the function was called before the AC library was initialized with the nn::ac::Initialize function. In debug builds, the function asserts before this error is returned. */ nn::Result GetConnectResult( nn::Result* pResult ); //! @} //! @name Checking the Connection Status //! @{ /*! @brief Gets whether there is a connection to the network. The pIsConnected pointer points to the address that will hold the value of the connection status (true for connected or false for not connected). If the application's connection status is true, it indicates that the status is somewhere between calls to the nn::ac::Connect function and the nn::ac::Close function. There are cases where an application is physically connected to the network before it calls the nn::ac::Connect function. However, from the application's perspective, it can only use the network from the time it requests a connection using the nn::ac::Connect function until it closes that connection using the nn::ac::Close function. However, even if the application does not call the nn::ac::Close function, the connection may be closed by network devices losing power or other processes that disconnect the entire system. In such cases, the connection status of the application is false. The AC library automatically reconnects when connectivity is lost. However, even if the application connects this way, its connection status remains false because of the previous disconnection until the nn::ac::Connect function is called again. 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. This function caches the connection status for the standard time (1 second), and when this function is called again, it returns the cached value. The function goes into the process for getting the actual connection status if called after the standard time for the cache has been exceeded. Be careful about the load on the system in such cases. However, after the nn::ac::Connect function succeeds and the connection is closed with the nn::ac::CloseAll function, the connection status cache is destroyed, so this function returns the correct connection status even if it is called immediately afterward. Also, if you open a connection with the asynchronous nn::ac::ConnectAsync function and the nn::ac::GetConnectStatus function reports that the connection is complete, this function still returns the correct connection status because internally the connection status cache has been destroyed. @param[out] pIsConnected Stores whether there is a connection. If true, the application is connected. @return Returns the execution result of the function. The following values are returned. @retval nn::ResultSuccess Indicates success. @retval nn::ac::ResultNotAcInitialized() Indicates that the function was called before the AC library was initialized with the nn::ac::Initialize function. In debug builds, the function asserts before this error is returned. */ nn::Result IsApplicationConnected( bool* pIsConnected ); //! @} //! @name Getting Error Codes //! @{ /*! @brief Gets the last error code issued. This error code is for displaying an error on the screen if Connect or Close processes do not succeed. The function may return 0 if it is not necessary to show an error. Get the error codes after detecting the processing failure and before calling other AC functions. The error codes might be cleared or overwritten by error codes for other processes. Note, however, that the error code does not change regardless of whether you call the nn::ac::GetConnectResult function to get a Result object; the nn::ac::GetLastErrorCode function to get an error code; the nn::ac::GetStatus, nn::ac::GetConnectStatus, or nn::ac::GetCloseStatus functions to get a Status object; or the nn::ac::IsApplicationConnected function to get the connection status. @param[out] pErrorCode The error code. @return Returns the execution result of the function. The following values are returned. @retval nn::ResultSuccess Indicates success. @retval nn::ac::ResultNotAcInitialized() Indicates that the function was called before the AC library was initialized with the nn::ac::Initialize function. In debug builds, the function asserts before this error is returned. */ nn::Result GetLastErrorCode( nn::ac::ErrorCode* pErrorCode ); //! @} //! @name Getting Addresses //! @{ /*! @brief Gets the assigned IP address. @param[out] pAddress The address. @return Returns the execution result of the function. The following values are returned. @retval nn::ResultSuccess Indicates success. @retval nn::ac::ResultNotAcInitialized() Indicates that the function was called before the AC library was initialized with the nn::ac::Initialize function. In debug builds, the function asserts before this error is returned. @retval nn::ac::ResultInvalidParameter() Indicates that NULL was specified in the obtained region. In debug builds, the function asserts before this error is returned. */ nn::Result GetAssignedAddress( nn::ac::IpAddress *pAddress ); /*! @brief Gets the assigned primary DNS address. @param[out] pAddress The primary DNS address. @return Returns the execution result of the function. The following values are returned. @retval nn::ResultSuccess Indicates success. @retval nn::ac::ResultNotAcInitialized() Indicates that the function was called before the AC library was initialized with the nn::ac::Initialize function. In debug builds, the function asserts before this error is returned. @retval nn::ac::ResultInvalidParameter() Indicates that NULL was specified in the obtained region. In debug builds, the function asserts before this error is returned. */ nn::Result GetAssignedPreferedDns( nn::ac::IpAddress *pAddress ); /*! @brief Gets the assigned secondary DNS address. @param[out] pAddress The secondary DNS address. @return Returns the execution result of the function. The following values are returned. @retval nn::ResultSuccess Indicates success. @retval nn::ac::ResultNotAcInitialized() Indicates that the function was called before the AC library was initialized with the nn::ac::Initialize function. In debug builds, the function asserts before this error is returned. @retval nn::ac::ResultInvalidParameter() Indicates that NULL was specified in the obtained region. In debug builds, the function asserts before this error is returned. */ // Gets secondary DNS. nn::Result GetAssignedAlternativeDns( nn::ac::IpAddress *pAddress ); /*! @brief Gets the assigned gateway address. @param[out] pAddress The assigned gateway address. @return Returns the execution result of the function. The following values are returned. @retval nn::ResultSuccess Indicates success. @retval nn::ac::ResultNotAcInitialized() Indicates that the function was called before the AC library was initialized with the nn::ac::Initialize function. In debug builds, the function asserts before this error is returned. @retval nn::ac::ResultInvalidParameter() Indicates that NULL was specified in the obtained region. In debug builds, the function asserts before this error is returned. */ nn::Result GetAssignedGateway( nn::ac::IpAddress *pAddress ); /*! @brief Gets the assigned subnet mask. @param[out] pAddress The assigned subnet mask. @return Returns the execution result of the function. The following values are returned. @retval nn::ResultSuccess Indicates success. @retval nn::ac::ResultNotAcInitialized() Indicates that the function was called before the AC library was initialized with the nn::ac::Initialize function. In debug builds, the function asserts before this error is returned. @retval nn::ac::ResultInvalidParameter() Indicates that NULL was specified in the obtained region. In debug builds, the function asserts before this error is returned. */ nn::Result GetAssignedSubnet( nn::ac::IpAddress *pAddress ); //! @} //! @} //! @} } // namespace ac } // namespace nn #endif // __cplusplus #include //! @addtogroup nn_ac //! @{ //! @defgroup nn_ac_api_c Automatic Connection (AC) API (C) //! @brief This is a list of Automatic Connection (AC) library C members. //! @{ //! @name Handling Processing Results //! @{ /*! @brief Checks whether the process succeeded. @param[in] result Specifies the processing result. @return Returns whether it was successful. */ NN_EXTERN_C BOOL ACIsSuccess(ACResult result); /*! @brief Checks whether the process failed. @param[in] result Specifies the processing result. @return Returns whether it failed. */ NN_EXTERN_C BOOL ACIsFailure(ACResult result); /*! @brief Checks whether to retry. @param[in] result Specifies the processing result. @return Returns whether to retry. */ NN_EXTERN_C BOOL ACIsRetryRequired(ACResult result); //! @} //! @name Initializing and Finalizing the Library //! @{ /*! @brief See the corresponding C++ function @ref nn::ac::Initialize. */ NN_EXTERN_C ACResult ACInitialize( void ); /*! @brief See the corresponding C++ function @ref nn::ac::Finalize. */ NN_EXTERN_C void ACFinalize( void ); //! @} //! @name Connecting and Disconnecting //! @{ /*! @brief See the corresponding C++ function @ref nn::ac::Connect. */ NN_EXTERN_C ACResult ACConnect( void ); /*! @brief See the corresponding C++ function @ref nn::ac::ConnectAsync. */ NN_EXTERN_C ACResult ACConnectAsync( void ); /*! @brief See the corresponding C++ function @ref nn::ac::Close. */ NN_EXTERN_C ACResult ACClose( void ); //! @} //! @name Checking the Status of an Asynchronous Process //! @{ /*! @brief See the corresponding C++ function @ref nn::ac::GetStatus. */ NN_EXTERN_C ACResult ACGetStatus( ACStatus* pStatus ); /*! @brief See the corresponding C++ function @ref nn::ac::GetConnectStatus. */ NN_EXTERN_C ACResult ACGetConnectStatus( ACStatus* pStatus ); /*! @brief See the corresponding C++ function @ref nn::ac::GetCloseStatus. */ NN_EXTERN_C ACResult ACGetCloseStatus( ACStatus* pStatus ); /*! @brief See the corresponding C++ function @ref nn::ac::GetConnectResult. */ NN_EXTERN_C ACResult ACGetConnectResult( ACResult* pResult ); //! @} //! @name Checking the Connection Status //! @{ /*! @brief See the corresponding C++ function @ref nn::ac::IsApplicationConnected. */ NN_EXTERN_C ACResult ACIsApplicationConnected( BOOL* pIsConnected ); //! @} //! @name Getting Error Codes //! @{ /*! @brief See the corresponding C++ function @ref nn::ac::GetLastErrorCode. */ NN_EXTERN_C ACResult ACGetLastErrorCode( ACErrorCode* pErrorCode ); //! @} //! @name Getting Addresses //! @{ /*! @brief See the corresponding C++ function @ref nn::ac::GetAssignedAddress. */ NN_EXTERN_C ACResult ACGetAssignedAddress( ACIpAddress* pAddress ); /*! @brief See the corresponding C++ function @ref nn::ac::GetAssignedPreferedDns. */ NN_EXTERN_C ACResult ACGetAssignedPreferedDns( ACIpAddress* pAddress ); /*! @brief See the corresponding C++ function @ref nn::ac::GetAssignedAlternativeDns. */ NN_EXTERN_C ACResult ACGetAssignedAlternativeDns( ACIpAddress* pAddress ); /*! @brief See the corresponding C++ function @ref nn::ac::GetAssignedGateway. */ NN_EXTERN_C ACResult ACGetAssignedGateway( ACIpAddress* pAddress ); /*! @brief See the corresponding C++ function @ref nn::ac::GetAssignedSubnet. */ NN_EXTERN_C ACResult ACGetAssignedSubnet( ACIpAddress* pAddress ); //! @} //! @} //! @} #endif // NN_AC_AC_API_H_