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".
8 // Initial Contributors:
9 // Nokia Corporation - initial contribution.
14 // Hardware Configuration Respoitory Platform Independent Layer (PIL)
15 // Contains internal definitions for the PIL software of the HCR component
16 // which includes the singleton class that contains the algorithms and the
17 // TRepository hierachy that encapsulated the repository data in all its forms
18 // hiding the specifics from the algoritms in the singleton HCRInternal object.
23 Kernel side definitions for the HCR Platform Independent Layer.
32 // -- INCLUDES ----------------------------------------------------------------
41 // -- CLASSES -----------------------------------------------------------------
49 /**< Mask for testing for word size settings */
50 static const TInt KMaskWordTypes = 0x0000FFFF;
52 /**< Mask for testing for large settings */
53 static const TInt KMaskLargeTypes = 0xFFFF0000;
57 * Class implements the reference to the setting, it consists of two
58 * pointers to the repository where the setting is set and to the setting
66 * Default C++ constructor. It initiates the reference class
67 * object with the reference structure data.
68 * @param aSetRef Reference Setting data
71 {iRep = NULL; iSet = NULL;}
74 * C++ constructor. It initiates the the reference class object
75 * @param aRepos Pointer to the settings repository
76 * @param aSetting Pointer to the setting
78 TSettingRef(TRepository* aRepos, SSettingBase* aSetting)
79 { iRep = aRepos; iSet = aSetting; }
90 /**< Pointer to the repository*/
92 /**< Pointer to the setting*/
97 //Disable WINS (old Visual C++) warning
98 #pragma warning(disable:4284)
100 * Internal HCR, SafeArray (TSa) class.
101 * Safe Array implementation is based on a smart pointer
102 * pattern which wraps the pointer by the template class and give it a new
103 * flavour. In this case it guarantees that the heap allocated array
104 * associated with the class instance variable pointer will be deallocated
105 * during stack unwinding.
107 * Please don't instantiate this class on the heap as this will break the
108 * functionality of this class. Operator [] does not check the boundary of
109 * the array, consider safe array implementation as a simple replacement of
110 * standard pointer with all its drawbacks.
113 template <typename T>
118 * Default constructor.
119 * During initialization it sets the member variable pointer iSa
122 inline TSa() :iSa(NULL){}
126 * operator()() returns an address to the array
127 * maintained by this SafeArray object.
128 * It can be usefull when it's necessary to get the pointer
129 * value, for instance passing as function parameter.
130 * @return Pointer to the first element of the
131 * maintained array of elements of type T.
134 inline T* operator ()(){return iSa;}
137 * operator=() changes the memory ownership by
138 * reinitiazing SafeArray class object with the address to
139 * already allocated array. The original heap allocation
140 * associated with this SafeArray object is deallocated before
141 * reassignment. It's implemented in hcr_pil.cpp.
142 * @param aP Pointer to the already allocated array of
143 * elements of the type T.
144 * @return Reference to (*this) object.
146 TSa<T>& operator=(T* aP);
150 * operator[]() returns the reference to the element of
151 * array maintained by this SafeArray object at position defined
152 * by aIndex function parameter.
153 * @param aIndex Position of the element within SafeArray
154 * @return Reference to the element from the array
156 inline T& operator[](TInt aIndex){return *(iSa + aIndex);}
167 * Copy constructor must not be called explicitly by the
170 inline TSa(TSa& aSa);
173 /**< Pointer to the allocated heap array*/
176 #pragma warning(default:4284)
180 * Internal HCR class, object of this class is created by the kernel
181 * when the kernel extensions are loaded and initialized.
188 * Internal HCR states
192 EStatUndef = 0x00000000,
193 EStatNotReady = 0x00010000,
194 EStatConstructed = EStatNotReady + 0x0001,
195 EStatVariantInitialised = EStatNotReady + 0x0002,
196 EStatInitialised = EStatNotReady + 0x0004,
198 EStatReady = 0x00020000,
200 EStatFailed = 0x00800000,
202 EStatMajornMask = 0xFFFF0000,
203 EStatMinorMask = 0x0000FFFF
215 * Default C++ constructor.
220 * C++ constructor with passing MVariant object for further
221 * instance variable initialization.
223 HCRInternal(HCR::MVariant* aVar);
231 * The method initializes internal instance variable pointers
232 * to the addresses of repositories by getting them via call to Variant
233 * object functional API.
235 * - KErrNone No errors reported
236 * - KErrGeneral Internal HCR fault
237 * - KErrArgument Programming error in PSL, ptr/rc
239 * - KErrNoMemory Memory allocation failure
244 * Based on the input parameter aId it switches the selected repository
245 * to the given name. It is searching the new repository file in
246 * \sys\bin and \sys\Data respectively. It keeps the original value of
247 * the repository if the file not found.
248 * @param aFileName The zero terminated, c-style ASCII string of the
249 * new repository file without path. If the name is
250 * an empty string (NULL) the it deletes the
252 * @param aId The internal repository identifier (see TReposId)
254 * - KErrNone if successful, the selected internal repository
255 * variables point to the new HCR or the referenced
256 * repository object deleted.
257 * - KErrNotFound if the new repository file not found.
258 * - KErrNotSupported if repository identifier not supported
260 TInt SwitchRepository(const TText * aFileName, const TReposId aId=ECoreRepos);
264 * Internal HCR method checks all repositories integrity.
266 * - KErrNone Successful, no errors reported
267 * - KErrAlreadyExist Check for the setting duplicates fails
268 * - KErrCorrupt One of the repositories was found to be corrupt
269 * e.g. repository header incorrect, settings not
272 TInt CheckIntegrity();
275 * Internal HCR method returns a current HCR state.
276 * @return Current HCR composite status flag data member, @see States
282 * The method searches the given setting defined by aId parameter
283 * and with the type defined by aType parameter. Reference setting data
284 * is returned in aSetting output parameter. The search procedure is
285 * performed through all enabled repositories. It starts looking in
286 * Override first, then if setting is not found it goes to CoreImg and
287 * in the end in Variant repository.
288 * @param aId in: setting to find
289 * @param aType in: required type
290 * @param aSetting out: found setting reference data
291 * @return The following errors are returned:
292 * - KErrNone It successfuly ends, no errors are reported
293 * - KErrNotFound The setting was not found
294 * - KErrArgument The found setting type does not match the aType
296 TInt FindSetting(const TSettingId& aId, TSettingType aType,
297 TSettingRef& aSetting);
300 * Internal HCR helper method finds setting and its type.
301 * @param aId in: setting id to find
302 * @param aType out: found setting type. If the setting is
303 * not found, the returned value is set to
305 * @param aSetting out: found setting data
306 * @return The following errors can be returned:
307 * - KErrNone It successfuly ends, no errors are reported
308 * - KErrNotFound The setting was not found
310 TInt FindSettingWithType(const TSettingId& aId, TSettingType& aType,
311 TSettingRef& aSetting);
315 * Internal helper method search all the word settings provided
316 * in aIds[] settings array. The search procedure starts from Override
317 * store, if the setting is not found there, it goes through the CoreImg
318 * and finaly ends up in the Variant data.
319 * @param aNum in: number of settings to find
320 * @param aIds in: array of settings to find
321 * @param aValues out: all found settings values are written
322 * back to this array. If the setting is not found
323 * the returned setting value is set to 0
324 * @param aTypes out: If this array is provided by upper user,
325 * the setting types are written back to this array.
326 * If the element is not found, its type is set to
328 * @param aErrors out: user must always provide this array,
329 * where the method will report the search result
330 * for each individual setting. There are three
332 * - KErrNone Setting is found, no errors reported
333 * - KErrNotFound Setting is not found
334 * - KErrErrArgument Found setting has larger than
336 * @return The following errors can be returned:
337 * - Zero or positive number of settings found in category, -ve on error
338 * - KErrArgument if some parameters are wrong(i.e. aErrors is a null
339 * pointer, aNum is negative and so on)
340 * - KErrNotReady if the HCR is used before it has been initialised
341 * - KErrCorrupt if HCR finds a repository to be corrupt
342 * - KErrGeneral if an internal failure occurs, see trace
344 * @pre Caller must invoke this function inside the thread critical
345 * section to let the method finish its job. It avoids memory leak
346 * in case of possible client thread termination.
348 TInt GetWordSettings(TInt aNum, const SSettingId aIds[], TInt32 aValues[],
349 TSettingType aTypes[], TInt aErrors[]);
352 * Internal HCR method returns the number of settings in the specified
354 * @param aCatUid in: The setting identifier category to use in the
357 * - Zero or positive number of settings found in category, -ve on error
358 * - KErrNotReady if the HCR is used before it has been initialised
359 * - KErrCorrupt if HCR finds a repository to be corrupt
360 * - KErrGeneral if an internal failure occurs, see trace
362 TInt FindNumSettingsInCategory (TCategoryUid aCatUid);
366 * Internal HCR method searches all elements within the specified
368 * @param aCatUid in: The setting identifier category to use in the search
369 * @param aMaxNum in: The maximum number of settings to return. It is also
370 * the size of the arrays in the following arguments
371 * @param aElIds out: Client supplied array populated on exit. Large
372 * enough to hold all elements in category.
373 * @param aTypes out: Client supplied array populated with setting types
374 * enumerations on exit. May be 0 if client is
376 * @param aLens out: Client supplied array populated with setting lengths
377 * on exit. May be 0 if client is not interested.
379 * @return Zero or positive number of settings found in category, -ve on error
380 * - KErrArgument if some parameters are wrong(i.e. aErrors is a null
381 * pointer, aNum is negative and so on)
382 * - KErrNotReady if the HCR is used before it has been initialised
383 * - KErrCorrupt if HCR finds a repository to be corrupt
384 * - KErrGeneral if an internal failure occurs, see trace
386 TInt FindSettings(TCategoryUid aCatUid,
387 TInt aMaxNum, TElementId aIds[],
388 TSettingType aTypes[], TUint16 aLens[]);
392 * Internal HCR method finds all the settings within the specified
393 * category and which matches aMask and aPattern.
394 * @param aCat in: The category to retrieve settings for
395 * @param aMaxNum in: The maximum number of settings to retrieve. It
396 * is also the size of the arrays in the following
398 * @param aElemMask in: The bits in the Element ID to be checked against
400 * @param aPattern in: Identified the bits that must be set for a
401 * setting to be returned in the search
402 * @param aIds out: Client supplied array populated on exit. Large
403 * enough to hold aMaxNum element ids.
404 * @param aTypes out: Client supplied array populated with setting types
405 * enumerations on exit. May be 0 if client is
407 * @param aLen out: Client supplied array populated with setting
408 * lengths on exit. May be 0 if client is not interested.
410 * - Zero or positive number of settings found in category, -ve on error
411 * - KErrArgument if some parameters are wrong(i.e. aErrors is a null
412 * pointer, aNum is negative and so on)
413 * - KErrNotReady if the HCR is used before it has been initialised
414 * - KErrCorrupt if HCR finds a repository to be corrupt
415 * - KErrGeneral if an internal failure occurs, see trace
417 TInt FindSettings(TCategoryUid aCat, TInt aMaxNum,
418 TUint32 aMask, TUint32 aPattern,
419 TElementId aIds[], TSettingType aTypes[], TUint16 aLens[]);
422 /** Member holding the status of the HCR service */
425 /** Handle on the variant code in the PSL component part */
426 HCR::MVariant* iVariant;
428 /** Compiled settings in the PSL code */
429 TRepository* iVariantStore;
431 /** File settings in the core ROM image */
432 TRepository* iCoreImgStore;
434 /** File settings shadowed in RAM from NAND */
435 TRepository* iOverrideStore;
437 friend class HCRInternalTestObserver;
443 * Base Repository class. This class defines API needed to be
444 * implemented in the derived classes.
449 // Repository methods
450 virtual ~TRepository();
451 virtual TInt CheckIntegrity ()=0;
452 virtual TInt FindSetting (const TSettingId& aId, TSettingRef& aSetting)=0;
455 * Pure virtual function, must implement the search procedure for the
456 * setting in the repository within the bounds defined by aLow and aHigh
457 * parameters. It returns found setting reference data and its position.
458 * @param aId in: Setting to find
459 * @param aSetting out: Found setting reference data
460 * @param aPosition out: Position the found setting in the repository
461 * @param aLow in: Low index where to start search
462 * @param aHigh in: High index where to end search
464 * - KErrNone Successful, no errors were reported
465 * - KErrNotFound Either the repository does not have any settings,
466 * and its length is zero or the setting was not
467 * found, all output parameters are set to zeros in
470 virtual TInt FindSetting (const TSettingId& aId, TSettingRef& aSetting,
471 TInt32& aPosition, TInt32 aLow, TInt32 aHigh) = 0;
474 * Pure virtual function, must implement the word setting search
476 * @param aNum in: Number of settings to be found
477 * @param aIds in: An array of setting ids pointers to be found
478 * @param aValues out: An array of pointers to the values
479 * populated during search procedure.
480 * @param aTypes out: An array of pointers to the types populated
481 * during search procedure.
482 * @param aErrors out: An array of pointers to the errors populated
483 * during search procedure. This can be the following
485 * - KErrNone Successfuly done, no errors
487 * - KErrNotFound The setting was not found
488 * - KErrArgument The found setting type is large
491 * - KErrNone Successfuly done, no errors reported
492 * - KErrNotReady Repository is not ready
493 * - system wider error
495 virtual TInt GetWordSettings(TInt aNum, SSettingId* aIds[],
496 TInt32* aValues[], TSettingType* aTypes[],
500 * Pure virtual function, must return a reference to TSettingRef
501 * structure at specified position within the repository.
502 * @param aIndex in: Setting position(index) in the repository
503 * @param aRef out: Reference data storage
505 virtual void GetSettingRef(TInt32 aIndex, TSettingRef& aRef) = 0;
508 * Pure virtual function, must implement the search all elements within
509 * the defined category.
510 * @param aCatUid in: Category id where to search the elements
511 * @param aFirst out: Repository index where the first element is
513 * @param aLast out: Repository index where the last element is
516 * - KErrNone Successfuly done, no errors were reported
517 * - KErrNotFound No any elements were found in this category or repo-
520 virtual TInt FindNumSettingsInCategory(TCategoryUid aCatUid,
521 TInt32& aFirst, TInt32& aLast) = 0;
524 // Setting accessor methods
525 virtual TBool IsWordValue(const TSettingRef& aRef);
526 virtual TBool IsLargeValue(const TSettingRef& aRef);
527 virtual void GetId(const TSettingRef& aRef, SSettingId& aId);
528 virtual TInt32 GetType(const TSettingRef& aRef);
529 virtual TUint16 GetLength(const TSettingRef& aRef);
531 virtual void GetSettingInfo(const TSettingRef& aRef,
532 TElementId& aId, TSettingType& aType, TUint16& aLen);
535 virtual TInt GetValue(const TSettingRef& aRef, UValueWord& aValue)=0;
536 virtual TInt GetLargeValue(const TSettingRef& aRef, UValueLarge& aValue)=0;
542 * Compoiled repository class
544 class TRepositoryCompiled : public TRepository
547 static TRepository* New(const SRepositoryCompiled* aRepos);
548 virtual ~TRepositoryCompiled();
550 virtual TInt CheckIntegrity();
552 virtual TInt FindSetting(const TSettingId& aId, TSettingRef& aSetting);
555 * Pure virtual function defined in the base class TRepository,
556 * it implements the search procedure for the setting in the repository
557 * within the bounds defined by aLow and aHigh parameters. It returns
558 * found setting reference data and its position. Also @see TRepository
561 virtual TInt FindSetting (const TSettingId& aId, TSettingRef& aSetting,
562 TInt32& aPosition,TInt32 aLow, TInt32 aHigh);
566 * Pure virtual function defined in the base TRepository class,
567 * it implement the word setting search procedure. Also @see TRepository
570 virtual TInt GetWordSettings(TInt aNum, SSettingId* aIds[],
571 TInt32* aValues[], TSettingType* aTypes[], TInt* aErrors[]);
575 * This method implements returning a reference to TSettingRef
576 * structure at specified position within the repository.
578 virtual void GetSettingRef(TInt32 aIndex, TSettingRef& aRef);
581 * Pure virtual function defined in the base TRepository class,
582 * implements the search for all elements procedure withinthe defined
583 * category. Also @see TRepository for more details.
585 virtual TInt FindNumSettingsInCategory(TCategoryUid aCatUid,
586 TInt32& aFirst, TInt32& aLast);
587 virtual TInt GetValue(const TSettingRef& aRef, UValueWord& aValue);
588 virtual TInt GetLargeValue(const TSettingRef& aRef, UValueLarge& aValue);
592 TRepositoryCompiled(const SRepositoryCompiled* aRepos);
595 const SRepositoryCompiled* iRepos;
600 class TRepositoryFile : public TRepository
603 static TRepository* New(const SRepositoryFile* aRepos);
604 virtual ~TRepositoryFile();
606 virtual TInt CheckIntegrity();
607 virtual TInt FindSetting(const TSettingId& aId, TSettingRef& aSetting);
610 * Pure virtual function defined in the base class TRepository,
611 * it implements the search procedure for the setting in the repository
612 * within the bounds defined by aLow and aHigh parameters. It returns
613 * found setting reference data and its position. Also @see TRepository
616 virtual TInt FindSetting (const TSettingId& aId, TSettingRef& aSetting,
617 TInt32& aPosition, TInt32 aLow, TInt32 aHigh);
620 * Pure virtual function defined in the base TRepository class,
621 * it implement the word setting search procedure. Also @see TRepository
624 virtual TInt GetWordSettings(TInt aNum, SSettingId* aIds[],
625 TInt32* aValues[], TSettingType* aTypes[],
629 * This method implements returning a reference to TSettingRef
630 * structure at specified position within the repository.
632 virtual void GetSettingRef(TInt32 aIndex, TSettingRef& aRef);
635 * Pure virtual function defined in the base TRepository class,
636 * implements the search for all elements procedure withinthe defined
637 * category. Also @see TRepository for more details.
639 virtual TInt FindNumSettingsInCategory(TCategoryUid aCatUid,
640 TInt32& aFirst, TInt32& aLast);
641 virtual TInt GetValue(const TSettingRef& aRef, UValueWord& aValue);
642 virtual TInt GetLargeValue(const TSettingRef& aRef, UValueLarge& aValue);
645 TRepositoryFile(const SRepositoryFile* aRepos);
648 const SRepositoryFile* iRepos;
656 // -- GLOBALS -----------------------------------------------------------------
659 GLREF_C HCR::HCRInternal gHCR;
661 #define HCRSingleton (&gHCR)
663 #define HCRReady ((gHCR.GetStatus() & HCRInternal::EStatReady) == HCRInternal::EStatReady)
664 #define HCRNotReady ((gHCR.GetStatus() & HCRInternal::EStatReady) == 0)