/*======================================================
FILE:  OEMNotify.h

SERVICES:   OEM notify interface

GENERAL DESCRIPTION:

Notify related definitions for the OEM interface

PUBLIC CLASSES:

None.

INITIALIZATION AND SEQUENCING REQUIREMENTS
None.

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

#include "AEE.h"

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

// OEM Notifications - These notifications are made by BREW to the OEM layer.  They
// replace some of the former functions (OEM_AppCanStart, etc.)

typedef enum { OEMNTF_APP_START,             // Can app be started? (dwParam == AEECLSID) (formerly OEM_AppCanStart)
               OEMNTF_ACTIVATE,              // dwParam == OEMAppState *
               OEMNTF_IDLE,                  // dwParam == OEMAppState *
               OEMNTF_RESET,                 // BREW wants the OEM to reset the device
               OEMNTF_CLOSE_FILE,            // BREW wants the OEM to close a file (dwParam == file name)
               OEMNTF_SHOW_CALL_DIALOGS,     // BREW is displaying call status UI - (formerly OEM_SetSystemAlertMask)
               OEMNTF_GET_CONTEXT,           // dwParam == OEMAppState *
               OEMNTF_APP_EVENT,             // dwParam == OEMAppEvent *
               OEMNTF_EXT_STOP,              // dwParam == 0 terminated list of AEECLSIDs of extension
               OEMNTF_SYS_ERROR,             // dwParam == AEESysError *
               OEMNTF_CREATEINSTANCE,        // dwParam == OEMNotifyCreate *
               OEMNTF_MODLOAD,               // dwParam == OEMModLoad * 
               OEMNTF_MODUNLOAD,             // dwParam == OEMModLoad * 
               OEMNTF_NEXT_ALARM,            // dwParam == MilliSeconds before next alarm
               OEMNTF_RESET_BREW             // Request to reset BREW. 
             } OEMNotifyEvent;

extern int              OEM_Notify(OEMNotifyEvent evt, uint32 dw);

typedef struct _OEMAppState
{
   AEECLSID cls;        // Class starting or being closed.
   uint32   dwOEMCtx;   // See below.
} OEMAppState;

typedef struct _OEMAppEvent
{
   AEECLSID cls;
   AEEEvent evt;
   uint16   wp;
   uint32   dwp;
   boolean        bRet;
} OEMAppEvent;

typedef struct _OEMNotifyCreate
{
   AEECLSID cls;  // class ID
   void    *pif;  // pointer to interface
} OEMNotifyCreate;

typedef struct _OEMNotifyModLoad
{
   const char *cpszFile;  // name of module file, in fs:/ terms
   void       *pLocation; // where the code image landed (might be a const file)
} OEMNotifyModLoad;


//
// OEMNTF_ACTIVATE - This notification is called when BREW starts an applet from the
// OEM's state BUT the activation came from inside of BREW.  In this case, the OEMAppState *
// is passed as the dwParam to the OEM to allow them to fill the dwOEMCtx.  This value
// is passed back to the OEM on OEMNT_IDLE.
//
// OEMNTF_IDLE - This notification is sent to the OEM when BREW is closing an applet
// that is returning control to the OEM's native UI.  In this case, the OEMAppState->dwOEMCtx
// value contains the value passed to BREW via the OEMNTF_ACTIVATE or OEMNTF_GET_CONTEXT
// call when the app was started.
//
// OEMNTF_GET_CONTEXT - This call is made by BREW when the OEM starts a BREW app
// directly to retrieve the OEMAppStart->dwOEMCxt.  This notification is required
// because in these cases OEMNTF_ACTIVATE is not called.
//
//

#if defined(__cplusplus)
}
#endif

/*==================================================================
OEM DOCUMENTATION
=======================================================================

Function: OEM_Notify

Description:
   This function is called by BREW to notify the OEM regarding
critical system functions.  These include:

OEMNTF_APP_START - A query to determine if the specified app can
be started.  The class ID of the app is specified in the dwParam.

OEMNTF_ACTIVATE - Notification to the OEM that the BREW layer is
activating an application.  Note that subsequent application start
notifications while a previous BREW app is running will not be
preceeded by this notification.

OEMNTF_IDLE - Notification to the OEM that the BREW layer is closing
the last active application in the stack of currently active BREW
applications.  Note that this does NOT mean that all BREW apps are close.
Rather, it simply means that control is returning to the native UI.

OEMNTF_RESET - A request by BREW to reset the device.

OEMNTF_CLOSE_FILE - BREW is requesting that a file be closed.

OEMNTF_SHOW_CALL_DIALOGS - Indicates whether the OEM should show
call dialogs or not.  If dwParam is TRUE, then the OEM should show
these dialogs.  If FALSE, they should be inhibited.  This call is
usually made only by the network layer to inhibit/re-enable display
of call status dialogs during PPP sessions.

OEMNTF_APP_EVENT - Sent soon after sending any event in the
range 0 - EVT_APP_LAST_EVENT to the apps.  This allows the OEM to monitor events
sent to applications and the return values from the apps for each event.

OEMNTF_SYS_ERROR - Sent when a system error occurs.dwParam is a pointer to structure
of type AEESysError

OEMNTF_NEXT_ALARM: This function is invoked to notify the OEM layer about the duration pending 
before the next BREW Alarm can expire. The dwParam contains the exact duration in milliseconds before the
next BREW alarm can expire. When there are no BREW alarms pending, the dwParam is set to 0.
If there are two or more BREW alarms pending, the dwParam always points to the shortest of the 
BREW Alarms that are pending. BREW alarms are persistent (i.e. remembered across power-cycles), but it requires the 
device to be powered up for the alarm to expire. If the alarm expired while the device is powered down, the app that set 
the alarm will be notified only when the device is powered up next time. On devices that support alarms in the RTC (Real 
Time Clock), this notification (OEMNTF_NEXT_ALARM) can be used by the OEMs to set the next BREW Alarm in the RTC. 
When the RTC alarm expires, if the device is currently powered down, the device should be powered up by the OEM. 
Powering up the device and initializing BREW (AEE_Init) will take care of expiring the BREW Alarm and notifying the app that 
set the alarm. If the device is already powered up when the RTC alarm expires, no action needs to be taken from the OEM 
Layer. In this case, the BREW alarm will be notified automatically to the app that set the alarm.


OEMNTF_RESET_BREW: This indicates a request to Reset BREW on the device. The entire device must not be reset. Instead, just
BREW must be reset. Resetting BREW involves exiting BREW (AEE_Exit) and re-initializing BREW (AEE_Init).
This call is made in user mode. So, to exit and re-initialize BREW, the user-mode-safe versions of these functions
should be called.(i.e AEE_SafeExit() and    AEE_SafeInit() respectively).


Prototype:
   int   OEM_Notify(OEMNotifyEvent evt, uint32 dwParam);

Parameters:
   evt:     The event code.
   dwParam: Context sensitive data.

Return Value:
   0 - SUCCESS

Comments:
   None

Side Effects:
   None

See Also:
   None

==================================================================*/
#endif // !defined(OEM_NOTIFY_H)
