#ifndef AEEKCB_H
#define AEEKCB_H
/*===========================================================================
                    IMPORTANT NOTICE

                  OEM DISTRIBUTION ONLY

FILE:  AEEkCB.h

SERVICES:  Kernel-level callbacks.

GENERAL DESCRIPTION:
   AEEkCB is an interface to schedule and recieive notifications in
   user-mode when kernel-mode events have occured.  AEEkCB can be
   safely passed to supervisor-mode APIs to await notification in 
   user-mode.

        Copyright © 2003 QUALCOMM Incorporated.
               All Rights Reserved.
            QUALCOMM Proprietary/GTDR
===========================================================================*/

#include "AEE.h"

#ifdef __cplusplus
extern "C" {
#endif /* #ifdef __cplusplus */

/**************************************************************************/
/*               AEE kCB EXPORTED METHODS                               */
/**************************************************************************/
typedef void *hAEEkCB;

extern AEE_EXPORTS int AEEkCB_New(hAEEkCB    *ph,
                      PFNNOTIFY   pfnNotify,
                      void       *pNotifyData);

extern AEE_EXPORTS boolean AEEkCB_IsQueued(const hAEEkCB *ph);

extern AEE_EXPORTS void AEEkCB_Cancel(const hAEEkCB *ph);

extern AEE_EXPORTS void AEEkCB_Delete(hAEEkCB *ph);

extern AEE_EXPORTS int AEEkCB_ToAEECallback(hAEEkCB h, AEECallback **ppcb);

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

/*=====================================================================
  DATA STRUCTURE DOCUMENTATION
 ======================================================================

=======================================================================
  INTERFACES   DOCUMENTATION
======================================================================= 
AEEkCB Interface
======================================================================= 
Function: AEEkCB_New()

Description:
   creates and initializes a new AEEkCB

Prototype:
  extern int AEEkCB_New(hAEEkCB    *ph,
                        PFNNOTIFY   pfnNotify,
                        void       *pNotifyData);


Parameters:
   ph: pointer to a handle to recieve the user-mode handle to the 
         new AEEkCB, 
   pfnNotify: pointer to a function to be called when the AEEkCB is 
          "ready".  Perfect analog of AEECallback's pfnNotify.  This 
           function will be called in the same ACONTEXT when AEEkCB_New()
           is called.
   pNotifyData: pointer to the user-supplied, opaque data structure
          to be passed to pfnNotify when the AEEkCB is "ready".

Return Value:
   SUCCESS on success
   ENOMEMORY if a new kCB cannot be allocated

Comments:
   This is a user-mode function.

   pfnNotify will be called (when the AEEkCB is ready), in the
    processor mode and AppContext (if applicable) that is asserted when
    AEEkCB_New() is called.

Side Effects:
   None

See Also:
   AEEkCB_Delete()

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

Function: AEEkCB_IsQueued()

Description:
   determines if an AEEkCB is in a list

Prototype:
   boolean AEEkCB_IsQueued(const hAEEkCB *ph);

Parameters:
   ph: const pointer to handle to the AEEkCB to check

Return Value:
   boolean - TRUE if the AEEkCB is in a list

Comments:
   This is a user-mode function.

Side Effects:
   None

See Also:
   AEEkCB_Cancel()

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

Function: AEEkCB_Cancel()

Description:
   cancels an AEEkCB

Prototype:
   void AEEkCB_Cancel(const hAEEkCB *ph);

Parameters:
   ph: pointer to handle to the AEEkCB to cancel

Return Value:
   None

Comments:
   This is a user-mode function.

Side Effects:
   None

See Also:
   AEEkCB_Delete()

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

Function: AEEkCB_Delete()

Description:
   cancels and deletes an AEEkCB

Prototype:
   void AEEkCB_Delete(hAEEkCB *ph);

Parameters:
   ph: pointer to handle to the AEEkCB to delete, set to 
             invalid AEEkCB on return

Return Value:
   None

Comments:
   This is a user-mode function.

Side Effects:
   None

See Also:
   AEEkCB_New()

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

Function: AEEkCB_ToAEECallback()

Description:
   gets an AEECallback from an AEEkCB

Prototype:
   int AEEkCB_ToAEECallback(hAEEkCB h, AEECallback **ppcb);

Parameters:
   h: handle to AEEkCB to get the AEECallback for
   ppcb:[out] pointer to pointer to AEECallback 

Return Value:
   SUCCESS if pHandle is a valid AEEkCB

Comments:
   This is a supervisor-mode function, and ppcb is 
     supervisor-mode memory

Side Effects:
   None

See Also:
   AEEkCB_New()

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

*/

#endif /* #ifndef AEEKCB_H */
