// Copyright (c) 1995-2010 Nokia Corporation and/or its subsidiary(-ies).
// All rights reserved.
// This component and the accompanying materials are made available
// under the terms of the License "Eclipse Public License v1.0"
// which accompanies this distribution, and is available
// at the URL "http://www.eclipse.org/legal/epl-v10.html".
//
// Initial Contributors:
// Nokia Corporation - initial contribution.
//
// Contributors:
//
// Description:
// hal\inc\hal.h
// 
// WARNING: This file contains some APIs which are internal and are subject
//          to change without notice. Such APIs should therefore not be used
//          outside the Kernel and Hardware Services package.
//

#ifndef __HAL_H__
#define __HAL_H__

#include <e32def.h>
#include <hal_data.h>
#include <e32property.h>




/**
@publishedPartner
@released

A set of static functions to get and set hardware attributes.

@see HALData
*/
class HAL : public HALData
	{
public:

    /**
    Synonyms for the attribute properties
    HALData::TAttributeProperty, and used in SEntry.
    */
	enum TEntryProperty
		{
		/**		
		When set, means that an attribute is meaningful on this device.
		*/
		EEntryValid=0x1,
		
		
		/**
		When set, means that an attribute is modifiable.
		*/
		EEntryDynamic=0x2,
		};

    
    /**
    Defines an entry in the array that is returned in a call to HAL::GetAll().
    */
	struct SEntry
		{
		/**
		The properties of the attribute.
		
		@see HAL::TEntryProperty
		*/
		TInt iProperties;
		
		/**
		The attribute value.
		
		@see HALData::TAttribute
		*/
		TInt iValue;
		};
public:
    /**
    Gets the value of the specified HAL attribute.

    @param aAttribute The HAL attribute.
    @param aValue	On successful return, contains the attribute value.
					Some attributes may accept aValue as an input as well, to select
					one of several alternate values. See the documentation for the
					individual HAL attributes for details of this.

    @return  KErrNone, if successful;
             KErrNotSupported, if the attribute is not defined in the list
             of attributes, or is not meaningful for this device.
			 KErrArgument, if aValue was invalid (for attributes
			 which take an argument). 
         
    @see HALData::TAttribute
    @see HALData::TAttributeProperty
    */
	IMPORT_C static TInt Get(TAttribute aAttribute, TInt& aValue);

	
	/**
    Sets the specified HAL attribute.

    @param aAttribute The HAL attribute.
    @param aValue      The attribute value.

    @return  KErrNone, if successful;
             KErrNotSupported, if the attribute is not defined in the list
             of attributes, or is not meaningful for this device, or is
             not settable.
         
    @see HALData::TAttribute
    @see HALData::TAttributeProperty

    @capability WriteDeviceData or other capability specified
    for individual attributes in TAttribute
    */
	IMPORT_C static TInt Set(TAttribute aAttribute, TInt aValue);


    /**
    Gets all HAL attributes, and their properties.

    For attributes that are not meaningful on this device (ie. those which have
	not been defined in the config.hcf file), the attribute value and its 
	associated property value are set to zero in the returned array.

	Attributes for which multiple values can be retrieved
	ie. EDisplayIsPalettized, EDisplayBitsPerPixel, EDisplayOffsetToFirstPixel,
	EDisplayOffsetBetweenLines, and EDisplayPaletteEntry will also be zero in
	the returned array.
	
	Attributes that allocate resources and open handles are also not returned 
	by this API. Their value and property values will be set to zero in the
	returned array. Use HAL::Get() for these attributes.

    @param aNumEntries On successful return, contains the total number
                       of HAL attributes.
                       If the function returns KErrNoMemory, this value is set
                       to zero.
    @param aData       On successful return, contains a pointer to an array
                       of SEntry objects, each of which contains an attribute value
                       and its property value. Note that the property value is
                       defined by the HAL::TEntry synonym.
                       If the function returns KErrNoMemory, this pointer is set
                       to NULL.

    @return KErrNone, if succesful;
            KErrNoMemory, if there is insufficient memory. 
    */
	IMPORT_C static TInt GetAll(TInt& aNumEntries, SEntry*& aData);

	
    /**
    Gets the value of the specified HAL attribute.

    @param aDeviceNumber The device number. (eg: screen number)
    @param aAttribute The HAL attribute.
    @param aValue	On successful return, contains the attribute value.
					Some attributes may accept aValue as an input as well, to select
					one of several alternate values. See the documentation for the
					individual HAL attributes for details of this.


    @return  KErrNone, if successful;
             KErrNotSupported, if the attribute is not defined in the list
             of attributes, or is not meaningful for this device.
			 KErrArgument, if aValue was invalid (for attributes
			 which take an argument). 
         
    @see HALData::TAttribute
    @see HALData::TAttributeProperty
    */
	IMPORT_C static TInt Get(TInt aDeviceNumber, TAttribute aAttribute, TInt& aValue);
	
	
    /**
    Sets the specified HAL attribute.

    @param aDeviceNumber The device number. (eg: screen number)
    @param aAttribute The HAL attribute.
    @param aValue      The attribute value.

    @return  KErrNone, if successful;
             KErrNotSupported, if the attribute is not defined in the list
             of attributes, or is not meaningful for this device, or is
             not settable.
         
    @see HALData::TAttribute
    @see HALData::TAttributeProperty

    @capability WriteDeviceData or other capability specified
    for individual attributes in TAttribute
    */
	IMPORT_C static TInt Set(TInt aDeviceNumber, TAttribute aAttribute, TInt aValue);
	};


/**
@internalComponent
*/
static const TInt32 KUidHalPropertyKeyBase = 0x1020E306;

__ASSERT_COMPILE(HAL::ENumHalAttributes<256); // only 256 UIDs allocated for HAL property keys



#endif