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_DEBUG_H_ 13 #define NN_AC_AC_API_DEBUG_H_ 14 15 #include <nn/ac/ac_Types.h> 16 #include <nn/ac/ac_TypesDebug.h> 17 #include <nn/ac/ac_Result.h> 18 19 #ifdef __cplusplus 20 21 namespace nn { 22 namespace ac { 23 24 //! @ingroup nn_ac 25 //! @defgroup nn_ac_devapi_cpp Automatic Connection (AC) API for Devonly (C++) 26 //! @brief This is a list of Automatic Connection (AC) library C++ members. (It is limited to use during development.) 27 //! 28 //! Use of these API members is permitted during development, but they must not be included in production versions. 29 //! @{ 30 31 //! @name Connecting and Disconnecting (For Development Use) 32 //! @{ 33 34 /*! 35 @brief Establishes a synchronous network connection based on the specified configuration. (For development.) 36 (Note that this function is provided for development purposes and cannot be incorporated into production versions.) 37 38 This function must be called in a state where no other processes are making connections. 39 For this reason, we recommend calling it after calling the <tt>nn::ac::CloseAll</tt> function to make sure the network connection is closed. 40 41 Be sure to close connections with the <tt>nn::ac::CloseAll</tt> function if you will be establishing a different connection after making a connection with this function. 42 43 Use the <tt>nn::ac::GetLastErrorCode</tt> function to get the error code if the connection fails. 44 45 @param[in] pConfig Specifies the connection configuration. 46 @return Returns the execution result of the function. The following values are returned. 47 @retval nn::ResultSuccess Indicates success. 48 @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. 49 @retval nn::ac::ResultCanceled() Indicates that the connection was canceled. Another process closed the connection. 50 @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. 51 @retval nn::ac::ResultConflictIpAddress() Indicates an IP address conflict. 52 @retval nn::ac::ResultFailedConnectAp() Indicates that the access point with the specified SSID could not be found, or the signal strength is very poor. 53 @retval nn::ac::ResultInvalidKeyValue() Indicates that the security key is incorrect. 54 @retval nn::ac::ResultNotInitialized() Indicates that the default network settings have not been saved. 55 @retval nn::ac::ResultInvalidData() Indicates incorrect settings in the saved settings. (However, the same check is performed when saving.) 56 @retval nn::ac::ResultAlreadyExclusive() Indicates an attempt to connect in local communication mode. 57 @retval nn::ac::ResultAlreadyExists() Indicates the function was called when another connection exists already. 58 @retval nn::ac::ResultFatal() Indicates that the number of connection tasks that can be registered at one time has been exceeded. 59 60 */ 61 nn::Result Connect( const Config* pConfig ); 62 63 /*! 64 @brief Establishes an asynchronous network connection based on the specified configuration. (For development.) 65 (Note that this function is provided for development purposes and cannot be incorporated into production versions.) 66 67 Use the <tt>nn::ac::GetStatus</tt> or <tt>nn::ac::GetConnectStatus</tt> function to check the status of asynchronous processes. 68 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. 69 70 For other applications, see the description of the <tt>nn::ac::Connect( const Config* pConfig )</tt> function that is used to connect with the specified settings. 71 72 @param[in] pConfig Specifies the connection configuration. 73 @return Returns the execution result of the function. 74 @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. 75 @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. 76 @retval nn::ac::ResultAlreadyExists() Indicates the function was called when another connection exists already. 77 @retval nn::ac::ResultFatal() Indicates that the number of connection tasks that can be registered at one time has been exceeded. 78 79 */ 80 nn::Result ConnectAsync( const Config* pConfig ); 81 82 /*! 83 @brief Establishes a synchronous network connection using the specified slot ID. (For development.) 84 (Note that this function is provided for development purposes and cannot be incorporated into production versions.) 85 86 This function must be called in a state where no other processes are making connections. 87 For this reason, we recommend calling it after calling the <tt>nn::ac::CloseAll</tt> function to make sure the network connection is closed. 88 89 Make sure that you close connections with the <tt>nn::ac::CloseAll</tt> function if you will be establishing a different connection after making a connection with this function. 90 91 Use the <tt>nn::ac::GetLastErrorCode</tt> function to get the error code if the connection fails. 92 93 @param[in] id Specifies the connection configuration ID. 94 @return Returns the execution result of the function. The following values are returned. 95 @retval nn::ResultSuccess Indicates success. 96 @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. 97 @retval nn::ac::ResultCanceled() Indicates that the connection was canceled. Another process closed the connection. 98 @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. 99 @retval nn::ac::ResultConflictIpAddress() Indicates an IP address conflict. 100 @retval nn::ac::ResultFailedConnectAp() Indicates that the access point with the specified SSID could not be found, or the signal strength is very poor. 101 @retval nn::ac::ResultInvalidKeyValue() Indicates that the security key is incorrect. 102 @retval nn::ac::ResultNotInitialized() Indicates that the default network settings have not been saved. 103 @retval nn::ac::ResultInvalidData() Indicates incorrect settings in the saved settings. (However, the same check is performed when saving.) 104 @retval nn::ac::ResultAlreadyExclusive() Indicates an attempt to connect in local communication mode. 105 @retval nn::ac::ResultAlreadyExists() Indicates the function was called when another connection exists already. 106 @retval nn::ac::ResultFatal() Indicates that the number of connection tasks that can be registered at one time has been exceeded. 107 108 */ 109 nn::Result Connect( ConfigId id ); 110 111 /*! 112 @brief Establishes an asynchronous network connection using the slot ID in the specified configuration. (For development.) 113 (Note that this function is provided for development purposes and cannot be incorporated into production versions.) 114 115 Use the <tt>nn::ac::GetStatus</tt> or <tt>nn::ac::GetConnectStatus</tt> function to check the status of asynchronous processes. 116 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. 117 118 For other applications, see the description of the <tt>nn::ac::Connect( ConfigId id )</tt> function that is used to connect with the specified ID. 119 120 @param[in] id Specifies the connection configuration ID. 121 @return Returns the execution result of the function. 122 @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. 123 @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. 124 @retval nn::ac::ResultAlreadyExists() Indicates the function was called when another connection exists already. 125 @retval nn::ac::ResultFatal() Indicates that the number of connection tasks that can be registered at one time has been exceeded. 126 127 */ 128 nn::Result ConnectAsync( ConfigId id ); 129 130 /*! 131 @brief Closes all network connections. (For development.) 132 (Note that this function is provided for development purposes and cannot be incorporated into production versions.) 133 134 Because this function is a synchronous function, when the function returns control it is definitely in a disconnected state. 135 Also, after calling this function, the background connection processing does not take place until the <tt>nn::ac::Connect</tt> function is called. 136 137 Nintendo strongly recommends making sure the connection has been closed by calling this function prior to calling the <tt>nn::ac::Connect(const Config* pConfig)</tt> function, which takes the configuration as an argument, or the <tt>nn::ac::Connect(ConfigId id)</tt> function, which takes the slot number of the configuration as an argument. (Both of these also apply to the asynchronous functions.) 138 139 Calling this function when you are already in a disconnected state, or when you perform other close processes, is not a problem. 140 141 @return Returns the execution result of the function. The following values are returned. 142 @retval nn::ResultSuccess Indicates success. 143 @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. 144 145 146 147 */ 148 nn::Result CloseAll(); 149 150 //! @} 151 152 //! @name Getting Error Codes (For Development Use) 153 //! @{ 154 155 /*! 156 @brief Gets the last detailed error code that was issued. (For development.) 157 (Note that this function is provided for development purposes and cannot be incorporated into production versions.) 158 159 Get the detailed error codes after detecting the processing failure and before calling other AC functions. 160 The error codes might be cleared or overwritten by error codes for other processes. 161 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; or 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. 162 163 @param[out] pDetailedErrorCode Detailed error code. 164 @param[out] pCommand The command. 165 @return Returns the execution result of the function. The following values are returned. 166 @retval nn::ResultSuccess Indicates success. 167 @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. 168 169 170 171 172 */ 173 nn::Result GetLastDetailedErrorCode( u32* pDetailedErrorCode, u32* pCommand ); 174 175 //! @} 176 177 //! @name Configuring the Connection 178 //! @{ 179 180 /*! 181 @brief Saves the connection configuration. (For development.) 182 (Note that this function is provided for development purposes and cannot be incorporated into production versions.) 183 184 The connection configuration specified by <var>pConfig</var> is saved in the configuration slot specified by <var>id</var>. 185 186 <b>Note:</b> 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 <tt>nn::ac::WriteConfig</tt>. These constraints may change in the future. 187 188 @param[in] id Specifies the slot number of the connection configuration to save (in the range from <tt>nn::ac::CONFIG_ID_1</tt> through <tt>nn::ac::CONFIG_ID_6</tt>). 189 @param[in] pConfig Specifies the connection configuration. 190 @return Returns the execution result of the function. The following values are returned. 191 @retval nn::ResultSuccess Indicates success. 192 @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. 193 @retval nn::ac::ResultInvalidParameter() Returns that the <var>id</var> parameter is out of bounds. In debug builds, the function asserts before this error is returned. 194 */ 195 nn::Result WriteConfig( ConfigId id, const Config* pConfig ); 196 197 /*! 198 @brief Gets a connection configuration. (For development.) 199 (Note that this function is provided for development purposes and cannot be incorporated into production versions.) 200 201 Places the content of the configuration slot specified by <var>id</var> in <var>pConfig</var>. 202 203 <b>Note:</b> 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 <tt>nn::ac::WriteConfig</tt>. These constraints may change in the future. 204 The \c nn::ac::ReadConfig function gets the converted value for these parameters. 205 @param[in] id Specifies the slot number of the connection configuration to get (in the range from <tt>nn::ac::CONFIG_ID_1</tt> through <tt>nn::ac::CONFIG_ID_6</tt>). 206 @param[in] pConfig Specifies where to store the retrieved connection configuration. 207 @return Returns the execution result of the function. The following values are returned. 208 @retval nn::ResultSuccess Indicates success. 209 @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. 210 @retval nn::ac::ResultInvalidParameter() <var>id</var> is out of bounds. In debug builds, the function asserts before this error is returned. 211 */ 212 nn::Result ReadConfig( ConfigId id, Config* pConfig ); 213 214 /*! 215 @brief Deletes the connection configuration. (For development.) 216 (Note that this function is provided for development purposes and cannot be incorporated into production versions.) 217 218 Deletes the content of the configuration slot specified by <var>id</var>. 219 220 @param[in] id Specifies the connection configuration ID (in the range from <tt>nn::ac::CONFIG_ID_1</tt> through <tt>nn::ac::CONFIG_ID_6</tt>). 221 222 @return Returns the execution result of the function. The following values are returned. 223 @retval nn::ResultSuccess Indicates success. 224 @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. 225 @retval nn::ac::ResultInvalidParameter() <var>id</var> is out of bounds. In debug builds, the function asserts before this error is returned. 226 227 */ 228 nn::Result DeleteConfig( ConfigId id ); 229 230 /*! 231 @brief Checks whether network configuration exists. (For development.) 232 (Note that this function is provided for development purposes and cannot be incorporated into production versions.) 233 234 Confirms whether a connection configuration exists in the configuration slot specified by <var>id</var>. 235 The result is stored in <var>pIsExisting</var>. If <tt>TRUE</tt> is stored, a configuration exists. 236 237 After the connection configuration is deleted with the <tt>nn::ac::DeleteConfig</tt> function, it is considered not to exist until written by a function like <tt>nn::ac::WriteConfig</tt>. 238 239 @param[in] id Specifies the connection configuration ID (in the range from <tt>nn::ac::CONFIG_ID_1</tt> through <tt>nn::ac::CONFIG_ID_6</tt>). 240 @param[out] pIsExisting Region that stores the configuration existence flag. 241 242 @return Returns the execution result of the function. The following values are returned. 243 @retval nn::ResultSuccess Indicates success. 244 @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. 245 @retval nn::ac::ResultInvalidParameter() <var>id</var> is out of bounds. In debug builds, the function asserts before this error is returned. 246 247 248 */ 249 nn::Result IsConfigExisting( ConfigId id, bool* pIsExisting ); 250 251 /*! 252 @brief Sets the configuration ID to use when connecting during system startup. (For development.) 253 (Note that this function is provided for development purposes and cannot be incorporated into production versions.) 254 255 Specifies the configuration slot ID that is used during startup or when connecting with <tt>nn::ac::Connect</tt>. 256 257 @param[in] id Specifies the connection configuration ID (in the range from <tt>nn::ac::CONFIG_ID_1</tt> through <tt>nn::ac::CONFIG_ID_6</tt>). 258 259 @return Returns the execution result of the function. The following values are returned. 260 @retval nn::ResultSuccess Indicates success. 261 @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. 262 @retval nn::ac::ResultInvalidParameter() <var>id</var> is out of bounds. In debug builds, the function asserts before this error is returned. 263 264 */ 265 nn::Result SetStartupId( ConfigId id ); 266 267 /*! 268 @brief Gets the configuration ID to use when connecting during system startup. (For development.) 269 (Note that this function is provided for development purposes and cannot be incorporated into production versions.) 270 271 @param[out] id Specifies the connection configuration ID (in the range from <tt>nn::ac::CONFIG_ID_1</tt> through <tt>nn::ac::CONFIG_ID_6</tt>). 272 273 @return Returns the execution result of the function. The following values are returned. 274 @retval nn::ResultSuccess Indicates success. 275 @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. 276 277 */ 278 nn::Result GetStartupId( ConfigId* id ); 279 280 //! @} 281 282 //! @} 283 284 } // namespace ac 285 } // namespace nn 286 287 #endif // __cplusplus 288 289 #include <nn/util/detail/util_CLibImpl.h> 290 291 //! @ingroup nn_ac 292 //! @defgroup nn_ac_devapi_c Automatic Connection (AC) API for Devonly (C) 293 //! @brief This is a list of Automatic Connection (AC) library C members. (It is limited to use during development.) 294 //! 295 //! Use of these API members is permitted during development, but they must not be included in production versions. 296 //! @{ 297 298 //! @name Connecting and Disconnecting (For Development Use) 299 //! @{ 300 301 /*! 302 @brief See the corresponding C++ function <tt>@ref nn::ac::Connect</tt> (which takes <tt>nn::ac::Config*</tt> as an argument). 303 */ 304 NN_EXTERN_C ACResult ACConnectWithConfig( const ACConfig* pConfig ); 305 /*! 306 @brief See the corresponding C++ function <tt>@ref nn::ac::ConnectAsync</tt> (which takes <tt>nn::ac::Config*</tt> as an argument). 307 */ 308 NN_EXTERN_C ACResult ACConnectWithConfigAsync( const ACConfig* pConfig ); 309 /*! 310 @brief See the corresponding C++ function <tt>@ref nn::ac::Connect</tt> (which takes <tt>nn::ac::ConfigId</tt> as an argument). 311 */ 312 NN_EXTERN_C ACResult ACConnectWithConfigId( ACConfigId id ); 313 /*! 314 @brief See the corresponding C++ function <tt>@ref nn::ac::ConnectAsync</tt> (which takes <tt>nn::ac::ConfigId</tt> as an argument). 315 */ 316 NN_EXTERN_C ACResult ACConnectWithConfigIdAsync( ACConfigId id ); 317 /*! 318 @brief See the corresponding C++ function <tt>@ref nn::ac::CloseAll</tt>. 319 */ 320 NN_EXTERN_C ACResult ACCloseAll(void); 321 /*! 322 @brief See the corresponding C++ function <tt>@ref nn::ac::GetLastDetailedErrorCode</tt>. 323 */ 324 NN_EXTERN_C ACResult ACGetLastDetailedErrorCode( u32* pDetailedErrorCode, u32* pCommand ); 325 326 //! @} 327 328 //! @name Configuring the Connection 329 //! @{ 330 331 /*! 332 @brief See the corresponding C++ function <tt>@ref nn::ac::WriteConfig</tt>. 333 */ 334 NN_EXTERN_C ACResult ACWriteConfig( ACConfigId id, const ACConfig* pConfig ); 335 336 /*! 337 @brief See the corresponding C++ function <tt>@ref nn::ac::ReadConfig</tt>. 338 */ 339 NN_EXTERN_C ACResult ACReadConfig( ACConfigId id, ACConfig* pConfig ); 340 341 /*! 342 @brief See the corresponding C++ function <tt>@ref nn::ac::DeleteConfig</tt>. 343 */ 344 NN_EXTERN_C ACResult ACDeleteConfig( ACConfigId id ); 345 /*! 346 @brief See the corresponding C++ function <tt>@ref nn::ac::SetStartupId</tt>. 347 */ 348 NN_EXTERN_C ACResult ACSetStartupId( ACConfigId id ); 349 /*! 350 @brief See the corresponding C++ function <tt>@ref nn::ac::GetStartupId</tt>. 351 */ 352 NN_EXTERN_C ACResult ACGetStartupId( ACConfigId* id ); 353 354 /*! 355 @brief See the corresponding C++ function <tt>@ref nn::ac::IsConfigExisting</tt>. 356 */ 357 NN_EXTERN_C ACResult ACIsConfigExisting( ACConfigId id, BOOL* pIsExisting ); 358 359 360 //! @} 361 362 //! @} 363 364 #endif // NN_AC_AC_API_DEBUG_H_ 365