/*---------------------------------------------------------------------------* 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_DEBUG_H_ #define NN_AC_AC_API_DEBUG_H_ #include #include #include #ifdef __cplusplus namespace nn { namespace ac { //! @ingroup nn_ac //! @defgroup nn_ac_devapi_cpp Automatic Connection (AC) API for Devonly (C++) //! @brief This is a list of Automatic Connection (AC) library C++ members. (It is limited to use during development.) //! //! Use of these API members is permitted during development, but they must not be included in production versions. //! @{ //! @name Connecting and Disconnecting (For Development Use) //! @{ /*! @brief Establishes a synchronous network connection based on the specified configuration. (For development.) (Note that this function is provided for development purposes and cannot be incorporated into production versions.) This function must be called in a state where no other processes are making connections. For this reason, we recommend calling it after calling the nn::ac::CloseAll function to make sure the network connection is closed. Be sure to close connections with the nn::ac::CloseAll function if you will be establishing a different connection after making a connection with this function. Use the nn::ac::GetLastErrorCode function to get the error code if the connection fails. @param[in] pConfig Specifies the connection configuration. @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. @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::ResultAlreadyExists() Indicates the function was called when another connection exists already. @retval nn::ac::ResultFatal() Indicates that the number of connection tasks that can be registered at one time has been exceeded. */ nn::Result Connect( const Config* pConfig ); /*! @brief Establishes an asynchronous network connection based on the specified configuration. (For development.) (Note that this function is provided for development purposes and cannot be incorporated into production versions.) 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. For other applications, see the description of the nn::ac::Connect( const Config* pConfig ) function that is used to connect with the specified settings. @param[in] pConfig Specifies the connection configuration. @return Returns the execution result of the function. @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::ResultAlreadyExists() Indicates the function was called when another connection exists already. @retval nn::ac::ResultFatal() Indicates that the number of connection tasks that can be registered at one time has been exceeded. */ nn::Result ConnectAsync( const Config* pConfig ); /*! @brief Establishes a synchronous network connection using the specified slot ID. (For development.) (Note that this function is provided for development purposes and cannot be incorporated into production versions.) This function must be called in a state where no other processes are making connections. For this reason, we recommend calling it after calling the nn::ac::CloseAll function to make sure the network connection is closed. Make sure that you close connections with the nn::ac::CloseAll function if you will be establishing a different connection after making a connection with this function. Use the nn::ac::GetLastErrorCode function to get the error code if the connection fails. @param[in] id Specifies the connection configuration ID. @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. @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::ResultAlreadyExists() Indicates the function was called when another connection exists already. @retval nn::ac::ResultFatal() Indicates that the number of connection tasks that can be registered at one time has been exceeded. */ nn::Result Connect( ConfigId id ); /*! @brief Establishes an asynchronous network connection using the slot ID in the specified configuration. (For development.) (Note that this function is provided for development purposes and cannot be incorporated into production versions.) 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. For other applications, see the description of the nn::ac::Connect( ConfigId id ) function that is used to connect with the specified ID. @param[in] id Specifies the connection configuration ID. @return Returns the execution result of the function. @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::ResultAlreadyExists() Indicates the function was called when another connection exists already. @retval nn::ac::ResultFatal() Indicates that the number of connection tasks that can be registered at one time has been exceeded. */ nn::Result ConnectAsync( ConfigId id ); /*! @brief Closes all network connections. (For development.) (Note that this function is provided for development purposes and cannot be incorporated into production versions.) Because this function is a synchronous function, when the function returns control it is definitely in a disconnected state. Also, after calling this function, the background connection processing does not take place until the nn::ac::Connect function is called. Nintendo strongly recommends making sure the connection has been closed by calling this function prior to calling the nn::ac::Connect(const Config* pConfig) function, which takes the configuration as an argument, or the nn::ac::Connect(ConfigId id) function, which takes the slot number of the configuration as an argument. (Both of these also apply to the asynchronous functions.) Calling this function when you are already in a disconnected state, or when you perform other close processes, is not a problem. @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 CloseAll(); //! @} //! @name Getting Error Codes (For Development Use) //! @{ /*! @brief Gets the last detailed error code that was issued. (For development.) (Note that this function is provided for development purposes and cannot be incorporated into production versions.) Get the detailed 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; or the nn::ac::GetStatus, nn::ac::GetConnectStatus, or nn::ac::GetCloseStatus functions to get a Status object. @param[out] pDetailedErrorCode Detailed error code. @param[out] pCommand The command. @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 GetLastDetailedErrorCode( u32* pDetailedErrorCode, u32* pCommand ); //! @} //! @name Configuring the Connection //! @{ /*! @brief Saves the connection configuration. (For development.) (Note that this function is provided for development purposes and cannot be incorporated into production versions.) The connection configuration specified by pConfig is saved in the configuration slot specified by id. Note: Due to constraints of the Wii U console, wired connections are always configured with auto-negotiation ON, the speed parameter as 0, and the communication method parameter as 0, regardless of the configuration written with nn::ac::WriteConfig. These constraints may change in the future. @param[in] id Specifies the slot number of the connection configuration to save (in the range from nn::ac::CONFIG_ID_1 through nn::ac::CONFIG_ID_6). @param[in] pConfig Specifies the connection configuration. @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() Returns that the id parameter is out of bounds. In debug builds, the function asserts before this error is returned. */ nn::Result WriteConfig( ConfigId id, const Config* pConfig ); /*! @brief Gets a connection configuration. (For development.) (Note that this function is provided for development purposes and cannot be incorporated into production versions.) Places the content of the configuration slot specified by id in pConfig. Note: Due to constraints of the Wii U console, wired connections are always configured with auto-negotiation ON, the speed parameter as 0, and the communication method parameter as 0, regardless of the configuration written with nn::ac::WriteConfig. These constraints may change in the future. The \c nn::ac::ReadConfig function gets the converted value for these parameters. @param[in] id Specifies the slot number of the connection configuration to get (in the range from nn::ac::CONFIG_ID_1 through nn::ac::CONFIG_ID_6). @param[in] pConfig Specifies where to store the retrieved connection configuration. @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() id is out of bounds. In debug builds, the function asserts before this error is returned. */ nn::Result ReadConfig( ConfigId id, Config* pConfig ); /*! @brief Deletes the connection configuration. (For development.) (Note that this function is provided for development purposes and cannot be incorporated into production versions.) Deletes the content of the configuration slot specified by id. @param[in] id Specifies the connection configuration ID (in the range from nn::ac::CONFIG_ID_1 through nn::ac::CONFIG_ID_6). @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() id is out of bounds. In debug builds, the function asserts before this error is returned. */ nn::Result DeleteConfig( ConfigId id ); /*! @brief Checks whether network configuration exists. (For development.) (Note that this function is provided for development purposes and cannot be incorporated into production versions.) Confirms whether a connection configuration exists in the configuration slot specified by id. The result is stored in pIsExisting. If TRUE is stored, a configuration exists. After the connection configuration is deleted with the nn::ac::DeleteConfig function, it is considered not to exist until written by a function like nn::ac::WriteConfig. @param[in] id Specifies the connection configuration ID (in the range from nn::ac::CONFIG_ID_1 through nn::ac::CONFIG_ID_6). @param[out] pIsExisting Region that stores the configuration existence flag. @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() id is out of bounds. In debug builds, the function asserts before this error is returned. */ nn::Result IsConfigExisting( ConfigId id, bool* pIsExisting ); /*! @brief Sets the configuration ID to use when connecting during system startup. (For development.) (Note that this function is provided for development purposes and cannot be incorporated into production versions.) Specifies the configuration slot ID that is used during startup or when connecting with nn::ac::Connect. @param[in] id Specifies the connection configuration ID (in the range from nn::ac::CONFIG_ID_1 through nn::ac::CONFIG_ID_6). @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() id is out of bounds. In debug builds, the function asserts before this error is returned. */ nn::Result SetStartupId( ConfigId id ); /*! @brief Gets the configuration ID to use when connecting during system startup. (For development.) (Note that this function is provided for development purposes and cannot be incorporated into production versions.) @param[out] id Specifies the connection configuration ID (in the range from nn::ac::CONFIG_ID_1 through nn::ac::CONFIG_ID_6). @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 GetStartupId( ConfigId* id ); //! @} //! @} } // namespace ac } // namespace nn #endif // __cplusplus #include //! @ingroup nn_ac //! @defgroup nn_ac_devapi_c Automatic Connection (AC) API for Devonly (C) //! @brief This is a list of Automatic Connection (AC) library C members. (It is limited to use during development.) //! //! Use of these API members is permitted during development, but they must not be included in production versions. //! @{ //! @name Connecting and Disconnecting (For Development Use) //! @{ /*! @brief See the corresponding C++ function @ref nn::ac::Connect (which takes nn::ac::Config* as an argument). */ NN_EXTERN_C ACResult ACConnectWithConfig( const ACConfig* pConfig ); /*! @brief See the corresponding C++ function @ref nn::ac::ConnectAsync (which takes nn::ac::Config* as an argument). */ NN_EXTERN_C ACResult ACConnectWithConfigAsync( const ACConfig* pConfig ); /*! @brief See the corresponding C++ function @ref nn::ac::Connect (which takes nn::ac::ConfigId as an argument). */ NN_EXTERN_C ACResult ACConnectWithConfigId( ACConfigId id ); /*! @brief See the corresponding C++ function @ref nn::ac::ConnectAsync (which takes nn::ac::ConfigId as an argument). */ NN_EXTERN_C ACResult ACConnectWithConfigIdAsync( ACConfigId id ); /*! @brief See the corresponding C++ function @ref nn::ac::CloseAll. */ NN_EXTERN_C ACResult ACCloseAll(void); /*! @brief See the corresponding C++ function @ref nn::ac::GetLastDetailedErrorCode. */ NN_EXTERN_C ACResult ACGetLastDetailedErrorCode( u32* pDetailedErrorCode, u32* pCommand ); //! @} //! @name Configuring the Connection //! @{ /*! @brief See the corresponding C++ function @ref nn::ac::WriteConfig. */ NN_EXTERN_C ACResult ACWriteConfig( ACConfigId id, const ACConfig* pConfig ); /*! @brief See the corresponding C++ function @ref nn::ac::ReadConfig. */ NN_EXTERN_C ACResult ACReadConfig( ACConfigId id, ACConfig* pConfig ); /*! @brief See the corresponding C++ function @ref nn::ac::DeleteConfig. */ NN_EXTERN_C ACResult ACDeleteConfig( ACConfigId id ); /*! @brief See the corresponding C++ function @ref nn::ac::SetStartupId. */ NN_EXTERN_C ACResult ACSetStartupId( ACConfigId id ); /*! @brief See the corresponding C++ function @ref nn::ac::GetStartupId. */ NN_EXTERN_C ACResult ACGetStartupId( ACConfigId* id ); /*! @brief See the corresponding C++ function @ref nn::ac::IsConfigExisting. */ NN_EXTERN_C ACResult ACIsConfigExisting( ACConfigId id, BOOL* pIsExisting ); //! @} //! @} #endif // NN_AC_AC_API_DEBUG_H_