/*---------------------------------------------------------------------------*
  Project:	Café KBD RPL
  File: 	kbd.h

  Copyright (C) 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.
 *---------------------------------------------------------------------------*/

 
#ifndef __KBD_H__
#define __KBD_H__

#include <types.h>
#include <cafe/kbd/kbd_key_defs.h>
#include <cafe/kbd/kbd_hid_codes.h>
#include <cafe/os.h>

#ifdef __cplusplus
extern "C" {
#endif


//////////////////////////////////////////////////////////////////////////////
// this symbol only exists for compatibility with old KBD API
#define KBD_MEM_SIZE	        3264

//////////////////////////////////////////////////////////////////////////////

// Up to 4 keyboards can be attached
#define KBD_MAX_CHANNELS	   (4)	    // valid channel numbers are 0-3

typedef enum _KBDEc     // function return code
{				 
    KBD_SUCCESS				    = 0,
    KBD_ERR_OTHER 			    = 1,	// usually from HID error
    KBD_ERR_NOT_INITIALIZED	    = 2,
    KBD_ERR_ALREADY_INITIALIZED = 3,
    KBD_ERR_BAD_VALUE 		    = 4,	// input argument out of range
    KBD_ERR_BAD_STATUS		    = 5,	// that is, keyboard disconnected
//	KBD_ERR_BAD_POINTER 		= 6,
    KBD_ERR_BUSY				= 7     // for KBDSetLeds
} KBDEc;

typedef enum _KBDChanStatus // status bits may be OR-ed together 
{ 
    KBD_CS_OK 		            = 0x00,
    KBD_CS_DISCONNECTED         = 0x01,
    KBD_CS_ROLL_OVER	        = 0x02,
    KBD_CS_ERROR		        = 0x04
} KBDChanStatus;

typedef u8 KBDChannel;
typedef u8 KBDHIDCode;

#define KBD_HID_NONE	        0       // value returned when queue is empty
#define KBD_HID_OVERFLOW        255     // value returned when queue overflows

typedef enum _KBDKeyMode
{
    KBD_KM_DOWN	                = 0x01, // 1 = key down, 0 = key up
    KBD_KM_REPEAT               = 0x02, // 1 = repeat key, 0 = initial key press
    KBD_KM_NULL	                = 0x00
} KBDKeyMode;

#define KBD_KEY_MODE_UP(_key_mode)	   (!((_key_mode) & KBD_KM_DOWN))
#define KBD_KEY_MODE_DOWN(_key_mode)   ((_key_mode) & KBD_KM_DOWN)
#define KBD_KEY_MODE_REPEAT(_key_mode) ((_key_mode) & KBD_KM_REPEAT)

// xxx Some of these countries may disappear from this list.
//	   Others may be added.  Names may be changed.

typedef enum _KBDCountryCode 
{
    KBD_CC_INTERNATIONAL,
    KBD_CC_CANADIAN_BI,
    KBD_CC_CANADIAN_FR,
    KBD_CC_DANISH,
    KBD_CC_FINNISH,
    KBD_CC_FRENCH,
    KBD_CC_GERMAN,
    KBD_CC_GREEK,
    KBD_CC_ITALIAN,
    KBD_CC_JAPANESE,
    KBD_CC_LATIN_AMERICAN,
    KBD_CC_NETHERLANDS_DUTCH,
    KBD_CC_NORWEGIAN,
    KBD_CC_PORTUGUESE,
    KBD_CC_SPANISH,
    KBD_CC_SWEDISH,
    KBD_CC_UNITED_KINGDOM,
    KBD_CC_UNITED_STATES,
    KBD_CC_RUSSIA,
    KBD_CC_RESERVED
} KBDCountryCode;

#define KBD_NUM_COUNTRY_CODES  KBD_CC_RESERVED

typedef enum _KBDModState   // state bits may be OR-ed together
{   
    KBD_MS_CTRL		            = 0x0001,
    KBD_MS_SHIFT		        = 0x0002,
    KBD_MS_ALT		            = 0x0004,
    KBD_MS_GUI		            = 0x0008,
    KBD_MS_EXTRA		        = 0x0010,
    KBD_MS_ALTGR		        = 0x0020,
    KBD_MS_LANG1		        = 0x0040,   // (Hiragana)
    KBD_MS_LANG2		        = 0x0080,   // (Katakana)
    KBD_MS_NUM_LOCK	            = 0x0100,
    KBD_MS_CAPS_LOCK	        = 0x0200,
    KBD_MS_SCROLL_LOCK          = 0x0400,
    KBD_MS_SHIFTED_KEY          = 0x0800,   // when CTRL/ALT/GUI/EXTRA is on, allow shifted key to be returned
                                            // (the default is that the base/unshifted key is returned)
    KBD_MS_SET_ALL	            = 0x1000,   // With KBDSetModState, allows setting of all bits
    KBD_MS_NULL		            = 0x0000
} KBDModState;

// define alternate names for these
#define KBD_MS_HIRAGANA         KBD_MS_LANG1
#define KBD_MS_KATAKANA         KBD_MS_LANG2

// define convenient groups of state
#define KBD_MS_TRANSIENTS       (KBD_MS_CTRL|KBD_MS_SHIFT|KBD_MS_ALT|KBD_MS_GUI|KBD_MS_EXTRA|KBD_MS_ALTGR)
#define KBD_MS_TOGGLES          (KBD_MS_LANG1|KBD_MS_LANG2|KBD_MS_NUM_LOCK|KBD_MS_CAPS_LOCK|KBD_MS_SCROLL_LOCK)

typedef u16                     KBDUnicode; // should it be wchar_t? xxx

// Indicate if a KBDUnicode value is private to KBD (special KBD internal value)
#define KBD_UC_IS_PRIVATE(uc)   (((uc)>=0xf000 && (uc)<=0xF1FF) || ((uc)==0xFFFF))

// This macro may be used to determine if a KBDUnicode is a modifier key
#define KBD_UC_IS_MODIFIER(uc)  ((uc)>=0xf000 && (uc)<=0xf01f)

// These defines may be used to determine if a KBDUnicode
// value is a regular ASCII key from the keypad, and if so, to
// convert that value to the regular ASCII value
#define KBD_UC_IS_KP_REG_KEY(uc) (((uc)>=0xf100) && ((uc)<=0xf13f))
#define KBD_KP_REG_KEY_TO_ASCII(uc) ((uc)&0x3f)

// Indicate if a key is a keypad number (digit) key with NUM LOCK on
#define KBD_UC_IS_KP_NUM_NL_KEY(uc) (((uc)>=KBK_Keypad_0 && ((uc)<=KBK_Keypad_9)))
// Indicate if a key is a keypad number (digit) key with NUM LOCK off
#define KBD_UC_IS_KP_NUM_UL_KEY(uc) (((uc)>=KBK_Keypad_Insert && ((uc)<=KBK_Keypad_Page_Up)))
// Convert from NUM LOCK off digit key to NUM LOCK on digit key
#define KBD_KP_NUM_UL_KEY_TO_KP_NUM_NL_KEY(uc) ((KBDUnicode)((uc)-0x40))

// Indicate if a ModState represents NUM LOCK == on
#define KBD_MS_IS_NUMLOCK(ms) (((ms)&KBD_MS_NUM_LOCK) && !((ms)&KBD_MS_SHIFT))

// Indicate if a key is a private control Unicode, and convert to ASCII
#define KBD_UC_IS_CTRL_KEY(uc)	(((uc)>=0xf1c0) && ((uc)<=0xf1df))
#define KBD_CTRL_KEY_TO_ASCII(uc) ((uc)&0x1f)

typedef enum _KBDLedState
{
    KBD_LED_NUM_LOCK	        = 0x01,
    KBD_LED_CAPS_LOCK           = 0x02,
    KBD_LED_SCROLL_LOCK         = 0x04,
    KBD_LED_NULL		        = 0x00,
    KBD_LED_RESERVED	        = 0x10
} KBDLedState;

//-----------------------------------------------------------------------------
// Structs:

typedef struct _KBDDevEvent     // kbd attach/detach callbacks
{				 
    KBDChannel  channel;
} KBDDevEvent;

typedef struct _KBDKeyEvent     // for key callback/getkey
{			 
    KBDChannel  channel;
    KBDHIDCode  hid;		    // USB HID code
    KBDKeyMode  mode; 	        // for up/down/etc
    KBDModState modState;       // modifier state
    KBDUnicode  unicode;	    // unicode, if any
} KBDKeyEvent;

typedef struct _KBDLedEvent     // kbd LED callback
{				 
    KBDChannel  channel;
    KBDLedState leds;
    KBDEc 	    rc;
} KBDLedEvent;

typedef void (*KBDDevCallbackF) (KBDDevEvent*);
typedef void (*KBDKeyCallbackF) (KBDKeyEvent*);
typedef void (*KBDLedCallbackF) (KBDLedEvent*, void*);


typedef struct _KBDReport       // HID report
{
  u8	modifier;
  u8	reserved;
  u8	keycode[6];

} KBDReport;


//////////////////////////////////////////////////////////////////////////////
// Function calls
//////////////////////////////////////////////////////////////////////////////

// for source compatibility, apps using old KBD API
void  KBDInitRegionUS(void);
void  KBDInitRegionJP(void);
void  KBDInitRegionEU(void);

KBDEc KBDInit(                          // setup library
                void*,                  // KBD mem, no longer required
                KBDDevCallbackF,        // callback for when keyboard is attached
                KBDDevCallbackF,        // callback for when keyboard is detached
                KBDKeyCallbackF         // callback for when key is pressed
                );  

KBDEc KBDExit (void);                   // teardown library

KBDEc KBDSetLeds(                       // set LEDs on keyboard
        KBDChannel,                     // keyboard number
        KBDLedState                     // LED state to set
        );

KBDEc KBDSetLedsAsync(                  // set LED on keyboard, non-blocking with callback
        KBDChannel,                     // keyboard number
        KBDLedState,                    // LED state to set
        KBDLedCallbackF,                // completion callback function
        void*                           // caller supplied parameter to pass to callback function
        );

KBDEc KBDSetLedsRetry(                  // set LEDs on keyboard with automatic retry
        KBDChannel,                     // keyboard number
        KBDLedState                     // LED state to set
        );


// Setup & Teardown APIs
KBDEc KBDSetup(                         // setup library
                KBDDevCallbackF,        // callback for when keyboard is attached
                KBDDevCallbackF,        // callback for when keyboard is detached
                KBDKeyCallbackF         // callback for when key is pressed
                );  

KBDEc KBDTeardown (void);               // teardown library


// Runtime APIs
KBDEc KBDGetChannelStatus(              // get status for keyboard
        KBDChannel,                     // keyboard number
        KBDChanStatus*                  // pointer to storage for status
        );

KBDEc KBDResetChannel(                  // reset key press state for keyboard
        KBDChannel                      // keyboard number
        );					            

KBDEc KBDSetCountry(                    // set country code for keyboard
        KBDChannel,                     // keyboard number
        KBDCountryCode                  // country code to set
        );

KBDEc KBDGetCountry(                    // get country code for keyboard
        KBDChannel,                     // keyboard number
        KBDCountryCode*                 // pointer to storage for country code
        );  

KBDEc KBDGetKey(                        // get key event for keyboard
        KBDChannel,                     // keyboard number
        KBDKeyEvent*                    // pointer to storage for event
        );     

KBDEc KBDEmptyQueue(                    // empty queue
        KBDChannel                      // keyboard number
        );

KBDEc KBDSetLockProcessing(             // set lock modifier processing
        KBDChannel,                     // keyboard number
        BOOL                            // TRUE = On, FALSE = Off
        );

KBDEc KBDGetLockProcessing(             // get lock modifier processing
        KBDChannel,                     // keyboard number
        BOOL*                           // pointer to storage for On/Off
        );

KBDEc KBDSetModState(                   // set mod state to keyboard
        KBDChannel,                     // keyboard number
        KBDModState                     // mod state to set
        );

KBDEc KBDGetModState(                   // get mod state from keyboard
        KBDChannel,                     // keyboard number
        KBDModState*                    // pointer to storage for mod state
        );

KBDEc KBDSetRepeat(                     // set repeat rate for keyboard
        KBDChannel,                     // keyboard number
        u16,                            // delay to set
        u16                             // interval to set
        );

KBDEc KBDGetRepeat(                     // get repeat rate for keyboard
        KBDChannel,                     // keyboard number
        u16*,                           // pointer to storage for delay 
        u16*                            // pointer to storage for interval
        );

KBDEc KBDSetAccessSticky(               // set sticky state for modifier keys
        KBDChannel,                     // keyboard number
        BOOL                            // TRUE = On, FALSE = Off
        );

KBDEc KBDGetAccessSticky(               // get sticky state for modifier keys
        KBDChannel,                     // keyboard number
        BOOL*                           // pointer to storage for On/Off
        );

KBDEc KBDSetLedsEx(                     // set LEDs on keyboard
        KBDChannel,                     // keyboard number
        KBDLedState                     // LED state to set
        );

KBDEc KBDSetLedsAsyncEx(                // set LED on keyboard, non-blocking with callback
        KBDChannel,                     // keyboard number
        KBDLedState,                    // LED state to set
        KBDLedCallbackF,                // completion callback function
        void*                           // caller supplied parameter to pass to callback function
        );

KBDEc KBDSetLedsRetryEx(                // set LEDs on keyboard with automatic retry
        KBDChannel,                     // keyboard number
        KBDLedState                     // LED state to set
        );

KBDUnicode KBDTranslateHidCode(         // returns translated KBD Unicode
        KBDHIDCode,                     // HID code to translate
        KBDModState,                    // keyboard mod state
        KBDCountryCode                  // country code
        );

int OSUTF32to8(                         // convert UTF32 to UTF8
        u32*,                           // pointer to UTF32 to convert
        char*                           // pointer to storage for UTF8 output
        );

int OSUTF16to32(                        // convert UTF16 to UTF32
        u16*,                           // pointer to UTF16 to convert
        u32*                            // pointer to storage for UTF32 output
        );

//////////////////////////////////////////////////////////////////////////////
#ifdef __cplusplus
}
#endif

#endif // __KBD_H__