Kernel side client API for Hardware Configuration Repository (HCR). 

The HCR service provides access to hardware settings defined for the base port. 

This API is used by kernel side components such as PDDs, hardware service 

providers and other kernel extensions.

client API of the Kernel Hardware Configuration Repository (HCR).

It provides accessor functions to retrieve settings held by the HCR and may be 

called by kernel components from with in thread context. 

The _published_ Setting IDs available for use with this API can be found

that clients can include to gain access to all IDs for the BSP. IDs for settings

that are internal to a component and not used by others are defined in a file

private to that component.

The HCR supports a number of setting repositories and searches them in a defined

order, always returns the first setting found matching the ID or criteria.

This allows setting values to be overriden by more recent repositories created

during platform development and product creation.

    setting in the HCR. Used in calls to HCR API to retrieve one setting. 

    Retrieve a word size integer setting value from the HCR.

    On error aValue is undefined.

    @param aId     in: The setting identifier

    @param aValue  out: The retrieved setting data value  

	/**

    Retrieve a boolean setting value from the HCR.

    On error aValue is undefined.

    @param aId     in: The setting identifier

    @param aValue  out: The retrieved setting data value  

	@return	KErrNone if successful, output parameters valid

            KErrNotFound if aId is not a known setting ID

            KErrArgument if the setting identified is not the correct type

            KErrNotReady if the HCR is used before it has been initialised

            KErrCorrupt if HCR finds a repository to be corrupt

            KErrGeneral if an internal failure occurs, see trace.

            Otherwise one of the other system-wide error codes. 

	@pre    Call from thread context, during Init1 or later

	*/

	/**

    Retrieve an word size unsigned integer setting value from the HCR.

    On error aValue is undefined.

    @param aId     in: The setting identifier

    @param aValue  out: The retrieved setting data value  

	@return	KErrNone if successful, output parameters valid

            KErrNotFound if aId is not a known setting ID

            KErrArgument if the setting identified is not the correct type

            KErrNotReady if the HCR is used before it has been initialised

            KErrCorrupt if HCR finds a repository to be corrupt

            KErrGeneral if an internal failure occurs, see trace.

            Otherwise one of the other system-wide error codes. 

	@pre    Call from thread context, during Init1 or later

	*/

	/**

    Retrieve a word size linear address setting value from the HCR.

    On error aValue is undefined.

    @param aId     in: The setting identifier

    @param aValue  out: The retrieved setting data value  

	@return	KErrNone if successful, output parameters valid

            KErrNotFound if aId is not a known setting ID

            KErrArgument if the setting identified is not the correct type

            KErrNotReady if the HCR is used before it has been initialised

            KErrCorrupt if HCR finds a repository to be corrupt

            KErrGeneral if an internal failure occurs, see trace.

            Otherwise one of the other system-wide error codes. 

	@pre    Call from thread context, during Init1 or later

	*/

    Retrieve a large binary data setting value from the HCR. The value

	is copied into the supplied descriptor buffer. 

	On error the descriptor and output arguments have undefined values.

    @param aId     in: The setting identifier

    @param aValue  inout: A pre-allocated descriptor to hold the value

    Retrieve a large binary data setting value from the HCR. The value is copied

	into the supplied byte array buffer. 

	On error the buffer and output arguments have undefined values.

    @param aId     in: The setting identifier

    @param aMaxLen in: The maximum value length that can be stored in the buffer

    @param aValue  inout: The address of a pre-allocated buffer to hold the value

    @param aLen    out: Contains the length of the setting value written

	@return	KErrNone if successful and aValue has been set

            KErrNotFound if aId is not a known setting ID

            KErrArgument if the setting identified is not the correct type

            KErrNotReady if the HCR is used before it has been initialised

            KErrCorrupt if HCR finds a repository to be corrupt

            KErrTooBig if the setting is larger than the supplied buffer

            KErrGeneral if an internal failure occurs, see trace

            Otherwise one of the other system-wide error codes.

	@pre    Call from thread context, during Init1 or later

	*/

    IMPORT_C TInt GetData(const TSettingId& aId, TUint16 aMaxLen, 

                                    TUint8* aValue, TUint16& aLen);   

	/**	

    Retrieve an 8 bit character string setting from the HCR.  The value

	is copied into the supplied descriptor buffer. Note the string is not zero

	terminated. 

	On error the descriptor and output arguments have undefined values.

    @param aId     in: The setting identifier

    @param aValue  inout: A pre-allocated descriptor to hold the value

	/**	

    Retrieve an 8 bit character string setting from the HCR.  The value

	is copied into the byte array buffer. Note the string is not zero

	terminated. 

	On error the descriptor and output arguments have undefined values.

    @param aId     in: The setting identifier

    @param aMaxLen in: The maximum value length that can be stored in the buffer

    @param aValue  inout: The address of a pre-allocated buffer to hold the value

	@param aLen    out: Contains the length of the setting value written    

	@return	KErrNone if successful and aValue has been set

            KErrNotFound if aId is not a known setting ID

            KErrArgument if the setting identified is not the correct type

            KErrNotReady if the HCR is used before it has been initialised

            KErrCorrupt if HCR finds a repository to be corrupt

            KErrTooBig if the setting is larger than the supplied buffer

            KErrGeneral if an internal failure occurs, see trace

            Otherwise one of the other system-wide error codes.

	@pre    Call from thread context, during Init1 or later

	*/

    Retrieve an array of signed integers from the HCR. The value

	is copied into the byte array buffer. 

	On error the descriptor and output arguments have undefined values.

    @param aId     in: The setting identifier

    @param aMaxLen in: The maximum value length that can be stored in the buffer

    @param aValue  inout: The address of a pre-allocated word array to hold the value

    @param aLen    out: Contains the length, in bytes of the setting value written

    Retrieve multiple word sized settings from the Hardware Configuration 

    bytes or less (i.e those with a type less than 0x0000ffff).

    The caller is responsible for pre-allocating the arrays supplied. Note the

    array of setting IDs (aIds) supplied by the client must be ordered with 

	aIds[0] containing the lowest and aIds[aNum-1] the highest. Undefined 

	behaviour will result if this pre-condition is not met.

	On successful return the client will need to check the number found (return

	value) matches their needs and cast each value in the aValues

	array to the correct type before use. The correct type is either known at 

	compile time by the caller or determined from aTypes, if supplied.

   	When an overall error is returned from the function the output arrays have 

	undefined values.

    @param aIds     in:  An ordered array of setting identifiers to retrieve

    @param aValues  inout: An array of values, populated on exit

    @param aTypes   inout: An optional array of type enumerations, populated on

					exit describing the type of each setting found. 

					May be 0 if client is not interested

    @param aErrors  inout: An array of search errors for each setting populated 

					on exit. If no error found for the setting then KErrNone

					is written. Possible error codes:

                    KErrArgument     the setting is not of a suitable type

                    KErrNotFound     the setting is not found

                    KErrNone         when setting found

    obtain the setting size should a buffer need to be allocated.

    On error the output arguments are undefined.    

    @param aId     in: The setting identifier

    @param aType   out: The type enumeration of the found setting

    @param aLen    out: The length in bytes of the found setting

    Retrieve the number of unique ettings held in the HCR for one particular 

	category. It allows a client to perpare buffers for other calls to the HCR 

	to retrieve these settings. 

	The method carries out a search to return the total number of unique setting

	records found across all HCR repositories for a given category. It does not 

	count settings that are duplicate from being redefined in different 

	repositories.

	The function is particularly useful for open-ended categories were the 

	run-time client can not predict the number of settings prvisioned. 

    Retrieve details of all the settings (ids, types and sizes) in one 

	particular category. This function can be used by clients to obtain the 

	number of, ids, sizes and types of all the settings in a category. 

	It allows a client to alloc buffers for other calls to the HCR to retrieve 

	the values of these settings.

   	On successful return the client will need to check the number found (return

	value) matches the expected number. When there are more defined in

	the category than was able to be returned, i.e. when number found 

	exceeded aMaxNum then aMaxNum is returned.

   	When an overall error is returned from the function the output arrays have 

	undefined values.

    @param aCat  	 in: The setting category to search for

    @param aKeyIds   inout: Client supplied array populated on exit. Large

						    enumerations on exit. Array address may be 0 if 

                            client is not interested.

						    on exit for those settings with a type > 0x0000ffff. 

							When less than this 0 is set in the aLens array element. 

							Array address may be 0 if client is not interested.

    Retrieve details of all the settings (ids, types and sizes) in one 

	particular category who's key ID matches the supplied bit pattern/mask.

	This function can be used by clients to obtain the number of, ids, sizes 

	and types of all the settings in a category. It allows a client to alloc 

	buffers for other calls to the HCR to retrieve the values of these settings. 

	This search method allows categories to contain structured settings 

	i.e. row/column structured or record based categories as might be used

	for configuration data of a hardware service provider.

    The caller supplies the category to search, a setting key ID mask and the 

    pattern to match. Setting keys that satisfy this logic are returned:

   	On successful return the client will need to check the number found (return

	value) matches the expected number. When there are more defined in

	the category than was able to be returned, i.e. when number found 

	exceeded aMaxNum then aMaxNum is returned.

   	When an overall error is returned from the function the output arrays have 

	undefined values.

    @param aMask     in: The bits in the Element ID to be checked against 

    @param aKeyIds   inout: Client supplied array populated on exit. Large

    @param aTypes	 inout: Client supplied array populated with setting types 

						    enumerations on exit. Array address may be 0 if 

                            client is not interested.

    @param aLens  	 inout: Client supplied array populated with setting lengths

						    on exit for those settings with a type > 0x0000ffff. 

							When less than this 0 is set in the aLens array element. 

							Array address may be 0 if client is not interested.