CRepository Class Reference

#include <centralrepository.h>

Link against: centralrepository.lib

class CRepository : public CBase

Inherits from

CRepository
- CBase

Public Member Type Definitions
typedef	TPckgBuf< TUint32 > TTransactionKeyInfoBuf

Public Member Enumerations
enum	TTransactionMode { EConcurrentReadWriteTransaction, EReadTransaction, EReadWriteTransaction }

Public Member Functions
virtual	~CRepository()
IMPORT_C void	CancelTransaction()
IMPORT_C void	CleanupCancelTransactionPushL()
IMPORT_C void	CleanupFailTransactionPushL()
void	CleanupRollbackTransactionPushL()
IMPORT_C TInt	CommitTransaction(TUint32 &)
IMPORT_C void	CommitTransaction(TDes8 &, TRequestStatus &)
IMPORT_C TInt	Create(TUint32, TInt)
IMPORT_C TInt	Create(TUint32, const TReal &)
IMPORT_C TInt	Create(TUint32, const TDesC8 &)
IMPORT_C TInt	Create(TUint32, const TDesC16 &)
IMPORT_C TInt	Delete(TUint32)
IMPORT_C TInt	Delete(TUint32, TUint32, TUint32 &)
IMPORT_C void	FailTransaction()
IMPORT_C TInt	FindEqL(TUint32, TUint32, TInt, RArray< TUint32 > &)
IMPORT_C TInt	FindEqL(TUint32, TUint32, const TReal &, RArray< TUint32 > &)
IMPORT_C TInt	FindEqL(TUint32, TUint32, const TDesC8 &, RArray< TUint32 > &)
IMPORT_C TInt	FindEqL(TUint32, TUint32, const TDesC16 &, RArray< TUint32 > &)
IMPORT_C TInt	FindL(TUint32, TUint32, RArray< TUint32 > &)
IMPORT_C TInt	FindNeqL(TUint32, TUint32, TInt, RArray< TUint32 > &)
IMPORT_C TInt	FindNeqL(TUint32, TUint32, const TReal &, RArray< TUint32 > &)
IMPORT_C TInt	FindNeqL(TUint32, TUint32, const TDesC8 &, RArray< TUint32 > &)
IMPORT_C TInt	FindNeqL(TUint32, TUint32, const TDesC16 &, RArray< TUint32 > &)
IMPORT_C TInt	Get(TUint32, TInt &)
IMPORT_C TInt	Get(TUint32, TReal &)
IMPORT_C TInt	Get(TUint32, TDes8 &)
IMPORT_C TInt	Get(TUint32, TDes8 &, TInt &)
IMPORT_C TInt	Get(TUint32, TDes16 &)
IMPORT_C TInt	Get(TUint32, TDes16 &, TInt &)
IMPORT_C TInt	GetMeta(TUint32, TUint32 &)
IMPORT_C TInt	Move(TUint32, TUint32, TUint32, TUint32 &)
IMPORT_C CRepository *	NewL(TUid)
IMPORT_C CRepository *	NewLC(TUid)
IMPORT_C TInt	NotifyCancel(TUint32)
IMPORT_C TInt	NotifyCancel(TUint32, TUint32)
IMPORT_C TInt	NotifyCancelAll()
IMPORT_C TInt	NotifyRequest(TUint32, TRequestStatus &)
IMPORT_C TInt	NotifyRequest(TUint32, TUint32, TRequestStatus &)
IMPORT_C TInt	Reset()
IMPORT_C TInt	Reset(TUint32)
void	RollbackTransaction()
IMPORT_C TInt	Set(TUint32, TInt)
IMPORT_C TInt	Set(TUint32, const TReal &)
IMPORT_C TInt	Set(TUint32, const TDesC8 &)
IMPORT_C TInt	Set(TUint32, const TDesC16 &)
IMPORT_C TInt	StartTransaction(TTransactionMode)
IMPORT_C void	StartTransaction(TTransactionMode, TRequestStatus &)

Inherited Functions
	CBase::CBase()
	CBase::Delete(CBase *)
	CBase::Extension_(TUint,TAny &,TAny )
	CBase::operator new(TUint)
	CBase::operator new(TUint,TAny *)
	CBase::operator new(TUint,TLeave)
	CBase::operator new(TUint,TLeave,TUint)
	CBase::operator new(TUint,TUint)
	CBase::~CBase()

Detailed Description

Provides access to a repository.

There are potentially 2^32 repositories, each identified by a UID. Within each repository up to 2^32 settings can be stored. Settings within a repository are identified by a 32-bit key and may be of the types integer, real or descriptor.

Member Type Definition Documentation

Typedef TTransactionKeyInfoBuf

typedef TPckgBuf< TUint32 >

TTransactionKeyInfoBuf

Buffer type for aKeyInfo parameter to asynchronous CommitTransaction.

Member Enumeration Documentation

Enum TTransactionMode

Transaction mode chosen with StartTransaction.

Enumerator	Value	Description
EConcurrentReadWriteTransaction	2	Standard optimistic non-serialised transaction. Can be started at any time Commit fails with KErrLocked if another client interrupts it by first committing changes: transaction should be repeated until KErrLocked is not returned.
EReadTransaction	1	Pessimistic locking transaction intended for reading consistent values. Can only be started if EReadWriteTransaction is not in progress. Automatically promoted to EReadWriteTransaction on first write operation if no other read transaction is in progress (or fails if not attainable). Use ONLY if all clients can agree not to use EConcurrentReadWriteTransaction, and only make changes in an EReadWriteTransaction.
EReadWriteTransaction	3	Pessimistic locking transaction intended for writing values. Can only be started if no EReadTransaction or EReadWriteTransactions are in progress. Use ONLY if all clients can agree not to use EConcurrentReadWriteTransaction, and only make changes in an EReadWriteTransaction.

Constructor & Destructor Documentation

~CRepository ( )

IMPORT_C

~CRepository

(

)

[virtual]

Destructor.

Member Function Documentation

CancelTransaction ( )

IMPORT_C void

CancelTransaction

(

)

Cancels the current transaction with rollback: discards any uncommitted changes. If the transaction is pending start or commit asynchronously, the request is completed with KErrCancel (unless it had already completed).

Post-condition: Not in a transaction.

CleanupCancelTransactionPushL ( )

IMPORT_C void

CleanupCancelTransactionPushL

(

)

Pushes onto the CleanupStack a TCleanupItem that calls CancelTransaction if activated by a Leave or PopAndDestroy. Important for releasing transaction resources including caches and read/write locks held over the repository.

Post-condition: CleanupStack has another item on it which must be popped later with CleanupStack::Pop() or similar.

CleanupFailTransactionPushL ( )

IMPORT_C void

CleanupFailTransactionPushL

(

)

Pushes onto the CleanupStack a TCleanupItem that calls FailTransaction if activated by a Leave or PopAndDestroy.

Post-condition: CleanupStack has another item on it which must be popped later with CleanupStack::Pop() or similar.

CleanupRollbackTransactionPushL ( )

void

CleanupRollbackTransactionPushL

(

)

[inline]

Same as CleanupCancelTransactionPushL.

CommitTransaction ( TUint32 & )

IMPORT_C TInt

CommitTransaction

(

TUint32 &

aKeyInfo

)

Commits a transaction. A successful return guarantees the consistency and persistence of all values read and written during the transaction.

Pre-condition: Must be in a transaction.

Post-condition: Not in a transaction. On success, changes have been made persistent. On failure, transaction changes have been rolled back.

Parameters
aKeyInfo	On success: returns the number of keys whose values were modified. On failure: returns the key or partial key involved in the first error, or KUnspecifiedKey if failure could not be attributed to any key.

Return Value: KErrNone on success, or error code giving first reason for failing. If KErrLocked is returned for EConcurrentReadWriteTransaction, transaction was interrupted by another client committing changes and should be repeated.

Panic Codes
CENREPCLI	4 Panics client if this session is not in a transaction.

CommitTransaction ( TDes8 &, TRequestStatus & )

IMPORT_C void	CommitTransaction	(	TDes8 &	aKeyInfo,
			TRequestStatus &	aStatus
		)

Commits a transaction asynchronously to allow client to avoid being blocked during the persist operation and other server activity. A successful return guarantees the consistency and persistence of all values read and written during the transaction. Use CancelTransaction to cancel asynchronous request.

Pre-condition: Must be in a transaction.

Post-condition: Cannot assume that transaction is "pending commit" as may have completed already. Once request is complete, session is not in a transaction: on success, changes have been made persistent; on failure, transaction changes have been rolled back.

Parameters
aKeyInfo	A descriptor to receive a TUint32 value, e.g. TTransactionKeyInfoBuf, which client must ensure remains in scope for the duration of the asynchronous request. On success: returns the number of keys whose values were modified. On failure: returns the key or partial key involved in the first error, or KUnspecifiedKey if failure could not be attributed to any key.
aStatus	Completion status of asynchronous request: On success (if not cancelled): KErrNone; On failure: error code giving first reason for failing. If KErrLocked is returned for EConcurrentReadWriteTransaction, transaction was interrupted by another client committing changes and should be repeated.

Panic Codes
CENREPCLI	4 Panics client if this session is not in a transaction.

Create ( TUint32, TInt )

IMPORT_C TInt	Create	(	TUint32	aKey,
			TInt	aValue
		)

Creates a new setting with an integer value.

Post-condition: Transactions fail on all error conditions. Outside transactions: on success the new setting is persistent, on failure the repository is unmodified.

Parameters
aKey	New setting key.
aValue	Setting value.

Return Value: KErrNone if successful, KErrAbort if in a transaction that has previously failed KErrPermissionDenied if caller fails capability check, KErrAlreadyExists if a setting with that key already exists plus other system-wide error codes.

Capability
Dependent	Caller must satisfy the write access policy of that key in the repository.

Create ( TUint32, const TReal & )

IMPORT_C TInt	Create	(	TUint32	aKey,
			const TReal &	aValue
		)

Creates a new setting with a floating-point value.

Post-condition: Transactions fail on all error conditions. Outside transactions: on success the new setting is persistent, on failure the repository is unmodified.

Parameters
aKey	New setting key.
aValue	Setting value.

Return Value: KErrNone if successful, KErrAbort if in a transaction that has previously failed KErrPermissionDenied if caller fails capability check, KErrAlreadyExists if a setting with that key already exists plus other system-wide error codes.

Capability
Dependent	Caller must satisfy the write access policy of that key in the repository.

Create ( TUint32, const TDesC8 & )

IMPORT_C TInt	Create	(	TUint32	aKey,
			const TDesC8 &	aValue
		)

Creates a new setting with a descriptor value.

Post-condition: Transactions fail on all error conditions. Outside transactions: on success the new setting is persistent, on failure the repository is unmodified.

Parameters
aKey	New setting key.
aValue	Setting value.

Return Value: KErrNone if successful, KErrAbort if in a transaction that has previously failed KErrPermissionDenied if caller fails capability check, KErrAlreadyExists if a setting with that key already exists KErrArgument if the descriptor is longer than KMaxBinaryLength, plus other system-wide error codes.

Capability
Dependent	Caller must satisfy the write access policy of that key in the repository.

Create ( TUint32, const TDesC16 & )

IMPORT_C TInt	Create	(	TUint32	aKey,
			const TDesC16 &	aValue
		)

Creates a new setting with a descriptor value.

Post-condition: Transactions fail on all error conditions. Outside transactions: on success the new setting is persistent, on failure the repository is unmodified.

Parameters
aKey	New setting key.
aValue	Setting value.

Return Value: KErrNone if successful, KErrAbort if in a transaction that has previously failed KErrPermissionDenied if caller fails capability check, KErrAlreadyExists if a setting with that key already exists KErrArgument if the descriptor is longer than KMaxUnicodeStringLength, plus other system-wide error codes.

Capability
Dependent	Caller must satisfy the write access policy of that key in the repository.

Delete ( TUint32 )

IMPORT_C TInt

Delete

(

TUint32

aKey

)

Deletes a setting.

Post-condition: Transactions fail on all error conditions except KErrNotFound. Outside transactions: on success the deletion of the setting is persistent, on failure the repository is unmodified.

Parameters
aKey	Key of setting to be deleted.

Return Value: KErrNone if successful, KErrAbort if in a transaction that has previously failed KErrPermissionDenied if caller fails capability check, KErrNotFound if the setting does not exist, plus other system-wide error codes.

Capability
Dependent	Caller must satisfy the write access policy for that key in the repository

Delete ( TUint32, TUint32, TUint32 & )

IMPORT_C TInt	Delete	(	TUint32	aPartialKey,
			TUint32	aMask,
			TUint32 &	aErrorKey
		)

Deletes all the settings that exist and match the specification: (key & mask) == (partialKey & mask) Partial key is guaranteed to be masked before use. Examples of use:

To delete a single key. Delete(key, 0xFFFFFFFF, errorKey);
To delete all keys from 0 to 0xFF: Delete(0, 0xFFFFFF00, errorKey); (digits from 0 to 0xFF would be ignored if given in the partial key)
To delete all keys matching 0x5B??3A?6: Delete(0x5B003A06, 0xFF00FF0F, errorKey);

Post-condition: Transactions fail on all error conditions except KErrNotFound Outside transactions: on success the changes are persistent, on failure the repository is unmodified.

Parameters
aPartialKey	Contains a bit pattern that all the keys must at least partially match.
aMask	Has bits set for all the bits in aPartialKey that must match the keys being deleted.
aErrorKey	If the delete operation fails this contains the key involved in the failure, or aPartialKey or KUnspecifiedKey if it could not be attributed to any key

Return Value: KErrNone if successful, KErrAbort if in a transaction that has previously failed KErrNotFound if no items were found in the partial key range. KErrPermissionDenied if caller fails capability check. plus other system-wide error codes.

Capability
Dependent	Caller must satisfy the write policies of all settings found in the partial key range.

FailTransaction ( )

IMPORT_C void

FailTransaction

(

)

Sets the active transaction to a failed state, releasing cache and locks but keeping it open. Has no effect when not in an active transaction, including when it has already failed or when pending asynchronous start or commit request completion. Use in preference to CancelTransaction whenever it is inappropriate to close the transaction at the time.

Post-condition: If previously in an active transaction: It is marked as failed. All uncommitted changes are discarded. Transaction resources including cache and read/write locks are released in the repository. All subsequent operations in the transaction fail until it is closed by CancelTransaction or CommitTransaction. CommitTransaction will fail and return KErrAbort.

FindEqL ( TUint32, TUint32, TInt, RArray< TUint32 > & )

IMPORT_C TInt	FindEqL	(	TUint32	aPartialKey,
			TUint32	aMask,
			TInt	aValue,
			RArray< TUint32 > &	aFoundKeys
		)

Finds all the settings that contain a given integer and match the specification given by aPartialKey and aMask.

See also: FindL()

Post-condition: Transactions fail only on those "other system-wide error codes".

See also: CClientRepository::FindEqL(TUint32 aPartialId, TUint32 aIdMask, TInt aVal, RArray<TUint32>& aFoundIds)

Parameters
aPartialKey	Contains a bit pattern that all the keys returned must at least partially match.
aMask	Has bits set for all the bits in aPartialKey that must match the returned keys.
aValue	Settings for the keys found will be integers with value aValue.
aFoundKeys	All the keys found. For each key k in aFoundKeys, (k & aMask) == (aPartialKey & aMask) and the setting with key k is an integer aValue.

Return Value: KErrNone if successful, KErrAbort if in a transaction that has previously failed KErrPermissionDenied if caller fails capability check, KErrNotFound if capability check passed but no matching items are found, plus other system-wide error codes.

Leave Codes
KErrNoMemory	The operation has failed with "out of memory" error.

Capability
Dependent	Caller must satisfy the read policies of all settings found in the source range.

FindEqL ( TUint32, TUint32, const TReal &, RArray< TUint32 > & )

IMPORT_C TInt	FindEqL	(	TUint32	aPartialKey,
			TUint32	aMask,
			const TReal &	aValue,
			RArray< TUint32 > &	aFoundKeys
		)

Finds all the settings that contain a given floating point value and match the specification given by aPartialKey and aMask.

See also: FindL()

Post-condition: Transactions fail only on those "other system-wide error codes".

See also: CClientRepository::FindEqL(TUint32 aPartialId, TUint32 aIdMask, const TReal& aVal, RArray<TUint32>& aFoundIds)

Parameters
aPartialKey	Contains a bit pattern that all the keys returned must at least partially match.
aMask	Has bits set for all the bits in aPartialKey that must match the returned keys.
aValue	Settings for the keys found will be floating point values with value aValue.
aFoundKeys	All the keys found. For each key k in aFoundKeys, (k & aMask) == (aPartialKey & aMask) and the setting with key k is a floating point value aValue.

Return Value: KErrNone if successful, KErrAbort if in a transaction that has previously failed KErrPermissionDenied if caller fails capability check, KErrNotFound if capability check passed but no matching items are found, plus other system-wide error codes.

Leave Codes
KErrNoMemory	The operation has failed with "out of memory" error.

Capability
Dependent	Caller must satisfy the read policies of all settings found in the source range.

FindEqL ( TUint32, TUint32, const TDesC8 &, RArray< TUint32 > & )

IMPORT_C TInt	FindEqL	(	TUint32	aPartialKey,
			TUint32	aMask,
			const TDesC8 &	aValue,
			RArray< TUint32 > &	aFoundKeys
		)

Finds all the settings that contain a given string value and match the specification given by aPartialKey and aMask.

See also: FindL()

Post-condition: Transactions fail only on those "other system-wide error codes".

See also: CClientRepository::FindEqL(TUint32 aPartialId, TUint32 aIdMask, const TDesC8& aVal, RArray<TUint32>& aFoundIds)

Parameters
aPartialKey	Contains a bit pattern that all the keys returned must at least partially match.
aMask	Has bits set for all the bits in aPartialKey that must match the returned keys.
aValue	Settings for the keys found will be string values with value aValue.
aFoundKeys	All the keys found. For each key k in aFoundKeys, (k & aMask) == (aPartialKey & aMask) and the setting with key k is a string value aValue.

Return Value: KErrNone if successful, KErrAbort if in a transaction that has previously failed KErrPermissionDenied if caller fails capability check, KErrNotFound if capability check passed but no matching items are found, plus other system-wide error codes.

Leave Codes
KErrNoMemory	The operation has failed with "out of memory" error.

Capability
Dependent	Caller must satisfy the read policies of all settings found in the source range.

FindEqL ( TUint32, TUint32, const TDesC16 &, RArray< TUint32 > & )

IMPORT_C TInt	FindEqL	(	TUint32	aPartialKey,
			TUint32	aMask,
			const TDesC16 &	aValue,
			RArray< TUint32 > &	aFoundKeys
		)

Finds all the settings that contain a given string value and match the specification given by aPartialKey and aMask.

See also: FindL()

Post-condition: Transactions fail only on those "other system-wide error codes".

See also: CClientRepository::FindEqL(TUint32 aPartialId, TUint32 aIdMask, const TDesC& aVal, RArray<TUint32>& aFoundIds)

Parameters
aPartialKey	Contains a bit pattern that all the keys returned must at least partially match.
aMask	Has bits set for all the bits in aPartialKey that must match the returned keys.
aValue	Settings for the keys found will be string values with value aValue.
aFoundKeys	All the keys found. For each key k in aFoundKeys, (k & aMask) == (aPartialKey & aMask) and the setting with key k is a string value aValue.

Return Value: KErrNone if successful, KErrAbort if in a transaction that has previously failed KErrPermissionDenied if caller fails capability check, KErrNotFound if capability check passed but no matching items are found, plus other system-wide error codes.

Leave Codes
KErrNoMemory	The operation has failed with "out of memory" error.

Capability
Dependent	Caller must satisfy the read policies of all settings found in the source range.

FindL ( TUint32, TUint32, RArray< TUint32 > & )

IMPORT_C TInt	FindL	(	TUint32	aPartialKey,
			TUint32	aMask,
			RArray< TUint32 > &	aFoundKeys
		)

Finds all the settings that exist and match the specification given by aPartialKey and aMask. Matches occur whenever (key & mask) == (partialKey & mask). The partial key is guaranteed to be masked before use.

Post-condition: Transactions fail only on those "other system-wide error codes".

See also: CClientRepository::FindL(TUint32 aPartialId, TUint32 aIdMask, RArray<TUint32>& aFoundIds)

Parameters
aPartialKey	Contains a bit pattern that all the keys returned must at least partially match.
aMask	Has bits set for all the bits in aPartialKey that must match the returned keys.
aFoundKeys	All the keys found.

Return Value: KErrNone if successful, KErrAbort if in a transaction that has previously failed KErrNotFound if no items were found in the source range, plus other system-wide error codes.

Leave Codes
KErrNoMemory	The operation has failed with "out of memory" error.

FindNeqL ( TUint32, TUint32, TInt, RArray< TUint32 > & )

IMPORT_C TInt	FindNeqL	(	TUint32	aPartialKey,
			TUint32	aMask,
			TInt	aValue,
			RArray< TUint32 > &	aFoundKeys
		)

Finds all the settings that match the specification given by aPartialKey and aMask, but are either not integer values or do not have the given value.

See also: FindL()

Post-condition: Transactions fail only on those "other system-wide error codes".

See also: CClientRepository::FindNeqL(TUint32 aPartialId, TUint32 aIdMask, TInt aVal, RArray<TUint32>& aFoundIds)

Parameters
aPartialKey	Contains a bit pattern that all the keys returned must at least partially match.
aMask	Has bits set for all the bits in aPartialKey that must match the returned keys.
aValue	Settings for the keys found will be settings that either contain values that are not integers or integers other than aValue.
aFoundKeys	All the keys found. For each key k in aFoundKeys, (k & aMask) == (aPartialKey & aMask) and the setting with key k is either not an integer or an integer not equal to aValue.

Return Value: KErrNone if successful, KErrAbort if in a transaction that has previously failed KErrPermissionDenied if caller fails capability check, KErrNotFound if capability check passed but no non-matching items are found, plus other system-wide error codes.

Leave Codes
KErrNoMemory	The operation has failed with "out of memory" error.

Capability
Dependent	Caller must satisfy the read policies of all settings found in the source range.

FindNeqL ( TUint32, TUint32, const TReal &, RArray< TUint32 > & )

IMPORT_C TInt	FindNeqL	(	TUint32	aPartialKey,
			TUint32	aMask,
			const TReal &	aValue,
			RArray< TUint32 > &	aFoundKeys
		)

Finds all the settings that match the specification given by aPartialKey and aMask, but are either not floating point values or do not have the given value.

See also: FindL()

Post-condition: Transactions fail only on those "other system-wide error codes".

See also: CClientRepository::FindNeqL(TUint32 aPartialId, TUint32 aIdMask, const TReal& aVal, RArray<TUint32>& aFoundIds)

Parameters
aPartialKey	Contains a bit pattern that all the keys returned must at least partially match.
aMask	Has bits set for all the bits in aPartialKey that must match the returned keys.
aValue	Settings for the keys found will be settings that either contain values that are not floating point or floating point values other than aValue.
aFoundKeys	All the keys found. For each key k in aFoundKeys, (k & aMask) == (aPartialKey & aMask) and the setting with key k is either not a floating point value or a floating point value not equal to aValue.

Return Value: KErrNone if successful, KErrAbort if in a transaction that has previously failed KErrPermissionDenied if caller fails capability check, KErrNotFound if capability check passed but no non-matching items are found, plus other system-wide error codes.

Leave Codes
KErrNoMemory	The operation has failed with "out of memory" error.

Capability
Dependent	Caller must satisfy the read policies of all settings found in the source range.

FindNeqL ( TUint32, TUint32, const TDesC8 &, RArray< TUint32 > & )

IMPORT_C TInt	FindNeqL	(	TUint32	aPartialKey,
			TUint32	aMask,
			const TDesC8 &	aValue,
			RArray< TUint32 > &	aFoundKeys
		)

Finds all the settings that match the specification given by aPartialKey and aMask, but are either not string values or do not match the given string.

See also: FindL()

Post-condition: Transactions fail only on those "other system-wide error codes".

See also: CClientRepository::FindNeqL(TUint32 aPartialId, TUint32 aIdMask, const TDesC8& aVal, RArray<TUint32>& aFoundIds)

Parameters
aPartialKey	Contains a bit pattern that all the keys returned must at least partially match.
aMask	Has bits set for all the bits in aPartialKey that must match the returned keys.
aValue	Settings for the keys found will be settings that either contain values that are not strings or strings with value other than aValue.
aFoundKeys	All the keys found. For each key k in aFoundKeys, (k & aMask) == (aPartialKey & aMask) and the setting with key k is either not a string value or a string value not equal to aValue.

Return Value: KErrNone if successful, KErrAbort if in a transaction that has previously failed KErrPermissionDenied if caller fails capability check, KErrNotFound if capability check passed but no non-matching items are found, plus other system-wide error codes.

Leave Codes
KErrNoMemory	The operation has failed with "out of memory" error.

Capability
Dependent	Caller must satisfy the read policies of all settings found in the source range.

FindNeqL ( TUint32, TUint32, const TDesC16 &, RArray< TUint32 > & )

IMPORT_C TInt	FindNeqL	(	TUint32	aPartialKey,
			TUint32	aMask,
			const TDesC16 &	aValue,
			RArray< TUint32 > &	aFoundKeys
		)

Finds all the settings that match the specification given by aPartialKey and aMask, but are either not string values or do not match the given string.

See also: FindL()

Post-condition: Transactions fail only on those "other system-wide error codes".

See also: CClientRepository::FindNeqL(TUint32 aPartialId, TUint32 aIdMask, const TDesC& aVal, RArray<TUint32>& aFoundIds)

Parameters
aPartialKey	Contains a bit pattern that all the keys returned must at least partially match.
aMask	Has bits set for all the bits in aPartialKey that must match the returned keys.
aValue	Settings for the keys found will be settings that either contain values that are not strings or strings with value other than aValue.
aFoundKeys	All the keys found. For each key k in aFoundKeys, (k & aMask) == (aPartialKey & aMask) and the setting with key k is either not a string value or a string value not equal to aValue.

Return Value: KErrNone if successful, KErrAbort if in a transaction that has previously failed KErrPermissionDenied if caller fails capability check, KErrNotFound if capability check passed but no non-matching items are found, plus other system-wide error codes.

Leave Codes
KErrNoMemory	The operation has failed with "out of memory" error.

Capability
Dependent	Caller must satisfy the read policies of all settings found in the source range.

Get ( TUint32, TInt & )

IMPORT_C TInt	Get	(	TUint32	aKey,
			TInt &	aValue
		)

Reads an integer setting.

Post-condition: Transactions fail only on those "other system-wide error codes".

Parameters
aKey	Key of setting to be read.
aValue	Returns the value of the setting if it is an integer.

Return Value: KErrNone if successful, KErrAbort if in a transaction that has previously failed KErrPermissionDenied if caller fails capability check, KErrNotFound if the setting does not exist, KErrArgument if the setting exists but is not an integer, plus other system-wide error codes.

Capability
Dependent	Caller must satisfy the read access policy of that key in the repository.

Get ( TUint32, TReal & )

IMPORT_C TInt	Get	(	TUint32	aKey,
			TReal &	aValue
		)

Reads a floating point setting.

Post-condition: Transactions fail only on those "other system-wide error codes".

Parameters
aKey	Key of setting to be read.
aValue	Returns the value of the setting if it is a floating point value.

Return Value: KErrNone if successful, KErrAbort if in a transaction that has previously failed KErrPermissionDenied if caller fails capability check, KErrNotFound if the setting does not exist, KErrArgument if the setting exists but is not a floating point value, plus other system-wide error codes.

Capability
Dependent	Caller must satisfy the read access policy of that key in the repository.

Get ( TUint32, TDes8 & )

IMPORT_C TInt	Get	(	TUint32	aKey,
			TDes8 &	aValue
		)

Reads a descriptor setting.

Post-condition: Transactions fail only on those "other system-wide error codes".

Parameters
aKey	Key of setting to be read.
aValue	Returns the value of the setting if it is a descriptor.

Return Value: KErrNone if successful, KErrAbort if in a transaction that has previously failed KErrPermissionDenied if caller fails capability check, KErrNotFound if the setting does not exist, KErrArgument if the setting exists but is not a descriptor, KErrOverflow if the descriptor is too small to receive the value in the repository, plus other system-wide error codes.

Capability
Dependent	Caller must satisfy the read access policy of that key in the repository.

Get ( TUint32, TDes8 &, TInt & )

IMPORT_C TInt	Get	(	TUint32	aId,
			TDes8 &	aValue,
			TInt &	aActualLength
		)

Reads a descriptor setting.

Post-condition: Transactions fail only on those "other system-wide error codes".

Parameters
aId	Key of setting to be read.
aValue	Returns the value of the setting if it is a descriptor.
aActualLength	Returns the actual length of the setting if it is a descriptor.

Return Value: KErrNone if successful, KErrAbort if in a transaction that has previously failed KErrPermissionDenied if caller fails capability check, KErrNotFound if the setting does not exist, KErrArgument if the setting exists but is not a descriptor, KErrOverflow if the descriptor is too small to receive the value in the repository, plus other system-wide error codes.

Capability
Dependent	Caller must satisfy the read access policy of that key in the repository.

Get ( TUint32, TDes16 & )

IMPORT_C TInt	Get	(	TUint32	aKey,
			TDes16 &	aValue
		)

Reads a descriptor setting.

Post-condition: Transactions fail only on those "other system-wide error codes".

Parameters
aKey	Key of setting to be read.
aValue	Returns the value of the setting if it is a descriptor.

Return Value: KErrNone if successful, KErrAbort if in a transaction that has previously failed KErrPermissionDenied if caller fails capability check, KErrNotFound if the setting does not exist, KErrArgument if the setting exists but is not a descriptor, KErrOverflow if the descriptor is too small to receive the value in the repository, plus other system-wide error codes.

Capability
Dependent	Caller must satisfy the read access policy of that key in the repository.

Get ( TUint32, TDes16 &, TInt & )

IMPORT_C TInt	Get	(	TUint32	aId,
			TDes16 &	aValue,
			TInt &	aActualLength
		)

Reads a descriptor setting.

Post-condition: Transactions fail only on those "other system-wide error codes".

Parameters
aId	Key of setting to be read.
aValue	Returns the value of the setting if it is a descriptor.
aActualLength	Returns the actual length of the setting if it is a descriptor.

Return Value: KErrNone if successful, KErrAbort if in a transaction that has previously failed KErrPermissionDenied if caller fails capability check, KErrNotFound if the setting does not exist, KErrArgument if the setting exists but is not a descriptor, KErrOverflow if the descriptor is too small to receive the value in the repository, plus other system-wide error codes.

Capability
Dependent	Caller must satisfy the read access policy of that key in the repository.

GetMeta ( TUint32, TUint32 & )

IMPORT_C TInt	GetMeta	(	TUint32	aKey,
			TUint32 &	aMeta
		)

Reads the metadata bound to a key

Post-condition: Transactions fail only on those "other system-wide error codes".

Parameters
aKey	The key
aMeta	Returns the metadata value for the key

Return Value: KErrNone if successful, KErrAbort if in a transaction that has previously failed KErrPermissionDenied if caller fails capability check, KErrNotFound if the setting does not exist, plus other system-wide error codes.

Capability
Dependent	Caller must satisfy the read access policy of that key in the repository.

Move ( TUint32, TUint32, TUint32, TUint32 & )

IMPORT_C TInt	Move	(	TUint32	aSourcePartialKey,
			TUint32	aTargetPartialKey,
			TUint32	aMask,
			TUint32 &	aErrorKey
		)

Moves all the settings that exist and match the specification: (oldkey & mask) == (sourcePartialKey & mask) to new locations where (newkey & mask) == (targetPartialKey & mask). For those keys that match the source specification, those bits in the key for which the corresponding mask bit is zero remain unchanged. All remaining bits change from (sourcePartialKey & mask) to (targetPartialKey & mask). Both partial keys are guaranteed to be masked before use. Examples of use:

To move a single key from oldKey to newKey. Move(oldKey, newKey, 0xFFFFFFFF, errorKey);
To move all keys from 0 to 0xFF to be from 0x100 to 0x1FF: Move(0, 0x100, 0xFFFFFF00, errorKey); (digits from 0 to 0xFF would be ignored if given in the partial keys)
To move all keys matching 0x5B??3A?6 to 0xDC??44?F: Move(0x5B003A06, 0xDC00440F, 0xFF00FF0F, errorKey);

Post-condition: Transactions fail on all error conditions except KErrNotFound. Outside transactions: on success the changes are persistent, on failure the repository is unmodified.

Parameters
aSourcePartialKey	Contains a bit pattern that all the source keys which must at least partially match.
aTargetPartialKey	Contains a bit pattern that all the target keys which must at least partially match.
aMask	Has bits set for all the bits in aPartialKey that must match the keys being moved.
aErrorKey	on failure, contains the key or partial key involved in the error or KUnspecifiedKey if failure could not be attributed to any key.

Return Value: KErrNone if successful, KErrAbort if in a transaction that has previously failed KErrNotFound if no items were found in the source range. KErrPermissionDenied if caller fails capability check, KErrAlreadyExists if an existing setting is using any intended target key. plus other system-wide error codes.

Capability
Dependent	Caller must satisfy the read and write policies of all settings found in the source range, and write policies on all intended target keys.

NewL ( TUid )

IMPORT_C CRepository *

NewL

(

TUid

aRepositoryUid

)

[static]

Creates a CRepository object for accessing a repository. If there is no such repository, the function leaves with KErrNotFound.

Parameters
aRepositoryUid	The UID of the repository to be accessed

Return Value: A pointer to a newly created CRepository object

NewLC ( TUid )

IMPORT_C CRepository *

NewLC

(

TUid

aRepositoryUid

)

[static]

Creates a CRepository object for accessing a repository. If there is no such repository, the function leaves with KErrNotFound. A pointer to the object is left on the cleanup stack.

Parameters
aRepositoryUid	The UID of the repository to be accessed

Return Value: A pointer to a newly created CRepository object

NotifyCancel ( TUint32 )

IMPORT_C TInt

NotifyCancel

(

TUint32

aKey

)

Cancels a notification previously requested from the two-argument overload of NotifyRequest.

Parameters
aKey	The parameter to the previous call to NotifyRequest to be cancelled.

Return Value: KErrNone The method always returns KErrNone.

NotifyCancel ( TUint32, TUint32 )

IMPORT_C TInt	NotifyCancel	(	TUint32	aPartialKey,
			TUint32	aMask
		)

Cancels a notification previously requested from the three-argument overload of NotifyRequest.

Parameters
aPartialKey	The parameter to the previous call to NotifyRequest to be cancelled.
aMask	The mask to be used with the partial key

Return Value: KErrNone The method always returns KErrNone.

NotifyCancelAll ( )

IMPORT_C TInt

NotifyCancelAll

(

)

Cancels all uncompleted notifications from this CRepository.

Return Value: KErrNone The method always returns KErrNone.

NotifyRequest ( TUint32, TRequestStatus & )

IMPORT_C TInt	NotifyRequest	(	TUint32	aKey,
			TRequestStatus &	aStatus
		)

Requests a notification if the value of a given setting changes. Only one notification can be received per call to NotifyRequest. Only one notification per setting per CRepository may be active at any one time.

Parameters
aKey	The key setting to be informed about.
aStatus	The object that will receive the notification. On a successful outcome, this will contain the Uid of the changed setting. If there is an existing notification on the same setting and same session, aStatus will be set to KErrAlreadyExists and the return value will be KErrNone.

Return Value: KErrNone if successful or if aStatus is set to KErrAlreadyExists. KErrPermissionDenied if caller fails capability check. KErrNotFound if the requested setting does not exist.

Capability
Note	The caller must satisfy the relevant access policies for the repository

NotifyRequest ( TUint32, TUint32, TRequestStatus & )

IMPORT_C TInt	NotifyRequest	(	TUint32	aPartialKey,
			TUint32	aMask,
			TRequestStatus &	aStatus
		)

Parameters
aPartialKey	The partial key setting to be informed about.
aMask	The mask to be used with the partial key.
aStatus	The object that will receive the notification. On a successful outcome, this will contain the Uid of the changed setting. On error the error code is stored in aStatus and KErrNone is returned.

Return Value: KErrNone The method always returns KErrNone.

Capability
Note	The caller must satisfy the relevant access policies for the repository

Reset ( )

IMPORT_C TInt

Reset

(

)

Resets the whole repository to the state of the initialization file originally used to set it up. Not currently supported in transactions.

Post-condition: Fails transaction if called when session is in one.

Return Value: KErrNone if successful, KErrNotSupported if this client session is in a transaction plus other system-wide error codes.

Capability
Dependent	The caller must satisfy the relevant access policies for the repository

Reset ( TUint32 )

IMPORT_C TInt

Reset

(

TUint32

aKey

)

Resets the a setting within the repository to the state of the setting described by the initialization file originally used to set the repository up. Not currently supported in transactions.

Post-condition: Fails transaction if called when session is in one.

Parameters
aKey	Key of setting to be reset.

Return Value: KErrNone if successful, KErrNotSupported if this client session is in a transaction plus other system-wide error codes.

Capability
Note	The caller must satisfy the relevant access policies for the repository

RollbackTransaction ( )

void

RollbackTransaction

(

)

[inline]

Same as CancelTransaction.

Set ( TUint32, TInt )

IMPORT_C TInt	Set	(	TUint32	aKey,
			TInt	aValue
		)

Sets an existing integer setting to a new value or creates a new setting with an integer value if the setting doesn't exist.

Post-condition: Transactions fail on all error conditions. Outside transactions: on success the new value is persistent, on failure the repository is unmodified.

Parameters
aKey	Key of setting to be written to.
aValue	Value to be written.

Return Value: KErrNone if successful, KErrAbort if in a transaction that has previously failed KErrPermissionDenied if caller fails capability check, KErrArgument if the setting exists but is not an integer plus other system-wide error codes.

Capability
Dependent	Caller must satisfy the write access policy of that key in the repository.

Set ( TUint32, const TReal & )

IMPORT_C TInt	Set	(	TUint32	aKey,
			const TReal &	aValue
		)

Sets an existing floating point setting to a new value or creates a new setting with a floating point value if the setting doesn't exist.

Post-condition: Transactions fail on all error conditions. Outside transactions: on success the new value is persistent, on failure the repository is unmodified.

Parameters
aKey	Key of setting to be written to.
aValue	Value to be written.

Return Value: KErrNone if successful, KErrAbort if in a transaction that has previously failed KErrPermissionDenied if caller fails capability check, KErrArgument if the setting exists but is not a floating point value plus other system-wide error codes.

Capability
Dependent	Caller must satisfy the write access policy of that key in the repository.

Set ( TUint32, const TDesC8 & )

IMPORT_C TInt	Set	(	TUint32	aKey,
			const TDesC8 &	aValue
		)

Sets an existing descriptor setting to a new value or creates a new setting with a descriptor value if the setting doesn't exist.

Post-condition: Transactions fail on all error conditions. Outside transactions: on success the new value is persistent, on failure the repository is unmodified.

Parameters
aKey	Key of setting to be written to.
aValue	Value to be written.

Return Value: KErrNone if successful, KErrAbort if in a transaction that has previously failed KErrPermissionDenied if caller fails capability check, KErrArgument if aValue is longer than KMaxBinaryLength or the setting exists but is not a descriptor, plus other system-wide error codes.

Capability
Dependent	Caller must satisfy the write access policy of that key in the repository.

Set ( TUint32, const TDesC16 & )

IMPORT_C TInt	Set	(	TUint32	aKey,
			const TDesC16 &	aValue
		)

Sets an existing descriptor setting to a new value or creates a new setting with a descriptor value if it doesn't exist.

Post-condition: Transactions fail on all error conditions. Outside transactions: on success the new value is persistent, on failure the repository is unmodified.

Parameters
aKey	Key of setting to be written to.
aValue	Value to be written.

Return Value: KErrNone if successful, KErrAbort if in a transaction that has previously failed KErrPermissionDenied if caller fails capability check, KErrArgument if aValue is longer than KMaxUnicodeStringLength or the setting exists but is not a descriptor, plus other system-wide error codes.

Capability
Dependent	Caller must satisfy the write access policy of that key in the repository.

StartTransaction ( TTransactionMode )

IMPORT_C TInt

StartTransaction

(

TTransactionMode

aMode

)

Attempts to starts a transaction in the given mode. Consistency and persistence of all values read and written during the transaction is only guaranteed after a successful return from CommitTransaction.

StartTransaction ( TTransactionMode, TRequestStatus & )

IMPORT_C void	StartTransaction	(	TTransactionMode	aMode,
			TRequestStatus &	aStatus
		)

Attempts to starts a transaction in the given mode asynchronously to allow client to avoid being blocked by server activity before starting. Consistency and persistence of all values read and written during the transaction is only guaranteed after a successful return from CommitTransaction. Use CancelTransaction to cancel asynchronous request.

Parameters
aMode	transaction mode: EConcurrentReadWriteTransaction (standard), EReadTransaction or EReadWriteTransaction.
aStatus	On completion of asynchronous request: KErrNone if successful - guaranteed for EConcurrentReadWriteTransaction unless cancelled, KErrLocked for other transaction types if read or write locks held by other clients prevent transaction from starting.