42 |
43 |
43 // -- CLASSES ----------------------------------------------------------------- |
44 // -- CLASSES ----------------------------------------------------------------- |
44 |
45 |
45 /** |
46 /** |
46 The HCR namespace contains all the types and APIs that make up the |
47 The HCR namespace contains all the types and APIs that make up the |
47 Kernel side Hardware Configuration Repository (HCR). |
48 client API of the Kernel Hardware Configuration Repository (HCR). |
48 It provides accessor functions to settings held by the HCR and may be used by |
49 It provides accessor functions to retrieve settings held by the HCR and may be |
49 kernel side clients such as physical device drivers and other services from |
50 called by kernel components from with in thread context. |
50 thread contexts. |
51 |
51 The published Setting IDs available for use with this API can be found |
52 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 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 that clients can include to gain access to all IDs for the BSP. IDs for settings |
|
55 that are internal to a component and not used by others are defined in a file |
|
56 private to that component. |
|
57 |
|
58 The HCR supports a number of setting repositories and searches them in a defined |
|
59 order, always returns the first setting found matching the ID or criteria. |
|
60 This allows setting values to be overriden by more recent repositories created |
|
61 during platform development and product creation. |
54 */ |
62 */ |
55 namespace HCR |
63 namespace HCR |
56 { |
64 { |
57 |
65 |
58 /** Maximum length of a large setting type, in bytes */ |
66 /** Maximum length of a large setting type, in bytes */ |
118 ETypeUInt64 = 0x02000000, //!< 64bit unsigned integer |
126 ETypeUInt64 = 0x02000000, //!< 64bit unsigned integer |
119 }; |
127 }; |
120 |
128 |
121 |
129 |
122 /** |
130 /** |
123 Retrieve settings of built in types from the HCR. |
131 Retrieve a word size integer setting value from the HCR. |
124 |
132 On error aValue is undefined. |
125 @param aId The setting identifier |
133 |
126 @param aValue The retrieved setting data value |
134 @param aId in: The setting identifier |
|
135 @param aValue out: The retrieved setting data value |
127 |
136 |
128 @return KErrNone if successful, output parameters valid |
137 @return KErrNone if successful, output parameters valid |
129 KErrNotFound if aId is not a known setting ID |
138 KErrNotFound if aId is not a known setting ID |
130 KErrArgument if the setting identified is not the correct type |
139 KErrArgument if the setting identified is not the correct type |
131 KErrNotReady if the HCR is used before it has been initialised |
140 KErrNotReady if the HCR is used before it has been initialised |
138 IMPORT_C TInt GetInt(const TSettingId& aId, TInt8& aValue); |
147 IMPORT_C TInt GetInt(const TSettingId& aId, TInt8& aValue); |
139 IMPORT_C TInt GetInt(const TSettingId& aId, TInt16& aValue); |
148 IMPORT_C TInt GetInt(const TSettingId& aId, TInt16& aValue); |
140 IMPORT_C TInt GetInt(const TSettingId& aId, TInt32& aValue); |
149 IMPORT_C TInt GetInt(const TSettingId& aId, TInt32& aValue); |
141 IMPORT_C TInt GetInt(const TSettingId& aId, TInt64& aValue); |
150 IMPORT_C TInt GetInt(const TSettingId& aId, TInt64& aValue); |
142 |
151 |
|
152 /** |
|
153 Retrieve a boolean setting value from the HCR. |
|
154 On error aValue is undefined. |
|
155 |
|
156 @param aId in: The setting identifier |
|
157 @param aValue out: The retrieved setting data value |
|
158 |
|
159 @return KErrNone if successful, output parameters valid |
|
160 KErrNotFound if aId is not a known setting ID |
|
161 KErrArgument if the setting identified is not the correct type |
|
162 KErrNotReady if the HCR is used before it has been initialised |
|
163 KErrCorrupt if HCR finds a repository to be corrupt |
|
164 KErrGeneral if an internal failure occurs, see trace. |
|
165 Otherwise one of the other system-wide error codes. |
|
166 |
|
167 @pre Call from thread context, during Init1 or later |
|
168 */ |
143 IMPORT_C TInt GetBool(const TSettingId& aId, TBool& aValue); |
169 IMPORT_C TInt GetBool(const TSettingId& aId, TBool& aValue); |
144 |
170 |
|
171 /** |
|
172 Retrieve an word size unsigned integer setting value from the HCR. |
|
173 On error aValue is undefined. |
|
174 |
|
175 @param aId in: The setting identifier |
|
176 @param aValue out: The retrieved setting data value |
|
177 |
|
178 @return KErrNone if successful, output parameters valid |
|
179 KErrNotFound if aId is not a known setting ID |
|
180 KErrArgument if the setting identified is not the correct type |
|
181 KErrNotReady if the HCR is used before it has been initialised |
|
182 KErrCorrupt if HCR finds a repository to be corrupt |
|
183 KErrGeneral if an internal failure occurs, see trace. |
|
184 Otherwise one of the other system-wide error codes. |
|
185 |
|
186 @pre Call from thread context, during Init1 or later |
|
187 */ |
145 IMPORT_C TInt GetUInt(const TSettingId& aId, TUint8& aValue); |
188 IMPORT_C TInt GetUInt(const TSettingId& aId, TUint8& aValue); |
146 IMPORT_C TInt GetUInt(const TSettingId& aId, TUint16& aValue); |
189 IMPORT_C TInt GetUInt(const TSettingId& aId, TUint16& aValue); |
147 IMPORT_C TInt GetUInt(const TSettingId& aId, TUint32& aValue); |
190 IMPORT_C TInt GetUInt(const TSettingId& aId, TUint32& aValue); |
148 IMPORT_C TInt GetUInt(const TSettingId& aId, TUint64& aValue); |
191 IMPORT_C TInt GetUInt(const TSettingId& aId, TUint64& aValue); |
149 |
192 |
|
193 /** |
|
194 Retrieve a word size linear address setting value from the HCR. |
|
195 On error aValue is undefined. |
|
196 |
|
197 @param aId in: The setting identifier |
|
198 @param aValue out: The retrieved setting data value |
|
199 |
|
200 @return KErrNone if successful, output parameters valid |
|
201 KErrNotFound if aId is not a known setting ID |
|
202 KErrArgument if the setting identified is not the correct type |
|
203 KErrNotReady if the HCR is used before it has been initialised |
|
204 KErrCorrupt if HCR finds a repository to be corrupt |
|
205 KErrGeneral if an internal failure occurs, see trace. |
|
206 Otherwise one of the other system-wide error codes. |
|
207 |
|
208 @pre Call from thread context, during Init1 or later |
|
209 */ |
150 IMPORT_C TInt GetLinAddr(const TSettingId& aId, TLinAddr& aValue); |
210 IMPORT_C TInt GetLinAddr(const TSettingId& aId, TLinAddr& aValue); |
151 |
211 |
152 /** |
212 |
153 Retrieve a binary data (ETypeBinData) setting from the HCR. |
213 /** |
154 |
214 Retrieve a large binary data setting value from the HCR. The value |
155 @param aId The setting identifier |
215 is copied into the supplied descriptor buffer. |
156 @param aMaxLen The maximum value length that can be stored in the buffer |
216 On error the descriptor and output arguments have undefined values. |
157 @param aValue A pointer to the buffer or a descriptor to hold the value |
217 |
158 @param aLen Contains the length of the setting value written |
218 @param aId in: The setting identifier |
159 |
219 @param aValue inout: A pre-allocated descriptor to hold the value |
160 |
220 |
161 @return KErrNone if successful and aValue has been set |
221 @return KErrNone if successful and aValue has been set |
162 KErrNotFound if aId is not a known setting ID |
222 KErrNotFound if aId is not a known setting ID |
163 KErrArgument if the setting identified is not the correct type |
223 KErrArgument if the setting identified is not the correct type |
164 KErrNotReady if the HCR is used before it has been initialised |
224 KErrNotReady if the HCR is used before it has been initialised |
168 Otherwise one of the other system-wide error codes. |
228 Otherwise one of the other system-wide error codes. |
169 |
229 |
170 @pre Call from thread context, during Init1 or later |
230 @pre Call from thread context, during Init1 or later |
171 */ |
231 */ |
172 IMPORT_C TInt GetData(const TSettingId& aId, TDes8& aValue); |
232 IMPORT_C TInt GetData(const TSettingId& aId, TDes8& aValue); |
|
233 |
|
234 /** |
|
235 Retrieve a large binary data setting value from the HCR. The value is copied |
|
236 into the supplied byte array buffer. |
|
237 On error the buffer and output arguments have undefined values. |
|
238 |
|
239 @param aId in: The setting identifier |
|
240 @param aMaxLen in: The maximum value length that can be stored in the buffer |
|
241 @param aValue inout: The address of a pre-allocated buffer to hold the value |
|
242 @param aLen out: Contains the length of the setting value written |
|
243 |
|
244 @return KErrNone if successful and aValue has been set |
|
245 KErrNotFound if aId is not a known setting ID |
|
246 KErrArgument if the setting identified is not the correct type |
|
247 KErrNotReady if the HCR is used before it has been initialised |
|
248 KErrCorrupt if HCR finds a repository to be corrupt |
|
249 KErrTooBig if the setting is larger than the supplied buffer |
|
250 KErrGeneral if an internal failure occurs, see trace |
|
251 Otherwise one of the other system-wide error codes. |
|
252 |
|
253 @pre Call from thread context, during Init1 or later |
|
254 */ |
173 IMPORT_C TInt GetData(const TSettingId& aId, TUint16 aMaxLen, |
255 IMPORT_C TInt GetData(const TSettingId& aId, TUint16 aMaxLen, |
174 TUint8* aValue, TUint16& aLen); |
256 TUint8* aValue, TUint16& aLen); |
175 /** |
257 |
176 Retrieve a character string (ETypeText8) setting from the HCR. |
258 /** |
177 |
259 Retrieve an 8 bit character string setting from the HCR. The value |
178 @param aId The setting identifier |
260 is copied into the supplied descriptor buffer. Note the string is not zero |
179 @param aMaxLen The maximum value length that can be stored in the buffer |
261 terminated. |
180 @param aValue A pointer to the buffer or a descriptor to hold the value |
262 On error the descriptor and output arguments have undefined values. |
181 @param aLen Contains the length of the setting value written |
263 |
|
264 @param aId in: The setting identifier |
|
265 @param aValue inout: A pre-allocated descriptor to hold the value |
182 |
266 |
183 @return KErrNone if successful and aValue has been set |
267 @return KErrNone if successful and aValue has been set |
184 KErrNotFound if aId is not a known setting ID |
268 KErrNotFound if aId is not a known setting ID |
185 KErrArgument if the setting identified is not the correct type |
269 KErrArgument if the setting identified is not the correct type |
186 KErrNotReady if the HCR is used before it has been initialised |
270 KErrNotReady if the HCR is used before it has been initialised |
190 Otherwise one of the other system-wide error codes. |
274 Otherwise one of the other system-wide error codes. |
191 |
275 |
192 @pre Call from thread context, during Init1 or later |
276 @pre Call from thread context, during Init1 or later |
193 */ |
277 */ |
194 IMPORT_C TInt GetString(const TSettingId& aId, TDes8& aValue); |
278 IMPORT_C TInt GetString(const TSettingId& aId, TDes8& aValue); |
|
279 |
|
280 /** |
|
281 Retrieve an 8 bit character string setting from the HCR. The value |
|
282 is copied into the byte array buffer. Note the string is not zero |
|
283 terminated. |
|
284 On error the descriptor and output arguments have undefined values. |
|
285 |
|
286 @param aId in: The setting identifier |
|
287 @param aMaxLen in: The maximum value length that can be stored in the buffer |
|
288 @param aValue inout: The address of a pre-allocated buffer to hold the value |
|
289 @param aLen out: Contains the length of the setting value written |
|
290 |
|
291 @return KErrNone if successful and aValue has been set |
|
292 KErrNotFound if aId is not a known setting ID |
|
293 KErrArgument if the setting identified is not the correct type |
|
294 KErrNotReady if the HCR is used before it has been initialised |
|
295 KErrCorrupt if HCR finds a repository to be corrupt |
|
296 KErrTooBig if the setting is larger than the supplied buffer |
|
297 KErrGeneral if an internal failure occurs, see trace |
|
298 Otherwise one of the other system-wide error codes. |
|
299 |
|
300 @pre Call from thread context, during Init1 or later |
|
301 */ |
195 IMPORT_C TInt GetString(const TSettingId& aId, TUint16 aMaxLen, |
302 IMPORT_C TInt GetString(const TSettingId& aId, TUint16 aMaxLen, |
196 TText8* aValue, TUint16& aLen); |
303 TText8* aValue, TUint16& aLen); |
197 |
304 |
198 /** |
305 /** |
199 Retrieve an array setting from the HCR. All value length paramters are |
306 Retrieve an array of signed integers from the HCR. The value |
200 measured in bytes. |
307 is copied into the byte array buffer. |
201 |
308 On error the descriptor and output arguments have undefined values. |
202 @param aId The setting identifier |
309 |
203 @param aMaxLen The maximum value length that can be stored in the buffer |
310 @param aId in: The setting identifier |
204 @param aValue A pointer to the buffer to hold the value |
311 @param aMaxLen in: The maximum value length that can be stored in the buffer |
205 @param aLen Contains the length of the setting value written |
312 @param aValue inout: The address of a pre-allocated word array to hold the value |
|
313 @param aLen out: Contains the length, in bytes of the setting value written |
206 |
314 |
207 @return KErrNone if successful and aValue has been set |
315 @return KErrNone if successful and aValue has been set |
208 KErrNotFound if aId is not a known setting ID |
316 KErrNotFound if aId is not a known setting ID |
209 KErrArgument if the setting identified is not the correct type |
317 KErrArgument if the setting identified is not the correct type |
210 KErrNotReady if the HCR is used before it has been initialised |
318 KErrNotReady if the HCR is used before it has been initialised |
219 TInt32* aValue, TUint16& aLen); |
327 TInt32* aValue, TUint16& aLen); |
220 IMPORT_C TInt GetArray(const TSettingId& aId, TUint16 aMaxLen, |
328 IMPORT_C TInt GetArray(const TSettingId& aId, TUint16 aMaxLen, |
221 TUint32* aValue, TUint16& aLen); |
329 TUint32* aValue, TUint16& aLen); |
222 |
330 |
223 /** |
331 /** |
224 Retrieve multiple simple settings from the Hardware Configuration |
332 Retrieve multiple word sized settings from the Hardware Configuration |
225 Repository in one call. This method can be used for all settings of size 4 |
333 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). |
334 bytes or less (i.e those with a type less than 0x0000ffff). |
227 |
335 The caller is responsible for pre-allocating the arrays supplied. Note the |
|
336 array of setting IDs (aIds) supplied by the client must be ordered with |
|
337 aIds[0] containing the lowest and aIds[aNum-1] the highest. Undefined |
|
338 behaviour will result if this pre-condition is not met. |
|
339 |
|
340 On successful return the client will need to check the number found (return |
|
341 value) matches their needs and cast each value in the aValues |
|
342 array to the correct type before use. The correct type is either known at |
|
343 compile time by the caller or determined from aTypes, if supplied. |
|
344 |
|
345 When an overall error is returned from the function the output arrays have |
|
346 undefined values. |
|
347 |
228 @param aNum in: The number of settings to retrieve. It is also the |
348 @param aNum in: The number of settings to retrieve. It is also the |
229 size of the arrays in the following arguments |
349 size of the arrays in the following arguments |
230 @param aIds in: An ordered array of setting identifiers to retrieve, lowest first |
350 @param aIds in: An ordered array of setting identifiers to retrieve |
231 @param aValues out: An array of values, populated on exit |
351 @param aValues inout: An array of values, populated on exit |
232 @param aTypes out: An optional array of type enumerations describing |
352 @param aTypes inout: An optional array of type enumerations, populated on |
233 the type of each setting found. May be 0 if client is |
353 exit describing the type of each setting found. |
234 not interested |
354 May be 0 if client is not interested |
235 @param aErrors out: A mandatory array supplied by the user which is populated by error |
355 @param aErrors inout: An array of search errors for each setting populated |
236 codes for each setting. If no error found for the setting then |
356 on exit. If no error found for the setting then KErrNone |
237 KErrNone(=0) is written |
357 is written. Possible error codes: |
238 setting. |
358 KErrArgument the setting is not of a suitable type |
239 Possible error codes: |
359 KErrNotFound the setting is not found |
240 KErrArgument if the setting has size larger than |
360 KErrNone when setting found |
241 four bytes |
|
242 KErrNotFound if the setting is not found |
|
243 KErrNone no any errors reported for this setting |
|
244 |
361 |
245 |
362 |
246 @return Zero or positive number of settings found, -ve on error |
363 @return Zero or positive number of settings found, -ve on error |
247 KErrArgument if some parameters are wrong(i.e. aErrors is a null |
364 KErrArgument if some parameters are wrong(i.e. aErrors is a null |
248 pointer, aNum is negative and so on) |
365 pointer, aNum is negative and so on) |
258 TInt32 aValues[], TSettingType aTypes[], TInt aErrors[]); |
375 TInt32 aValues[], TSettingType aTypes[], TInt aErrors[]); |
259 |
376 |
260 |
377 |
261 /** |
378 /** |
262 Retrieve the type and size of a HCR setting. Can be used by clients to |
379 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. |
380 obtain the setting size should a buffer need to be allocated. |
264 |
381 On error the output arguments are undefined. |
265 @param aId The setting identifier |
382 |
266 @param aType The type enumeration of found setting |
383 @param aId in: The setting identifier |
267 @param aLen The length in bytes of found setting |
384 @param aType out: The type enumeration of the found setting |
|
385 @param aLen out: The length in bytes of the found setting |
268 |
386 |
269 @return KErrNone if successful, output parameters valid |
387 @return KErrNone if successful, output parameters valid |
270 KErrNotFound if aId is not a known setting ID |
388 KErrNotFound if aId is not a known setting ID |
271 KErrNotReady if the HCR is used before it has been initialised |
389 KErrNotReady if the HCR is used before it has been initialised |
272 KErrCorrupt if HCR finds a repository to be corrupt |
390 KErrCorrupt if HCR finds a repository to be corrupt |
277 */ |
395 */ |
278 IMPORT_C TInt GetTypeAndSize(const TSettingId& aId, |
396 IMPORT_C TInt GetTypeAndSize(const TSettingId& aId, |
279 TSettingType& aType, TUint16& aLen); |
397 TSettingType& aType, TUint16& aLen); |
280 |
398 |
281 /** |
399 /** |
282 Retrieve the number of settings held in the HCR for one particular category. |
400 Retrieve the number of unique ettings held in the HCR for one particular |
283 It allows a client to perpare buffers for other calls to the HCR to |
401 category. It allows a client to perpare buffers for other calls to the HCR |
284 retrieve these settings. |
402 to retrieve these settings. |
285 This search method will return the total number of setting records found |
403 The method carries out a search to return the total number of unique setting |
286 across all HCR repositories for a given category. It does not apply the |
404 records found across all HCR repositories for a given category. It does not |
287 override rules of other routines meaning that it counts duplicates to |
405 count settings that are duplicate from being redefined in different |
288 maintain performance. |
406 repositories. |
289 |
407 The function is particularly useful for open-ended categories were the |
|
408 run-time client can not predict the number of settings prvisioned. |
|
409 |
290 @param aCatUid in: The setting identifier category to use in the search |
410 @param aCatUid in: The setting identifier category to use in the search |
291 |
411 |
292 @return Zero or positive number of settings found in category, -ve on error |
412 @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 |
413 KErrNotReady if the HCR is used before it has been initialised |
294 KErrCorrupt if HCR finds a repository to be corrupt |
414 KErrCorrupt if HCR finds a repository to be corrupt |
298 @pre Call from thread context, during Init1 or later |
418 @pre Call from thread context, during Init1 or later |
299 */ |
419 */ |
300 IMPORT_C TInt FindNumSettingsInCategory (TCategoryUid aCatUid); |
420 IMPORT_C TInt FindNumSettingsInCategory (TCategoryUid aCatUid); |
301 |
421 |
302 /** |
422 /** |
303 Retrieve all the setting ids, types and sizes in one particular |
423 Retrieve details of all the settings (ids, types and sizes) in one |
304 category. Can be used by clients to obtain the number, size and types of |
424 particular category. This function can be used by clients to obtain the |
305 all the settings in a category. It allows a client to alloc buffers for |
425 number of, ids, sizes and types of all the settings in a category. |
306 other calls to the HCR to retrieve these settings should any be larger than |
426 It allows a client to alloc buffers for other calls to the HCR to retrieve |
307 4 bytes. |
427 the values of these settings. |
308 |
428 |
309 @param aCatUid in: The setting identifier category to use in the search |
429 On successful return the client will need to check the number found (return |
|
430 value) matches the expected number. When there are more defined in |
|
431 the category than was able to be returned, i.e. when number found |
|
432 exceeded aMaxNum then aMaxNum is returned. |
|
433 |
|
434 When an overall error is returned from the function the output arrays have |
|
435 undefined values. |
|
436 |
|
437 @param aCat in: The setting category to search for |
310 @param aMaxNum in: The maximum number of settings to return. It is also |
438 @param aMaxNum in: The maximum number of settings to return. It is also |
311 the size of the arrays in the following arguments |
439 the size of the arrays in the following arguments |
312 @param aKeyIds inout: Client supplied array populated on exit. Large |
440 @param aKeyIds inout: Client supplied array populated on exit. Large |
313 enough to hold all elements in category. |
441 enough to hold all elements in category. |
314 @param aTypes inout: Client supplied array populated with setting types |
442 @param aTypes inout: Client supplied array populated with setting types |
315 enumerations on exit. May be 0 if client is |
443 enumerations on exit. Array address may be 0 if |
316 not interested. |
444 client is not interested. |
317 @param aLens inout: Client supplied array populated with setting lengths |
445 @param aLens inout: Client supplied array populated with setting lengths |
318 on exit. May be 0 if client is not interested. |
446 on exit for those settings with a type > 0x0000ffff. |
|
447 When less than this 0 is set in the aLens array element. |
|
448 Array address may be 0 if client is not interested. |
319 |
449 |
320 @return Zero or positive number of settings found in category, -ve on error |
450 @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 |
451 KErrArgument if some parameters are wrong(i.e. aErrors is a null |
322 pointer, aNum is negative and so on) |
452 pointer, aNum is negative and so on) |
323 KErrNotReady if the HCR is used before it has been initialised |
453 KErrNotReady if the HCR is used before it has been initialised |
329 */ |
459 */ |
330 IMPORT_C TInt FindSettings(TCategoryUid aCatUid, TInt aMaxNum, |
460 IMPORT_C TInt FindSettings(TCategoryUid aCatUid, TInt aMaxNum, |
331 TElementId aKeyIds[], TSettingType aTypes[], TUint16 aLens[]); |
461 TElementId aKeyIds[], TSettingType aTypes[], TUint16 aLens[]); |
332 |
462 |
333 /** |
463 /** |
334 Finds multiple settings in the Hardware Configuration Repository who's |
464 Retrieve details of all the settings (ids, types and sizes) in one |
335 setting ID matches the supplied search bit pattern. This method is useful |
465 particular category who's key ID matches the supplied bit pattern/mask. |
336 for categories that contain structured settings i.e. row/column structured |
466 This function can be used by clients to obtain the number of, ids, sizes |
337 or record based categories as might be the case with hardware service |
467 and types of all the settings in a category. It allows a client to alloc |
338 providers. |
468 buffers for other calls to the HCR to retrieve the values of these settings. |
339 |
469 |
340 The caller supplies the category to search, an element ID mask and the |
470 This search method allows categories to contain structured settings |
341 pattern to match. SettingIDs that satisfy this logic are returned: |
471 i.e. row/column structured or record based categories as might be used |
|
472 for configuration data of a hardware service provider. |
|
473 |
|
474 The caller supplies the category to search, a setting key ID mask and the |
|
475 pattern to match. Setting keys that satisfy this logic are returned: |
342 ((elementID & aElementMask) == (aPattern & aElementMask)) |
476 ((elementID & aElementMask) == (aPattern & aElementMask)) |
343 |
477 |
344 For example, a set of driver capability structures might be encoded into |
478 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 |
479 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: |
480 are the column/field index. Thus to retrieve all fields in row 2 supply: |
347 aElemMask = 0xffffff00, aPattern = 0x000002** |
481 aElemMask = 0xffffff00, aPattern = 0x000002** |
348 to retrieve key fields of all records supply: |
482 to retrieve key fields of all records supply: |
349 aElemMask = 0x000000ff, aPattern = 0x******01 |
483 aElemMask = 0x000000ff, aPattern = 0x******01 |
350 (* = dont care) |
484 (* = dont care) |
|
485 |
|
486 On successful return the client will need to check the number found (return |
|
487 value) matches the expected number. When there are more defined in |
|
488 the category than was able to be returned, i.e. when number found |
|
489 exceeded aMaxNum then aMaxNum is returned. |
|
490 |
|
491 When an overall error is returned from the function the output arrays have |
|
492 undefined values. |
351 |
493 |
352 @param aCat in: The category to retrieve settings for |
494 @param aCat in: The category to retrieve settings for |
353 @param aMaxNum in: The maximum number of settings to retrieve. It is also |
495 @param aMaxNum in: The maximum number of settings to retrieve. It is also |
354 the size of the arrays in the following arguments |
496 the size of the arrays in the following arguments |
355 @param aElemMask in: The bits in the Element ID to be checked against |
497 @param aMask in: The bits in the Element ID to be checked against |
356 aPattern |
498 aPattern |
357 @param aPattern in: Identified the bits that must be set for a |
499 @param aPattern in: Identified the bits that must be set for a |
358 setting to be returned in the search |
500 setting to be returned in the search |
359 @param aKeyIds inout: Client supplied array populated on exit. Large |
501 @param aKeyIds inout: Client supplied array populated on exit. Large |
360 enough to hold aMaxNum element ids. |
502 enough to hold aMaxNum element ids. |
361 @param aTypes inout: Client supplied array populated with setting types |
503 @param aTypes inout: Client supplied array populated with setting types |
362 enumerations on exit. May be 0 if client is |
504 enumerations on exit. Array address may be 0 if |
363 not interested. |
505 client is not interested. |
364 @param aLen inout: Client supplied array populated with setting lengths |
506 @param aLens inout: Client supplied array populated with setting lengths |
365 on exit. May be 0 if client is not interested. |
507 on exit for those settings with a type > 0x0000ffff. |
|
508 When less than this 0 is set in the aLens array element. |
|
509 Array address may be 0 if client is not interested. |
366 |
510 |
367 @return Zero or positive number of settings found in category, -ve on error |
511 @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 |
512 KErrArgument if some parameters are wrong(i.e. aErrors is a null |
369 pointer, aNum is negative and so on) |
513 pointer, aNum is negative and so on) |
370 KErrNotReady if the HCR is used before it has been initialised |
514 KErrNotReady if the HCR is used before it has been initialised |