/*---------------------------------------------------------------------------*
  Project:  Horizon
  File:     uds.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: 46526 $
 *---------------------------------------------------------------------------*/

/*!
    @file
    @brief    Local Communication (UDS) API function declarations.

    :include nn/uds.h
*/

#ifndef NN_UDS_H_
#define NN_UDS_H_

/*!
    @defgroup  nn_uds  Local Communication (UDS) Library
    @brief     A library for local communication (wireless communication with the CTR).

@section nn_uds_overview Overview

The CAFE UDS library supports only master mode, and sends the CTR UDS client to the partner. <br />
In addition to this API reference, see the <i>CTR Programming Manual: Wireless Communication</i> provided for the CTR. <br />
The CAFE UDS library is the same as the CTR UDS library except for the following points.

- Only host mode is supported. <br />
- Up to nine devices can be connected, including the host. <br />
- The method to detect a state update is different. CTR used an <tt>Event</tt> instance initialized with the <tt>nn::uds::Cafe::Initialize</tt> function, but CAFE uses the <tt>nn::uds::PollStateChange</tt> function. <br />
- The default user name is different. If no user name is specified to the <tt>nn::uds::Cafe::Initialize</tt> function, CTR uses the name specified in System Settings. Cafe uses the Mii character name associated with the account that is currently logged in, if no user name is specified. <br />
- The boundary of the buffer passed to the API is different. For buffers passed to API functions, such as <tt>nn::uds::Cafe::Initialize</tt>, ensure that they have 64-byte boundary alignment and a byte size that is a multiple of 64. <br />
- Link level is not supported. Accordingly, there is no <tt>nn::uds::GetLinkLevel</tt> to get the link level. <br />
- Unlike CTR, Cafe does not have an error state (<tt>nn::uds::STATE_ERROR</tt>) that occurs because the wireless button was turned off or to the sleep state when the system is closed.

@section nn_uds_notes_about_hbm Notes About the HOME Button menu

We recommend that you use the UDS communications library with threads running on Core 2. For more information, see the Nintendo documentation <i>Foreground and Background Processing for Games</i> (<tt>WiiU-FG_BG_Processing-en.pdf</tt>).

When using UDS on a core besides Core 2, specify the <tt>NO_WAIT</tt> option to <tt>nn::uds::ReceiveFrom</tt> and <tt>nn::uds::PollStateChange</tt>. <br />
If this library is used without the <tt>NO_WAIT</tt> option specified, API functions may not return until UDS communications are complete. <br />
If an application switches to background mode before an API function makes its return,  API calls made before returning to foreground mode are not guaranteed to succeed. <br />
For UDS, even if there is no API call, the network in the UDS layer continues to be maintained.

@section nn_uds_wifi_and_ethernet Wi-Fi and Ethernet

Both Wi-Fi and Ethernet are unavailable while the UDS library is being used (between successful calls to <tt>nn::uds::Cafe::Initialize</tt> and <tt>nn::uds::Cafe::Finalize</tt>).

    @{
*/

/*!
    @namespace  nn::uds
    @brief      Namespace for the Local Communication (UDS) Library.
    
    @}
*/
#if defined(NN_PLATFORM_CTR)
    /*!
        @ingroup nn_uds
        @namespace  nn::uds::CTR
        @brief      Namespace for the CTR Local Communication (CTR UDS) Library.
            (The namespace <tt>nn::uds::CTR</tt> can also be shortened to <tt>nn::uds</tt>.)
    */
    #ifdef  __cplusplus
        #include <nn/uds/CTR/uds_Api.h>
        #include <nn/uds/CTR/uds_Type.h>
        #include <nn/uds/CTR/uds_Result.h>
        #include <nn/uds/CTR/uds_InfoElement.h>
        #include <nn/uds/CTR/uds_ScanResultReader.h>
        #include <nn/uds/CTR/uds_NetworkDescription.h>

        namespace nn {
            namespace uds {
                using namespace nn::uds::CTR;
            }
        }

    #endif // __cplusplus
#elif defined(NN_PLATFORM_CAFE)
    /*!
        @ingroup nn_uds
        @namespace  nn::uds::Cafe
        @brief      Namespace for the Cafe Local Communication (Cafe UDS) Library.
            (The namespace <tt>nn::uds::Cafe</tt> can also be shortened to <tt>nn::uds</tt>.)
    */
    #ifdef  __cplusplus
        #include <nn/uds/CAFE/uds_Api.h>
        #include <nn/uds/CAFE/uds_Type.h>
        #include <nn/uds/CAFE/uds_Result.h>
        //#include <nn/uds/CAFE/uds_InfoElement.h>
        //#include <nn/uds/CAFE/uds_ScanResultReader.h>
        //#include <nn/uds/CAFE/uds_NetworkDescription.h>

        namespace nn {
            namespace uds {
                using namespace nn::uds::Cafe;
            }
        }

    #endif // __cplusplus
#else
    #error no platform selected
#endif

#endif /* NN_UDS_H_ */