/*======================================================
FILE:  AEE_OEMEvent.h

SERVICES:  AEE Event Interface header

GENERAL DESCRIPTION:

This file contains all of the function prototypes for
event routines that are required by the OEM.

PUBLIC CLASSES:

None.

INITIALIZATION AND SEQUENCING REQUIREMENTS
None.

        Copyright © 2003 QUALCOMM Incorporated.
               All Rights Reserved.
            QUALCOMM Proprietary/GTDR
=====================================================*/
#if !defined(AEE_OEM_EVENT_H)
#define AEE_OEM_EVENT_H  1

#include "AEE_OEMComdef.h"
#include "AEE.h"

#if defined(__cplusplus)
extern "C" {
#endif

#define AEE_KeyPress(k)    AEE_Event(EVT_KEY_PRESS,(uint16)k,0)
#define AEE_KeyRelease(k)  AEE_Event(EVT_KEY_RELEASE,(uint16)k,0)
#define AEE_Key(k)         AEE_Event(EVT_KEY,(uint16)k,0)
#define AEE_KeyRepeat(k)   AEE_Event(EVT_KEY,(uint16)k,KB_AUTOREPEAT)

// This routine and these macros are provided to simplify the use of the BREW AEE by the
// OEM.  These calls are equivalent to calling ISHELL_SendEvent() but are provided to
// reduce complexity.

extern AEECLSID            AEE_Active(void);
extern void                AEE_Suspend(void);
extern boolean             AEE_Resume(void);
extern boolean             AEE_Event(AEEEvent evt, uint16 wParam, uint32 dwParam);

extern int                 AEE_StartApplet(AEECLSID cls, uint16 wFlags);
extern int                 AEE_CloseApplet(boolean bCloseAll);

extern void                AEE_SetEventHandler(void * pData, AEEHANDLER pfn);
extern boolean             AEE_AppCtxtSendEvent(PACONTEXT pac, AEEEvent evt, uint16 wp, uint32 dwp);

extern int                 AEE_Notify(AEECLSID clsType,uint32 dwm, void * pData);

#if defined(__cplusplus)
}
#endif

/*=======================================================================
  INTERFACE DOCUMENTATION
=======================================================================
AEE_OEMEvent Interface
=========================================================================

Function:  AEE_KeyPress()

Description:
   This function sends a keypress event to the AEE.

Prototype:

   boolean AEE_KeyPress(AVKType key)

Parameters:
   Key:  BREW keycode (AEEVCodes.h)

Return Value:
   TRUE: Keypress is handled.
   FALSE: Keypress is ignored.

Comments:
   Most BREW applications ignore this event.  It is provided for
games and other complicated applications.

Side Effects:
   None

See Also:
   AEE_KeyRelease()
   AEE_Key()
   AEE_KeyRepeat()

=======================================================================
Function:  AEE_KeyRelease()

Description:
   This function sends a key release event to the AEE.

Prototype:

   boolean AEE_KeyRelease(AVKType key)

Parameters:
   Key:  BREW keycode (AEEVCodes.h)

Return Value:
   TRUE: Event is handled
   FALSE: Event is ignored

Comments:
   Most BREW applications ignore this event.  It is provided for
games and other complicated applications.

Side Effects:
   None

See Also:
   AEE_KeyPress()
   AEE_Key()
   AEE_KeyRepeat()

=======================================================================
Function:  AEE_Key()

Description:
   This function sends a key event to the AEE. It is important, as most
   BREW applications ONLY process EVT_KEY events generated by this call.

Prototype:

   boolean AEE_Key(AVKType key)

Parameters:
   Key:  The BREW keycode (AEEVCodes.h)

Return Value:
   TRUE:    The event is handled.
   FALSE:   The event is ignored.

Comments:
   None

Side Effects:
   None

See Also:
   AEE_KeyPress()
   AEE_KeyRelease()
   AEE_KeyRepeat()

=======================================================================
Function:  AEE_KeyRepeat()

Description:
   This function sends a key event to the AEE and indicates that this is a repeat
   event for a key that has been held.  It is up to the OEM layer to determine when a key is 
   held.
   This sends an EVT_KEY event with wParam set to the keycode and dwParam set to
   the bit KB_AUTOREPEAT so that the recepient of the event knows that this is a repeat
   EVT_KEY event.

Prototype:

   boolean AEE_KeyRepeat(AVKType key)

Parameters:
   Key:  BREW keycode (AEEVCodes.h)

Return Value:
   TRUE:    Event is handled
   FALSE:   Event is ignored

Comments:
   None

Side Effects:
   None

See Also:
   AEE_KeyPress()
   AEE_KeyRelease()
   AEE_Key()

=======================================================================
Function:  AEE_Active()

Description:
   This function can be called by the OEM layer to determine the ClassID of
the active applet or control in the AEE.  It returns 0 (zero) if there is
no active applet.  The function is provided primarily for key handling so
that the OEM layer can determine whether keypad events must be passed to
the AEE or handled by the existing User Interface (UI).

Prototype:

   AEECLSID AEE_Active(void);

Parameters:
   None

Return Value:
   AEECLSID of the active applet or control.
   0 (zero) if there is no active applet

Comments:
   None

Side Effects:
   None

See Also:
   None

=======================================================================
Function:  AEE_Suspend()

Description:
   This function allows the OEM layer to suspend the active BREW application. It
is equivalent to calling ISHELL_SendEvent(EVT_APP_SUSPEND).  The application
can be restarted by calling AEE_Resume().

This function simplifies the suspension of any AEE activity
during times when the User Interface (UI) is active.

Prototype:

   void AEE_Suspend(void)

Parameters:
   None

Return Value:
   None

Comments:
   None

Side Effects:
   None

See Also:
   AEE_Resume()

=======================================================================
Function:  AEE_Resume()

Description:
   This function allows the OEM layer to restart the BREW application that
   was suspended using AEE_Suspend().  This is equivalent to calling 
   ISHELL_SendEvent(EVT_APP_RESUME), which restarts the suspended application.
   This function simplifies the reactivation of any BREW application
   that was suspended by the User Interface (UI).

Prototype:

   boolean AEE_Resume(void)

Parameters:
   None

Return Value:
   TRUE: The event is successfully processed.
   FALSE: The event is not processed.

Comments:
   None

Side Effects:
   None

See Also:
   AEE_Suspend(), AEE_ResumeCallback()

=======================================================================
Function:  AEE_Event()

Description:
   This function sends an event to the active BREW application.  It is 
   equivalent to calling ISHELL_SendEvent() and reduces the complexity of the OEM layers.

Prototype:

   boolean AEE_Event(AEEEvent evt, uint16 wParam, uint32 dwParam)

Parameters:
   evt:  AEE Event Code
   wParam:   extra parameter (16-bits)
   dwParam:  extra parameter (32-bits)

Return Value:
   TRUE:  The event is handled.
   FALSE: The event is ignored.

Comments:
   None

Side Effects:
   None

See Also:
   AEE_KeyPress()
   AEE_KeyRelease()
   AEE_Key()
   AEE_KeyRepeat()

=======================================================================
Function:   AEE_StartApplet()
   
Description:
   This function instructs BREW to start the applet associated with the
   specified 32-bit ClassID. If the requested class is supported and can be started,
   the BREW loads and starts the applet. This call returns immediately to the
   caller before starting the applet.

   The applet is started asynchronously, so if the applet classID being specified
   is not found, the function returns SUCCESS but the applet is not started. 

   Please note the following:

   - AEE_StartApplet is an asynchronous function.  The new applet
   will not be started until control is released to the system.

   - AEE_StartApplet will cause the current applet to receive an EVT_APP_SUSPEND
   event immediately before the new application is started.

Prototype:
    int AEE_StartApplet(AEECLSID cls, uint16 wFlags);

Parameters:
    cls  :  32-bit applet ClassID.
    wFlags: Flag to indicate condition for starting the applet. Possible values are:
~
            SSA_NORMAL            Normal applet~
            SSA_NO_VOICE_CALL     Do not start if a voice call is in progress.~
            SSA_AFTER_VOICE_CALL  Start the app after a voice call if there is one in progress.~
            SSA_CONFIG            Configuration screen (if applicable)~
            SSA_HIDDEN_CONFIG     Hidden configuration (if applicable)~
            SSA_UNIQUE            Force a new/unique instance of the app~
            SSA_SSAVER            App started in screen saver mode~
*  
Return Value:
   SUCCESS - Applet created and started
   EALREADY - Another applet is already starting.
   EBADCLASS - The shell class supplied is invalid.
   ENOMEMORY - Insufficient memory
   ECLASSNOTSUPPORT - The class specified is not supported.
   EEXPIRED - The applet has expired.
   EFILENOEXISTS - The applet has been disabled.
   EUNABLETOLOAD - The OEM layer refused to load the applet.
   EBADSID - Applet downloaded from a different SIM card


Comments:
    None

See Also:
    None.
    
=======================================================================

Function: AEE_CloseApplet()

Description:
   This method instructs the shell to close the active applet.
The applet will be sent the EVT_APP_STOP message.  Its release method
will then be called.

The bCloseAll parameter indicates whether the AEE should close
all other active applications and return the idle screen.  This parameter
is not supported on the SDK.

Prototype:

   int AEE_CloseApplet(boolean bCloseAll)

Parameters:
   bCloseAll: This parameter indicates whether the AEE should close
all other active applications and return to the idle screen.  This parameter
is not supported on the SDK.


Return Value:

   SUCCESS - The operation was successful.
   EBADCLASS - Invalid shell class object
   EFAILED - The operation failed.

Comments:
   None

Side Effects:
   None

See Also:
   None

=======================================================================

Function:  AEE_SetEventHandler()

Description:
   This function allows an OEM layer to create and use AEE controls
from outside AEE applets.  The callback is called whenever the control
or AEE issues an event.

Prototype:

   void AEE_SetEventHandler(void * pData, AEEHANDLER pfn);

Parameters:

   pData:  private data that is passed as the first parameter to the callback
   pfn:  private callback function that will be called by the AEE

Return Value:
   None

Comments:
   None

Side Effects:
   None

See Also:
   None

=======================================================================

Function:  AEE_Notify()

Description:
   This function sends an Notify events to the BREW applications registered. It is 
   equivalent to calling ISHELL_Notify() and reduces the complexity of the OEM layers.

Prototype:

   int AEE_Notify(AEECLSID clsType,uint32 dwm, void * pData);

Parameters:

   clsType: class that issued the notification
   dwm:     mask of events.  Normally only 1 bit will be set for any given event.
   pData:   context-sensitive data

Return Value:
   EBADCLASS - invalid class ID
   EBADPARM - invalid parameter
   ENOMEMORY - insufficient memory
   EREENTERED - attempt to reenter ISHELL_Notify() or AEE_Notify()
   EBADTASK - invalid task issuing notify
   AEE_SUCCESS - if successful

Comments:
   AEE_Notify() should be invoked from the same task context as the main thread of BREW.
   Otherwise it would fail with EBADTASK.

Side Effects:
   None

See Also:
   None

=======================================================================*/

#endif // !defined(AEE_OEM_EVENT_H)

