sl@0: // Copyright (c) 2004-2009 Nokia Corporation and/or its subsidiary(-ies). sl@0: // All rights reserved. sl@0: // This component and the accompanying materials are made available sl@0: // under the terms of "Eclipse Public License v1.0" sl@0: // which accompanies this distribution, and is available sl@0: // at the URL "http://www.eclipse.org/legal/epl-v10.html". sl@0: // sl@0: // Initial Contributors: sl@0: // Nokia Corporation - initial contribution. sl@0: // sl@0: // Contributors: sl@0: // sl@0: // Description: sl@0: // sl@0: sl@0: #include "clirep.h" sl@0: sl@0: /** Creates a CRepository object for accessing a repository. sl@0: If there is no such repository, the function leaves with KErrNotFound. sl@0: A pointer to the object is left on the cleanup stack. sl@0: @param aRepositoryUid The UID of the repository to be accessed sl@0: @return A pointer to a newly created CRepository object sl@0: */ sl@0: EXPORT_C CRepository* CRepository::NewLC(TUid aRepositoryUid) sl@0: { sl@0: return CClientRepository::NewLC(aRepositoryUid); sl@0: } sl@0: sl@0: sl@0: /** Creates a CRepository object for accessing a repository. sl@0: If there is no such repository, the function leaves with KErrNotFound. sl@0: @param aRepositoryUid The UID of the repository to be accessed sl@0: @return A pointer to a newly created CRepository object sl@0: */ sl@0: EXPORT_C CRepository* CRepository::NewL(TUid aRepositoryUid) sl@0: { sl@0: CRepository* rep = CRepository::NewLC(aRepositoryUid); sl@0: CleanupStack::Pop(); sl@0: return rep; sl@0: } sl@0: sl@0: sl@0: /** Destructor. sl@0: */ sl@0: EXPORT_C CRepository::~CRepository() sl@0: { sl@0: } sl@0: sl@0: sl@0: /** Creates a new setting with an integer value. sl@0: @param aKey New setting key. sl@0: @param aValue Setting value. sl@0: @return sl@0: KErrNone if successful, sl@0: KErrAbort if in a transaction that has previously failed sl@0: KErrPermissionDenied if caller fails capability check, sl@0: KErrAlreadyExists if a setting with that key already exists sl@0: plus other system-wide error codes. sl@0: @post sl@0: Transactions fail on all error conditions. sl@0: Outside transactions: on success the new setting is persistent, sl@0: on failure the repository is unmodified. sl@0: @capability Dependent Caller must satisfy the write access policy of that key in the repository. sl@0: */ sl@0: EXPORT_C TInt CRepository::Create(TUint32 aKey, TInt aValue) sl@0: { sl@0: return (static_cast(this))->Create(aKey, aValue); sl@0: } sl@0: sl@0: sl@0: /** Creates a new setting with a floating-point value. sl@0: @param aKey New setting key. sl@0: @param aValue Setting value. sl@0: @return sl@0: KErrNone if successful, sl@0: KErrAbort if in a transaction that has previously failed sl@0: KErrPermissionDenied if caller fails capability check, sl@0: KErrAlreadyExists if a setting with that key already exists sl@0: plus other system-wide error codes. sl@0: @post sl@0: Transactions fail on all error conditions. sl@0: Outside transactions: on success the new setting is persistent, sl@0: on failure the repository is unmodified. sl@0: @capability Dependent Caller must satisfy the write access policy of that key in the repository. sl@0: */ sl@0: EXPORT_C TInt CRepository::Create(TUint32 aKey, const TReal& aValue) sl@0: { sl@0: return (static_cast(this))->Create(aKey, aValue); sl@0: } sl@0: sl@0: sl@0: /** Creates a new setting with a descriptor value. sl@0: @param aKey New setting key. sl@0: @param aValue Setting value. sl@0: @return sl@0: KErrNone if successful, sl@0: KErrAbort if in a transaction that has previously failed sl@0: KErrPermissionDenied if caller fails capability check, sl@0: KErrAlreadyExists if a setting with that key already exists sl@0: KErrArgument if the descriptor is longer than KMaxBinaryLength, sl@0: plus other system-wide error codes. sl@0: @post sl@0: Transactions fail on all error conditions. sl@0: Outside transactions: on success the new setting is persistent, sl@0: on failure the repository is unmodified. sl@0: @capability Dependent Caller must satisfy the write access policy of that key in the repository. sl@0: */ sl@0: EXPORT_C TInt CRepository::Create(TUint32 aKey, const TDesC8& aValue) sl@0: { sl@0: return (static_cast(this))->Create(aKey, aValue); sl@0: } sl@0: sl@0: /** Creates a new setting with a descriptor value. sl@0: @param aKey New setting key. sl@0: @param aValue Setting value. sl@0: @return sl@0: KErrNone if successful, sl@0: KErrAbort if in a transaction that has previously failed sl@0: KErrPermissionDenied if caller fails capability check, sl@0: KErrAlreadyExists if a setting with that key already exists sl@0: KErrArgument if the descriptor is longer than KMaxUnicodeStringLength, sl@0: plus other system-wide error codes. sl@0: @post sl@0: Transactions fail on all error conditions. sl@0: Outside transactions: on success the new setting is persistent, sl@0: on failure the repository is unmodified. sl@0: @capability Dependent Caller must satisfy the write access policy of that key in the repository. sl@0: */ sl@0: EXPORT_C TInt CRepository::Create(TUint32 aKey, const TDesC16& aValue) sl@0: { sl@0: return (static_cast(this))->Create(aKey, aValue); sl@0: } sl@0: sl@0: /** Deletes a setting. sl@0: @param aKey Key of setting to be deleted. sl@0: @return sl@0: KErrNone if successful, sl@0: KErrAbort if in a transaction that has previously failed sl@0: KErrPermissionDenied if caller fails capability check, sl@0: KErrNotFound if the setting does not exist, sl@0: plus other system-wide error codes. sl@0: @post sl@0: Transactions fail on all error conditions except KErrNotFound. sl@0: Outside transactions: on success the deletion of the setting is persistent, sl@0: on failure the repository is unmodified. sl@0: @capability Dependent Caller must satisfy the write access policy for that key in the repository sl@0: */ sl@0: EXPORT_C TInt CRepository::Delete(TUint32 aKey) sl@0: { sl@0: return (static_cast(this))->Delete(aKey); sl@0: } sl@0: sl@0: /** Deletes all the settings that exist and match the specification: sl@0: (key & mask) == (partialKey & mask) sl@0: Partial key is guaranteed to be masked before use. sl@0: Examples of use: sl@0: - To delete a single key. sl@0: Delete(key, 0xFFFFFFFF, errorKey); sl@0: - To delete all keys from 0 to 0xFF: sl@0: Delete(0, 0xFFFFFF00, errorKey); sl@0: (digits from 0 to 0xFF would be ignored if given in the partial key) sl@0: - To delete all keys matching 0x5B??3A?6: sl@0: Delete(0x5B003A06, 0xFF00FF0F, errorKey); sl@0: sl@0: @param aPartialKey sl@0: Contains a bit pattern that all the keys must at least partially sl@0: match. sl@0: @param aMask sl@0: Has bits set for all the bits in aPartialKey that must match the keys being deleted. sl@0: @param aErrorKey If the delete operation fails this contains the key involved in the sl@0: failure, or aPartialKey or KUnspecifiedKey if it could not be attributed to any key sl@0: @return sl@0: KErrNone if successful, sl@0: KErrAbort if in a transaction that has previously failed sl@0: KErrNotFound if no items were found in the partial key range. sl@0: KErrPermissionDenied if caller fails capability check. sl@0: plus other system-wide error codes. sl@0: @post sl@0: Transactions fail on all error conditions except KErrNotFound sl@0: Outside transactions: on success the changes are persistent, on failure the sl@0: repository is unmodified. sl@0: @capability Dependent Caller must satisfy the write policies of all settings found in the sl@0: partial key range. sl@0: */ sl@0: EXPORT_C TInt CRepository::Delete (TUint32 aPartialKey, TUint32 aMask, TUint32 &aErrorKey) sl@0: { sl@0: return (static_cast(this))->Delete(aPartialKey, aMask, aErrorKey); sl@0: } sl@0: sl@0: sl@0: /** Reads an integer setting. sl@0: @param aKey Key of setting to be read. sl@0: @param aValue Returns the value of the setting if it is an integer. sl@0: @return sl@0: KErrNone if successful, sl@0: KErrAbort if in a transaction that has previously failed sl@0: KErrPermissionDenied if caller fails capability check, sl@0: KErrNotFound if the setting does not exist, sl@0: KErrArgument if the setting exists but is not an integer, sl@0: plus other system-wide error codes. sl@0: @post Transactions fail only on those "other system-wide error codes". sl@0: @capability Dependent Caller must satisfy the read access policy of that key in the repository. sl@0: */ sl@0: EXPORT_C TInt CRepository::Get(TUint32 aKey, TInt& aValue) sl@0: { sl@0: return (static_cast(this))->Get(aKey, aValue); sl@0: } sl@0: sl@0: sl@0: /** Sets an existing integer setting to a new value or creates a new setting sl@0: with an integer value if the setting doesn't exist. sl@0: @param aKey Key of setting to be written to. sl@0: @param aValue Value to be written. sl@0: @return sl@0: KErrNone if successful, sl@0: KErrAbort if in a transaction that has previously failed sl@0: KErrPermissionDenied if caller fails capability check, sl@0: KErrArgument if the setting exists but is not an integer sl@0: plus other system-wide error codes. sl@0: @post sl@0: Transactions fail on all error conditions. sl@0: Outside transactions: on success the new value is persistent, sl@0: on failure the repository is unmodified. sl@0: @capability Dependent Caller must satisfy the write access policy of that key in the repository. sl@0: */ sl@0: EXPORT_C TInt CRepository::Set(TUint32 aKey, TInt aValue) sl@0: { sl@0: return (static_cast(this))->Set(aKey, aValue); sl@0: } sl@0: sl@0: sl@0: /** Reads a floating point setting. sl@0: @param aKey Key of setting to be read. sl@0: @param aValue Returns the value of the setting if it is a floating point value. sl@0: @return sl@0: KErrNone if successful, sl@0: KErrAbort if in a transaction that has previously failed sl@0: KErrPermissionDenied if caller fails capability check, sl@0: KErrNotFound if the setting does not exist, sl@0: KErrArgument if the setting exists but is not a floating point value, sl@0: plus other system-wide error codes. sl@0: @post Transactions fail only on those "other system-wide error codes". sl@0: @capability Dependent Caller must satisfy the read access policy of that key in the repository. sl@0: */ sl@0: EXPORT_C TInt CRepository::Get(TUint32 aKey, TReal& aValue) sl@0: { sl@0: return (static_cast(this))->Get(aKey, aValue); sl@0: } sl@0: sl@0: sl@0: /** Sets an existing floating point setting to a new value or creates a new setting sl@0: with a floating point value if the setting doesn't exist. sl@0: @param aKey Key of setting to be written to. sl@0: @param aValue Value to be written. sl@0: @return sl@0: KErrNone if successful, sl@0: KErrAbort if in a transaction that has previously failed sl@0: KErrPermissionDenied if caller fails capability check, sl@0: KErrArgument if the setting exists but is not a floating point value sl@0: plus other system-wide error codes. sl@0: @post sl@0: Transactions fail on all error conditions. sl@0: Outside transactions: on success the new value is persistent, sl@0: on failure the repository is unmodified. sl@0: @capability Dependent Caller must satisfy the write access policy of that key in the repository. sl@0: */ sl@0: EXPORT_C TInt CRepository::Set(TUint32 aKey, const TReal& aValue) sl@0: { sl@0: return (static_cast(this))->Set(aKey, aValue); sl@0: } sl@0: sl@0: sl@0: /** Reads a descriptor setting. sl@0: @param aKey Key of setting to be read. sl@0: @param aValue Returns the value of the setting if it is a descriptor. sl@0: @return sl@0: KErrNone if successful, sl@0: KErrAbort if in a transaction that has previously failed sl@0: KErrPermissionDenied if caller fails capability check, sl@0: KErrNotFound if the setting does not exist, sl@0: KErrArgument if the setting exists but is not a descriptor, sl@0: KErrOverflow if the descriptor is too small to receive the value in the repository, sl@0: plus other system-wide error codes. sl@0: @post Transactions fail only on those "other system-wide error codes". sl@0: @capability Dependent Caller must satisfy the read access policy of that key in the repository. sl@0: */ sl@0: EXPORT_C TInt CRepository::Get(TUint32 aKey, TDes8& aValue) sl@0: { sl@0: return (static_cast(this))->Get(aKey, aValue); sl@0: } sl@0: sl@0: /** Reads a descriptor setting. sl@0: @param aKey Key of setting to be read. sl@0: @param aValue Returns the value of the setting if it is a descriptor. sl@0: @param aActualLength Returns the actual length of the setting if it is a descriptor. sl@0: @return sl@0: KErrNone if successful, sl@0: KErrAbort if in a transaction that has previously failed sl@0: KErrPermissionDenied if caller fails capability check, sl@0: KErrNotFound if the setting does not exist, sl@0: KErrArgument if the setting exists but is not a descriptor, sl@0: KErrOverflow if the descriptor is too small to receive the value in the repository, sl@0: plus other system-wide error codes. sl@0: @post Transactions fail only on those "other system-wide error codes". sl@0: @capability Dependent Caller must satisfy the read access policy of that key in the repository. sl@0: */ sl@0: EXPORT_C TInt CRepository::Get(TUint32 aKey, TDes8& aValue, TInt& aActualLength) sl@0: { sl@0: return (static_cast(this))->Get(aKey, aValue, aActualLength); sl@0: } sl@0: sl@0: /** Sets an existing descriptor setting to a new value or creates a new setting sl@0: with a descriptor value if the setting doesn't exist. sl@0: @param aKey Key of setting to be written to. sl@0: @param aValue Value to be written. sl@0: @return sl@0: KErrNone if successful, sl@0: KErrAbort if in a transaction that has previously failed sl@0: KErrPermissionDenied if caller fails capability check, sl@0: KErrArgument if aValue is longer than KMaxBinaryLength or sl@0: the setting exists but is not a descriptor, sl@0: plus other system-wide error codes. sl@0: @post sl@0: Transactions fail on all error conditions. sl@0: Outside transactions: on success the new value is persistent, sl@0: on failure the repository is unmodified. sl@0: @capability Dependent Caller must satisfy the write access policy of that key in the repository. sl@0: */ sl@0: EXPORT_C TInt CRepository::Set(TUint32 aKey, const TDesC8& aValue) sl@0: { sl@0: return (static_cast(this))->Set(aKey, aValue); sl@0: } sl@0: sl@0: sl@0: /** Reads a descriptor setting. sl@0: @param aKey Key of setting to be read. sl@0: @param aValue Returns the value of the setting if it is a descriptor. sl@0: @return sl@0: KErrNone if successful, sl@0: KErrAbort if in a transaction that has previously failed sl@0: KErrPermissionDenied if caller fails capability check, sl@0: KErrNotFound if the setting does not exist, sl@0: KErrArgument if the setting exists but is not a descriptor, sl@0: KErrOverflow if the descriptor is too small to receive the value in the repository, sl@0: plus other system-wide error codes. sl@0: @post Transactions fail only on those "other system-wide error codes". sl@0: @capability Dependent Caller must satisfy the read access policy of that key in the repository. sl@0: */ sl@0: EXPORT_C TInt CRepository::Get(TUint32 aKey, TDes16& aValue) sl@0: { sl@0: return (static_cast(this))->Get(aKey, aValue); sl@0: } sl@0: sl@0: /** Reads a descriptor setting. sl@0: @param aKey Key of setting to be read. sl@0: @param aValue Returns the value of the setting if it is a descriptor. sl@0: @param aActualLength Returns the actual length of the setting if it is a descriptor. sl@0: @return sl@0: KErrNone if successful, sl@0: KErrAbort if in a transaction that has previously failed sl@0: KErrPermissionDenied if caller fails capability check, sl@0: KErrNotFound if the setting does not exist, sl@0: KErrArgument if the setting exists but is not a descriptor, sl@0: KErrOverflow if the descriptor is too small to receive the value in the repository, sl@0: plus other system-wide error codes. sl@0: @post Transactions fail only on those "other system-wide error codes". sl@0: @capability Dependent Caller must satisfy the read access policy of that key in the repository. sl@0: */ sl@0: EXPORT_C TInt CRepository::Get(TUint32 aKey, TDes16& aValue, TInt& aActualLength) sl@0: { sl@0: return (static_cast(this))->Get(aKey, aValue, aActualLength); sl@0: } sl@0: sl@0: /** Sets an existing descriptor setting to a new value or creates a new setting sl@0: with a descriptor value if it doesn't exist. sl@0: @param aKey Key of setting to be written to. sl@0: @param aValue Value to be written. sl@0: @return sl@0: KErrNone if successful, sl@0: KErrAbort if in a transaction that has previously failed sl@0: KErrPermissionDenied if caller fails capability check, sl@0: KErrArgument if aValue is longer than KMaxUnicodeStringLength or sl@0: the setting exists but is not a descriptor, sl@0: plus other system-wide error codes. sl@0: @post sl@0: Transactions fail on all error conditions. sl@0: Outside transactions: on success the new value is persistent, sl@0: on failure the repository is unmodified. sl@0: @capability Dependent Caller must satisfy the write access policy of that key in the repository. sl@0: */ sl@0: EXPORT_C TInt CRepository::Set(TUint32 aKey, const TDesC16& aValue) sl@0: { sl@0: return (static_cast(this))->Set(aKey, aValue); sl@0: } sl@0: sl@0: /** Reads the metadata bound to a key sl@0: @param aKey The key sl@0: @param aMeta Returns the metadata value for the key sl@0: @return sl@0: KErrNone if successful, sl@0: KErrAbort if in a transaction that has previously failed sl@0: KErrPermissionDenied if caller fails capability check, sl@0: KErrNotFound if the setting does not exist, sl@0: plus other system-wide error codes. sl@0: @post Transactions fail only on those "other system-wide error codes". sl@0: @capability Dependent Caller must satisfy the read access policy of that key in the repository. sl@0: */ sl@0: EXPORT_C TInt CRepository::GetMeta(TUint32 aKey, TUint32& aMeta) sl@0: { sl@0: return (static_cast(this))->GetMeta(aKey, aMeta); sl@0: } sl@0: sl@0: /** Moves all the settings that exist and match the specification: sl@0: (oldkey & mask) == (sourcePartialKey & mask) sl@0: to new locations where sl@0: (newkey & mask) == (targetPartialKey & mask). sl@0: For those keys that match the source specification, those bits in the key for sl@0: which the corresponding mask bit is zero remain unchanged. All remaining bits sl@0: change from (sourcePartialKey & mask) to (targetPartialKey & mask). sl@0: Both partial keys are guaranteed to be masked before use. sl@0: Examples of use: sl@0: - To move a single key from oldKey to newKey. sl@0: Move(oldKey, newKey, 0xFFFFFFFF, errorKey); sl@0: - To move all keys from 0 to 0xFF to be from 0x100 to 0x1FF: sl@0: Move(0, 0x100, 0xFFFFFF00, errorKey); sl@0: (digits from 0 to 0xFF would be ignored if given in the partial keys) sl@0: - To move all keys matching 0x5B??3A?6 to 0xDC??44?F: sl@0: Move(0x5B003A06, 0xDC00440F, 0xFF00FF0F, errorKey); sl@0: sl@0: @param aSourcePartialKey sl@0: Contains a bit pattern that all the source keys which must at least partially sl@0: match. sl@0: @param aMask sl@0: Has bits set for all the bits in aPartialKey that must match the keys being moved. sl@0: @param aTargetPartialKey sl@0: Contains a bit pattern that all the target keys which must at least partially sl@0: match. sl@0: @param aErrorKey on failure, contains the key or partial key involved in the error sl@0: or KUnspecifiedKey if failure could not be attributed to any key. sl@0: @return sl@0: KErrNone if successful, sl@0: KErrAbort if in a transaction that has previously failed sl@0: KErrNotFound if no items were found in the source range. sl@0: KErrPermissionDenied if caller fails capability check, sl@0: KErrAlreadyExists if an existing setting is using any intended target key. sl@0: plus other system-wide error codes. sl@0: @post sl@0: Transactions fail on all error conditions except KErrNotFound. sl@0: Outside transactions: on success the changes are persistent, on failure the sl@0: repository is unmodified. sl@0: @capability Dependent Caller must satisfy the read and write policies of all settings found in the sl@0: source range, and write policies on all intended target keys. sl@0: */ sl@0: EXPORT_C TInt CRepository::Move (TUint32 aSourcePartialKey, TUint32 aTargetPartialKey, sl@0: TUint32 aMask, TUint32 &aErrorKey) sl@0: { sl@0: return (static_cast(this))->Move(aSourcePartialKey, aTargetPartialKey, aMask, aErrorKey); sl@0: } sl@0: sl@0: sl@0: /** Finds all the settings that exist and match the specification given by sl@0: aPartialKey and aMask. sl@0: Matches occur whenever (key & mask) == (partialKey & mask). sl@0: The partial key is guaranteed to be masked before use. sl@0: @param aPartialKey sl@0: Contains a bit pattern that all the keys returned must at least partially sl@0: match. sl@0: @param aMask sl@0: Has bits set for all the bits in aPartialKey that must match the returned sl@0: keys. sl@0: @param aFoundKeys All the keys found. sl@0: @return sl@0: KErrNone if successful, sl@0: KErrAbort if in a transaction that has previously failed sl@0: KErrNotFound if no items were found in the source range, sl@0: plus other system-wide error codes. sl@0: @post Transactions fail only on those "other system-wide error codes". sl@0: */ sl@0: EXPORT_C TInt CRepository::FindL(TUint32 aPartialKey, TUint32 aMask, sl@0: RArray& aFoundKeys) sl@0: { sl@0: return (static_cast(this))->FindL(aPartialKey, aMask, aFoundKeys); sl@0: } sl@0: sl@0: sl@0: /** Finds all the settings that contain a given integer and match the sl@0: specification given by aPartialKey and aMask. sl@0: @param aPartialKey sl@0: Contains a bit pattern that all the keys returned must at least partially sl@0: match. sl@0: @param aMask sl@0: Has bits set for all the bits in aPartialKey that must match the returned sl@0: keys. sl@0: @param aValue Settings for the keys found will be integers with value aValue. sl@0: @param aFoundKeys All the keys found. sl@0: For each key k in aFoundKeys, (k & aMask) == (aPartialKey & aMask) and sl@0: the setting with key k is an integer aValue. sl@0: @see FindL() sl@0: @return sl@0: KErrNone if successful, sl@0: KErrAbort if in a transaction that has previously failed sl@0: KErrPermissionDenied if caller fails capability check, sl@0: KErrNotFound if capability check passed but no matching items are found, sl@0: plus other system-wide error codes. sl@0: @post Transactions fail only on those "other system-wide error codes". sl@0: @capability Dependent Caller must satisfy the read policies of all settings found in the source range. sl@0: */ sl@0: EXPORT_C TInt CRepository::FindEqL(TUint32 aPartialKey, TUint32 aMask, sl@0: TInt aValue, RArray& aFoundKeys) sl@0: { sl@0: return (static_cast(this))->FindEqL(aPartialKey, aMask, aValue, aFoundKeys); sl@0: } sl@0: sl@0: sl@0: /** Finds all the settings that contain a given floating point value and match sl@0: the specification given by aPartialKey and aMask. sl@0: @param aPartialKey sl@0: Contains a bit pattern that all the keys returned must at least partially sl@0: match. sl@0: @param aMask sl@0: Has bits set for all the bits in aPartialKey that must match the returned sl@0: keys. sl@0: @param aValue sl@0: Settings for the keys found will be floating point values with value aValue. sl@0: @param aFoundKeys All the keys found. sl@0: For each key k in aFoundKeys, (k & aMask) == (aPartialKey & aMask) and sl@0: the setting with key k is a floating point value aValue. sl@0: @see FindL() sl@0: @return sl@0: KErrNone if successful, sl@0: KErrAbort if in a transaction that has previously failed sl@0: KErrPermissionDenied if caller fails capability check, sl@0: KErrNotFound if capability check passed but no matching items are found, sl@0: plus other system-wide error codes. sl@0: @post Transactions fail only on those "other system-wide error codes". sl@0: @capability Dependent Caller must satisfy the read policies of all settings found in the source range. sl@0: */ sl@0: EXPORT_C TInt CRepository::FindEqL(TUint32 aPartialKey, TUint32 aMask, sl@0: const TReal& aValue, RArray& aFoundKeys) sl@0: { sl@0: return (static_cast(this))->FindEqL(aPartialKey, aMask, aValue, aFoundKeys); sl@0: } sl@0: sl@0: sl@0: /** Finds all the settings that contain a given string value and match the sl@0: specification given by aPartialKey and aMask. sl@0: @param aPartialKey sl@0: Contains a bit pattern that all the keys returned must at least partially sl@0: match. sl@0: @param aMask sl@0: Has bits set for all the bits in aPartialKey that must match the returned sl@0: keys. sl@0: @param aValue sl@0: Settings for the keys found will be string values with value aValue. sl@0: @param aFoundKeys All the keys found. sl@0: For each key k in aFoundKeys, (k & aMask) == (aPartialKey & aMask) and sl@0: the setting with key k is a string value aValue. sl@0: @see FindL() sl@0: @return sl@0: KErrNone if successful, sl@0: KErrAbort if in a transaction that has previously failed sl@0: KErrPermissionDenied if caller fails capability check, sl@0: KErrNotFound if capability check passed but no matching items are found, sl@0: plus other system-wide error codes. sl@0: @post Transactions fail only on those "other system-wide error codes". sl@0: @capability Dependent Caller must satisfy the read policies of all settings found in the source range. sl@0: */ sl@0: EXPORT_C TInt CRepository::FindEqL(TUint32 aPartialKey, TUint32 aMask, sl@0: const TDesC8& aValue, RArray& aFoundKeys) sl@0: { sl@0: return (static_cast(this))->FindEqL(aPartialKey, aMask, aValue, aFoundKeys); sl@0: } sl@0: sl@0: sl@0: /** Finds all the settings that contain a given string value and match the sl@0: specification given by aPartialKey and aMask. sl@0: @param aPartialKey sl@0: Contains a bit pattern that all the keys returned must at least partially sl@0: match. sl@0: @param aMask sl@0: Has bits set for all the bits in aPartialKey that must match the returned sl@0: keys. sl@0: @param aValue sl@0: Settings for the keys found will be string values with value aValue. sl@0: @param aFoundKeys All the keys found. sl@0: For each key k in aFoundKeys, (k & aMask) == (aPartialKey & aMask) and sl@0: the setting with key k is a string value aValue. sl@0: @see FindL() sl@0: @return sl@0: KErrNone if successful, sl@0: KErrAbort if in a transaction that has previously failed sl@0: KErrPermissionDenied if caller fails capability check, sl@0: KErrNotFound if capability check passed but no matching items are found, sl@0: plus other system-wide error codes. sl@0: @post Transactions fail only on those "other system-wide error codes". sl@0: @capability Dependent Caller must satisfy the read policies of all settings found in the source range. sl@0: */ sl@0: EXPORT_C TInt CRepository::FindEqL(TUint32 aPartialKey, TUint32 aMask, sl@0: const TDesC16& aValue, RArray& aFoundKeys) sl@0: { sl@0: return (static_cast(this))->FindEqL(aPartialKey, aMask, aValue, aFoundKeys); sl@0: } sl@0: sl@0: sl@0: /** Finds all the settings that match the specification given by aPartialKey sl@0: and aMask, but are either not integer values or do not have the given value. sl@0: @param aPartialKey sl@0: Contains a bit pattern that all the keys returned must at least partially sl@0: match. sl@0: @param aMask sl@0: Has bits set for all the bits in aPartialKey that must match the returned sl@0: keys. sl@0: @param aValue sl@0: Settings for the keys found will be settings that either contain values sl@0: that are not integers or integers other than aValue. sl@0: @param aFoundKeys All the keys found. sl@0: For each key k in aFoundKeys, (k & aMask) == (aPartialKey & aMask) and sl@0: the setting with key k is either not an integer or an integer not equal to sl@0: aValue. sl@0: @see FindL() sl@0: @return sl@0: KErrNone if successful, sl@0: KErrAbort if in a transaction that has previously failed sl@0: KErrPermissionDenied if caller fails capability check, sl@0: KErrNotFound if capability check passed but no non-matching items are found, sl@0: plus other system-wide error codes. sl@0: @post Transactions fail only on those "other system-wide error codes". sl@0: @capability Dependent Caller must satisfy the read policies of all settings found in the source range. sl@0: */ sl@0: EXPORT_C TInt CRepository::FindNeqL(TUint32 aPartialKey, TUint32 aMask, sl@0: TInt aValue, RArray& aFoundKeys) sl@0: { sl@0: return (static_cast(this))->FindNeqL(aPartialKey, aMask, aValue, aFoundKeys); sl@0: } sl@0: sl@0: sl@0: /** Finds all the settings that match the specification given by aPartialKey sl@0: and aMask, but are either not floating point values or do not have the given value. sl@0: @param aPartialKey sl@0: Contains a bit pattern that all the keys returned must at least partially sl@0: match. sl@0: @param aMask sl@0: Has bits set for all the bits in aPartialKey that must match the returned sl@0: keys. sl@0: @param aValue sl@0: Settings for the keys found will be settings that either contain values sl@0: that are not floating point or floating point values other than aValue. sl@0: @param aFoundKeys All the keys found. sl@0: For each key k in aFoundKeys, (k & aMask) == (aPartialKey & aMask) and sl@0: the setting with key k is either not a floating point value or a floating sl@0: point value not equal to aValue. sl@0: @see FindL() sl@0: @return sl@0: KErrNone if successful, sl@0: KErrAbort if in a transaction that has previously failed sl@0: KErrPermissionDenied if caller fails capability check, sl@0: KErrNotFound if capability check passed but no non-matching items are found, sl@0: plus other system-wide error codes. sl@0: @post Transactions fail only on those "other system-wide error codes". sl@0: @capability Dependent Caller must satisfy the read policies of all settings found in the source range. sl@0: */ sl@0: EXPORT_C TInt CRepository::FindNeqL(TUint32 aPartialKey, TUint32 aMask, sl@0: const TReal& aValue, RArray& aFoundKeys) sl@0: { sl@0: return (static_cast(this))->FindNeqL(aPartialKey, aMask, aValue, aFoundKeys); sl@0: } sl@0: sl@0: sl@0: /** Finds all the settings that match the specification given by aPartialKey sl@0: and aMask, but are either not string values or do not match the given string. sl@0: @param aPartialKey sl@0: Contains a bit pattern that all the keys returned must at least partially sl@0: match. sl@0: @param aMask sl@0: Has bits set for all the bits in aPartialKey that must match the returned sl@0: keys. sl@0: @param aValue sl@0: Settings for the keys found will be settings that either contain values sl@0: that are not strings or strings with value other than aValue. sl@0: @param aFoundKeys All the keys found. sl@0: For each key k in aFoundKeys, (k & aMask) == (aPartialKey & aMask) and sl@0: the setting with key k is either not a string value or a string value not sl@0: equal to aValue. sl@0: @see FindL() sl@0: @return sl@0: KErrNone if successful, sl@0: KErrAbort if in a transaction that has previously failed sl@0: KErrPermissionDenied if caller fails capability check, sl@0: KErrNotFound if capability check passed but no non-matching items are found, sl@0: plus other system-wide error codes. sl@0: @post Transactions fail only on those "other system-wide error codes". sl@0: @capability Dependent Caller must satisfy the read policies of all settings found in the source range. sl@0: */ sl@0: EXPORT_C TInt CRepository::FindNeqL(TUint32 aPartialKey, TUint32 aMask, sl@0: const TDesC8& aValue, RArray& aFoundKeys) sl@0: { sl@0: return (static_cast(this))->FindNeqL(aPartialKey, aMask, aValue, aFoundKeys); sl@0: } sl@0: sl@0: /** Finds all the settings that match the specification given by aPartialKey sl@0: and aMask, but are either not string values or do not match the given string. sl@0: @param aPartialKey sl@0: Contains a bit pattern that all the keys returned must at least partially sl@0: match. sl@0: @param aMask sl@0: Has bits set for all the bits in aPartialKey that must match the returned sl@0: keys. sl@0: @param aValue sl@0: Settings for the keys found will be settings that either contain values sl@0: that are not strings or strings with value other than aValue. sl@0: @param aFoundKeys All the keys found. sl@0: For each key k in aFoundKeys, (k & aMask) == (aPartialKey & aMask) and sl@0: the setting with key k is either not a string value or a string value not sl@0: equal to aValue. sl@0: @see FindL() sl@0: @return sl@0: KErrNone if successful, sl@0: KErrAbort if in a transaction that has previously failed sl@0: KErrPermissionDenied if caller fails capability check, sl@0: KErrNotFound if capability check passed but no non-matching items are found, sl@0: plus other system-wide error codes. sl@0: @post Transactions fail only on those "other system-wide error codes". sl@0: @capability Dependent Caller must satisfy the read policies of all settings found in the source range. sl@0: */ sl@0: EXPORT_C TInt CRepository::FindNeqL(TUint32 aPartialKey, TUint32 aMask, sl@0: const TDesC16& aValue, RArray& aFoundKeys) sl@0: { sl@0: return (static_cast(this))->FindNeqL(aPartialKey, aMask, aValue, aFoundKeys); sl@0: } sl@0: sl@0: sl@0: /** Requests a notification if the value of a given setting changes. sl@0: Only one notification can be received per call to NotifyRequest. sl@0: Only one notification per setting per CRepository may be active at any one sl@0: time. sl@0: @param aKey The key setting to be informed about. sl@0: @param aStatus The object that will receive the notification. On a successful sl@0: outcome, this will contain the Uid of the changed setting. sl@0: If there is an existing notification on the same setting and same session, aStatus sl@0: will be set to KErrAlreadyExists and the return value will be KErrNone. sl@0: @return sl@0: KErrNone if successful or if aStatus is set to KErrAlreadyExists. sl@0: KErrPermissionDenied if caller fails capability check. sl@0: KErrNotFound if the requested setting does not exist. sl@0: @capability Note The caller must satisfy the relevant access policies for the repository sl@0: */ sl@0: EXPORT_C TInt CRepository::NotifyRequest(TUint32 aKey, TRequestStatus& aStatus) sl@0: { sl@0: return (static_cast(this))->NotifyRequest(aKey, aStatus); sl@0: } sl@0: sl@0: sl@0: /** Cancels a notification previously requested from the two-argument overload sl@0: of NotifyRequest. sl@0: @param aKey The parameter to the previous call to NotifyRequest to be cancelled. sl@0: @return KErrNone The method always returns KErrNone. sl@0: */ sl@0: EXPORT_C TInt CRepository::NotifyCancel(TUint32 aKey) sl@0: { sl@0: //We deliberately ignore the return value from the server and return KErrNone because sl@0: //it is incorrect for a cancel function to return an error code - if there is no sl@0: //outstanding notification then the cancel should do nothing. sl@0: (void)(static_cast(this))->NotifyCancel(aKey); sl@0: return KErrNone; sl@0: } sl@0: sl@0: sl@0: /** Cancels all uncompleted notifications from this CRepository. sl@0: @return KErrNone The method always returns KErrNone. sl@0: */ sl@0: EXPORT_C TInt CRepository::NotifyCancelAll() sl@0: { sl@0: //We deliberately ignore the return value from the server and return KErrNone because sl@0: //it is incorrect for a cancel function to return an error code - if there is no sl@0: //outstanding notification then the cancel should do nothing. sl@0: (void)(static_cast(this))->NotifyCancelAll(); sl@0: return KErrNone; sl@0: } sl@0: sl@0: sl@0: /** Requests a notification if the value of a given setting changes. sl@0: Only one notification can be received per call to NotifyRequest. sl@0: Only one notification per setting per CRepository may be active at any one sl@0: time. sl@0: @param aPartialKey The partial key setting to be informed about. sl@0: @param aMask The mask to be used with the partial key. sl@0: @param aStatus The object that will receive the notification. On a successful sl@0: outcome, this will contain the Uid of the changed setting. sl@0: On error the error code is stored in aStatus and KErrNone is returned. sl@0: @return sl@0: KErrNone The method always returns KErrNone. sl@0: @capability Note The caller must satisfy the relevant access policies for the repository sl@0: */ sl@0: EXPORT_C TInt CRepository::NotifyRequest(TUint32 aPartialKey, TUint32 aMask, sl@0: TRequestStatus& aStatus) sl@0: { sl@0: return (static_cast(this)) sl@0: ->NotifyRequest(aPartialKey, aMask, aStatus); sl@0: } sl@0: sl@0: sl@0: /** Cancels a notification previously requested from the three-argument overload sl@0: of NotifyRequest. sl@0: @param aPartialKey The parameter to the previous call to NotifyRequest to be cancelled. sl@0: @param aMask The mask to be used with the partial key sl@0: @return KErrNone The method always returns KErrNone. sl@0: */ sl@0: EXPORT_C TInt CRepository::NotifyCancel(TUint32 aPartialKey, TUint32 aMask) sl@0: { sl@0: (void)(static_cast(this))->NotifyCancel(aPartialKey, aMask); sl@0: return KErrNone; sl@0: } sl@0: sl@0: sl@0: /** Resets the whole repository to the state of the initialization file sl@0: originally used to set it up. Not currently supported in transactions. sl@0: @return sl@0: KErrNone if successful, sl@0: KErrNotSupported if this client session is in a transaction sl@0: plus other system-wide error codes. sl@0: @post Fails transaction if called when session is in one. sl@0: @capability Dependent The caller must satisfy the relevant access policies for the repository sl@0: */ sl@0: EXPORT_C TInt CRepository::Reset() sl@0: { sl@0: return (static_cast(this))->Reset(); sl@0: } sl@0: sl@0: sl@0: /** Resets the a setting within the repository to the state of the setting sl@0: described by the initialization file originally used to set the repository up. sl@0: Not currently supported in transactions. sl@0: @param aKey Key of setting to be reset. sl@0: @return sl@0: KErrNone if successful, sl@0: KErrNotSupported if this client session is in a transaction sl@0: plus other system-wide error codes. sl@0: @post Fails transaction if called when session is in one. sl@0: @capability Note The caller must satisfy the relevant access policies for the repository sl@0: */ sl@0: EXPORT_C TInt CRepository::Reset(TUint32 aKey) sl@0: { sl@0: return (static_cast(this))->Reset(aKey); sl@0: } sl@0: sl@0: sl@0: /** Attempts to starts a transaction in the given mode. sl@0: Consistency and persistence of all values read and written during the transaction sl@0: is only guaranteed after a successful return from CommitTransaction. sl@0: @param aMode transaction mode: EConcurrentReadWriteTransaction (standard), sl@0: EReadTransaction or EReadWriteTransaction. sl@0: @return KErrNone if successful - guaranteed for EConcurrentReadWriteTransaction, sl@0: KErrLocked for other transaction types if read or write locks held by other clients sl@0: prevent transaction from starting. sl@0: @see CRepository::TTransactionMode sl@0: @pre Must not be in a transaction. sl@0: @post If it returns KErrNone: in a transaction; Any other error code: not in a transaction. sl@0: @panic CENREPCLI 3 Panics client if this session is already in a transaction. sl@0: */ sl@0: EXPORT_C TInt CRepository::StartTransaction(TTransactionMode aMode) sl@0: { sl@0: return (static_cast(this))->StartTransaction(aMode); sl@0: } sl@0: sl@0: sl@0: /** Attempts to starts a transaction in the given mode asynchronously to sl@0: allow client to avoid being blocked by server activity before starting. sl@0: Consistency and persistence of all values read and written during the transaction sl@0: is only guaranteed after a successful return from CommitTransaction. sl@0: Use CancelTransaction to cancel asynchronous request. sl@0: @param aMode transaction mode: EConcurrentReadWriteTransaction (standard), sl@0: EReadTransaction or EReadWriteTransaction. sl@0: @see CRepository::TTransactionMode sl@0: @param aStatus On completion of asynchronous request: KErrNone if successful - sl@0: guaranteed for EConcurrentReadWriteTransaction unless cancelled, sl@0: KErrLocked for other transaction types if read or write locks held by other clients sl@0: prevent transaction from starting. sl@0: @pre Must not be in a transaction. sl@0: @post If it completes with KErrNone and request not cancelled: in a transaction; sl@0: Any other error code or request cancelled: not in a transaction. sl@0: @panic CENREPCLI 3 Panics client if this session is already in a transaction. sl@0: */ sl@0: EXPORT_C void CRepository::StartTransaction(TTransactionMode aMode, TRequestStatus& aStatus) sl@0: { sl@0: (static_cast(this))->StartTransaction(aMode, aStatus); sl@0: } sl@0: sl@0: sl@0: /** Commits a transaction. A successful return guarantees the consistency and sl@0: persistence of all values read and written during the transaction. sl@0: @return KErrNone on success, or error code giving first reason for failing. sl@0: If KErrLocked is returned for EConcurrentReadWriteTransaction, transaction sl@0: was interrupted by another client committing changes and should be repeated. sl@0: @param aKeyInfo sl@0: On success: returns the number of keys whose values were modified. sl@0: On failure: returns the key or partial key involved in the first error, or sl@0: KUnspecifiedKey if failure could not be attributed to any key. sl@0: @pre Must be in a transaction. sl@0: @post Not in a transaction. On success, changes have been made persistent. On failure, sl@0: transaction changes have been rolled back. sl@0: @panic CENREPCLI 4 Panics client if this session is not in a transaction. sl@0: */ sl@0: EXPORT_C TInt CRepository::CommitTransaction(TUint32& aKeyInfo) sl@0: { sl@0: return (static_cast(this))->CommitTransaction(aKeyInfo); sl@0: } sl@0: sl@0: sl@0: /** Commits a transaction asynchronously to allow client to avoid being blocked sl@0: during the persist operation and other server activity. A successful return guarantees sl@0: the consistency and persistence of all values read and written during the transaction. sl@0: Use CancelTransaction to cancel asynchronous request. sl@0: @param aKeyInfo sl@0: A descriptor to receive a TUint32 value, e.g. TTransactionKeyInfoBuf, which sl@0: client must ensure remains in scope for the duration of the asynchronous request. sl@0: On success: returns the number of keys whose values were modified. sl@0: On failure: returns the key or partial key involved in the first error, or sl@0: KUnspecifiedKey if failure could not be attributed to any key. sl@0: @see CRepository::TTransactionKeyInfoBuf sl@0: @param aStatus Completion status of asynchronous request: sl@0: On success (if not cancelled): KErrNone; sl@0: On failure: error code giving first reason for failing. sl@0: If KErrLocked is returned for EConcurrentReadWriteTransaction, transaction sl@0: was interrupted by another client committing changes and should be repeated. sl@0: @pre Must be in a transaction. sl@0: @post Cannot assume that transaction is "pending commit" as may have completed already. sl@0: Once request is complete, session is not in a transaction: on success, changes sl@0: have been made persistent; on failure, transaction changes have been rolled back. sl@0: @panic CENREPCLI 4 Panics client if this session is not in a transaction. sl@0: */ sl@0: EXPORT_C void CRepository::CommitTransaction(TDes8& aKeyInfo, TRequestStatus& aStatus) sl@0: { sl@0: (static_cast(this))->CommitTransaction(aKeyInfo, aStatus); sl@0: } sl@0: sl@0: sl@0: /** Cancels the current transaction with rollback: discards any uncommitted changes. sl@0: If the transaction is pending start or commit asynchronously, the request is sl@0: completed with KErrCancel (unless it had already completed). sl@0: @post Not in a transaction. sl@0: */ sl@0: EXPORT_C void CRepository::CancelTransaction() sl@0: { sl@0: (static_cast(this))->CancelTransaction(); sl@0: } sl@0: sl@0: sl@0: /** Pushes onto the CleanupStack a TCleanupItem that calls CancelTransaction if sl@0: activated by a Leave or PopAndDestroy. Important for releasing transaction resources sl@0: including caches and read/write locks held over the repository. sl@0: @post CleanupStack has another item on it which must be popped later with sl@0: CleanupStack::Pop() or similar. sl@0: */ sl@0: EXPORT_C void CRepository::CleanupCancelTransactionPushL() sl@0: { sl@0: (static_cast(this))->CleanupCancelTransactionPushL(); sl@0: } sl@0: sl@0: sl@0: /** Sets the active transaction to a failed state, releasing cache and locks but sl@0: keeping it open. Has no effect when not in an active transaction, including when it sl@0: has already failed or when pending asynchronous start or commit request completion. sl@0: Use in preference to CancelTransaction whenever it is inappropriate to close the sl@0: transaction at the time. sl@0: @post sl@0: If previously in an active transaction: It is marked as failed. All uncommitted sl@0: changes are discarded. Transaction resources including cache and read/write locks sl@0: are released in the repository. All subsequent operations in the transaction fail sl@0: until it is closed by CancelTransaction or CommitTransaction. CommitTransaction sl@0: will fail and return KErrAbort. sl@0: */ sl@0: EXPORT_C void CRepository::FailTransaction() sl@0: { sl@0: (static_cast(this))->FailTransaction(); sl@0: } sl@0: sl@0: sl@0: /** Pushes onto the CleanupStack a TCleanupItem that calls FailTransaction if sl@0: activated by a Leave or PopAndDestroy. sl@0: @post CleanupStack has another item on it which must be popped later with sl@0: CleanupStack::Pop() or similar. sl@0: */ sl@0: EXPORT_C void CRepository::CleanupFailTransactionPushL() sl@0: { sl@0: (static_cast(this))->CleanupFailTransactionPushL(); sl@0: }