1 /*---------------------------------------------------------------------------* 2 Project: Horizon 3 File: uds_Api.h 4 5 Copyright (C) 2009-2011 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 $Rev: 54504 $ 14 *---------------------------------------------------------------------------*/ 15 16 #ifndef INCLUDE_NN_UDS_CAFE_UDS_API_H_ 17 #define INCLUDE_NN_UDS_CAFE_UDS_API_H_ 18 19 /*! @file 20 @brief These are members of the UDS Library. 21 */ 22 23 #include <nn/uds/CAFE/uds_Type.h> 24 #include <nn/uds/CAFE/uds_Result.h> 25 #ifdef NN_UDS_SUPPORT_CLIENT 26 #include <nn/uds/CAFE/uds_NetworkDescription.h> 27 #endif 28 #include <nn/fnd/fnd_TimeSpan.h> 29 30 namespace nn { 31 namespace uds { 32 namespace Cafe { 33 34 /*! 35 @ingroup nn_uds 36 @defgroup nn_uds_api Local Communication (UDS) API 37 @brief This file lists Local Communication (UDS) library API members. (Includes only C++ API members.) 38 @{ 39 */ 40 41 /*! 42 @name Initialization and Shutdown 43 @{ 44 */ 45 46 /*! 47 @brief Initializes the UDS library. Initialization fails if any other communication features are already in use. 48 49 Background communications are terminated and execution is blocked for 120 to 150 msec so the UDS library can take ownership of the communication device until <tt>@ref Finalize</tt> executes. 50 51 Always call the <tt>@ref Finalize</tt> function to release the communication device after you are finished using the UDS library. <br /> 52 This function is thread-unsafe. 53 54 @param[in] receiveBuffer Pointer to the start of the receive buffer used by the UDS library. Specify a buffer aligned to 64 bytes. 55 Access to the memory region specified by the buffer is prohibited until the <tt>@ref Finalize</tt> function completes. 56 @param[in] bufferSize The size of the receive buffer. Specify a value greater than <tt>ATTACH_BUFFER_SIZE_MIN</tt> that is a multiple of 64. 57 58 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 59 @retval Result::IsSuccess Indicates that initialization succeeded. 60 @retval ResultAlreadyOccupiedWirelessDevice Indicates that communication is already taking place. New UDS communication cannot begin. 61 @retval ResultOutOfResource Indicates that the system is out of resources. Try again. 62 @retval ResultBusy Indicates that the system is busy. Try again. 63 */ 64 nn::Result Initialize( void* receiveBuffer, const size_t bufferSize); 65 66 /*! 67 @brief Initializes the UDS library. Initialization fails if any other communication features are already in use. 68 69 Background communications are terminated and execution is blocked for 120 to 150 msec so the UDS library can take ownership of the communication device until <tt>@ref Finalize</tt> executes. 70 71 Always call the <tt>@ref Finalize</tt> function to release the communication device after you are finished using the UDS library. <br /> 72 Handle the user name specified by <span class="argument">pUserName</span> according to UGC guidelines. <br /> 73 This function is thread-unsafe. 74 75 @param[in] receiveBuffer Pointer to the start of the receive buffer used by the UDS library. Specify a buffer aligned to 64 bytes. 76 Access to the memory region specified by the buffer is prohibited until the <tt>@ref Finalize</tt> function completes. 77 @param[in] bufferSize The size of the receive buffer. Specify a value that is a multiple of 64. 78 @param[in] pUserName The user name. Handle user names according to UGC guidelines. If you specify <tt>NULL</tt>, the function uses the Mii character name of the account that is logged in. 79 80 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 81 @retval Result::IsSuccess Indicates that initialization succeeded. 82 @retval ResultAlreadyOccupiedWirelessDevice Indicates that communication is already taking place. New UDS communication cannot begin. 83 @retval ResultOutOfResource Indicates that the system is out of resources. Try again. 84 @retval ResultBusy Indicates that the system is busy. Try again. 85 */ 86 nn::Result Initialize( void* receiveBuffer, const size_t bufferSize, nn::cfg::CTR::UserName* pUserName); 87 88 /*! 89 @brief Finalizes the UDS library. After executing, other communication features become usable. 90 91 Blocks for 50 to 60 milliseconds. 92 Releases the communication device held by the <tt>@ref Initialize</tt> function. 93 The receive buffer specified by the <tt>@ref Initialize</tt> function can be accessed from the application after this function's execution completes. <br /> 94 Finalizes the event received by the <tt>@ref Initialize</tt> function, which is used to send notifications of connection status updates. Destroys an <tt>endpoint</tt> that has not been destroyed. <br /> 95 The buffer allocated by the <tt>@ref Attach</tt> function is released. <br /> 96 This function is thread-unsafe. 97 98 @return None. 99 */ 100 void Finalize (); 101 102 /*! 103 @} 104 */ 105 /*! 106 @name Networks (Creating, Destroying, Connecting, and Disconnecting) 107 @{ 108 */ 109 110 /*! 111 @brief Creates a local communication ID from a unique ID. 112 113 This uses a 20-bit unique ID assigned by Nintendo to generate a 32-bit value (a <i>local communication ID</i>) to use for UDS communication. <br /> 114 If Nintendo has not assigned a unique ID to you, use one of the unique IDs for game prototypes (in the range from <tt>0xFF000</tt> through <tt>0xFF3FF</tt>). <br /> 115 However, you must get a unique ID from Nintendo for your retail product. <br /> 116 This function is thread-safe. 117 118 @param[in] uniqueId The unique ID. To communicate between multiple titles, specify either of their unique IDs. 119 @param[in] isDemo This flag is used when the same unique ID is used for both the retail and demo versions. 120 Specify <tt>true</tt> for the demo if you do not want communication between the retail product and downloadable demo versions. 121 <b>Note:</b> Always set this flag to <tt>false</tt> in retail builds. 122 @return Returns the local communication ID. 123 */ 124 bit32 CreateLocalCommunicationId( bit32 uniqueId, bool isDemo = false); 125 126 /*! 127 @brief Creates a new network. 128 129 This function blocks for a period of 100 to 120 milliseconds until automatic channel selection is complete. <br /> 130 This function is thread-safe. 131 132 @param[in] subId Specifies the ID for identifying the communication mode. Set this parameter to a value between <tt>0x00</tt> and <tt>0xFE</tt>. 133 @param[in] maxEntry Specifies the maximum number of nodes that can connect to the network. This value can be up to <tt>@ref NODE_MAX</tt>, including the local device. 134 @param[in] localId Specifies the local communication ID. Specify the value generated by <tt>@ref CreateLocalCommunicationId</tt>. 135 @param[in] passphrase Specifies the string holding the seed of the passphrase to use for wireless layer encryption. 136 With UDS, communication can only be established if <SPAN class="argument">uniqueId</SPAN> and <SPAN class="argument">passphrase</SPAN> match. 137 @param[in] passphraseLength Specifies the passphrase length. Specify a value that is at least <tt>IR_PASSPHRASE_LENGTH_MIN</tt>, but no larger than <tt>IR_PASSPHRASE_LENGTH_MAX</tt>. 138 139 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 140 @retval Result::IsSuccess Indicates the node successfully established local communication and began operating as a host. 141 @retval ResultNotInitialized Indicates that the library is not initialized. Call the <tt>@ref Initialize</tt> function. 142 @retval ResultInvalidState Indicates that the function cannot be executed in this state. Returned when the function is executed in a state other than <tt>@ref STATE_DISCONNECTED</tt>. 143 @retval ResultOutOfRange Indicates that an argument was outside of the allowed range. The function may succeed if you execute it again with a suitable value for the argument. 144 @retval ResultNotAuthorized Indicates an invalid value for <span class="argument">localId</span>. Specify the value generated by <tt>@ref CreateLocalCommunicationId</tt>. 145 @retval ResultOutOfResource Indicates that the system is out of resources. Try again. 146 @retval ResultBusy Indicates that the system is busy. Try again. 147 */ 148 nn::Result CreateNetwork( 149 u8 subId, 150 u8 maxEntry, 151 bit32 localId, 152 const char passphrase[], 153 size_t passphraseLength ); 154 155 /*! 156 @brief Sets application data in the beacon and builds a new network. 157 158 This function blocks for a period of 100 to 120 milliseconds until automatic channel selection is complete. <br /> 159 This API function allows you to set application data in the beacon when building the network. 160 To update the beacon's application data after the network has been built, use the <tt>@ref SetApplicationDataToBeacon</tt> function. 161 The maximum size of this application data is <tt>@ref NET_DESC_APPDATA_SIZE_MAX</tt> bytes. 162 The data is not encrypted. It can be collected by any general-purpose computing device, such as a desktop computer. 163 Other devices can get this data by calling <tt>Scan</tt> while they are connected as a <tt>Client</tt> or <tt>Spectator</tt>. <br /> 164 This function is thread-safe. 165 166 @param[in] subId Specifies the ID for identifying the communication mode. Set this parameter to a value between <tt>0x00</tt> and <tt>0xFE</tt>. 167 @param[in] maxEntry Specifies the maximum number of nodes that can connect to the network. This value can be up to <tt>@ref NODE_MAX</tt>, including the local device. 168 @param[in] localId Specifies the local communication ID. Specify the value generated by <tt>@ref CreateLocalCommunicationId</tt>. 169 @param[in] passphrase Specifies the string holding the seed of the passphrase to use for wireless layer encryption. 170 With UDS, communication can only be established if <SPAN class="argument">uniqueId</SPAN> and <SPAN class="argument">passphrase</SPAN> match. 171 @param[in] passphraseLength Specifies the passphrase length. Specify a value that is at least <tt>IR_PASSPHRASE_LENGTH_MIN</tt>, but no larger than <tt>IR_PASSPHRASE_LENGTH_MAX</tt>. 172 @param[in] pData Specifies a pointer to the application data to set in the beacon. 173 @param[in] dataSize Specifies the size of the application data to set in the beacon. Specify a value no greater than <tt>@ref NET_DESC_APPDATA_SIZE_MAX</tt>. 174 175 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 176 @retval Result::IsSuccess Indicates that the node successfully established local communication and began operating as a host. 177 @retval ResultNotInitialized Indicates that the library is not initialized. Call the <tt>@ref Initialize</tt> function. 178 @retval ResultInvalidState Indicates that the function cannot be executed in this state. Returned when the function is executed in a state other than <tt>@ref STATE_DISCONNECTED</tt>. 179 @retval ResultOutOfRange Indicates that an argument was outside of the allowed range. The function may succeed if you execute it again with a suitable value for the argument. 180 @retval ResultNotAuthorized Indicates an invalid value for <span class="argument">localId</span>. Specify the value generated by <tt>@ref CreateLocalCommunicationId</tt>. 181 @retval ResultOutOfResource Indicates that the system is out of resources. Try again. 182 @retval ResultBusy Indicates that the system is busy. Try again. 183 @retval ResultTooLarge Indicates that <span class="argument">dataSize</span> is greater than <tt>@ref NET_DESC_APPDATA_SIZE_MAX</tt>. 184 @retval ResultInvalidPointer Indicates that <span class="argument">pData</span> is <tt>NULL</tt>. <tt>NULL</tt> is allowed when <span class="argument">dataSize</span> is <tt>0</tt>. 185 */ 186 nn::Result CreateNetwork( 187 u8 subId, 188 u8 maxEntry, 189 bit32 localId, 190 const char passphrase[], 191 size_t passphraseLength, 192 const void* pData, 193 size_t dataSize ); 194 195 /*! 196 @brief Creates a new network. This function is provided for debugging purposes, and can be used to specify the channel to use for wireless communication during development. 197 198 The channel argument is ignored in production mode. 199 This function blocks for a period of 100 to 120 milliseconds until automatic channel selection is complete. <br /> 200 This function is thread-safe. 201 @param[in] subId Specifies the ID for identifying the communication mode. Set this parameter to a value between <tt>0x00</tt> and <tt>0xFE</tt>. 202 @param[in] maxEntry Specifies the maximum number of nodes that can connect to the network. This value can be up to <tt>@ref NODE_MAX</tt>, including the local device. 203 @param[in] localId Specifies the local communication ID. Specify the value generated by <tt>@ref CreateLocalCommunicationId</tt>. 204 @param[in] passphrase Specifies the string holding the seed of the passphrase to use for wireless layer encryption. 205 With UDS, communication can only be established if <SPAN class="argument">uniqueId</SPAN> and <SPAN class="argument">passphrase</SPAN> match. 206 @param[in] passphraseLength Specifies the passphrase length. Specify a value that is at least <tt>IR_PASSPHRASE_LENGTH_MIN</tt>, but no larger than <tt>IR_PASSPHRASE_LENGTH_MAX</tt>. 207 @param[in] channel Specifies the channel to use for communication. Specify channel <tt>0</tt> (automatic), <tt>1</tt>, <tt>6</tt>, or <tt>11</tt>. When this function runs in production mode, the channel is always selected automatically. 208 209 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 210 @retval Result::IsSuccess Indicates that the node successfully established local communication and began operating as a host. 211 @retval ResultNotInitialized Indicates that the library is not initialized. Call the <tt>@ref Initialize</tt> function. 212 @retval ResultInvalidState Indicates that the function cannot be executed in this state. Returned when the function is executed in a state other than <tt>@ref STATE_DISCONNECTED</tt>. 213 @retval ResultOutOfRange Indicates that an argument was outside of the allowed range. The function may succeed if you execute it again with a suitable value for the argument. 214 @retval ResultNotAuthorized Indicates an invalid value for <span class="argument">localId</span>. Specify the value generated by <tt>@ref CreateLocalCommunicationId</tt>. 215 @retval ResultOutOfResource Indicates that the system is out of resources. Try again. 216 @retval ResultInvalidPointer Indicates that <span class="argument">pData</span> is <tt>NULL</tt>. <tt>NULL</tt> is allowed when <span class="argument">dataSize</span> is <tt>0</tt>. 217 */ 218 nn::Result CreateNetwork( 219 u8 subId, 220 u8 maxEntry, 221 bit32 localId, 222 const char passphrase[], 223 size_t passphraseLength, 224 u8 channel ); 225 226 /*! 227 @brief Sets application data in the beacon and builds a new network. This function is provided for debugging purposes, and can be used to specify the channel to use for wireless communication during development. 228 229 The channel argument is ignored in production mode. 230 This function blocks for a period of 100 to 120 milliseconds until automatic channel selection is complete. <br /> 231 This API function allows you to set application data in the beacon when building the network. 232 To update the beacon's application data after the network has been built, use the <tt>@ref SetApplicationDataToBeacon</tt> function. 233 The maximum size of this application data is <tt>@ref NET_DESC_APPDATA_SIZE_MAX</tt> bytes. 234 The data is not encrypted. It can be collected by any general-purpose computing device, such as a desktop computer. 235 Other devices can get this data by calling <tt>Scan</tt> while they are connected as a <tt>Client</tt> or <tt>Spectator</tt>. <br /> 236 This function is thread-safe. 237 @param[in] subId Specifies the ID for identifying the communication mode. Set this parameter to a value between <tt>0x00</tt> and <tt>0xFE</tt>. 238 @param[in] maxEntry Specifies the maximum number of nodes that can connect to the network. This value can be up to <tt>@ref NODE_MAX</tt>, including the local device. 239 @param[in] localId Specifies the local communication ID. Specify the value generated by <tt>@ref CreateLocalCommunicationId</tt>. 240 @param[in] passphrase Specifies the string holding the seed of the passphrase to use for wireless layer encryption. 241 With UDS, communication can only be established if <SPAN class="argument">uniqueId</SPAN> and <SPAN class="argument">passphrase</SPAN> match. 242 @param[in] passphraseLength Specifies the passphrase length. Specify a value that is at least <tt>IR_PASSPHRASE_LENGTH_MIN</tt>, but no larger than <tt>IR_PASSPHRASE_LENGTH_MAX</tt>. 243 @param[in] channel Specifies the channel to use for communication. Specify channel <tt>0</tt> (automatic), <tt>1</tt>, <tt>6</tt>, or <tt>11</tt>. In production mode, the channel is always selected automatically. 244 @param[in] pData Specifies a pointer to the application data to set in the beacon. 245 @param[in] dataSize Specifies the size of the application data to set in the beacon. Specify a value no greater than <tt>@ref NET_DESC_APPDATA_SIZE_MAX</tt>. 246 247 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 248 @retval Result::IsSuccess Indicates that the node successfully established local communication and began operating as a host. 249 @retval ResultNotInitialized Indicates that the library is not initialized. Call the <tt>@ref Initialize</tt> function. 250 @retval ResultInvalidState Indicates that the function cannot be executed in this state. Returned when the function is executed in a state other than <tt>@ref STATE_DISCONNECTED</tt>. 251 @retval ResultOutOfRange Indicates that an argument was outside of the allowed range. The function may succeed if you execute it again with a suitable value for the argument. 252 @retval ResultNotAuthorized Indicates an invalid value for <span class="argument">localId</span>. Specify the value generated by <tt>@ref CreateLocalCommunicationId</tt>. 253 @retval ResultOutOfResource Indicates that the system is out of resources. Try again. 254 @retval ResultBusy Indicates that the system is busy. Try again. 255 @retval ResultTooLarge Indicates that <span class="argument">dataSize</span> is greater than <tt>@ref NET_DESC_APPDATA_SIZE_MAX</tt>. 256 @retval ResultInvalidPointer Indicates that <span class="argument">pData</span> is <tt>NULL</tt>. <tt>NULL</tt> is allowed when <span class="argument">dataSize</span> is <tt>0</tt>. 257 */ 258 nn::Result CreateNetwork( 259 u8 subId, 260 u8 maxEntry, 261 bit32 localId, 262 const char passphrase[], 263 size_t passphraseLength, 264 u8 channel, 265 const void* pData, 266 size_t dataSize ); 267 268 #ifdef NN_UDS_SUPPORT_CLIENT 269 /*! 270 @brief Scans for nearby networks. 271 272 By default, this feature requires 330 ms to complete. 273 274 This function is thread-safe. 275 276 @param[out] pBuffer Specifies the buffer for storing information about discovered networks. 277 @param[in] bufferSize Specifies the size of the buffer. Estimate roughly 1 KB per network. 278 @param[in] subId Specifies the ID used to identify the arbitrary communication mode set by the application. Specify <tt>0xff</tt> to search all <tt>SubID</tt>s. 279 @param[in] localId Specifies the local communication ID. Specify the value generated by <tt>@ref CreateLocalCommunicationId</tt>. 280 281 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 282 @retval Result::IsSuccess Indicates that local communication was successfully established and the located network information was stored in the buffer. 283 @retval ResultNotInitialized Indicates that the library is not initialized. Call the <tt>@ref Initialize</tt> function. 284 @retval ResultInvalidState Indicates that the function cannot be executed in this state. Returned when the function is executed in a state other than <tt>STATE_DISCONNECTED</tt>. 285 @retval ResultOutOfRange Indicates that an argument was outside of the allowed range. The function may succeed if you execute it again with a suitable value for the argument. 286 @retval ResultWirelessOff Indicates that the device entered wireless off mode. Reinitialization is required. 287 @retval Other Indicates failure for other reasons. 288 */ 289 nn::Result Scan( void* pBuffer, size_t bufferSize, u8 subId, bit32 localId ); 290 291 /*! 292 :private 293 @brief Scans for nearby networks. This feature is only used in special circumstances such as when a scan channel must be specified. 294 295 By default, this feature requires 330 ms to complete. 296 297 This function is thread-safe. 298 299 @param[out] pBuffer Specifies the buffer for storing information about discovered networks. 300 @param[in] bufferSize Specifies the size of the buffer. Estimate roughly 1 KB per network. 301 @param[in] subId Specifies the ID used to identify the arbitrary communication mode set by the application. Specify <tt>0xff</tt> to search all <tt>SubID</tt>s. 302 @param[in] localId Specifies the local communication ID. Specify the value generated by <tt>@ref CreateLocalCommunicationId</tt>. 303 @param[in] channel By default, the function scans all channels used by UDS. Only set this value when you want to scan a specific channel. 304 (0: Scans all channels used by UDS: 1, 6, and 11.) 305 @param[in] scanTime Specifies the scan time per channel. There is normally no need to specify this. (0: 110 milliseconds) 306 307 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 308 @retval Result::IsSuccess Indicates that local communication was successfully established and the located network information was stored in the buffer. 309 @retval ResultNotInitialized Indicates that the library is not initialized. Call the <tt>@ref Initialize</tt> function. 310 @retval ResultInvalidState Indicates that the function cannot be executed in this state. Returned when the function is executed in a state other than <tt>STATE_DISCONNECTED</tt>. 311 @retval ResultOutOfRange Indicates that an argument was outside of the allowed range. The function may succeed if you execute it again with a suitable value for the argument. 312 @retval ResultWirelessOff Indicates that the device entered wireless off mode. Reinitialization is required. 313 @retval Other Indicates failure for other reasons. 314 */ 315 nn::Result Scan( void* pBuffer, size_t bufferSize, u8 subId, bit32 localId, u8 channel, u16 scanTime = 0 ); 316 317 /*! 318 @brief Connects to an existing network. 319 320 Connection takes longer when the signal strength is poor. Up to approximately 800 ms is required until completion. 321 322 This function is thread-safe. 323 324 @param[in] networkDescription Specifies network information. This is obtained from the scanning results. 325 @param[in] type Specifies the network type. 326 @param[in] passphrase Specifies the passphrase to use for wireless layer encryption. 327 With UDS, communication can only be established if <SPAN class="argument">uniqueId</SPAN> and <SPAN class="argument">passphrase</SPAN> match. 328 @param[in] passphraseLength Specifies the passphrase length. Specify a value that is at least <tt>IR_PASSPHRASE_LENGTH_MIN</tt>, but no larger than <tt>IR_PASSPHRASE_LENGTH_MAX</tt>. 329 330 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 331 @retval Result::IsSuccess Indicates that the connection succeeded and operations began for the specified connection type. 332 @retval ResultNotInitialized Indicates that the library is not initialized. Call the <tt>@ref Initialize</tt> function. 333 @retval ResultNotFoundNetwork Indicates that the connection target network was not found. Returned when the network has already been destroyed or when it is outside the range of communications. 334 @retval ResultAlreadyNetworkIsFull Indicates the number of network nodes has already reached the maximum number of connections. You cannot connect unless you reduce the number of nodes. 335 @retval ResultDeniedFromMaster Indicates that the host denied the connection. Returned when the host has denied a connection to the network. Also returned when the passphrase is in error. 336 @retval ResultConnectionTimeout Indicates that the connection was not established in time. Returned when the signal strength is bad or when there is excessive load on the host. 337 @retval ResultInvalidState Indicates that the function cannot be executed in this state. Returned when the function is executed in a state other than <tt>STATE_DISCONNECTED</tt>. 338 @retval ResultOutOfRange Indicates that an argument was outside of the allowed range. The function may succeed if you execute it again with a suitable value for the argument. 339 @retval ResultWirelessOff Indicates that the device entered wireless off mode. Reinitialization is required. 340 @retval Other Indicates failure for other reasons. 341 */ 342 nn::Result ConnectNetwork( 343 const NetworkDescription& networkDescription, 344 ConnectType type, 345 const char passphrase[], 346 size_t passphraseLength ); 347 #endif 348 349 /*! 350 @brief Kicks the specified node off the network. Only the host can call this function. 351 352 This function is thread-safe. 353 354 @param[in] nodeId The ID of the node being added. If <tt>@ref BROADCAST_NODE_ID</tt> is specified, all connected nodes are disconnected. 355 356 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 357 @retval Result::IsSuccess Indicates the specified node was removed from the network. 358 @retval ResultNotInitialized Indicates that the library is not initialized. Call the <tt>@ref Initialize</tt> function. 359 @retval ResultInvalidState Indicates that the function cannot be executed in this state. Returned when executed in a state other than host. 360 @retval ResultNotAuthorized Indicates the node ID of the host was specified. 361 */ 362 nn::Result EjectClient ( u16 nodeId ); 363 364 /*! 365 @brief Prevents client nodes from connecting to the network. Does not affect clients that are currently connected. 366 367 The intended use of this feature is to deny connections by new clients after an online game has started. 368 When you want to allow connections again, call the <tt>@ref AllowToConnect</tt> function. 369 Only the host can call this function. <br /> 370 This function is thread-safe. 371 372 @param[in] isDisallowToReconnect If set to <tt>false</tt>, only the clients that were disconnected after calling this function can reconnect. 373 374 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 375 @retval Result::IsSuccess Indicates that the operation succeeded. 376 @retval ResultNotInitialized Indicates that the library is not initialized. Call the <tt>@ref Initialize</tt> function. 377 @retval ResultOutOfResource Indicates that the system is out of resources. Try again. 378 @retval ResultBusy Indicates that the system is busy. Try again. 379 */ 380 nn::Result DisallowToConnect(bool isDisallowToReconnect = false); 381 382 /*! 383 @brief Allows the client to connect to the network. 384 385 This function is used to connects a client denied connection by the <tt>@ref DisallowToConnect</tt> function. 386 This function does not clear the spectator's denied connection state resulting from the <tt>@ref EjectSpectator</tt> function. 387 Only the host can call this function. <br /> 388 This function is thread-safe. 389 390 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 391 @retval Result::IsSuccess Indicates that the operation succeeded. 392 @retval ResultNotInitialized Indicates that the library is not initialized. Call the <tt>@ref Initialize</tt> function. 393 @retval ResultOutOfResource Indicates that the system is out of resources. Try again. 394 @retval ResultBusy Indicates that the system is busy. Try again. 395 */ 396 nn::Result AllowToConnect(); 397 398 /*! 399 @brief Kicks all connected spectators off the network. 400 401 New spectators cannot connect after you execute this function. 402 To allow <tt>Spectator</tt> nodes to connect again, call the <tt>@ref AllowToSpectate</tt> function. 403 Only the host can call this function. <br /> 404 This function is thread-safe. 405 406 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 407 @retval Result::IsSuccess Indicates that the operation succeeded. 408 @retval ResultNotInitialized Indicates that the library is not initialized. Call the <tt>@ref Initialize</tt> function. 409 @retval ResultInvalidState Indicates that the function cannot be executed in this state. Returned when executed in a state other than host. 410 */ 411 nn::Result EjectSpectator( void ); 412 413 /*! 414 @brief Allows the spectator to connect to the network. 415 416 Use this function when you want to reconnect a <tt>Spectator</tt> to the network after executing the <tt>@ref EjectSpectator</tt> function. <br /> 417 This function is thread-safe. 418 419 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 420 @retval Result::IsSuccess Indicates that the operation succeeded. 421 @retval ResultNotInitialized Indicates that the library is not initialized. Call the <tt>@ref Initialize</tt> function. 422 @retval ResultOutOfResource Indicates that the system is out of resources. Try again. 423 @retval ResultBusy Indicates that the system is busy. Try again. 424 */ 425 nn::Result AllowToSpectate(); 426 427 /*! 428 @brief Destroys the network. 429 430 All connected clients and spectators are released and the network is destroyed. Only the host can call this function. 431 When you call this function, a disconnect request packet is sent to clients and spectators and they immediately disconnect from the network. 432 At this time, the <tt>@ref GetConnectionStatus</tt> function returns <tt>DISCARDED_FROM_NETWORK</tt> as the reason for disconnection (<tt>DisconnectReason</tt>). 433 However, depending on the communications environment, there may be times when the disconnect request packet does not reach clients and spectators. In this case, they are disconnected roughly one second after this function is called. 434 In this case, the reason for disconnection is <tt>CONNECTION_LOST</tt>. <br /> 435 This function is thread-safe. 436 437 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 438 @retval Result::IsSuccess Indicates that the network was destroyed and the node transitioned to the <tt>STATE_DISCONNECTED</tt> state. 439 @retval ResultNotInitialized Indicates that the library is not initialized. Call the <tt>@ref Initialize</tt> function. 440 @retval ResultInvalidState Indicates that the function cannot be executed in this state. Returned when executed in a state other than host. 441 */ 442 nn::Result DestroyNetwork ( void ); 443 444 #ifdef NN_UDS_SUPPORT_CLIENT 445 /*! 446 @brief Disconnects the local node from the network. 447 448 Only clients and spectators can call this function. 449 This function also succeeds when the node is not connected to the network, because the node may have already been disconnected (because of external factors, for example). 450 451 This function is thread-safe. 452 453 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 454 @retval Result::IsSuccess Indicates that the network was destroyed and the node transitioned to the <tt>STATE_DISCONNECTED</tt> state. 455 @retval ResultNotInitialized Indicates that the library is not initialized. Call the <tt>@ref Initialize</tt> function. 456 @retval ResultInvalidState Indicates that the function cannot be executed in this state. Returned when executed in a state other than host. 457 @retval ResultWirelessOff Indicates that the device entered wireless off mode. Reinitialization is required. 458 @retval Other Indicates failure for other reasons. 459 */ 460 nn::Result DisconnectNetwork ( void ); 461 #endif 462 463 /*! 464 @} 465 */ 466 /*! 467 @name Functions for Sending and Receiving Data 468 @{ 469 */ 470 471 /*! 472 @brief Creates a network endpoint and returns the corresponding descriptor. 473 474 <b>[Provisional spec]</b> Currently, up to 16 endpoints can be created. <br /> 475 This function is thread-safe. 476 477 @param[out] pEndpointDesc Descriptor indicating the endpoint to create. 478 479 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 480 @retval Result::IsSuccess Indicates that the operation succeeded. 481 @retval ResultNotInitialized Indicates that the library is not initialized. Call the <tt>@ref Initialize</tt> function. 482 @retval ResultOutOfResource More than the stipulated number of endpoints were already generated. Destroy an existing endpoint. 483 */ 484 nn::Result CreateEndpoint( EndpointDescriptor* pEndpointDesc ); 485 486 /*! 487 @brief Specifies the maximum send delay time. 488 489 For the system to improve the efficiency of its physical layer, smaller packets are sent bundled together. 490 As a result, when the maximum amount of data is sent by the <tt>@ref SendTo</tt> function, it may wait up to the amount of time set by this function. 491 When minimizing latency is more important than communication efficiency, you can specify <tt>@ref NO_WAIT</tt> to the <tt>@ref SendTo</tt> function to avoid this delay in sending data. 492 This can be executed only when not connected to the network. <br /> 493 This function is thread-safe. 494 495 @param[in] maxDelay Specifies the maximum latency. Specify a value in the range from 5 to 100 milliseconds. The default is 10 milliseconds. 496 497 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 498 @retval Result::IsSuccess Indicates that the operation succeeded. 499 @retval ResultNotInitialized Indicates that the library is not initialized. Call the <tt>@ref Initialize</tt> function. 500 @retval ResultInvalidState Indicates that the function cannot be executed in this state. Returned when executed while communicating. 501 */ 502 nn::Result SetMaxSendDelay ( nn::fnd::TimeSpan maxDelay ); 503 504 /*! 505 @brief Sends data to the specified port on the specified partner's system. 506 507 This function blocks until it has finished sending data. 508 The send method can be specified by setting <span class="argument">option</span> to <tt>@ref NO_WAIT</tt> or <tt>@ref FORCE_DIRECT_BC</tt>. 509 To specify multiple options, you can OR multiple values. <br /> 510 This function is thread-safe. 511 512 @param[in] endpointDesc Specifies a <tt>descriptor</tt> indicating the <tt>endpoint</tt> to use. 513 @param[in] data Specifies a pointer to the data to send. Processing efficiency is better if the buffer is on a 64-byte address boundary, and its size is a multiple of 64 bytes. 514 @param[in] dataSize Specifies the size of the data to send (in bytes). The maximum size of the data to send is <tt>@ref UDS_PACKET_PAYLOAD_MAX_SIZE</tt> bytes. 515 @param[in] destNodeId Specifies the recipient. Specify <tt>@ref BROADCAST_NODE_ID</tt> to broadcast the data. 516 @param[in] port Specifies the port to assign. Port <tt>0x00</tt> is reserved by the system and cannot be used. 517 @param[in] option Specifies the send options. 518 519 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 520 @retval Result::IsSuccess Indicates that the operation succeeded. 521 @retval ResultNotInitialized Indicates that the library is not initialized. Call the <tt>@ref Initialize</tt> function. 522 @retval ResultInvalidState Indicates that the function cannot be executed in this state. Returned when this function is executed by a local device acting as other than a host or client. 523 @retval ResultTooLarge Indicates that <span class="argument">dataSize</span> is greater than <tt>@ref UDS_PACKET_PAYLOAD_MAX_SIZE</tt>. 524 @retval ResultOutOfRange Indicates that an argument was outside of the allowed range. The function may succeed if you execute it again with a suitable value for the argument. 525 @retval ResultBufferIsFull Indicates that packets exceeding the transmission capacity of the wireless device were sent when the <tt>NO_WAIT</tt> option was specified. This result can occur more frequently when the signal strength is bad. 526 @retval ResultMisalignedAddress Indicates that the value of <span class="argument">data</span> is invalid. The function may succeed if you execute it again with a suitable value for the argument. 527 You might succeed by retrying, but if this errors occurs frequently, try specifying a larger buffer size with the <tt>@ref Initialize</tt> function. 528 */ 529 nn::Result SendTo ( const EndpointDescriptor& endpointDesc, const void* data, size_t dataSize, u16 destNodeId, u8 port, bit8 option = 0x00 ); 530 531 /*! 532 @brief Enables the local device to receive packets from the endpoint. 533 534 Assigns the specified port and node ID to the endpoint. 535 The system creates a receive buffer and prepares to receive packets at the port specified below. <br /> 536 This function is thread-safe. 537 538 @param[in] pEndpointDesc Specifies a descriptor indicating the endpoint to use. 539 @param[in] srcNodeId Specifies the node ID being assigned. Specify <tt>@ref BROADCAST_NODE_ID</tt> to attach all nodes. 540 @param[in] port Specifies the port being assigned. Port <tt>0x00</tt> is reserved by the system and cannot be used. 541 @param[in] receiveBufferSize Specifies the size of the receive buffer being allocated. Memory is allocated from the memory block retrieved by the <tt>@ref Initialize</tt> function. Do not try to allocate a receive buffer larger than that total. 542 You must specify at least <tt>@ref ATTACH_BUFFER_SIZE_MIN</tt> bytes. The default value is <tt>@ref ATTACH_BUFFER_SIZE_DEFAULT</tt> bytes. 543 Communication is most efficient when the specified data size is a multiple of 64. 544 545 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 546 @retval Result::IsSuccess Indicates that the operation succeeded. 547 @retval ResultNotInitialized Indicates that the library is not initialized. Call the <tt>@ref Initialize</tt> function. 548 @retval ResultOutOfResource The buffer specified with the <tt>@ref Initialize</tt> function was insufficient. 549 @retval ResultOutOfRange Indicates that an argument was outside of the allowed range. The function may succeed if you execute it again with a suitable value for the argument. 550 551 */ 552 nn::Result Attach ( EndpointDescriptor* pEndpointDesc, u16 srcNodeId, u8 port, size_t receiveBufferSize = ATTACH_BUFFER_SIZE_DEFAULT ); 553 554 /*! 555 @brief Receives data. (No functionality is provided for getting the address of the sender.) 556 557 Other than the parameters, this function is the same as <tt>@ref ReceiveFrom</tt>. For more information, see the <tt>@ref ReceiveFrom</tt> function reference. <br /> 558 This function is thread-safe. 559 560 @param[in] endpointDesc Specifies a <tt>descriptor</tt> indicating the <tt>endpoint</tt> to use. The port and sender must be attached in advance using the <tt>@ref Attach</tt> function. 561 @param[out] pBuffer Specifies the location to store received data. It is efficient to specify a buffer that is 64-byte aligned. 562 @param[out] pReceivedSize Specifies the size of the received data. The UDS maximum received data size is <tt>@ref UDS_PACKET_PAYLOAD_MAX_SIZE</tt> bytes. 563 @param[in] bufferSize Specifies the size (in bytes) of the receive buffer (<span class="argument">pBuffer</span>). It is efficient to specify a multiple of 64. 564 @param[in] option Specifies the receive options. Specifying <tt>@ref NO_WAIT</tt> causes the function to return immediately, even if no data has been received. 565 If not specified, the function does not return until either it receives data or an error occurs. 566 567 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 568 @retval Result::IsSuccess Indicates that the operation succeeded. 569 @retval ResultNotInitialized Indicates that the specified <tt>endpoint</tt> did not exist when the library was not initialized. 570 @retval ResultInvalidState Indicates that the function cannot be executed in this state. Returns that it was executed in a state where it was not connected to the network. 571 @retval ResultNotAuthorized Indicates that an <tt>endpoint</tt> that was not attached was specified. 572 @retval ResultTooLarge Indicates that the <span class="argument">bufferSize</span> was smaller than the received data. The best size is <tt>@ref UDS_PACKET_PAYLOAD_MAX_SIZE</tt>. 573 @retval ResultOutOfRange Indicates that an argument was outside of the allowed range. The function may succeed if you execute it again with a suitable value for the argument. 574 @retval ResultMisalignedSize Invalid <span class="argument">bufferSize</span>. The function may succeed if you execute it again with a suitable value for the argument. 575 @retval ResultMisalignedAddress The value of <span class="argument">pBuffer</span> is invalid. The function may succeed if you execute it again with a suitable value for the argument. 576 @retval ResultBusy Packet reception with the specified endpoint is in progress. Call after the previous reception process finishes. 577 You might succeed by retrying, but if this errors occurs frequently, try specifying a larger buffer size with the <tt>@ref Initialize</tt> function. 578 */ 579 nn::Result Receive ( const EndpointDescriptor& endpointDesc, void* pBuffer, size_t* pReceivedSize, size_t bufferSize, bit8 option = 0x00 ); 580 581 /*! 582 @brief Receives data. 583 584 Receives packets sent to an endpoint for which the <tt>@ref Attach</tt> function was executed. 585 This function blocks when there are no packets to receive. (Unless an error occurs.) 586 The function exits even if it does not receive packets if <tt>@ref NO_WAIT</tt> is specified in <span class="argument">option</span>. <br /> 587 This function is thread-safe. 588 589 @param[in] endpointDesc Specifies a <tt>descriptor</tt> indicating the <tt>endpoint</tt> to use. The port and sender must be attached in advance using the <tt>@ref Attach</tt> function. 590 @param[out] pBuffer Specifies the location to store received data. It is efficient to specify a buffer that is 64-byte aligned. 591 @param[out] pReceivedSize Specifies the size of the received data. The UDS maximum received data size is <tt>@ref UDS_PACKET_PAYLOAD_MAX_SIZE</tt> bytes. 592 @param[out] pSrcNodeId The ID of the sending node. 593 @param[in] bufferSize Specifies the size (in bytes) of the receive buffer (<span class="argument">pBuffer</span>). It is efficient to specify a multiple of 64. 594 @param[in] option Specifies the receive options. Specifying <tt>@ref NO_WAIT</tt> causes the function to return immediately, even if no data has been received. 595 If not specified, the function does not return until either it receives data or an error occurs. 596 597 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 598 @retval Result::IsSuccess Indicates that the operation succeeded. 599 @retval ResultNotInitialized Indicates that the specified <tt>endpoint</tt> did not exist when the library was not initialized. 600 @retval ResultInvalidState Indicates that the function cannot be executed in this state. Returned when the function is executed in a state where it was not connected to the network. 601 @retval ResultNotAuthorized Indicates that an <tt>endpoint</tt> that was not attached was specified. 602 @retval ResultTooLarge Indicates that the <span class="argument">bufferSize</span> was smaller than the received data. The best size is <tt>@ref UDS_PACKET_PAYLOAD_MAX_SIZE</tt>. 603 @retval ResultOutOfRange Indicates that an argument was outside of the allowed range. The function may succeed if you execute it again with a suitable value for the argument. 604 @retval ResultMisalignedSize Invalid <span class="argument">bufferSize</span>. The function may succeed if you execute it again with a suitable value for the argument. 605 @retval ResultMisalignedAddress The value of <span class="argument">pBuffer</span> is invalid. The function may succeed if you execute it again with a suitable value for the argument. 606 @retval ResultBusy Packet reception with the specified endpoint is in progress. Call after the previous reception process finishes. 607 You might succeed by retrying, but if this errors occurs frequently, try specifying a larger buffer size with the <tt>@ref Initialize</tt> function. 608 */ 609 nn::Result ReceiveFrom ( const EndpointDescriptor& endpointDesc, void* pBuffer, size_t* pReceivedSize, u16* pSrcNodeId, size_t bufferSize, bit8 option = 0x00 ); 610 611 /*! 612 @brief Destroys an endpoint. 613 614 Frees the receive buffer if the <tt>@ref Attach</tt> function has been called with the specified endpoint. 615 The freed receive buffer can be reused with the <tt>@ref Attach</tt> function, but note that the application can only access it after the <tt>@ref Finalize</tt> function is executed. <br /> 616 This function is thread-safe. 617 618 @param[in] pEndpointDesc Descriptor indicating the endpoint. 619 620 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 621 @retval Result::IsSuccess Indicates that the operation succeeded. 622 @retval ResultNotInitialized Indicates that the library is not initialized. Call the <tt>@ref Initialize</tt> function. 623 @retval ResultNotAuthorized Indicates that an invalid endpoint descriptor was specified. 624 */ 625 nn::Result DestroyEndpoint( EndpointDescriptor* pEndpointDesc ); 626 627 /*! 628 @} 629 */ 630 631 /*! 632 @name Functions for detecting state changes and getting information 633 @{ 634 */ 635 636 /*! 637 @brief Gets the current connection status. 638 639 Calling this function is sufficient only when the <tt>@ref PollStateChange</tt> function succeeds (that is, when there is a change in the state).<br/> <br /> 640 This function is thread-safe. 641 642 @param[out] pStatus The current connection status. 643 644 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 645 @retval Result::IsSuccess Indicates that the operation succeeded. 646 @retval ResultNotInitialized Indicates that the library is not initialized. Call the <tt>@ref Initialize</tt> function. 647 */ 648 nn::Result GetConnectionStatus( ConnectionStatus* pStatus ); 649 650 /*! 651 @brief Gets the current channel. 652 653 This function is thread-safe. 654 655 @param[out] pChannel Returns the channel. 656 657 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 658 @retval Result::IsSuccess Indicates that the operation succeeded. 659 @retval ResultNotInitialized Indicates that the library is not initialized. Execute the <tt>nn::uds::Initialize</tt> function. 660 */ 661 nn::Result GetChannel(u8* pChannel); 662 663 /*! 664 @brief Gets information about the specified node. 665 666 This function is thread-safe. 667 668 @param[out] pNodeInfo Information about the node. 669 @param[in] nodeId The ID of the target node. 670 671 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 672 @retval Result::IsSuccess Indicates that the operation succeeded. 673 @retval ResultNotInitialized Indicates that the library is not initialized. Call the <tt>@ref Initialize</tt> function. 674 @retval ResultInvalidNode The target node does not exist on the network. You might be disconnected. 675 */ 676 nn::Result GetNodeInformation ( NodeInformation* pNodeInfo, u16 nodeId ); 677 678 /*! 679 @brief Queries whether a host has changed status or a client has connected or disconnected. 680 681 Excluding the case when <tt>NO_WAIT</tt> is specified in the <span class="argument">option</span> parameter, this API does not return until there is a change in the state. <br /> 682 This function is thread-safe. 683 684 When <tt>NO_WAIT</tt> is specified, returns the result without blocking. 685 686 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 687 @retval Result::IsSuccess The state has changed. For more information about the state, see the <tt>@ref GetConnectionStatus</tt> function. 688 @retval ResultNotInitialized Indicates that the library is not initialized. Call the <tt>@ref Initialize</tt> function. 689 @retval ResultNotFound The state has not changed. Returned only when <tt>NO_WAIT</tt> is specified in the <span class="argument">option</span> parameter. 690 @retval ResultBusy Called by another thread. Call after the previous call completes. 691 */ 692 nn::Result PollStateChange(u8 option); 693 694 /*! 695 @} 696 */ 697 698 /*! 699 @name Accessors for Beacon Application Data 700 @{ 701 */ 702 703 /*! 704 @brief Sets application data in the beacon. 705 706 Specifies up to <tt>@ref NET_DESC_APPDATA_SIZE_MAX</tt> bytes of application data. 707 The data is not encrypted. It can be collected by any general-purpose computing device, such as a desktop computer. 708 Other devices can get this data by calling <tt>Scan</tt> while they are connected as a <tt>Client</tt> or <tt>Spectator</tt>. 709 Only the host can run this function. <br /> 710 This function is thread-safe. 711 712 @param[in] pData Pointer to data being set. 713 @param[in] dataSize Size of the data to set. Specify a value no greater than <tt>@ref NET_DESC_APPDATA_SIZE_MAX</tt>. 714 715 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 716 @retval Result::IsSuccess Indicates that the operation succeeded. 717 @retval ResultNotInitialized Indicates that the library is not initialized. Call the <tt>@ref Initialize</tt> function. 718 @retval ResultInvalidState Indicates that the function cannot be executed in this state. Returned when the function is executed in a state other than host. 719 @retval ResultTooLarge Indicates that <span class="argument">dataSize</span> is greater than <tt>@ref NET_DESC_APPDATA_SIZE_MAX</tt>. 720 @retval ResultOutOfResource Indicates that the system is out of resources. Try again. 721 @retval ResultBusy Indicates that the system is busy. Try again. 722 */ 723 nn::Result SetApplicationDataToBeacon ( const void* pData, size_t dataSize ); 724 725 /*! 726 @brief Gets the data set in the beacon. 727 728 The host gets the data set using the <tt>@ref SetApplicationDataToBeacon</tt> function. 729 This function can only be run when connected to the network. 730 There is no notification if the data is updated. <br /> 731 This function is thread-safe. 732 733 @param[out] pBuffer Specifies the location storing the data. 734 @param[out] pDataSize Specifies the size of the data. Returns <tt>0</tt> when the <span class="argument">bufferSize</span> was smaller than the received data. 735 @param[in] bufferSize Specifies the size of the buffer. The sender can freely change the size of the data. In general, specify <tt>@ref NET_DESC_APPDATA_SIZE_MAX</tt> bytes. 736 737 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 738 @retval Result::IsSuccess Indicates that the operation succeeded. 739 @retval ResultNotInitialized Indicates that the library is not initialized. Call the <tt>@ref Initialize</tt> function. 740 @retval ResultInvalidState Indicates that the function cannot be executed in this state. Returned when the function is executed in a state where it was not connected to the network. 741 */ 742 nn::Result GetApplicationDataFromBeacon ( void* pBuffer, size_t* pDataSize, size_t bufferSize ); 743 744 /*! 745 @} 746 */ 747 748 /*! 749 @} 750 */ 751 752 #ifdef NN_UDS_SUPPORT_POWER_SAVE 753 /*! 754 :private 755 @brief Changes the power-saving mode. (This has not yet been implemented.) 756 757 This setting can only be changed for a host. Clients and spectators follow the host's settings. 758 This function is not yet implemented. It always fails if run. 759 After the feature is implemented, you can dynamically change to a power-save mode during communications. Do not change the mode very frequently (more frequently than once every few seconds). <br /> 760 <br /> 761 This function is thread-safe. 762 763 @param[in] mode The power-saving mode. Enabling a power-saving mode may cause a slight decline in connectivity. 764 765 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 766 @retval ResultNotImplemented Not yet implemented. 767 768 */ 769 nn::Result SetPowerSaveMode(PowerSaveMode mode); 770 #endif 771 namespace detail{ 772 #if 0 773 /*! 774 :private 775 @brief Gets the detailed signal intensity. 776 777 Do not use this function on retail consoles as it is only provided for use on development hardware to aid development. 778 Communication is negatively affected if this function is called too frequently. Execute it about once per second. 779 780 This function is thread-safe. 781 782 @param[out] info The signal intensity. Stores data if the function succeeds. 783 784 @return Returns the result of the function. If execution succeeds, the function stores data in <span class="argument">info</span> and returns a value for which <tt>@ref nn::Result::IsSuccess</tt> returns <tt>true</tt>. 785 */ 786 nn::Result GetRadioStrengthInfo(RadioStrengthInfo* info); 787 #endif 788 /*! 789 :private 790 @brief Destroys an endpoint. 791 792 The receive buffer created when <tt>Attach</tt> was called is freed at this time. 793 This function is used for debugging purposes. It allows you to get information about packets lost because of UDS receive buffer overflow, even when wireless transfer has succeeded. <br /> 794 This function is thread-safe. 795 796 @param[in] pEndpoint Descriptor indicating the endpoint. 797 @param[out] pReport Information about packets that arrived at the destroyed endpoint. 798 799 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 800 @retval Result::IsSuccess Indicates that the operation succeeded. 801 @retval ResultNotInitialized Indicates that the library is not initialized. Call the <tt>@ref Initialize</tt> function. 802 @retval ResultNotAuthorized Indicates that an invalid endpoint descriptor was specified. 803 */ 804 nn::Result DestroyEndpoint( EndpointDescriptor* pEndpointDesc, ReceiveReport* pReport ); 805 806 } // end of namespace detail 807 808 } // end of namespace Cafe 809 } // end of namespace uds 810 } // end of namespace nn 811 812 813 814 #endif // ifndef INCLUDE_NN_UDS_CAFE_UDS_API_H_ 815