|
1 // Copyright (c) 2008-2009 Nokia Corporation and/or its subsidiary(-ies). |
|
2 // All rights reserved. |
|
3 // This component and the accompanying materials are made available |
|
4 // under the terms of the License "Eclipse Public License v1.0" |
|
5 // which accompanies this distribution, and is available |
|
6 // at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
7 // |
|
8 // Initial Contributors: |
|
9 // Nokia Corporation - initial contribution. |
|
10 // |
|
11 // Contributors: |
|
12 // |
|
13 // Description: |
|
14 // Hardware Configuration Respoitory Platform Independent Layer (PIL) |
|
15 // |
|
16 |
|
17 |
|
18 /** |
|
19 @file hcr.h |
|
20 Kernel side API for Hardware Configuration Repository (HCR). The HCR service |
|
21 provides access to hardware settings defined for the base port. |
|
22 |
|
23 @publishedPartner |
|
24 @prototype |
|
25 */ |
|
26 |
|
27 |
|
28 |
|
29 |
|
30 #ifndef HCR_H |
|
31 #define HCR_H |
|
32 |
|
33 |
|
34 // -- INCLUDES ---------------------------------------------------------------- |
|
35 |
|
36 |
|
37 #include <e32err.h> |
|
38 #include <e32def.h> |
|
39 #include <e32cmn.h> |
|
40 #include <e32des8.h> |
|
41 |
|
42 |
|
43 // -- CLASSES ----------------------------------------------------------------- |
|
44 |
|
45 /** |
|
46 The HCR namespace contains all the types and APIs that make up the |
|
47 Kernel side Hardware Configuration Repository (HCR). |
|
48 It provides accessor functions to settings held by the HCR and may be used by |
|
49 kernel side clients such as physical device drivers and other services from |
|
50 thread contexts. |
|
51 The published Setting IDs available for use with this API can be found |
|
52 in the BSP exported header 'hcrconfig.h'. This provides the top-level header |
|
53 that clients can include to gain access to all IDs for the BSP. |
|
54 */ |
|
55 namespace HCR |
|
56 { |
|
57 |
|
58 /** Maximum length of a large setting type, in bytes */ |
|
59 static const TInt KMaxSettingLength = 512; |
|
60 |
|
61 |
|
62 /** Setting category identifier type */ |
|
63 typedef TUint32 TCategoryUid; |
|
64 |
|
65 /** Setting element identifier type */ |
|
66 typedef TUint32 TElementId; |
|
67 |
|
68 /** The setting Identifier structure. Used to create static initialised |
|
69 arrys for use with multiple setting retrieval calls. |
|
70 */ |
|
71 struct SSettingId |
|
72 { |
|
73 TCategoryUid iCat; //!< Allocated UID for setting category |
|
74 TElementId iKey; //!< Element indetifier for setting in category |
|
75 }; |
|
76 |
|
77 /** The setting Identifier type. A class used to uniquely identify a |
|
78 setting in the HCR. Used in calls to HCR API. |
|
79 */ |
|
80 class TSettingId : public SSettingId |
|
81 { |
|
82 public: |
|
83 TSettingId () |
|
84 { iCat = iKey = 0; }; |
|
85 TSettingId (TCategoryUid aCat, TElementId aKey) |
|
86 { iCat = aCat; iKey = aKey; }; |
|
87 TSettingId (const SSettingId& aId) |
|
88 { iCat = aId.iCat; iKey = aId.iKey; }; |
|
89 TSettingId& operator= (const SSettingId& rhs) |
|
90 { iCat = rhs.iCat; iKey = rhs.iKey; return *this; } |
|
91 |
|
92 }; |
|
93 |
|
94 /** The setting types supported. The types are shown in two groups: Word |
|
95 size - a maximum of 4 bytes; and ii) Large size - types exceeding 4 bytes |
|
96 in size. |
|
97 */ |
|
98 enum TSettingType |
|
99 { |
|
100 ETypeUndefined = 0, //!< Type unknown/not set |
|
101 |
|
102 // Word size settings |
|
103 ETypeInt32 = 0x00000001, //!< 32bit signed integer |
|
104 ETypeInt16 = 0x00000002, //!< 16bit signed integer |
|
105 ETypeInt8 = 0x00000004, //!< 8bit signed integer |
|
106 ETypeBool = 0x00000008, //!< 32bit boolean value |
|
107 ETypeUInt32 = 0x00000010, //!< 32bit unsigned integer |
|
108 ETypeUInt16 = 0x00000020, //!< 16bit unsigned integer |
|
109 ETypeUInt8 = 0x00000040, //!< 8bit unsigned integer |
|
110 ETypeLinAddr = 0x00000100, //!< 32bit virtual address |
|
111 |
|
112 // Large settings |
|
113 ETypeBinData = 0x00010000, //!< Raw binary data (TUint8 array) |
|
114 ETypeText8 = 0x00020000, //!< String data (TText8 array) |
|
115 ETypeArrayInt32 = 0x00040000, //!< 32bit signed integer array |
|
116 ETypeArrayUInt32 = 0x00080000, //!< 32bit unsigned integer array |
|
117 ETypeInt64 = 0x01000000, //!< 64bit signed integer |
|
118 ETypeUInt64 = 0x02000000, //!< 64bit unsigned integer |
|
119 }; |
|
120 |
|
121 |
|
122 /** |
|
123 Retrieve settings of built in types from the HCR. |
|
124 |
|
125 @param aId The setting identifier |
|
126 @param aValue The retrieved setting data value |
|
127 |
|
128 @return KErrNone if successful, output parameters valid |
|
129 KErrNotFound if aId is not a known setting ID |
|
130 KErrArgument if the setting identified is not the correct type |
|
131 KErrNotReady if the HCR is used before it has been initialised |
|
132 KErrCorrupt if HCR finds a repository to be corrupt |
|
133 KErrGeneral if an internal failure occurs, see trace. |
|
134 Otherwise one of the other system-wide error codes. |
|
135 |
|
136 @pre Call from thread context, during Init1 or later |
|
137 */ |
|
138 IMPORT_C TInt GetInt(const TSettingId& aId, TInt8& aValue); |
|
139 IMPORT_C TInt GetInt(const TSettingId& aId, TInt16& aValue); |
|
140 IMPORT_C TInt GetInt(const TSettingId& aId, TInt32& aValue); |
|
141 IMPORT_C TInt GetInt(const TSettingId& aId, TInt64& aValue); |
|
142 |
|
143 IMPORT_C TInt GetBool(const TSettingId& aId, TBool& aValue); |
|
144 |
|
145 IMPORT_C TInt GetUInt(const TSettingId& aId, TUint8& aValue); |
|
146 IMPORT_C TInt GetUInt(const TSettingId& aId, TUint16& aValue); |
|
147 IMPORT_C TInt GetUInt(const TSettingId& aId, TUint32& aValue); |
|
148 IMPORT_C TInt GetUInt(const TSettingId& aId, TUint64& aValue); |
|
149 |
|
150 IMPORT_C TInt GetLinAddr(const TSettingId& aId, TLinAddr& aValue); |
|
151 |
|
152 /** |
|
153 Retrieve a binary data (ETypeBinData) setting from the HCR. |
|
154 |
|
155 @param aId The setting identifier |
|
156 @param aMaxLen The maximum value length that can be stored in the buffer |
|
157 @param aValue A pointer to the buffer or a descriptor to hold the value |
|
158 @param aLen Contains the length of the setting value written |
|
159 |
|
160 |
|
161 @return KErrNone if successful and aValue has been set |
|
162 KErrNotFound if aId is not a known setting ID |
|
163 KErrArgument if the setting identified is not the correct type |
|
164 KErrNotReady if the HCR is used before it has been initialised |
|
165 KErrCorrupt if HCR finds a repository to be corrupt |
|
166 KErrTooBig if the setting is larger than the supplied buffer |
|
167 KErrGeneral if an internal failure occurs, see trace |
|
168 Otherwise one of the other system-wide error codes. |
|
169 |
|
170 @pre Call from thread context, during Init1 or later |
|
171 */ |
|
172 IMPORT_C TInt GetData(const TSettingId& aId, TDes8& aValue); |
|
173 IMPORT_C TInt GetData(const TSettingId& aId, TUint16 aMaxLen, |
|
174 TUint8* aValue, TUint16& aLen); |
|
175 /** |
|
176 Retrieve a character string (ETypeText8) setting from the HCR. |
|
177 |
|
178 @param aId The setting identifier |
|
179 @param aMaxLen The maximum value length that can be stored in the buffer |
|
180 @param aValue A pointer to the buffer or a descriptor to hold the value |
|
181 @param aLen Contains the length of the setting value written |
|
182 |
|
183 @return KErrNone if successful and aValue has been set |
|
184 KErrNotFound if aId is not a known setting ID |
|
185 KErrArgument if the setting identified is not the correct type |
|
186 KErrNotReady if the HCR is used before it has been initialised |
|
187 KErrCorrupt if HCR finds a repository to be corrupt |
|
188 KErrTooBig if the setting is larger than the supplied buffer |
|
189 KErrGeneral if an internal failure occurs, see trace |
|
190 Otherwise one of the other system-wide error codes. |
|
191 |
|
192 @pre Call from thread context, during Init1 or later |
|
193 */ |
|
194 IMPORT_C TInt GetString(const TSettingId& aId, TDes8& aValue); |
|
195 IMPORT_C TInt GetString(const TSettingId& aId, TUint16 aMaxLen, |
|
196 TText8* aValue, TUint16& aLen); |
|
197 |
|
198 /** |
|
199 Retrieve an array setting from the HCR. All value length paramters are |
|
200 measured in bytes. |
|
201 |
|
202 @param aId The setting identifier |
|
203 @param aMaxLen The maximum value length that can be stored in the buffer |
|
204 @param aValue A pointer to the buffer to hold the value |
|
205 @param aLen Contains the length of the setting value written |
|
206 |
|
207 @return KErrNone if successful and aValue has been set |
|
208 KErrNotFound if aId is not a known setting ID |
|
209 KErrArgument if the setting identified is not the correct type |
|
210 KErrNotReady if the HCR is used before it has been initialised |
|
211 KErrCorrupt if HCR finds a repository to be corrupt |
|
212 KErrTooBig if the setting is larger than the supplied buffer |
|
213 KErrGeneral if an internal failure occurs, see trace |
|
214 Otherwise one of the other system-wide error codes. |
|
215 |
|
216 @pre Call from thread context, during Init1 or later |
|
217 */ |
|
218 IMPORT_C TInt GetArray(const TSettingId& aId, TUint16 aMaxLen, |
|
219 TInt32* aValue, TUint16& aLen); |
|
220 IMPORT_C TInt GetArray(const TSettingId& aId, TUint16 aMaxLen, |
|
221 TUint32* aValue, TUint16& aLen); |
|
222 |
|
223 /** |
|
224 Retrieve multiple simple settings from the Hardware Configuration |
|
225 Repository in one call. This method can be used for all settings of size 4 |
|
226 bytes or less (i.e those with a type in 0x0000ffff). |
|
227 |
|
228 @param aNum in: The number of settings to retrieve. It is also the |
|
229 size of the arrays in the following arguments |
|
230 @param aIds in: An ordered array of setting identifiers to retrieve, lowest first |
|
231 @param aValues out: An array of values, populated on exit |
|
232 @param aTypes out: An optional array of type enumerations describing |
|
233 the type of each setting found. May be 0 if client is |
|
234 not interested |
|
235 @param aErrors out: A mandatory array supplied by the user which is populated by error |
|
236 codes for each setting. If no error found for the setting then |
|
237 KErrNone(=0) is written |
|
238 setting. |
|
239 Possible error codes: |
|
240 KErrArgument if the setting has size larger than |
|
241 four bytes |
|
242 KErrNotFound if the setting is not found |
|
243 KErrNone no any errors reported for this setting |
|
244 |
|
245 |
|
246 @return Zero or positive number of settings found, -ve on error |
|
247 KErrArgument if some parameters are wrong(i.e. aErrors is a null |
|
248 pointer, aNum is negative and so on) |
|
249 KErrCorrupt if HCR finds a repository to be corrupt |
|
250 KErrGeneral if an internal failure occurs, see trace |
|
251 KErrNotReady if the HCR is used before it has been initialised |
|
252 KErrNoMemory if the memory allocation within this function failed |
|
253 Otherwise one of the other system-wide error codes. |
|
254 |
|
255 @pre Call from thread context, during Init1 or later |
|
256 */ |
|
257 IMPORT_C TInt GetWordSettings(TInt aNum, const SSettingId aIds[], |
|
258 TInt32 aValues[], TSettingType aTypes[], TInt aErrors[]); |
|
259 |
|
260 |
|
261 /** |
|
262 Retrieve the type and size of a HCR setting. Can be used by clients to |
|
263 obtain the setting size if a dynamic buffer is to be used. |
|
264 |
|
265 @param aId The setting identifier |
|
266 @param aType The type enumeration of found setting |
|
267 @param aLen The length in bytes of found setting |
|
268 |
|
269 @return KErrNone if successful, output parameters valid |
|
270 KErrNotFound if aId is not a known setting ID |
|
271 KErrNotReady if the HCR is used before it has been initialised |
|
272 KErrCorrupt if HCR finds a repository to be corrupt |
|
273 KErrGeneral if an internal failure occurs, see trace |
|
274 Otherwise one of the other system-wide error codes. |
|
275 |
|
276 @pre Call from thread context, during Init1 or later |
|
277 */ |
|
278 IMPORT_C TInt GetTypeAndSize(const TSettingId& aId, |
|
279 TSettingType& aType, TUint16& aLen); |
|
280 |
|
281 /** |
|
282 Retrieve the number of settings held in the HCR for one particular category. |
|
283 It allows a client to perpare buffers for other calls to the HCR to |
|
284 retrieve these settings. |
|
285 This search method will return the total number of setting records found |
|
286 across all HCR repositories for a given category. It does not apply the |
|
287 override rules of other routines meaning that it counts duplicates to |
|
288 maintain performance. |
|
289 |
|
290 @param aCatUid in: The setting identifier category to use in the search |
|
291 |
|
292 @return Zero or positive number of settings found in category, -ve on error |
|
293 KErrNotReady if the HCR is used before it has been initialised |
|
294 KErrCorrupt if HCR finds a repository to be corrupt |
|
295 KErrGeneral if an internal failure occurs, see trace |
|
296 Otherwise one of the other system-wide error codes. |
|
297 |
|
298 @pre Call from thread context, during Init1 or later |
|
299 */ |
|
300 IMPORT_C TInt FindNumSettingsInCategory (TCategoryUid aCatUid); |
|
301 |
|
302 /** |
|
303 Retrieve all the setting ids, types and sizes in one particular |
|
304 category. Can be used by clients to obtain the number, size and types of |
|
305 all the settings in a category. It allows a client to alloc buffers for |
|
306 other calls to the HCR to retrieve these settings should any be larger than |
|
307 4 bytes. |
|
308 |
|
309 @param aCatUid in: The setting identifier category to use in the search |
|
310 @param aMaxNum in: The maximum number of settings to return. It is also |
|
311 the size of the arrays in the following arguments |
|
312 @param aKeyIds inout: Client supplied array populated on exit. Large |
|
313 enough to hold all elements in category. |
|
314 @param aTypes inout: Client supplied array populated with setting types |
|
315 enumerations on exit. May be 0 if client is |
|
316 not interested. |
|
317 @param aLens inout: Client supplied array populated with setting lengths |
|
318 on exit. May be 0 if client is not interested. |
|
319 |
|
320 @return Zero or positive number of settings found in category, -ve on error |
|
321 KErrArgument if some parameters are wrong(i.e. aErrors is a null |
|
322 pointer, aNum is negative and so on) |
|
323 KErrNotReady if the HCR is used before it has been initialised |
|
324 KErrCorrupt if HCR finds a repository to be corrupt |
|
325 KErrGeneral if an internal failure occurs, see trace |
|
326 Otherwise one of the other system-wide error codes. |
|
327 |
|
328 @pre Call from thread context, during Init1 or later |
|
329 */ |
|
330 IMPORT_C TInt FindSettings(TCategoryUid aCatUid, TInt aMaxNum, |
|
331 TElementId aKeyIds[], TSettingType aTypes[], TUint16 aLens[]); |
|
332 |
|
333 /** |
|
334 Finds multiple settings in the Hardware Configuration Repository who's |
|
335 setting ID matches the supplied search bit pattern. This method is useful |
|
336 for categories that contain structured settings i.e. row/column structured |
|
337 or record based categories as might be the case with hardware service |
|
338 providers. |
|
339 |
|
340 The caller supplies the category to search, an element ID mask and the |
|
341 pattern to match. SettingIDs that satisfy this logic are returned: |
|
342 ((elementID & aElementMask) == (aPattern & aElementMask)) |
|
343 |
|
344 For example, a set of driver capability structures might be encoded into |
|
345 an element ID where the 24 MSb are the row/record number and the 8 LSb |
|
346 are the column/field index. Thus to retrieve all fields in row 2 supply: |
|
347 aElemMask = 0xffffff00, aPattern = 0x000002** |
|
348 to retrieve key fields of all records supply: |
|
349 aElemMask = 0x000000ff, aPattern = 0x******01 |
|
350 (* = dont care) |
|
351 |
|
352 @param aCat in: The category to retrieve settings for |
|
353 @param aMaxNum in: The maximum number of settings to retrieve. It is also |
|
354 the size of the arrays in the following arguments |
|
355 @param aElemMask in: The bits in the Element ID to be checked against |
|
356 aPattern |
|
357 @param aPattern in: Identified the bits that must be set for a |
|
358 setting to be returned in the search |
|
359 @param aKeyIds inout: Client supplied array populated on exit. Large |
|
360 enough to hold aMaxNum element ids. |
|
361 @param aTypes inout: Client supplied array populated with setting types |
|
362 enumerations on exit. May be 0 if client is |
|
363 not interested. |
|
364 @param aLen inout: Client supplied array populated with setting lengths |
|
365 on exit. May be 0 if client is not interested. |
|
366 |
|
367 @return Zero or positive number of settings found in category, -ve on error |
|
368 KErrArgument if some parameters are wrong(i.e. aErrors is a null |
|
369 pointer, aNum is negative and so on) |
|
370 KErrNotReady if the HCR is used before it has been initialised |
|
371 KErrCorrupt if HCR finds a repository to be corrupt |
|
372 KErrGeneral if an internal failure occurs, see trace |
|
373 KErrNoMemory if the memory allocation within this function failed |
|
374 Otherwise one of the other system-wide error codes. |
|
375 |
|
376 |
|
377 @pre Call from thread context, during Init1 or later |
|
378 */ |
|
379 IMPORT_C TInt FindSettings(TCategoryUid aCat, TInt aMaxNum, |
|
380 TUint32 aMask, TUint32 aPattern, TElementId aKeyIds[], |
|
381 TSettingType aTypes[], TUint16 aLens[]); |
|
382 |
|
383 } |
|
384 |
|
385 #endif // HCR_H |
|
386 |