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