#ifndef AEEBACKLIGHT_H
#define AEEBACKLIGHT_H
/*=============================================================================
 
FILE: AEEBacklight.h

SERVICES: The IBacklight interface manages the Backlight.  

GENERAL DESCRIPTION:

PUBLIC CLASSES AND STATIC FUNCTIONS:
   IBacklight

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

                     INCLUDE FILES FOR MODULE

=============================================================================*/
#include "AEE.h"

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

                    CLASS DEFINITIONS

=============================================================================*/
typedef struct
{
    uint32 dwSize;
    uint32 dwMinBrightnessLevel;
    uint32 dwMaxBrightnessLevel;
    uint32 dwDefaultBrightnessLevel;
    uint32 dwMinContrastLevel;
    uint32 dwMaxContrastLevel;
    uint32 dwDefaultContrastLevel;
    RGBVAL dwBacklightColor;
} AEEBacklightInfo;

typedef struct IBacklight         IBacklight;

AEEINTERFACE(IBacklight)
{
   INHERIT_IQueryInterface(IBacklight);
   int (*Enable)(IBacklight *p);
   int (*Disable)(IBacklight *p);
   boolean (*IsEnabled)(IBacklight *p);
   int (*GetBacklightInfo)(IBacklight *p, AEEBacklightInfo * pBacklightInfo);
   int (*GetBrightnessLevel)(IBacklight *p, uint32* pdwBrightnessLevel);
   int (*SetBrightnessLevel)(IBacklight *p, uint32 dwBrightnessLevel);
   int (*GetContrastLevel)(IBacklight *p, uint32* pdwContrastLevel);
   int (*SetContrastLevel)(IBacklight *p, uint32 dwContrastLevel);
};

#define IBACKLIGHT_AddRef(p)                       AEEGETPVTBL((p),IBacklight)->AddRef((p))
#define IBACKLIGHT_Release(p)                      AEEGETPVTBL((p),IBacklight)->Release((p))
#define IBACKLIGHT_QueryInterface(p,clsid,pp)      AEEGETPVTBL((p),IBacklight)->QueryInterface((p),(clsid),(pp))
#define IBACKLIGHT_Enable(p)                       AEEGETPVTBL((p),IBacklight)->Enable((p))
#define IBACKLIGHT_Disable(p)                      AEEGETPVTBL((p),IBacklight)->Disable((p))
#define IBACKLIGHT_IsEnabled(p)                    AEEGETPVTBL((p),IBacklight)->IsEnabled((p))
#define IBACKLIGHT_GetBacklightInfo(p,pbi)         AEEGETPVTBL((p),IBacklight)->GetBacklightInfo((p),(pbi))
#define IBACKLIGHT_GetBrightnessLevel(p,pdwbl)     AEEGETPVTBL((p),IBacklight)->GetBrightnessLevel((p),(pdwbl))
#define IBACKLIGHT_SetBrightnessLevel(p,dwbl)      AEEGETPVTBL((p),IBacklight)->SetBrightnessLevel((p),(dwbl))
#define IBACKLIGHT_GetContrastLevel(p,pdwcl)       AEEGETPVTBL((p),IBacklight)->GetContrastLevel((p),(pdwcl))
#define IBACKLIGHT_SetContrastLevel(p,dwcl)        AEEGETPVTBL((p),IBacklight)->SetContrastLevel((p),(dwcl))

#endif // AEEBACKLIGHT_H

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

Description:
   Backlight Information

Definition:
typedef struct
{
    uint32 dwSize;
    uint32 dwMinBrightnessLevel;
    uint32 dwMaxBrightnessLevel;
    uint32 dwDefaultBrightnessLevel;
    uint32 dwMinContrastLevel;
    uint32 dwMaxContrastLevel;
    uint32 dwDefaultContrastLevel;
    RGBVAL dwBacklightColor;
} AEEBacklightInfo;

Members:
    dwSize : Size of the back light structure
    dwMinBrightnessLevel : Minimum Brightness Level
    dwMaxBrightnessLevel : Maximum Brightness Level
    dwDefaultBrightnessLevel : Default Brightness Level
    dwMinContrastLevel : Minimum Contrast Level
    dwMaxContrastLevel : Maximum Contrast Level
    dwDefaultContrastLevel : Default Contrast Level
    dwBacklightColor : Backlight Color

Comments:
   None

See Also:
   None

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

Interface Name: IBacklight

Description:
    IBacklight interface enables applications control various back lights 
available on a device.

   A device can have multiple components which support back light e.g.
primary display, secondary display and key pad. Moreover, each device
component supporting back light might support multiple back lights,
possibly of different colors, e.g. primary display might support red, green, 
blue and yellow color back lights. For controlling a back light, 
applications create IBacklight interface by specifying back light class ID 
associated with the back light. IBacklight methods let application control
various parameters of a back light e.g. on/off status, brightness and 
contrast.

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

IBACKLIGHT_AddRef()

Description:
   This method increments the reference count of the IBacklight 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 IBACKLIGHT_AddRef(IBacklight * po)

Parameters:

   po [in]: Pointer to the IBacklight Interface object

Return Value:
   Incremented reference count for the object

Comments:
   A valid object returns a positive reference count.

Side Effects:
   None

See Also:
   IBACKLIGHT_Release()

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

IBACKLIGHT_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 IBACKLIGHT_Release(IBacklight * po)

Parameters:

   po [in]: Pointer to the IBacklight 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:
   IBACKLIGHT_AddRef()

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

Function: IBACKLIGHT_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 IBACKLIGHT_QueryInterface(IBacklight *po, AEECLSID id, void **p)

Parameters:

   po [in]: Pointer to IBacklight 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 *po to NULL.

Side Effects:
   None

See Also:
   None

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

IBACKLIGHT_Enable()

Description:
   This method turns back light on.

Prototype:
   int IBACKLIGHT_Enable(IBacklight * po)

Parameters:

   po [in]: Pointer to the IBacklight Interface object

Return Value:
   SUCCESS - If successful
   Error Code - Otherwise

Comments:
   None

Side Effects:
   None

See Also:
   IBACKLIGHT_Disable()

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

IBACKLIGHT_Disable()

Description:
   This method turns back light off.

Prototype:
   int IBACKLIGHT_Disable(IBacklight * po)

Parameters:

   po [in]: Pointer to the IBacklight Interface object

Return Value:
   SUCCESS - If successful
   Error Code - Otherwise

Comments:
   None

Side Effects:
   None

See Also:
   IBACKLIGHT_Enable()

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

IBACKLIGHT_IsEnabled()

Description:
   This method checks if back light is on.

Prototype:
   boolean IBACKLIGHT_IsEnabled(IBacklight * po)

Parameters:

   po [in]: Pointer to the IBacklight Interface object

Return Value:
   TRUE - If back light is on
   FALSE - Otherwise

Comments:
   None

Side Effects:
   None

See Also:
   IBACKLIGHT_Enable(), IBACKLIGHT_Disable()

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

IBACKLIGHT_GetBacklightInfo()

Description:
   This method provides information about various parameters associated with the 
   back light.

Prototype:
   int IBACKLIGHT_GetBacklightInfo(IBacklight *p, AEEBacklightInfo * pBacklightInfo)

Parameters:

   po [in]: Pointer to the IBacklight Interface object
   pBacklightInfo [out]: Pointer to back light information structure

Return Value:
   SUCCESS - If successful
   Error Code - Otherwise

Comments:
   None

Side Effects:
   None

See Also:
   AEEBacklightInfo

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

IBACKLIGHT_GetBrightnessLevel()

Description:
   This method provides information about the current brightness level of the 
   back light.

Prototype:
   int IBACKLIGHT_GetBrightnessLevel(IBacklight *p, uint32* pdwBrightnessLevel)

Parameters:

   po [in]: Pointer to the IBacklight Interface object
   pdwBrightnessLevel [out]: Pointer to brightness level

Return Value:
   SUCCESS - If successful
   Error Code - Otherwise

Comments:
   None

Side Effects:
   None

See Also:
   AEEBacklightInfo

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

IBACKLIGHT_SetBrightnessLevel()

Description:
   This method sets the brightness level of the back light.

Prototype:
   int IBACKLIGHT_SetBrightnessLevel(IBacklight *p, uint32 dwBrightnessLevel)

Parameters:

   po [in]: Pointer to the IBacklight Interface object
   dwBrightnessLevel [in]: Brightness Level

Return Value:
   SUCCESS - If successful
   Error Code - Otherwise

Comments:
   None

Side Effects:
   None

See Also:
   AEEBacklightInfo

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

IBACKLIGHT_GetContrastLevel()

Description:
   This method provides information about the current contrast level of the 
   back light.

Prototype:
   int IBACKLIGHT_GetContrastLevel(IBacklight *p, uint32* pdwContrastLevel)

Parameters:

   po [in]: Pointer to the IBacklight Interface object
   pdwContrastLevel [out]: Pointer to contrast level

Return Value:
   SUCCESS - If successful
   Error Code - Otherwise

Comments:
   None

Side Effects:
   None

See Also:
   AEEBacklightInfo

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

IBACKLIGHT_SetContrastLevel()

Description:
   This method sets the contrast level of the back light.

Prototype:
   int IBACKLIGHT_SetContrastLevel(IBacklight *p, uint32 dwContrastLevel)

Parameters:

   po [in]: Pointer to the IBacklight Interface object
   dwContrastLevel [in]: Contrast Level

Return Value:
   SUCCESS - If successful
   Error Code - Otherwise

Comments:
   None

Side Effects:
   None

See Also:
   AEEBacklightInfo

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