91 }; |
75 }; |
92 |
76 |
93 /** The setting Identifier type. A class used to uniquely identify a |
77 /** The setting Identifier type. A class used to uniquely identify a |
94 setting in the HCR. Used in calls to HCR API. |
78 setting in the HCR. Used in calls to HCR API. |
95 */ |
79 */ |
96 class TSettingId |
80 class TSettingId : public SSettingId |
97 { |
81 { |
98 public: |
82 public: |
99 TSettingId () |
83 TSettingId () |
100 { iCat = iKey = 0; }; |
84 { iCat = iKey = 0; }; |
101 TSettingId (TCategoryUid aCat, TElementId aKey) |
85 TSettingId (TCategoryUid aCat, TElementId aKey) |
102 { iCat = aCat; iKey = aKey; }; |
86 { iCat = aCat; iKey = aKey; }; |
103 TSettingId (const SSettingId& aId) |
87 TSettingId (const SSettingId& aId) |
104 { iCat = aId.iCat; iKey = aId.iKey; }; |
88 { iCat = aId.iCat; iKey = aId.iKey; }; |
105 TSettingId& operator= (const SSettingId& rhs) |
89 TSettingId& operator= (const SSettingId& rhs) |
106 { iCat = rhs.iCat; iKey = rhs.iKey; return *this; } |
90 { iCat = rhs.iCat; iKey = rhs.iKey; return *this; } |
107 |
91 |
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 }; |
92 }; |
114 |
93 |
115 /** The setting types supported. The types are shown in two groups: Word |
94 /** 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 |
95 size - a maximum of 4 bytes; and ii) Large size - types exceeding 4 bytes |
117 in size. |
96 in size. |
150 KErrNotFound if aId is not a known setting ID |
129 KErrNotFound if aId is not a known setting ID |
151 KErrArgument if the setting identified is not the correct type |
130 KErrArgument if the setting identified is not the correct type |
152 KErrNotReady if the HCR is used before it has been initialised |
131 KErrNotReady if the HCR is used before it has been initialised |
153 KErrCorrupt if HCR finds a repository to be corrupt |
132 KErrCorrupt if HCR finds a repository to be corrupt |
154 KErrGeneral if an internal failure occurs, see trace. |
133 KErrGeneral if an internal failure occurs, see trace. |
|
134 Otherwise one of the other system-wide error codes. |
155 |
135 |
156 @pre Call from thread context, during Init1 or later |
136 @pre Call from thread context, during Init1 or later |
157 */ |
137 */ |
158 IMPORT_C TInt GetInt(const TSettingId& aId, TInt8& aValue); |
138 IMPORT_C TInt GetInt(const TSettingId& aId, TInt8& aValue); |
159 IMPORT_C TInt GetInt(const TSettingId& aId, TInt16& aValue); |
139 IMPORT_C TInt GetInt(const TSettingId& aId, TInt16& aValue); |
183 KErrArgument if the setting identified is not the correct type |
163 KErrArgument if the setting identified is not the correct type |
184 KErrNotReady if the HCR is used before it has been initialised |
164 KErrNotReady if the HCR is used before it has been initialised |
185 KErrCorrupt if HCR finds a repository to be corrupt |
165 KErrCorrupt if HCR finds a repository to be corrupt |
186 KErrTooBig if the setting is larger than the supplied buffer |
166 KErrTooBig if the setting is larger than the supplied buffer |
187 KErrGeneral if an internal failure occurs, see trace |
167 KErrGeneral if an internal failure occurs, see trace |
|
168 Otherwise one of the other system-wide error codes. |
188 |
169 |
189 @pre Call from thread context, during Init1 or later |
170 @pre Call from thread context, during Init1 or later |
190 */ |
171 */ |
191 IMPORT_C TInt GetData(const TSettingId& aId, TDes8& aValue); |
172 IMPORT_C TInt GetData(const TSettingId& aId, TDes8& aValue); |
192 IMPORT_C TInt GetData(const TSettingId& aId, TUint16 aMaxLen, |
173 IMPORT_C TInt GetData(const TSettingId& aId, TUint16 aMaxLen, |
204 KErrArgument if the setting identified is not the correct type |
185 KErrArgument if the setting identified is not the correct type |
205 KErrNotReady if the HCR is used before it has been initialised |
186 KErrNotReady if the HCR is used before it has been initialised |
206 KErrCorrupt if HCR finds a repository to be corrupt |
187 KErrCorrupt if HCR finds a repository to be corrupt |
207 KErrTooBig if the setting is larger than the supplied buffer |
188 KErrTooBig if the setting is larger than the supplied buffer |
208 KErrGeneral if an internal failure occurs, see trace |
189 KErrGeneral if an internal failure occurs, see trace |
|
190 Otherwise one of the other system-wide error codes. |
209 |
191 |
210 @pre Call from thread context, during Init1 or later |
192 @pre Call from thread context, during Init1 or later |
211 */ |
193 */ |
212 IMPORT_C TInt GetString(const TSettingId& aId, TDes8& aValue); |
194 IMPORT_C TInt GetString(const TSettingId& aId, TDes8& aValue); |
213 IMPORT_C TInt GetString(const TSettingId& aId, TUint16 aMaxLen, |
195 IMPORT_C TInt GetString(const TSettingId& aId, TUint16 aMaxLen, |
227 KErrArgument if the setting identified is not the correct type |
209 KErrArgument if the setting identified is not the correct type |
228 KErrNotReady if the HCR is used before it has been initialised |
210 KErrNotReady if the HCR is used before it has been initialised |
229 KErrCorrupt if HCR finds a repository to be corrupt |
211 KErrCorrupt if HCR finds a repository to be corrupt |
230 KErrTooBig if the setting is larger than the supplied buffer |
212 KErrTooBig if the setting is larger than the supplied buffer |
231 KErrGeneral if an internal failure occurs, see trace |
213 KErrGeneral if an internal failure occurs, see trace |
|
214 Otherwise one of the other system-wide error codes. |
232 |
215 |
233 @pre Call from thread context, during Init1 or later |
216 @pre Call from thread context, during Init1 or later |
234 */ |
217 */ |
235 IMPORT_C TInt GetArray(const TSettingId& aId, TUint16 aMaxLen, |
218 IMPORT_C TInt GetArray(const TSettingId& aId, TUint16 aMaxLen, |
236 TInt32* aValue, TUint16& aLen); |
219 TInt32* aValue, TUint16& aLen); |
238 TUint32* aValue, TUint16& aLen); |
221 TUint32* aValue, TUint16& aLen); |
239 |
222 |
240 /** |
223 /** |
241 Retrieve multiple simple settings from the Hardware Configuration |
224 Retrieve multiple simple settings from the Hardware Configuration |
242 Repository in one call. This method can be used for all settings of size 4 |
225 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). |
226 bytes or less (i.e those with a type in 0x0000ffff). |
244 |
227 |
245 @param aNum in: The number of settings to retrieve. It is also the |
228 @param aNum in: The number of settings to retrieve. It is also the |
246 size of the arrays in the following arguments |
229 size of the arrays in the following arguments |
247 @param aIds in: An ordered array of setting identifiers to retrieve, lowest first |
230 @param aIds in: An ordered array of setting identifiers to retrieve, lowest first |
248 @param aValues out: An array of values, populated on exit |
231 @param aValues out: An array of values, populated on exit |
249 @param aTypes out: An optional array of type enumerations describing |
232 @param aTypes out: An optional array of type enumerations describing |
250 the type of each setting found. May be 0 if client is |
233 the type of each setting found. May be 0 if client is |
251 not interested |
234 not interested |
252 @param aErrors out: An optional array of return codes to describe the |
235 @param aErrors out: A mandatory array supplied by the user which is populated by error |
253 result of the lookup for each setting. May be 0 if |
236 codes for each setting. If no error found for the setting then |
254 client is not interested |
237 KErrNone(=0) is written |
255 |
238 setting. |
256 @return KErrNone if successful and all values have been retrieved |
239 Possible error codes: |
257 KErrArgument if one of the arguments is incorrect. |
240 KErrArgument if the setting has size larger than |
258 KErrNotFound if one or more setting IDs is not known |
241 four bytes |
259 KErrNotReady if the HCR is used before it has been initialised |
242 KErrNotFound if the setting is not found |
260 KErrCorrupt if HCR finds a repository to be corrupt |
243 KErrNone no any errors reported for this setting |
261 KErrGeneral if an internal failure occurs, see trace |
244 |
262 KErrNotSupported if method is not supported |
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. |
263 |
254 |
264 @pre Call from thread context, during Init1 or later |
255 @pre Call from thread context, during Init1 or later |
265 */ |
256 */ |
266 IMPORT_C TInt GetWordSettings(TInt aNum, const SSettingId aIds[], |
257 IMPORT_C TInt GetWordSettings(TInt aNum, const SSettingId aIds[], |
267 TInt32 aValues[], TSettingType aTypes[], |
258 TInt32 aValues[], TSettingType aTypes[], TInt aErrors[]); |
268 TInt aErrors[]); |
259 |
269 |
260 |
270 /** |
261 /** |
271 Retrieve the type and size of a HCR setting. Can be used by clients to |
262 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. |
263 obtain the setting size if a dynamic buffer is to be used. |
273 |
264 |
278 @return KErrNone if successful, output parameters valid |
269 @return KErrNone if successful, output parameters valid |
279 KErrNotFound if aId is not a known setting ID |
270 KErrNotFound if aId is not a known setting ID |
280 KErrNotReady if the HCR is used before it has been initialised |
271 KErrNotReady if the HCR is used before it has been initialised |
281 KErrCorrupt if HCR finds a repository to be corrupt |
272 KErrCorrupt if HCR finds a repository to be corrupt |
282 KErrGeneral if an internal failure occurs, see trace |
273 KErrGeneral if an internal failure occurs, see trace |
283 KErrNotSupported if method is not supported |
274 Otherwise one of the other system-wide error codes. |
284 |
275 |
285 @pre Call from thread context, during Init1 or later |
276 @pre Call from thread context, during Init1 or later |
286 */ |
277 */ |
287 IMPORT_C TInt GetTypeAndSize(const TSettingId& aId, |
278 IMPORT_C TInt GetTypeAndSize(const TSettingId& aId, |
288 TSettingType& aType, TUint16& aLen); |
279 TSettingType& aType, TUint16& aLen); |
300 |
291 |
301 @return Zero or positive number of settings found in category, -ve on error |
292 @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 |
293 KErrNotReady if the HCR is used before it has been initialised |
303 KErrCorrupt if HCR finds a repository to be corrupt |
294 KErrCorrupt if HCR finds a repository to be corrupt |
304 KErrGeneral if an internal failure occurs, see trace |
295 KErrGeneral if an internal failure occurs, see trace |
305 KErrNotSupported if method is not supported |
296 Otherwise one of the other system-wide error codes. |
306 |
297 |
307 @pre Call from thread context, during Init1 or later |
298 @pre Call from thread context, during Init1 or later |
308 */ |
299 */ |
309 IMPORT_C TInt FindNumSettingsInCategory (TCategoryUid aCatUid); |
300 IMPORT_C TInt FindNumSettingsInCategory (TCategoryUid aCatUid); |
310 |
301 |
311 /** |
302 /** |
312 Retrieve all the setting ids, types and sizes in one particular |
303 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 |
304 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 |
305 all the settings in a category. It allows a client to alloc buffers for |
315 other calls to the HCR to retrieve these settings. |
306 other calls to the HCR to retrieve these settings should any be larger than |
|
307 4 bytes. |
316 |
308 |
317 @param aCatUid in: The setting identifier category to use in the search |
309 @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 |
310 @param aMaxNum in: The maximum number of settings to return. It is also |
319 the size of the arrays in the following arguments |
311 the size of the arrays in the following arguments |
320 |
312 @param aKeyIds inout: Client supplied array populated on exit. Large |
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. |
313 enough to hold all elements in category. |
324 @param aTypes inout: Client supplied array populated with setting types |
314 @param aTypes inout: Client supplied array populated with setting types |
325 enumerations on exit. May be 0 if client is |
315 enumerations on exit. May be 0 if client is |
326 not interested. |
316 not interested. |
327 @param aLen inout: Client supplied array populated with setting lengths |
317 @param aLens inout: Client supplied array populated with setting lengths |
328 on exit. May be 0 if client is not interested. |
318 on exit. May be 0 if client is not interested. |
329 |
319 |
330 @return Zero or positive number of settings found in category, -ve on error |
320 @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 |
321 KErrArgument if some parameters are wrong(i.e. aErrors is a null |
|
322 pointer, aNum is negative and so on) |
332 KErrNotReady if the HCR is used before it has been initialised |
323 KErrNotReady if the HCR is used before it has been initialised |
333 KErrCorrupt if HCR finds a repository to be corrupt |
324 KErrCorrupt if HCR finds a repository to be corrupt |
334 KErrGeneral if an internal failure occurs, see trace |
325 KErrGeneral if an internal failure occurs, see trace |
335 KErrNotSupported if method is not supported |
326 Otherwise one of the other system-wide error codes. |
336 |
327 |
337 @pre Call from thread context, during Init1 or later |
328 @pre Call from thread context, during Init1 or later |
338 */ |
329 */ |
339 IMPORT_C TInt FindSettings(TCategoryUid aCatUid, |
330 IMPORT_C TInt FindSettings(TCategoryUid aCatUid, TInt aMaxNum, |
340 TInt aMaxNum, TUint32& aNumFound, |
331 TElementId aKeyIds[], TSettingType aTypes[], TUint16 aLens[]); |
341 TElementId* aElIds, TSettingType* aTypes, TUint16* aLens); |
|
342 |
332 |
343 /** |
333 /** |
344 Finds multiple settings in the Hardware Configuration Repository who's |
334 Finds multiple settings in the Hardware Configuration Repository who's |
345 setting ID matches the supplied search bit pattern. This method is useful |
335 setting ID matches the supplied search bit pattern. This method is useful |
346 for categories that contain structured settings i.e. row/column structured |
336 for categories that contain structured settings i.e. row/column structured |
360 (* = dont care) |
350 (* = dont care) |
361 |
351 |
362 @param aCat in: The category to retrieve settings for |
352 @param aCat in: The category to retrieve settings for |
363 @param aMaxNum in: The maximum number of settings to retrieve. It is also |
353 @param aMaxNum in: The maximum number of settings to retrieve. It is also |
364 the size of the arrays in the following arguments |
354 the size of the arrays in the following arguments |
365 @param aAtId in: The Minimum element ID to commence the search at. |
355 @param aElemMask in: The bits in the Element ID to be checked against |
366 Used when retrieving settings in batches. |
356 aPattern |
367 @param aElemMask in: Element ID mask. |
357 @param aPattern in: Identified the bits that must be set for a |
368 @param aPattern in: Identifies the set of fieldy to return in the search. |
358 setting to be returned in the search |
369 |
359 @param aKeyIds inout: Client supplied array populated on exit. Large |
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. |
360 enough to hold aMaxNum element ids. |
373 @param aTypes inout: Client supplied array populated with setting types |
361 @param aTypes inout: Client supplied array populated with setting types |
374 enumerations on exit. May be 0 if client is |
362 enumerations on exit. May be 0 if client is |
375 not interested. |
363 not interested. |
376 @param aLen inout: Client supplied array populated with setting lengths |
364 @param aLen inout: Client supplied array populated with setting lengths |
377 on exit. May be 0 if client is not interested. |
365 on exit. May be 0 if client is not interested. |
378 |
366 |
379 @return Zero or positive number of settings found in category, -ve on error |
367 @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 |
368 KErrArgument if some parameters are wrong(i.e. aErrors is a null |
381 KErrNotReady if the HCR is used before it has been initialised |
369 pointer, aNum is negative and so on) |
382 KErrCorrupt if HCR finds a repository to be corrupt |
370 KErrNotReady if the HCR is used before it has been initialised |
383 KErrGeneral if an internal failure occurs, see trace |
371 KErrCorrupt if HCR finds a repository to be corrupt |
384 KErrNotSupported if method is not supported |
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 |
385 |
376 |
386 @pre Call from thread context, during Init1 or later |
377 @pre Call from thread context, during Init1 or later |
387 */ |
378 */ |
388 IMPORT_C TInt FindSettings(TCategoryUid aCat, |
379 IMPORT_C TInt FindSettings(TCategoryUid aCat, TInt aMaxNum, |
389 TInt aMaxNum, TUint32 aAtId, |
380 TUint32 aMask, TUint32 aPattern, TElementId aKeyIds[], |
390 TUint32 aMask, TUint32 aPattern, TUint32& aNumFound, |
381 TSettingType aTypes[], TUint16 aLens[]); |
391 TElementId* aElIds, TSettingType* aTypes, TUint16* aLens); |
|
392 |
382 |
393 } |
383 } |
394 |
384 |
395 #endif // HCR_H |
385 #endif // HCR_H |
396 |
386 |