aeebattery.h

BREW SDK 3.1。BREW应用程序的开发包。

See Also:
   IBATTERY_GetBatteryLevel
===============================================================================

GETBATTERYLEVEL()

Description:
   This macro retrieves battery level from 32 bit battery level value
provided by IBATTERY_GetBatteryLevel().

Definition:

#define GETBATTERYLEVEL(dwLevel)       (uint16)(dwLevel & 0x0000ffff)

Parameters:
   dwLevel: 32 bit battery level value provided by IBATTERY_GetBatteryLevel()

Evaluation Value:
   16 bit battery level

Comments:
   None

Side Effects:
   None

See Also:
   IBATTERY_GetBatteryLevel

===============================================================================
  INTERFACES   DOCUMENTATION
===============================================================================

Interface Name: IBatteryNotifier

Description:
  IBatteryNotifier is the notifier class with which applications can register
  for battery notifications in following ways:

  1. Using application MIF
  2. Using ISHELL_RegisterNotify()

  Applications are not required and can't create an instance of IBatteryNotifier.

Following are the notification masks supported by IBatteryNotifier:

#define NMASK_BATTERY_STATUS_CHANGE                   0x0001

// An EVT_NOTIFY event with NMASK_BATTERY_STATUS_CHANGE mask is sent when there is a 
// change in the battery status as reported by IBATTERY_GetBatteryStatus().
//
// ((AEENotify*)dwParam)->pData contains the new battery status.
//
// Note: A battery status of AEEBATTERY_STATUS_POWERDOWN may occur even when external 
//       power is present, if external power fails to provide sufficient power to 
//       maintain a voice call.

#define NMASK_BATTERY_LEVEL_CHANGE                    0x0002

// An EVT_NOTIFY event with NMASK_BATTERY_LEVEL_CHANGE mask is sent when there is a 
// change in the battery level as reported by IBATTERY_GetBatteryLevel().
//
// ((AEENotify*)dwParam)->pData contains the new battery level.

#define NMASK_BATTERY_CHARGERSTATUS_CHANGE            0x0004

// An EVT_NOTIFY event with NMASK_BATTERY_CHARGERSTATUS_CHANGE mask is sent when there 
// is a change in the battery charger status as reported by IBATTERY_GetBatteryChargerStatus().
//
// ((AEENotify*)dwParam)->pData contains the new battery charger status.

#define NMASK_BATTERY_EXTPWR_CHANGE                   0x0008

// An EVT_NOTIFY event with NMASK_BATTERY_EXTPWR_CHANGE mask is sent when there is 
// a change in the external power state.
//
// ((AEENotify*)dwParam)->pData is TRUE if external power is currently present and
// is FALSE if external power is currently not present.

===============================================================================
  INTERFACES   DOCUMENTATION
===============================================================================

Interface Name: IBattery

Description:
   IBattery interface lets application get battery related information.

The IBattery interface instance is obtained via ISHELL_CreateInstance()
mechanism.

IBattery also supports IModel interfcae. Client can access IModel
interface by calling IBATTERY_QueryInterface() with AEEIID_MODEL and 
register listeners using IMODEL_AddListener.

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

IBATTERY_AddRef()

Description:
   This method increments the reference count of the IBattery Interface object.
   This allows the object to be shared by multiple callers. The object is freed when
   the reference count reaches 0 (zero).

Prototype:
   uint32 IBATTERY_AddRef(IBattery * po)

Parameters:

   po [in]: Pointer to the IBattery Interface object

Return Value:
   Incremented reference count for the object

Comments:
   A valid object returns a positive reference count.

Side Effects:
   None

See Also:
   IBATTERY_Release()

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

IBATTERY_Release()

Description:
   This method decrements the reference count of an object. The object is freed
   from memory and is no longer valid once the reference count reaches 0 (zero).

Prototype:
   uint32 IBATTERY_Release(IBattery * po)

Parameters:

   po [in]: Pointer to the IBATTERY Interface object

Return Value:
   Decremented reference count for the object. The object has been freed and is no
   longer valid if 0 (zero) is returned.

Comments:
   None

Side Effects:
   None

See Also:
   IBATTERY_AddRef()

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

IBATTERY_QueryInterface()

Description:

   This method retrieves a pointer to an interface conforming to the
   definition of the specified class ID.  This can be used to query for
   extended functionality, like future versions or proprietary extensions.

   Upon a successful query, the interace is returned AddRef'ed.  The caller is
   responsible for calling Release() at some point in the future.  One
   exception is when the pointer returned is not an interface pointer.  In
   that case, the memory will share the lifetime of the object being queried,
   and the returned pointer will not be used to free or release the object.

Prototype:

   int IBATTERY_QueryInterface(IBattery *po, AEECLSID id, void **p)

Parameters:

   po [in]: Pointer to IBattery interface.

   id [in]: A globally unique id to identify the entity (interface or data) that we
            are trying to query.

   p [out]: Pointer to the data or interface that we want to retrieve.  If the interface
            is not available, this is set to NULL.

Return Value:

   Return SUCCESS on success,
   ECLASSNOTSUPPORT if class ID not supported

Comments:

   On failure, QueryInterface() must set *p to NULL.

Side Effects:
   None

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

IBATTERY_GetBatteryStatus

Description:  
   This method queries the current battery status

Prototype:
   int IBATTERY_GetBatteryStatus(IBattery *p, AEEBatteryStatus *pBatteryStatus)

Parameters:
   p [in]: Pointer to IBattery interface
   pBatteryStatus [in/out]: Place holder for battery status

Return Value:
   SUCCESS on success,
   Error code otherwise

Comments:
   None

Side Effects:
   None

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

IBATTERY_GetBatteryLevel

Description:  
   This method queries the current battery level. Most significant 16 bits give 
battery level scale whereas least significant 16 bits will give battery level.

Prototype:
   int IBATTERY_GetBatteryLevel(IBattery *p, uint32 * pdwData)

Parameters:
   p [in]: Pointer to IBattery interface
   pdwData [in/out]: Place holder for battery level

Return Value:
   SUCCESS on success,
   Error code otherwise

Comments:
   Use GETBATTERYSCALE() and GETBATTERYLEVEL() to get battery level scale and
battery level.

Side Effects:
   None

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

IBATTERY_GetBatteryChargerStatus

Description:  
   This method queries the current battery charger status

Prototype:
   int IBATTERY_GetBatteryChargerStatus(IBattery *p, AEEBatteryChargerStatus *pBatteryChargerStatus)

Parameters:
   p [in]: Pointer to IBattery interface
   pBatteryChargerStatus [in/out]: Place holder for battery charger status

Return Value:
   SUCCESS on success,
   Error code otherwise

Comments:
   None

Side Effects:
   None

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

IBATTERY_IsExternalPowerPresent

Description:  
   This method queries if external power is present

Prototype:
   int IBATTERY_IsExternalPowerPresent(IBattery *p, boolean *pbData)

Parameters:
   p [in]: Pointer to IBattery interface
   pbData [in/out]: Place holder for information about external power

Return Value:
   SUCCESS on success,
   Error code otherwise

Comments:
   None

Side Effects:
   None

=============================================================================*/
#endif //AEEBATTERY_H