/*---------------------------------------------------------------------------*
  Project:  Horizon
  File:     uds_Api.h

  Copyright (C) 2009-2011 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.

  $Rev: 54504 $
 *---------------------------------------------------------------------------*/

#ifndef INCLUDE_NN_UDS_CAFE_UDS_API_H_
#define INCLUDE_NN_UDS_CAFE_UDS_API_H_

/*! @file
@brief These are members of the UDS Library.
*/

#include <nn/uds/CAFE/uds_Type.h>
#include <nn/uds/CAFE/uds_Result.h>
#ifdef NN_UDS_SUPPORT_CLIENT
#include <nn/uds/CAFE/uds_NetworkDescription.h>
#endif
#include <nn/fnd/fnd_TimeSpan.h>

namespace nn {
namespace uds {
namespace Cafe {

/*!
@ingroup nn_uds
@defgroup nn_uds_api  Local Communication (UDS) API
@brief This file lists Local Communication (UDS) library API members. (Includes only C++ API members.)
    @{
*/

/*!
@name  Initialization and Shutdown
  @{
*/

/*!
@brief Initializes the UDS library. Initialization fails if any other communication features are already in use.

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.

Always call the <tt>@ref Finalize</tt> function to release the communication device after you are finished using the UDS library. <br />
This function is thread-unsafe.

@param[in]  receiveBuffer  Pointer to the start of the receive buffer used by the UDS library. Specify a buffer aligned to 64 bytes.
Access to the memory region specified by the buffer is prohibited until the <tt>@ref Finalize</tt> function completes.
@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.

@return Returns the result of the function. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess  Indicates that initialization succeeded.
@retval ResultAlreadyOccupiedWirelessDevice  Indicates that communication is already taking place. New UDS communication cannot begin.
@retval ResultOutOfResource  Indicates that the system is out of resources. Try again.
@retval ResultBusy  Indicates that the system is busy. Try again.
*/
nn::Result Initialize( void* receiveBuffer, const size_t bufferSize);

/*!
@brief Initializes the UDS library. Initialization fails if any other communication features are already in use.

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.

Always call the <tt>@ref Finalize</tt> function to release the communication device after you are finished using the UDS library. <br />
Handle the user name specified by <span class="argument">pUserName</span> according to UGC guidelines. <br />
This function is thread-unsafe.

@param[in]  receiveBuffer  Pointer to the start of the receive buffer used by the UDS library. Specify a buffer aligned to 64 bytes.
Access to the memory region specified by the buffer is prohibited until the <tt>@ref Finalize</tt> function completes.
@param[in]  bufferSize  The size of the receive buffer. Specify a value that is a multiple of 64.
@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.

@return Returns the result of the function. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess  Indicates that initialization succeeded.
@retval ResultAlreadyOccupiedWirelessDevice  Indicates that communication is already taking place. New UDS communication cannot begin.
@retval ResultOutOfResource  Indicates that the system is out of resources. Try again.
@retval ResultBusy  Indicates that the system is busy. Try again.
*/
nn::Result Initialize( void* receiveBuffer, const size_t bufferSize, nn::cfg::CTR::UserName* pUserName);

/*!
@brief Finalizes the UDS library. After executing, other communication features become usable.

Blocks for 50 to 60 milliseconds.
Releases the communication device held by the <tt>@ref Initialize</tt> function.
The receive buffer specified by the <tt>@ref Initialize</tt> function can be accessed from the application after this function's execution completes. <br />
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 />
The buffer allocated by the <tt>@ref Attach</tt> function is released. <br />
This function is thread-unsafe.

@return None.
*/
void Finalize  ();

/*!
  @}
*/
/*!
@name  Networks (Creating, Destroying, Connecting, and Disconnecting)
  @{
*/

/*!
@brief Creates a local communication ID from a unique ID.

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 />
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 />
However, you must get a unique ID from Nintendo for your retail product. <br />
This function is thread-safe.

@param[in] uniqueId The unique ID. To communicate between multiple titles, specify either of their unique IDs.
@param[in] isDemo  This flag is used when the same unique ID is used for both the retail and demo versions.
Specify <tt>true</tt> for the demo if you do not want communication between the retail product and downloadable demo versions.
<b>Note:</b> Always set this flag to <tt>false</tt> in retail builds.
@return Returns the local communication ID.
*/
bit32 CreateLocalCommunicationId( bit32 uniqueId, bool isDemo = false);

/*!
@brief Creates a new network.

This function blocks for a period of 100 to 120 milliseconds until automatic channel selection is complete. <br />
This function is thread-safe.

@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>.
@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.
@param[in] localId  Specifies the local communication ID. Specify the value generated by <tt>@ref CreateLocalCommunicationId</tt>.
@param[in] passphrase  Specifies the string holding the seed of the passphrase to use for wireless layer encryption.
With UDS, communication can only be established if <SPAN class="argument">uniqueId</SPAN> and <SPAN class="argument">passphrase</SPAN> match.
@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>.

@return Returns the result of the function. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess  Indicates the node successfully established local communication and began operating as a host.
@retval ResultNotInitialized  Indicates that the library is not initialized. Call the <tt>@ref Initialize</tt> function.
@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>.
@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.
@retval ResultNotAuthorized  Indicates an invalid value for <span class="argument">localId</span>. Specify the value generated by <tt>@ref CreateLocalCommunicationId</tt>.
@retval ResultOutOfResource  Indicates that the system is out of resources. Try again.
@retval ResultBusy  Indicates that the system is busy. Try again.
*/
nn::Result CreateNetwork(
        u8 subId,
        u8 maxEntry,
        bit32 localId,
        const char passphrase[],
        size_t passphraseLength );

/*!
@brief Sets application data in the beacon and builds a new network.

This function blocks for a period of 100 to 120 milliseconds until automatic channel selection is complete. <br />
This API function allows you to set application data in the beacon when building the network.
To update the beacon's application data after the network has been built, use the <tt>@ref SetApplicationDataToBeacon</tt> function.
The maximum size of this application data is <tt>@ref NET_DESC_APPDATA_SIZE_MAX</tt> bytes.
The data is not encrypted. It can be collected by any general-purpose computing device, such as a desktop computer.
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 />
This function is thread-safe.

@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>.
@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.
@param[in] localId  Specifies the local communication ID. Specify the value generated by <tt>@ref CreateLocalCommunicationId</tt>.
@param[in] passphrase  Specifies the string holding the seed of the passphrase to use for wireless layer encryption.
With UDS, communication can only be established if <SPAN class="argument">uniqueId</SPAN> and <SPAN class="argument">passphrase</SPAN> match.
@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>.
@param[in] pData  Specifies a pointer to the application data to set in the beacon.
@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>.

@return Returns the result of the function. Returns one of the following <tt>Result</tt> values.
@retval  Result::IsSuccess  Indicates that the node successfully established local communication and began operating as a host.
@retval ResultNotInitialized  Indicates that the library is not initialized. Call the <tt>@ref Initialize</tt> function.
@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>.
@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.
@retval ResultNotAuthorized  Indicates an invalid value for <span class="argument">localId</span>. Specify the value generated by <tt>@ref CreateLocalCommunicationId</tt>.
@retval ResultOutOfResource  Indicates that the system is out of resources. Try again.
@retval ResultBusy  Indicates that the system is busy. Try again.
@retval ResultTooLarge  Indicates that <span class="argument">dataSize</span> is greater than <tt>@ref NET_DESC_APPDATA_SIZE_MAX</tt>.
@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>.
*/
nn::Result CreateNetwork(
        u8 subId,
        u8 maxEntry,
        bit32 localId,
        const char passphrase[],
        size_t passphraseLength,
        const void* pData,
        size_t dataSize );

/*!
@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.

The channel argument is ignored in production mode.
This function blocks for a period of 100 to 120 milliseconds until automatic channel selection is complete. <br />
This function is thread-safe.
@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>.
@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.
@param[in] localId  Specifies the local communication ID. Specify the value generated by <tt>@ref CreateLocalCommunicationId</tt>.
@param[in] passphrase  Specifies the string holding the seed of the passphrase to use for wireless layer encryption.
With UDS, communication can only be established if <SPAN class="argument">uniqueId</SPAN> and <SPAN class="argument">passphrase</SPAN> match.
@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>.
@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.

@return Returns the result of the function. Returns one of the following <tt>Result</tt> values.
@retval  Result::IsSuccess  Indicates that the node successfully established local communication and began operating as a host.
@retval ResultNotInitialized  Indicates that the library is not initialized. Call the <tt>@ref Initialize</tt> function.
@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>.
@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.
@retval ResultNotAuthorized  Indicates an invalid value for <span class="argument">localId</span>. Specify the value generated by <tt>@ref CreateLocalCommunicationId</tt>.
@retval ResultOutOfResource  Indicates that the system is out of resources. Try again.
@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>.
*/
nn::Result CreateNetwork(
        u8 subId,
        u8 maxEntry,
        bit32 localId,
        const char passphrase[],
        size_t passphraseLength,
        u8 channel );

/*!
@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.

The channel argument is ignored in production mode.
This function blocks for a period of 100 to 120 milliseconds until automatic channel selection is complete. <br />
This API function allows you to set application data in the beacon when building the network.
To update the beacon's application data after the network has been built, use the <tt>@ref SetApplicationDataToBeacon</tt> function.
The maximum size of this application data is <tt>@ref NET_DESC_APPDATA_SIZE_MAX</tt> bytes.
The data is not encrypted. It can be collected by any general-purpose computing device, such as a desktop computer.
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 />
This function is thread-safe.
@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>.
@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.
@param[in] localId  Specifies the local communication ID. Specify the value generated by <tt>@ref CreateLocalCommunicationId</tt>.
@param[in] passphrase  Specifies the string holding the seed of the passphrase to use for wireless layer encryption.
With UDS, communication can only be established if <SPAN class="argument">uniqueId</SPAN> and <SPAN class="argument">passphrase</SPAN> match.
@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>.
@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.
@param[in] pData  Specifies a pointer to the application data to set in the beacon.
@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>.

@return Returns the result of the function. Returns one of the following <tt>Result</tt> values.
@retval  Result::IsSuccess  Indicates that the node successfully established local communication and began operating as a host.
@retval ResultNotInitialized  Indicates that the library is not initialized. Call the <tt>@ref Initialize</tt> function.
@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>.
@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.
@retval ResultNotAuthorized  Indicates an invalid value for <span class="argument">localId</span>. Specify the value generated by <tt>@ref CreateLocalCommunicationId</tt>.
@retval ResultOutOfResource  Indicates that the system is out of resources. Try again.
@retval ResultBusy  Indicates that the system is busy. Try again.
@retval ResultTooLarge  Indicates that <span class="argument">dataSize</span> is greater than <tt>@ref NET_DESC_APPDATA_SIZE_MAX</tt>.
@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>.
*/
nn::Result CreateNetwork(
        u8 subId,
        u8 maxEntry,
        bit32 localId,
        const char passphrase[],
        size_t passphraseLength,
        u8 channel,
        const void* pData,
        size_t dataSize );

#ifdef NN_UDS_SUPPORT_CLIENT
/*!
@brief Scans for nearby networks.

By default, this feature requires 330 ms to complete.

This function is thread-safe.

@param[out] pBuffer  Specifies the buffer for storing information about discovered networks.
@param[in] bufferSize  Specifies the size of the buffer. Estimate roughly 1 KB per network.
@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.
@param[in] localId  Specifies the local communication ID. Specify the value generated by <tt>@ref CreateLocalCommunicationId</tt>.

@return Returns the result of the function. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess  Indicates that local communication was successfully established and the located network information was stored in the buffer.
@retval ResultNotInitialized  Indicates that the library is not initialized. Call the <tt>@ref Initialize</tt> function.
@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>.
@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.
@retval ResultWirelessOff  Indicates that the device entered wireless off mode. Reinitialization is required.
@retval Other  Indicates failure for other reasons.
*/
nn::Result Scan( void* pBuffer, size_t bufferSize, u8 subId, bit32 localId );

/*!
:private
@brief Scans for nearby networks. This feature is only used in special circumstances such as when a scan channel must be specified.

By default, this feature requires 330 ms to complete.

This function is thread-safe.

@param[out] pBuffer  Specifies the buffer for storing information about discovered networks.
@param[in] bufferSize  Specifies the size of the buffer. Estimate roughly 1 KB per network.
@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.
@param[in] localId  Specifies the local communication ID. Specify the value generated by <tt>@ref CreateLocalCommunicationId</tt>.
@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.
(0: Scans all channels used by UDS: 1, 6, and 11.)
@param[in] scanTime  Specifies the scan time per channel. There is normally no need to specify this. (0: 110 milliseconds)

@return Returns the result of the function. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess  Indicates that local communication was successfully established and the located network information was stored in the buffer.
@retval ResultNotInitialized  Indicates that the library is not initialized. Call the <tt>@ref Initialize</tt> function.
@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>.
@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.
@retval ResultWirelessOff  Indicates that the device entered wireless off mode. Reinitialization is required.
@retval Other  Indicates failure for other reasons.
*/
nn::Result Scan( void* pBuffer, size_t bufferSize, u8 subId, bit32 localId, u8 channel, u16 scanTime = 0 );

/*!
@brief Connects to an existing network.

Connection takes longer when the signal strength is poor. Up to approximately 800 ms is required until completion.

This function is thread-safe.

@param[in] networkDescription  Specifies network information. This is obtained from the scanning results.
@param[in] type  Specifies the network type.
@param[in] passphrase  Specifies the passphrase to use for wireless layer encryption.
With UDS, communication can only be established if <SPAN class="argument">uniqueId</SPAN> and <SPAN class="argument">passphrase</SPAN> match.
@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>.

@return Returns the result of the function. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess  Indicates that the connection succeeded and operations began for the specified connection type.
@retval ResultNotInitialized  Indicates that the library is not initialized. Call the <tt>@ref Initialize</tt> function.
@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.
@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.
@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.
@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.
@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>.
@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.
@retval ResultWirelessOff  Indicates that the device entered wireless off mode. Reinitialization is required.
@retval Other  Indicates failure for other reasons.
*/
nn::Result ConnectNetwork(
        const NetworkDescription& networkDescription,
        ConnectType type,
        const char passphrase[],
        size_t passphraseLength );
#endif

/*!
@brief Kicks the specified node off the network. Only the host can call this function.

This function is thread-safe.

@param[in]  nodeId  The ID of the node being added. If <tt>@ref BROADCAST_NODE_ID</tt> is specified, all connected nodes are disconnected.

@return Returns the result of the function. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess  Indicates the specified node was removed from the network.
@retval ResultNotInitialized  Indicates that the library is not initialized. Call the <tt>@ref Initialize</tt> function.
@retval ResultInvalidState  Indicates that the function cannot be executed in this state. Returned when executed in a state other than host.
@retval ResultNotAuthorized  Indicates the node ID of the host was specified.
*/
nn::Result EjectClient ( u16 nodeId );

/*!
@brief Prevents client nodes from connecting to the network. Does not affect clients that are currently connected.

The intended use of this feature is to deny connections by new clients after an online game has started.
When you want to allow connections again, call the <tt>@ref AllowToConnect</tt> function.
Only the host can call this function. <br />
This function is thread-safe.

@param[in]  isDisallowToReconnect If set to <tt>false</tt>, only the clients that were disconnected after calling this function can reconnect.

@return Returns the result of the function. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess  Indicates that the operation succeeded.
@retval ResultNotInitialized  Indicates that the library is not initialized. Call the <tt>@ref Initialize</tt> function.
@retval ResultOutOfResource  Indicates that the system is out of resources. Try again.
@retval ResultBusy  Indicates that the system is busy. Try again.
*/
nn::Result DisallowToConnect(bool isDisallowToReconnect = false);

/*!
@brief Allows the client to connect to the network.

This function is used to connects a client denied connection by the <tt>@ref DisallowToConnect</tt> function.
This function does not clear the spectator's denied connection state resulting from the <tt>@ref EjectSpectator</tt> function.
Only the host can call this function. <br />
This function is thread-safe.

@return Returns the result of the function. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess  Indicates that the operation succeeded.
@retval ResultNotInitialized  Indicates that the library is not initialized. Call the <tt>@ref Initialize</tt> function.
@retval ResultOutOfResource  Indicates that the system is out of resources. Try again.
@retval ResultBusy  Indicates that the system is busy. Try again.
*/
nn::Result AllowToConnect();

/*!
@brief Kicks all connected spectators off the network.

New spectators cannot connect after you execute this function.
To allow <tt>Spectator</tt> nodes to connect again, call the <tt>@ref AllowToSpectate</tt> function.
Only the host can call this function. <br />
This function is thread-safe.

@return Returns the result of the function. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess  Indicates that the operation succeeded.
@retval ResultNotInitialized  Indicates that the library is not initialized. Call the <tt>@ref Initialize</tt> function.
@retval ResultInvalidState  Indicates that the function cannot be executed in this state. Returned when executed in a state other than host.
*/
nn::Result EjectSpectator( void );

/*!
@brief Allows the spectator to connect to the network.

Use this function when you want to reconnect a <tt>Spectator</tt> to the network after executing the <tt>@ref EjectSpectator</tt> function. <br />
This function is thread-safe.

@return Returns the result of the function. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess  Indicates that the operation succeeded.
@retval ResultNotInitialized  Indicates that the library is not initialized. Call the <tt>@ref Initialize</tt> function.
@retval ResultOutOfResource  Indicates that the system is out of resources. Try again.
@retval ResultBusy  Indicates that the system is busy. Try again.
*/
nn::Result AllowToSpectate();

/*!
@brief Destroys the network.

All connected clients and spectators are released and the network is destroyed. Only the host can call this function.
When you call this function, a disconnect request packet is sent to clients and spectators and they immediately disconnect from the network.
At this time, the <tt>@ref GetConnectionStatus</tt> function returns <tt>DISCARDED_FROM_NETWORK</tt> as the reason for disconnection (<tt>DisconnectReason</tt>).
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.
In this case, the reason for disconnection is <tt>CONNECTION_LOST</tt>. <br />
This function is thread-safe.

@return Returns the result of the function. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess  Indicates that the network was destroyed and the node transitioned to the <tt>STATE_DISCONNECTED</tt> state.
@retval ResultNotInitialized  Indicates that the library is not initialized. Call the <tt>@ref Initialize</tt> function.
@retval ResultInvalidState  Indicates that the function cannot be executed in this state. Returned when executed in a state other than host.
*/
nn::Result DestroyNetwork ( void );

#ifdef NN_UDS_SUPPORT_CLIENT
/*!
@brief Disconnects the local node from the network.

Only clients and spectators can call this function.
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).

This function is thread-safe.

@return Returns the result of the function. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess  Indicates that the network was destroyed and the node transitioned to the <tt>STATE_DISCONNECTED</tt> state.
@retval ResultNotInitialized  Indicates that the library is not initialized. Call the <tt>@ref Initialize</tt> function.
@retval ResultInvalidState  Indicates that the function cannot be executed in this state. Returned when executed in a state other than host.
@retval ResultWirelessOff  Indicates that the device entered wireless off mode. Reinitialization is required.
@retval Other  Indicates failure for other reasons.
*/
nn::Result DisconnectNetwork  ( void );
#endif

/*!
  @}
*/
/*!
@name  Functions for Sending and Receiving Data
  @{
*/

/*!
@brief Creates a network endpoint and returns the corresponding descriptor.

<b>[Provisional spec]</b> Currently, up to 16 endpoints can be created. <br />
This function is thread-safe.

@param[out]  pEndpointDesc  Descriptor indicating the endpoint to create.

@return Returns the result of the function. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess  Indicates that the operation succeeded.
@retval ResultNotInitialized  Indicates that the library is not initialized. Call the <tt>@ref Initialize</tt> function.
@retval  ResultOutOfResource  More than the stipulated number of endpoints were already generated. Destroy an existing endpoint.
*/
nn::Result CreateEndpoint( EndpointDescriptor* pEndpointDesc );

/*!
@brief Specifies the maximum send delay time.

For the system to improve the efficiency of its physical layer, smaller packets are sent bundled together.
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.
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.
This can be executed only when not connected to the network. <br />
This function is thread-safe.

@param[in] maxDelay  Specifies the maximum latency. Specify a value in the range from 5 to 100 milliseconds. The default is 10 milliseconds.

@return Returns the result of the function. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess  Indicates that the operation succeeded.
@retval ResultNotInitialized  Indicates that the library is not initialized. Call the <tt>@ref Initialize</tt> function.
@retval ResultInvalidState  Indicates that the function cannot be executed in this state. Returned when executed while communicating.
*/
nn::Result SetMaxSendDelay ( nn::fnd::TimeSpan maxDelay );

/*!
@brief Sends data to the specified port on the specified partner's system.

This function blocks until it has finished sending data.
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>.
To specify multiple options, you can OR multiple values. <br />
This function is thread-safe.

@param[in] endpointDesc  Specifies a <tt>descriptor</tt> indicating the <tt>endpoint</tt> to use.
@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.
@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.
@param[in] destNodeId  Specifies the recipient. Specify <tt>@ref BROADCAST_NODE_ID</tt> to broadcast the data.
@param[in] port  Specifies the port to assign. Port <tt>0x00</tt> is reserved by the system and cannot be used.
@param[in] option  Specifies the send options.

@return Returns the result of the function. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess  Indicates that the operation succeeded.
@retval ResultNotInitialized  Indicates that the library is not initialized. Call the <tt>@ref Initialize</tt> function.
@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.
@retval ResultTooLarge  Indicates that <span class="argument">dataSize</span> is greater than <tt>@ref UDS_PACKET_PAYLOAD_MAX_SIZE</tt>.
@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.
@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.
@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.
You might succeed by retrying, but if this errors occurs frequently, try specifying a larger buffer size with the <tt>@ref Initialize</tt> function.
*/
nn::Result SendTo ( const EndpointDescriptor& endpointDesc, const void* data, size_t dataSize, u16 destNodeId, u8 port, bit8 option = 0x00 );

/*!
@brief Enables the local device to receive packets from the endpoint.

Assigns the specified port and node ID to the endpoint.
The system creates a receive buffer and prepares to receive packets at the port specified below. <br />
This function is thread-safe.

@param[in] pEndpointDesc  Specifies a descriptor indicating the endpoint to use.
@param[in] srcNodeId  Specifies the node ID being assigned. Specify <tt>@ref BROADCAST_NODE_ID</tt> to attach all nodes.
@param[in] port  Specifies the port being assigned. Port <tt>0x00</tt> is reserved by the system and cannot be used.
@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.
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.
Communication is most efficient when the specified data size is a multiple of 64.

@return Returns the result of the function. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess  Indicates that the operation succeeded.
@retval ResultNotInitialized  Indicates that the library is not initialized. Call the <tt>@ref Initialize</tt> function.
@retval  ResultOutOfResource  The buffer specified with the <tt>@ref Initialize</tt> function was insufficient.
@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.

*/
nn::Result Attach ( EndpointDescriptor* pEndpointDesc, u16 srcNodeId, u8 port, size_t receiveBufferSize = ATTACH_BUFFER_SIZE_DEFAULT );

/*!
@brief Receives data. (No functionality is provided for getting the address of the sender.)

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 />
This function is thread-safe.

@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.
@param[out] pBuffer  Specifies the location to store received data. It is efficient to specify a buffer that is 64-byte aligned.
@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.
@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.
@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.
If not specified, the function does not return until either it receives data or an error occurs.

@return Returns the result of the function. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess  Indicates that the operation succeeded.
@retval ResultNotInitialized  Indicates that the specified <tt>endpoint</tt> did not exist when the library was not initialized.
@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.
@retval ResultNotAuthorized  Indicates that an <tt>endpoint</tt> that was not attached was specified.
@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>.
@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.
@retval  ResultMisalignedSize  Invalid <span class="argument">bufferSize</span>. The function may succeed if you execute it again with a suitable value for the argument.
@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.
@retval  ResultBusy    Packet reception with the specified endpoint is in progress. Call after the previous reception process finishes.
You might succeed by retrying, but if this errors occurs frequently, try specifying a larger buffer size with the <tt>@ref Initialize</tt> function.
*/
nn::Result Receive     ( const EndpointDescriptor& endpointDesc, void* pBuffer, size_t* pReceivedSize, size_t bufferSize, bit8 option = 0x00 );

/*!
@brief Receives data.

Receives packets sent to an endpoint for which the <tt>@ref Attach</tt> function was executed.
This function blocks when there are no packets to receive. (Unless an error occurs.)
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 />
This function is thread-safe.

@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.
@param[out] pBuffer  Specifies the location to store received data. It is efficient to specify a buffer that is 64-byte aligned.
@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.
@param[out] pSrcNodeId  The ID of the sending node.
@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.
@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.
If not specified, the function does not return until either it receives data or an error occurs.

@return Returns the result of the function. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess  Indicates that the operation succeeded.
@retval ResultNotInitialized  Indicates that the specified <tt>endpoint</tt> did not exist when the library was not initialized.
@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.
@retval ResultNotAuthorized  Indicates that an <tt>endpoint</tt> that was not attached was specified.
@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>.
@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.
@retval  ResultMisalignedSize  Invalid <span class="argument">bufferSize</span>. The function may succeed if you execute it again with a suitable value for the argument.
@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.
@retval  ResultBusy    Packet reception with the specified endpoint is in progress. Call after the previous reception process finishes.
You might succeed by retrying, but if this errors occurs frequently, try specifying a larger buffer size with the <tt>@ref Initialize</tt> function.
*/
nn::Result ReceiveFrom ( const EndpointDescriptor& endpointDesc, void* pBuffer, size_t* pReceivedSize, u16* pSrcNodeId, size_t bufferSize, bit8 option = 0x00 );

/*!
@brief  Destroys an endpoint.

Frees the receive buffer if the <tt>@ref Attach</tt> function has been called with the specified endpoint.
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 />
This function is thread-safe.

@param[in]  pEndpointDesc  Descriptor indicating the endpoint.

@return Returns the result of the function. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess  Indicates that the operation succeeded.
@retval ResultNotInitialized  Indicates that the library is not initialized. Call the <tt>@ref Initialize</tt> function.
@retval  ResultNotAuthorized  Indicates that an invalid endpoint descriptor was specified.
*/
nn::Result DestroyEndpoint( EndpointDescriptor* pEndpointDesc );

/*!
  @}
*/

/*!
@name  Functions for detecting state changes and getting information
  @{
*/

/*!
@brief Gets the current connection status.

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 />
This function is thread-safe.

@param[out]  pStatus  The current connection status.

@return Returns the result of the function. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess  Indicates that the operation succeeded.
@retval ResultNotInitialized  Indicates that the library is not initialized. Call the <tt>@ref Initialize</tt> function.
*/
nn::Result GetConnectionStatus( ConnectionStatus* pStatus );

/*!
@brief Gets the current channel.

This function is thread-safe.

@param[out]  pChannel  Returns the channel.

@return Returns the result of the function. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess  Indicates that the operation succeeded.
@retval ResultNotInitialized  Indicates that the library is not initialized. Execute the <tt>nn::uds::Initialize</tt> function.
*/
nn::Result GetChannel(u8* pChannel);

/*!
@brief Gets information about the specified node.

This function is thread-safe.

@param[out]  pNodeInfo Information about the node.
@param[in]  nodeId  The ID of the target node.

@return Returns the result of the function. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess  Indicates that the operation succeeded.
@retval ResultNotInitialized  Indicates that the library is not initialized. Call the <tt>@ref Initialize</tt> function.
@retval  ResultInvalidNode  The target node does not exist on the network. You might be disconnected.
*/
nn::Result GetNodeInformation ( NodeInformation* pNodeInfo, u16 nodeId );

/*!
@brief Queries whether a host has changed status or a client has connected or disconnected.

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 />
This function is thread-safe.

When <tt>NO_WAIT</tt> is specified, returns the result without blocking.

@return Returns the result of the function. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess  The state has changed. For more information about the state, see the <tt>@ref GetConnectionStatus</tt> function.
@retval ResultNotInitialized  Indicates that the library is not initialized. Call the <tt>@ref Initialize</tt> function.
@retval ResultNotFound  The state has not changed. Returned only when <tt>NO_WAIT</tt> is specified in the <span class="argument">option</span> parameter.
@retval  ResultBusy   Called by another thread. Call after the previous call completes.
*/
nn::Result PollStateChange(u8 option);

/*!
  @}
*/

/*!
@name  Accessors for Beacon Application Data
  @{
*/

/*!
@brief Sets application data in the beacon.

Specifies up to <tt>@ref NET_DESC_APPDATA_SIZE_MAX</tt> bytes of application data.
The data is not encrypted. It can be collected by any general-purpose computing device, such as a desktop computer.
Other devices can get this data by calling <tt>Scan</tt> while they are connected as a <tt>Client</tt> or <tt>Spectator</tt>.
Only the host can run this function. <br />
This function is thread-safe.

@param[in]  pData  Pointer to data being set.
@param[in]  dataSize Size of the data to set. Specify a value no greater than <tt>@ref NET_DESC_APPDATA_SIZE_MAX</tt>.

@return Returns the result of the function. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess  Indicates that the operation succeeded.
@retval ResultNotInitialized  Indicates that the library is not initialized. Call the <tt>@ref Initialize</tt> function.
@retval ResultInvalidState  Indicates that the function cannot be executed in this state. Returned when the function is executed in a state other than host.
@retval ResultTooLarge  Indicates that <span class="argument">dataSize</span> is greater than <tt>@ref NET_DESC_APPDATA_SIZE_MAX</tt>.
@retval ResultOutOfResource  Indicates that the system is out of resources. Try again.
@retval ResultBusy  Indicates that the system is busy. Try again.
*/
nn::Result SetApplicationDataToBeacon   ( const void* pData, size_t dataSize );

/*!
@brief Gets the data set in the beacon.

The host gets the data set using the <tt>@ref SetApplicationDataToBeacon</tt> function.
This function can only be run when connected to the network.
There is no notification if the data is updated. <br />
This function is thread-safe.

@param[out] pBuffer  Specifies the location storing the data.
@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.
@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.

@return Returns the result of the function. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess  Indicates that the operation succeeded.
@retval ResultNotInitialized  Indicates that the library is not initialized. Call the <tt>@ref Initialize</tt> function.
@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.
*/
nn::Result GetApplicationDataFromBeacon ( void* pBuffer, size_t* pDataSize, size_t bufferSize );

/*!
  @}
*/

/*!
  @}
*/

#ifdef NN_UDS_SUPPORT_POWER_SAVE
/*!
:private
@brief Changes the power-saving mode. (This has not yet been implemented.)

This setting can only be changed for a host. Clients and spectators follow the host's settings.
This function is not yet implemented. It always fails if run.
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 />
<br />
This function is thread-safe.

@param[in]  mode The power-saving mode. Enabling a power-saving mode may cause a slight decline in connectivity.

@return Returns the result of the function. Returns one of the following <tt>Result</tt> values.
@retval  ResultNotImplemented  Not yet implemented.

*/
nn::Result SetPowerSaveMode(PowerSaveMode mode);
#endif
namespace detail{
#if 0
/*!
:private
@brief Gets the detailed signal intensity.

Do not use this function on retail consoles as it is only provided for use on development hardware to aid development.
Communication is negatively affected if this function is called too frequently. Execute it about once per second.

This function is thread-safe.

@param[out] info  The signal intensity. Stores data if the function succeeds.

@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>.
*/
nn::Result GetRadioStrengthInfo(RadioStrengthInfo* info);
#endif
/*!
:private
@brief Destroys an endpoint.

The receive buffer created when <tt>Attach</tt> was called is freed at this time.
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 />
This function is thread-safe.

@param[in]  pEndpoint  Descriptor indicating the endpoint.
@param[out]  pReport   Information about packets that arrived at the destroyed endpoint.

@return Returns the result of the function. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess  Indicates that the operation succeeded.
@retval ResultNotInitialized  Indicates that the library is not initialized. Call the <tt>@ref Initialize</tt> function.
@retval  ResultNotAuthorized  Indicates that an invalid endpoint descriptor was specified.
*/
nn::Result DestroyEndpoint( EndpointDescriptor* pEndpointDesc, ReceiveReport* pReport );

} // end of namespace detail

} // end of namespace Cafe
} // end of namespace uds
} // end of namespace nn



#endif  // ifndef INCLUDE_NN_UDS_CAFE_UDS_API_H_