/*
  Project:  NitroSDK - wireless_shared - demos - wh
  File:     wh.h

  Copyright 2003,2004 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.

  $Log: wh.h,v $
  Revision 1.12  2004/11/16 03:01:11  takano_makoto
  Added the WH_GetCurrentAid function.

  Revision 1.11  2004/11/08 02:46:17  takano_makoto
  Prevented multiple calling of WM_EndScan

  Revision 1.10  2004/11/05 04:27:40  sasakis
  Added the lobby screen and parent selection screen, and made the necessary modifications (such as scan related).

  Revision 1.9  2004/11/02 19:36:19  takano_makoto
  Changed the return values of WH_StartMeasureChannel and WH_EndScan to BOOL

  Revision 1.8  2004/11/01 09:38:14  seiki_masashi
  Changed the WH_DS_DATA_SIZE from 14 to 12
  Revised comments

  Revision 1.7  2004/11/01 09:16:47  takano_makoto
  Changed the return value type of the WH functions, and added the WH_SYSSTATE_FATAL state

  Revision 1.6  2004/10/29 02:16:34  takano_makoto
  Changed the WH_StartScan argument

  Revision 1.4  2004/10/28 07:11:20  takano_makoto
  Changed the WH_Connect function name

  Revision 1.3  2004/10/27 02:31:31  takano_makoto
  Integrated the multiple MeasureChannel-related functions
  Fixed a bug that was deciding on WM_ERRCODE_SUCCESS in a section that should wait on WM_ERRCODE_OPERATING
  Fixed other bugs

  Revision 1.2  2004/10/25 02:29:54  seiki_masashi
  Applied the maximum send size of the parent device to WH_CHILD_MAX
  Integrated the maximum send size of the parent and child into WH_{PARENT,CHILD}_MAX_SIZE
  Revised comments

  Revision 1.1  2004/10/21 00:41:50  yosizaki
  Initial upload.

  $NoKeywords$
 */

/*
  Log : (from multiboot-model)
  Revision 1.6  2004/09/30 08:28:14  yosizaki
  add SDK_MAKEGGID_SYSTEM macro.

  Revision 1.5  2004/09/30 03:58:40  takano_makoto
  Added WH_SYSSTATE_CONNECT_FAIL.

  Revision 1.4  2004/09/27 08:34:38  takano_makoto
  Changed interface for WH_ChildConnect, WH_Initialize.

  Revision 1.3  2004/09/17 14:12:45  takano_makoto
  Added a routine that makes a connected child determination.

  Revision 1.2  2004/09/17 10:29:47  takano_makoto
  Defined WH_PARENT_MAX_SIZE, WH_CHILD_MAX_SIZE.

  Revision 1.1  2004/09/16 14:07:11  takano_makoto
  Initial Update
*/

/*
  Log : (from dataShare-model)
  Revision 1.15  2004/10/06 05:11:35  sasakis
  Addition of a flag display, etc.

  Revision 1.14  2004/10/05 09:21:57  seiki_masashi
  Made changes so that a callback is designated in WH_SendData
  Added an error check to the function that alters the character string of constants

  Revision 1.13  2004/10/01 01:58:54  seiki_masashi
  Restored the normal MP communication-related functions

  Revision 1.12  2004/09/30 08:46:48  seiki_masashi
  Configured the official values allocated to the GGID

  Revision 1.11  2004/09/30 06:26:49  seiki_masashi
  Temporarily deleted the normal MP communications-related functions

  Revision 1.10  2004/09/30 06:20:03  seiki_masashi
  Changed an indent

  Revision 1.9  2004/09/30 06:16:38  seiki_masashi
  Made changes to be compliant with the newest SDK specifications

  Revision 1.8  2004/09/24 09:43:35  sasakis
  Made several small bug fixes.

  Revision 1.7  2004/09/24 06:12:35  sasakis
  Added a manual channel selection feature.

  Revision 1.6  2004/09/22 09:39:33  sasakis
  Added a debug screen.

  Revision 1.5  2004/09/15 10:23:40  sasakis
  Added a radio reception strength icon, conversions to make the data size variable, etc.

  Revision 1.4  2004/09/10 08:44:52  sasakis
  Added a guideline compliance process, made error-related reconsiderations, etc.

  Revision 1.3  2004/09/08 08:55:35  sasakis
  Slightly strengthened the connection process.

  Revision 1.2  2004/09/08 01:52:52  sasakis
  Error / disconnection related improvements.

  Revision 1.1  2004/09/07 04:59:42  sasakis
  Registration of the initial version.
*/


#ifndef __WMHIGH_H__
#define __WMHIGH_H__

enum
{
    WH_SYSSTATE_STOP,           // Initial state
    WH_SYSSTATE_IDLE,           // Idling
    WH_SYSSTATE_SCANNING,       // Scanning
    WH_SYSSTATE_BUSY,           // Connection busy
    WH_SYSSTATE_CONNECTED,      // Completed connection (Communications are possible in this state)
    WH_SYSSTATE_DATASHARING,    // data-sharing is valid and connection has completed
    WH_SYSSTATE_KEYSHARING,     // key-sharing is valid and connection has completed
    WH_SYSSTATE_MEASURECHANNEL, // Check the radio usage rate of the channel
    WH_SYSSTATE_CONNECT_FAIL,   // Lost connection to the parent device
    WH_SYSSTATE_ERROR,          // An error has occurred
    WH_SYSSTATE_FATAL,          // A FATAL error has occurred
    WH_SYSSTATE_NUM
};

enum
{
    WH_CONNECTMODE_MP_PARENT,  // Parent device MP connection mode
    WH_CONNECTMODE_MP_CHILD,   // Child device MP connection mode
    WH_CONNECTMODE_KS_PARENT,  // Parent device key-sharing connection mode
    WH_CONNECTMODE_KS_CHILD,   // Child device key-sharing connection mode
    WH_CONNECTMODE_DS_PARENT,  // Parent device data-sharing connection mode
    WH_CONNECTMODE_DS_CHILD,   // Child device data-sharing connection mode
    WH_CONNECTMODE_NUM
};

enum {
    // Independent error codes
    WH_ERRCODE_DISCONNECTED      = WM_ERRCODE_MAX, // Disconnected from parent
    WH_ERRCODE_PARENT_NOT_FOUND,                   // No parent
    WH_ERRCODE_NO_RADIO,                           // Wireless cannot be used
    WH_ERRCODE_LOST_PARENT,                        // Parent lost
    WH_ERRCODE_NOMORE_CHANNEL,                     // Scan has finished on all channels
    WH_ERRCODE_MAX
};

typedef void (*WHStartScanCallbackFunc)( WMBssDesc* bssDesc );


/* The macro that defines the GGID reserved for the SDK sample demo */
#define SDK_MAKEGGID_SYSTEM(num)    (0x003FFF00 | (num))

#define WH_DMA_NO                 2
#define WH_DEFAULT_CHANNEL        1
#define WH_SCAN_TIME_MAX          30

// Maximum number of child devices (Number does not include parent device)
#define WH_CHILD_MAX              15

/* The bitmap value that indicates not connected, or a state where there is only the parent */
#define WH_BITMAP_EMPTY           1

// The maximum size of the sharable data
#define WH_DS_DATA_SIZE           12

// The maximum size of the data that can be sent in one communication.
// When performing normal communications in addition to data sharing, only increase
// the value here by that maximum data size. When doing so, additional header and footer
// sections must be added by sending multiple packets.
// For further details, see docs/TechnicalNotes/WirelessManager.doc.
// GUIDELINE : Guideline compliance points (6.3.2)
// It is recommended that the time required for one MP communication calculated with
// the reference wireless manager-->diagram/information-->wireless communications time calculation sheet be less than 5600 nanoseconds.
#define WH_PARENT_MAX_SIZE      (WH_DS_DATA_SIZE * (1 + WH_CHILD_MAX) + 4)
#define WH_CHILD_MAX_SIZE       (WH_DS_DATA_SIZE)

// The port used in data sharing
#define WH_DS_PORT                13

// The port used in normal MP communications
#define WH_DATA_PORT              14

// The priority used in normal MP communications
#define WH_DATA_PRIO              WM_PRIORITY_NORMAL

// The send callback type (for data-sharing model)
typedef void (*WHSendCallbackFunc)(BOOL result);

// The function type that decides to allow communications (for multiboot model)
typedef BOOL (*WHJudgeAcceptFunc)(WMStartParentCallback*);

// The reception callback type
typedef void (*WHReceiver)(u16 aid, u16* data, u16 size);



/**************************************************************************
 * The functions below alter each type of WH configuration values.
 **************************************************************************/

/*---------------------------------------------------------------------------*
  Name:         WH_SetGgid

  Description:  Configures the game group ID.
                Call before making a connection to the parent device.

  Arguments:    ggid    The game group ID to configure.

  Returns:      None.
 *---------------------------------------------------------------------------*/
extern void WH_SetGgid( u32 ggid );

/*---------------------------------------------------------------------------*
  Name:         WH_SetDebugOutput

  Description:  Configures the function for outputting the debug character string.

  Arguments:    func    The function to configure for outputting the debug character string.

  Returns:      None.
 *---------------------------------------------------------------------------*/
void WH_SetDebugOutput( void (*func)(const char *, ...) );


/**************************************************************************
 * The wrapper functions below get the lowest-layer WM library states.
 **************************************************************************/

/* ----------------------------------------------------------------------
  Name:        WH_GetLinkLevel
  Description: Gets the radio reception strength.
  Arguments:   none.
  Returns:     Returns the numeric value of WMLinkLevel.
  ---------------------------------------------------------------------- */
extern int WH_GetLinkLevel(void);

/* ----------------------------------------------------------------------
   Name:        WH_GetAllowedChannel
   Description: Gets the bit pattern of a channel that can be used for connection.
   Arguments:   none.
   Returns:     channel pattern
   ---------------------------------------------------------------------- */
extern u16 WH_GetAllowedChannel(void);


/**************************************************************************
 * The functions below get the WH state.
 **************************************************************************/

/* ----------------------------------------------------------------------
   Name:        WH_GetBitmap
   Description: Gets the bit pattern that indicates the connection state.
   Arguments:   none.
   Returns:     bitmap pattern
   ---------------------------------------------------------------------- */
extern u16 WH_GetBitmap(void);

/* ----------------------------------------------------------------------
   Name:        WH_GetSystemState
   Description: Gets the WH internal state.
   Arguments:   none.
   Returns:     The internal state (WH_SYSSTATE_XXXX).
   ---------------------------------------------------------------------- */
extern int WH_GetSystemState(void);

/* ----------------------------------------------------------------------
   Name:        WH_GetConnectMode
   Description: Gets the connection information.
   Arguments:   none.
   Returns:     The connection information (WH_CONNECTMODE_XX_XXXX).
   ---------------------------------------------------------------------- */
extern int WH_GetConnectMode(void);

/* ----------------------------------------------------------------------
   Name:        WH_GetLastError
   Description: Gets the error code that most recently occurred.
   Arguments:   none.
   Returns:     The error code.
   ---------------------------------------------------------------------- */
extern int WH_GetLastError(void);

/*---------------------------------------------------------------------------*
  Name:         WH_PrintBssDesc

  Description:  Debug outputs the members of the WMBssDesc structure.

  Arguments:    info    The pointer to the BssDesc to be debug outputted.

  Returns:      None.
 *---------------------------------------------------------------------------*/
extern void WH_PrintBssDesc( WMBssDesc* info );


/**************************************************************************
 * The functions below perform channel-related processes.
 **************************************************************************/

/*---------------------------------------------------------------------------*
  Name:         WH_StartMeasureChannel

  Description:  Starts measuring the radio usage rate on every usable channel.
                Once the measurement completes, the channel with the lowest usage rate is internally calculated
                and the state transitions to WH_SYSSTATE_MEASURECHANNEL.

  Arguments:    None.

  Returns:      None.
 *---------------------------------------------------------------------------*/
extern BOOL WH_StartMeasureChannel( void );

/*---------------------------------------------------------------------------*
  Name:         WH_GetMeasureChannel

  Description:  Returns the channel with the lowest usage rate from all the usable channels.
                The WH_MeasureChannel operations must be complete and it must be in
                the WH_SYSSTATE_MEASURECHANNEL state.
                When this function is called, it returns the channel with the lowest usage rate
                and transitions to the WH_SYSSTATE_IDLE state.

  Arguments:    None.

  Returns:      The channel number of the usable channel with the lowest usage rate
 *---------------------------------------------------------------------------*/
extern u16 WH_GetMeasureChannel( void );


/**************************************************************************
 * The functions below initialize wireless, and transition to a state where communications is possible.
 **************************************************************************/

/* ----------------------------------------------------------------------
   Name:        WH_Initialize
   Description: Performs initialization operations, and starts the initialization sequence.
   Arguments:   None.
   Returns:     TRUE if the sequence start was a success.
   ---------------------------------------------------------------------- */
extern BOOL WH_Initialize(void);


/*---------------------------------------------------------------------------*
  Name:         WH_StartScan

  Description:  The function that gets the parent device beacon.

  Arguments:    callback - Sets the callback returned when the parent device is found.

                macAddr  - Designate the MAC address of the parent device to connect to.
                           If 0xFFFFFF, search for all parent devices.

                channel  - Designate the channel that searches for the parent.
                           If 0, search for all channels.

  Returns:      None.
 *---------------------------------------------------------------------------*/
extern BOOL WH_StartScan( WHStartScanCallbackFunc callback, const u8* macAddr, u16 channel );

/*---------------------------------------------------------------------------*
  Name:         WH_EndScan

  Description:  The function that gets the parent device beacon.

  Arguments:    None.

  Returns:      None.
 *---------------------------------------------------------------------------*/
extern BOOL WH_EndScan( void );

/* ----------------------------------------------------------------------
  Name:        WH_ParentConnect
  Description: Starts the connection sequence.
  Arguments:   mode    - Start MP as the parent if WH_CONNECTMODE_MP_PARENT.
                          Start DataSharing as the parent if WH_CONNECTMODE_DS_PARENT.
                          Start KeySharing as the parent if WH_CONNECTMODE_KS_PARENT.
               tgid    - The parent device communications tgid
               channel - The parent device communications channel
  Returns:     TRUE if the connection sequence is successful
  ---------------------------------------------------------------------- */
extern BOOL WH_ParentConnect(int mode, u16 tgid, u16 channel);

/* ----------------------------------------------------------------------
  Name:        WH_ChildConnect
  Description: Starts the connection sequence.
  Arguments:   mode -    Start MP as the child if WH_CONNECTMODE_MP_CHILD.
                         Start DataSharing as the child if WH_CONNECTMODE_DS_CHILD.
                         Start KeySharing as the child if WH_CONNECTMODE_KS_CHILD.
               bssDesc - The bssDesc of the parent device to connect.

  Returns:     TRUE if the connection sequence is successful
  ---------------------------------------------------------------------- */
extern BOOL WH_ChildConnect( int mode, WMBssDesc *bssDesc );

/* ----------------------------------------------------------------------
   Name:        WH_ChildConnectAuto
   Description: Starts the child device connection sequence.
                However, each type of setting designated by WH_ParentConnect or WH_ChildConnect
                is left to the automatic internal processing.
   Arguments:   mode    - Start MP as the child if WH_CONNECTMODE_MP_CHILD.
                          Start DataSharing as the child if WH_CONNECTMODE_DS_CHILD.
                          Start KeySharing as the child if WH_CONNECTMODE_KS_CHILD.

                macAddr - Designate the MAC address of the parent device to connect to.
                          If 0xFFFFFF, search for all parent devices.

                channel - Designate the channel that searches for the parent.
                          If 0, search for all channels.

  Returns:     TRUE if the connection sequence is successful
   ---------------------------------------------------------------------- */
extern BOOL WH_ChildConnectAuto( int mode, const u8* macAddr, u16 channel );

/*---------------------------------------------------------------------------*
  Name:         WH_SetJudgeAcceptFunc

  Description:  Sets the functions used to determine whether to accept the child device connection.

  Arguments:    Set the child device connection determination functions.

  Returns:      None.
 *---------------------------------------------------------------------------*/
extern void WH_SetJudgeAcceptFunc( WHJudgeAcceptFunc func );


/**************************************************************************
 * The functions below are for direct MP communications that use the WH_DATA_PORT port.
 **************************************************************************/

/* ----------------------------------------------------------------------
   Name:        WH_SetReceiver
   Description: Configures the data reception callback in the WH_DATA_PORT port.
   Arguments:   proc - The data reception callback
   Returns:     none.
   ---------------------------------------------------------------------- */
extern void WH_SetReceiver(WHReceiver proc);

/* ----------------------------------------------------------------------
   Name:        WH_SendData
   Description: Starts sending data to the WH_DATA_PORT port.
               (For MP communications. There is no need to call this function while data sharing, etc.)
   Arguments:   size - The data size
   Returns:     Returns TRUE if starting the send is successful.
   ---------------------------------------------------------------------- */
extern BOOL WH_SendData(void *data, u16 datasize, WHSendCallbackFunc callback);


/**************************************************************************
 * The functions below control data sharing communications.
 **************************************************************************/

/* ----------------------------------------------------------------------
   Name:        WH_GetKeySet
   Description: Reads the shared key data.
   Arguments:   keyset - Designates the data storage destination
   Returns:     TRUE if successful.
   ---------------------------------------------------------------------- */
extern BOOL WH_GetKeySet(WMKeySet *keyset);

/* ----------------------------------------------------------------------
   Name:        WH_GetSharedDataAdr
  Description:  Calculates and gets the data address obtained from the machine with
                the designated aid from the shared data address.
   Arguments:   aid - The machine designation
   Returns:     NULL when failed.
   ---------------------------------------------------------------------- */
extern u16 *WH_GetSharedDataAdr(u16 aid);

/* ----------------------------------------------------------------------
   Name:        WH_StepDS
   Description: Advances the synchronization of the data sharing by 1.
                If communication is performed in each frame, this function must also
                be called in each frame.
   Arguments:   data - The data to send
   Returns:     TRUE if successful.
   ---------------------------------------------------------------------- */
extern BOOL WH_StepDS(void *data);


/**************************************************************************
 * The functions below end communications and transition to initialization states.
 **************************************************************************/

/* ----------------------------------------------------------------------
   Name:        WH_Reset
   Description: Starts the reset sequence.
                When this function is called, it resets regardless of the current state.
        		It is used for forced recovery from errors.
   Arguments:   none.
   Returns:     TRUE if the process successfully starts
   ---------------------------------------------------------------------- */
extern void WH_Reset(void);

/* ----------------------------------------------------------------------
   Name:        WH_Finalize
   Description: Starts the post-processing / end sequence.
                When this function is called, it looks at the current state, and executes
                an appropriate end sequence.
                This function is used in the normal end process (not WH_Reset).
   Arguments:   None.
   Returns:     None.
   ---------------------------------------------------------------------- */
extern void WH_Finalize(void);

/*---------------------------------------------------------------------------*
  Name:         WH_End

  Description:  Ends wireless communications.

  Arguments:    None.

  Returns:      None.
 *---------------------------------------------------------------------------*/
extern BOOL WH_End( void );

/*---------------------------------------------------------------------------*
  Name:         WH_GetCurrentAid

  Description:  Acquires its own current AID.
                Children may change when they connect or disconnect.

  Arguments:    None.

  Returns:      AID value
 *---------------------------------------------------------------------------*/
extern u16 WH_GetCurrentAid( void );

#endif
