os/persistentdata/persistentstorage/centralrepository/cenrepcli/centralrepository.cpp
1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/persistentdata/persistentstorage/centralrepository/cenrepcli/centralrepository.cpp Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,986 @@
1.4 +// Copyright (c) 2004-2009 Nokia Corporation and/or its subsidiary(-ies).
1.5 +// All rights reserved.
1.6 +// This component and the accompanying materials are made available
1.7 +// under the terms of "Eclipse Public License v1.0"
1.8 +// which accompanies this distribution, and is available
1.9 +// at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.10 +//
1.11 +// Initial Contributors:
1.12 +// Nokia Corporation - initial contribution.
1.13 +//
1.14 +// Contributors:
1.15 +//
1.16 +// Description:
1.17 +//
1.18 +
1.19 +#include "clirep.h"
1.20 +
1.21 +/** Creates a CRepository object for accessing a repository.
1.22 +If there is no such repository, the function leaves with KErrNotFound.
1.23 +A pointer to the object is left on the cleanup stack.
1.24 +@param aRepositoryUid The UID of the repository to be accessed
1.25 +@return A pointer to a newly created CRepository object
1.26 +*/
1.27 +EXPORT_C CRepository* CRepository::NewLC(TUid aRepositoryUid)
1.28 + {
1.29 + return CClientRepository::NewLC(aRepositoryUid);
1.30 + }
1.31 +
1.32 +
1.33 +/** Creates a CRepository object for accessing a repository.
1.34 +If there is no such repository, the function leaves with KErrNotFound.
1.35 +@param aRepositoryUid The UID of the repository to be accessed
1.36 +@return A pointer to a newly created CRepository object
1.37 +*/
1.38 +EXPORT_C CRepository* CRepository::NewL(TUid aRepositoryUid)
1.39 + {
1.40 + CRepository* rep = CRepository::NewLC(aRepositoryUid);
1.41 + CleanupStack::Pop();
1.42 + return rep;
1.43 + }
1.44 +
1.45 +
1.46 +/** Destructor.
1.47 +*/
1.48 +EXPORT_C CRepository::~CRepository()
1.49 + {
1.50 + }
1.51 +
1.52 +
1.53 +/** Creates a new setting with an integer value.
1.54 +@param aKey New setting key.
1.55 +@param aValue Setting value.
1.56 +@return
1.57 + KErrNone if successful,
1.58 + KErrAbort if in a transaction that has previously failed
1.59 + KErrPermissionDenied if caller fails capability check,
1.60 + KErrAlreadyExists if a setting with that key already exists
1.61 + plus other system-wide error codes.
1.62 +@post
1.63 + Transactions fail on all error conditions.
1.64 + Outside transactions: on success the new setting is persistent,
1.65 + on failure the repository is unmodified.
1.66 +@capability Dependent Caller must satisfy the write access policy of that key in the repository.
1.67 +*/
1.68 +EXPORT_C TInt CRepository::Create(TUint32 aKey, TInt aValue)
1.69 + {
1.70 + return (static_cast<CClientRepository*>(this))->Create(aKey, aValue);
1.71 + }
1.72 +
1.73 +
1.74 +/** Creates a new setting with a floating-point value.
1.75 +@param aKey New setting key.
1.76 +@param aValue Setting value.
1.77 +@return
1.78 + KErrNone if successful,
1.79 + KErrAbort if in a transaction that has previously failed
1.80 + KErrPermissionDenied if caller fails capability check,
1.81 + KErrAlreadyExists if a setting with that key already exists
1.82 + plus other system-wide error codes.
1.83 +@post
1.84 + Transactions fail on all error conditions.
1.85 + Outside transactions: on success the new setting is persistent,
1.86 + on failure the repository is unmodified.
1.87 +@capability Dependent Caller must satisfy the write access policy of that key in the repository.
1.88 +*/
1.89 +EXPORT_C TInt CRepository::Create(TUint32 aKey, const TReal& aValue)
1.90 + {
1.91 + return (static_cast<CClientRepository*>(this))->Create(aKey, aValue);
1.92 + }
1.93 +
1.94 +
1.95 +/** Creates a new setting with a descriptor value.
1.96 +@param aKey New setting key.
1.97 +@param aValue Setting value.
1.98 +@return
1.99 + KErrNone if successful,
1.100 + KErrAbort if in a transaction that has previously failed
1.101 + KErrPermissionDenied if caller fails capability check,
1.102 + KErrAlreadyExists if a setting with that key already exists
1.103 + KErrArgument if the descriptor is longer than KMaxBinaryLength,
1.104 + plus other system-wide error codes.
1.105 +@post
1.106 + Transactions fail on all error conditions.
1.107 + Outside transactions: on success the new setting is persistent,
1.108 + on failure the repository is unmodified.
1.109 +@capability Dependent Caller must satisfy the write access policy of that key in the repository.
1.110 +*/
1.111 +EXPORT_C TInt CRepository::Create(TUint32 aKey, const TDesC8& aValue)
1.112 + {
1.113 + return (static_cast<CClientRepository*>(this))->Create(aKey, aValue);
1.114 + }
1.115 +
1.116 +/** Creates a new setting with a descriptor value.
1.117 +@param aKey New setting key.
1.118 +@param aValue Setting value.
1.119 +@return
1.120 + KErrNone if successful,
1.121 + KErrAbort if in a transaction that has previously failed
1.122 + KErrPermissionDenied if caller fails capability check,
1.123 + KErrAlreadyExists if a setting with that key already exists
1.124 + KErrArgument if the descriptor is longer than KMaxUnicodeStringLength,
1.125 + plus other system-wide error codes.
1.126 +@post
1.127 + Transactions fail on all error conditions.
1.128 + Outside transactions: on success the new setting is persistent,
1.129 + on failure the repository is unmodified.
1.130 +@capability Dependent Caller must satisfy the write access policy of that key in the repository.
1.131 +*/
1.132 +EXPORT_C TInt CRepository::Create(TUint32 aKey, const TDesC16& aValue)
1.133 + {
1.134 + return (static_cast<CClientRepository*>(this))->Create(aKey, aValue);
1.135 + }
1.136 +
1.137 +/** Deletes a setting.
1.138 +@param aKey Key of setting to be deleted.
1.139 +@return
1.140 + KErrNone if successful,
1.141 + KErrAbort if in a transaction that has previously failed
1.142 + KErrPermissionDenied if caller fails capability check,
1.143 + KErrNotFound if the setting does not exist,
1.144 + plus other system-wide error codes.
1.145 +@post
1.146 + Transactions fail on all error conditions except KErrNotFound.
1.147 + Outside transactions: on success the deletion of the setting is persistent,
1.148 + on failure the repository is unmodified.
1.149 +@capability Dependent Caller must satisfy the write access policy for that key in the repository
1.150 +*/
1.151 +EXPORT_C TInt CRepository::Delete(TUint32 aKey)
1.152 + {
1.153 + return (static_cast<CClientRepository*>(this))->Delete(aKey);
1.154 + }
1.155 +
1.156 +/** Deletes all the settings that exist and match the specification:
1.157 + (key & mask) == (partialKey & mask)
1.158 +Partial key is guaranteed to be masked before use.
1.159 +Examples of use:
1.160 +- To delete a single key.
1.161 + Delete(key, 0xFFFFFFFF, errorKey);
1.162 +- To delete all keys from 0 to 0xFF:
1.163 + Delete(0, 0xFFFFFF00, errorKey);
1.164 + (digits from 0 to 0xFF would be ignored if given in the partial key)
1.165 +- To delete all keys matching 0x5B??3A?6:
1.166 + Delete(0x5B003A06, 0xFF00FF0F, errorKey);
1.167 +
1.168 +@param aPartialKey
1.169 + Contains a bit pattern that all the keys must at least partially
1.170 + match.
1.171 +@param aMask
1.172 + Has bits set for all the bits in aPartialKey that must match the keys being deleted.
1.173 +@param aErrorKey If the delete operation fails this contains the key involved in the
1.174 + failure, or aPartialKey or KUnspecifiedKey if it could not be attributed to any key
1.175 +@return
1.176 + KErrNone if successful,
1.177 + KErrAbort if in a transaction that has previously failed
1.178 + KErrNotFound if no items were found in the partial key range.
1.179 + KErrPermissionDenied if caller fails capability check.
1.180 + plus other system-wide error codes.
1.181 +@post
1.182 + Transactions fail on all error conditions except KErrNotFound
1.183 + Outside transactions: on success the changes are persistent, on failure the
1.184 + repository is unmodified.
1.185 +@capability Dependent Caller must satisfy the write policies of all settings found in the
1.186 + partial key range.
1.187 +*/
1.188 +EXPORT_C TInt CRepository::Delete (TUint32 aPartialKey, TUint32 aMask, TUint32 &aErrorKey)
1.189 + {
1.190 + return (static_cast<CClientRepository*>(this))->Delete(aPartialKey, aMask, aErrorKey);
1.191 + }
1.192 +
1.193 +
1.194 +/** Reads an integer setting.
1.195 +@param aKey Key of setting to be read.
1.196 +@param aValue Returns the value of the setting if it is an integer.
1.197 +@return
1.198 + KErrNone if successful,
1.199 + KErrAbort if in a transaction that has previously failed
1.200 + KErrPermissionDenied if caller fails capability check,
1.201 + KErrNotFound if the setting does not exist,
1.202 + KErrArgument if the setting exists but is not an integer,
1.203 + plus other system-wide error codes.
1.204 +@post Transactions fail only on those "other system-wide error codes".
1.205 +@capability Dependent Caller must satisfy the read access policy of that key in the repository.
1.206 +*/
1.207 +EXPORT_C TInt CRepository::Get(TUint32 aKey, TInt& aValue)
1.208 + {
1.209 + return (static_cast<CClientRepository*>(this))->Get(aKey, aValue);
1.210 + }
1.211 +
1.212 +
1.213 +/** Sets an existing integer setting to a new value or creates a new setting
1.214 +with an integer value if the setting doesn't exist.
1.215 +@param aKey Key of setting to be written to.
1.216 +@param aValue Value to be written.
1.217 +@return
1.218 + KErrNone if successful,
1.219 + KErrAbort if in a transaction that has previously failed
1.220 + KErrPermissionDenied if caller fails capability check,
1.221 + KErrArgument if the setting exists but is not an integer
1.222 + plus other system-wide error codes.
1.223 +@post
1.224 + Transactions fail on all error conditions.
1.225 + Outside transactions: on success the new value is persistent,
1.226 + on failure the repository is unmodified.
1.227 +@capability Dependent Caller must satisfy the write access policy of that key in the repository.
1.228 +*/
1.229 +EXPORT_C TInt CRepository::Set(TUint32 aKey, TInt aValue)
1.230 + {
1.231 + return (static_cast<CClientRepository*>(this))->Set(aKey, aValue);
1.232 + }
1.233 +
1.234 +
1.235 +/** Reads a floating point setting.
1.236 +@param aKey Key of setting to be read.
1.237 +@param aValue Returns the value of the setting if it is a floating point value.
1.238 +@return
1.239 + KErrNone if successful,
1.240 + KErrAbort if in a transaction that has previously failed
1.241 + KErrPermissionDenied if caller fails capability check,
1.242 + KErrNotFound if the setting does not exist,
1.243 + KErrArgument if the setting exists but is not a floating point value,
1.244 + plus other system-wide error codes.
1.245 +@post Transactions fail only on those "other system-wide error codes".
1.246 +@capability Dependent Caller must satisfy the read access policy of that key in the repository.
1.247 +*/
1.248 +EXPORT_C TInt CRepository::Get(TUint32 aKey, TReal& aValue)
1.249 + {
1.250 + return (static_cast<CClientRepository*>(this))->Get(aKey, aValue);
1.251 + }
1.252 +
1.253 +
1.254 +/** Sets an existing floating point setting to a new value or creates a new setting
1.255 +with a floating point value if the setting doesn't exist.
1.256 +@param aKey Key of setting to be written to.
1.257 +@param aValue Value to be written.
1.258 +@return
1.259 + KErrNone if successful,
1.260 + KErrAbort if in a transaction that has previously failed
1.261 + KErrPermissionDenied if caller fails capability check,
1.262 + KErrArgument if the setting exists but is not a floating point value
1.263 + plus other system-wide error codes.
1.264 +@post
1.265 + Transactions fail on all error conditions.
1.266 + Outside transactions: on success the new value is persistent,
1.267 + on failure the repository is unmodified.
1.268 +@capability Dependent Caller must satisfy the write access policy of that key in the repository.
1.269 +*/
1.270 +EXPORT_C TInt CRepository::Set(TUint32 aKey, const TReal& aValue)
1.271 + {
1.272 + return (static_cast<CClientRepository*>(this))->Set(aKey, aValue);
1.273 + }
1.274 +
1.275 +
1.276 +/** Reads a descriptor setting.
1.277 +@param aKey Key of setting to be read.
1.278 +@param aValue Returns the value of the setting if it is a descriptor.
1.279 +@return
1.280 + KErrNone if successful,
1.281 + KErrAbort if in a transaction that has previously failed
1.282 + KErrPermissionDenied if caller fails capability check,
1.283 + KErrNotFound if the setting does not exist,
1.284 + KErrArgument if the setting exists but is not a descriptor,
1.285 + KErrOverflow if the descriptor is too small to receive the value in the repository,
1.286 + plus other system-wide error codes.
1.287 +@post Transactions fail only on those "other system-wide error codes".
1.288 +@capability Dependent Caller must satisfy the read access policy of that key in the repository.
1.289 +*/
1.290 +EXPORT_C TInt CRepository::Get(TUint32 aKey, TDes8& aValue)
1.291 + {
1.292 + return (static_cast<CClientRepository*>(this))->Get(aKey, aValue);
1.293 + }
1.294 +
1.295 +/** Reads a descriptor setting.
1.296 +@param aKey Key of setting to be read.
1.297 +@param aValue Returns the value of the setting if it is a descriptor.
1.298 +@param aActualLength Returns the actual length of the setting if it is a descriptor.
1.299 +@return
1.300 + KErrNone if successful,
1.301 + KErrAbort if in a transaction that has previously failed
1.302 + KErrPermissionDenied if caller fails capability check,
1.303 + KErrNotFound if the setting does not exist,
1.304 + KErrArgument if the setting exists but is not a descriptor,
1.305 + KErrOverflow if the descriptor is too small to receive the value in the repository,
1.306 + plus other system-wide error codes.
1.307 +@post Transactions fail only on those "other system-wide error codes".
1.308 +@capability Dependent Caller must satisfy the read access policy of that key in the repository.
1.309 +*/
1.310 +EXPORT_C TInt CRepository::Get(TUint32 aKey, TDes8& aValue, TInt& aActualLength)
1.311 + {
1.312 + return (static_cast<CClientRepository*>(this))->Get(aKey, aValue, aActualLength);
1.313 + }
1.314 +
1.315 +/** Sets an existing descriptor setting to a new value or creates a new setting
1.316 +with a descriptor value if the setting doesn't exist.
1.317 +@param aKey Key of setting to be written to.
1.318 +@param aValue Value to be written.
1.319 +@return
1.320 + KErrNone if successful,
1.321 + KErrAbort if in a transaction that has previously failed
1.322 + KErrPermissionDenied if caller fails capability check,
1.323 + KErrArgument if aValue is longer than KMaxBinaryLength or
1.324 + the setting exists but is not a descriptor,
1.325 + plus other system-wide error codes.
1.326 +@post
1.327 + Transactions fail on all error conditions.
1.328 + Outside transactions: on success the new value is persistent,
1.329 + on failure the repository is unmodified.
1.330 +@capability Dependent Caller must satisfy the write access policy of that key in the repository.
1.331 +*/
1.332 +EXPORT_C TInt CRepository::Set(TUint32 aKey, const TDesC8& aValue)
1.333 + {
1.334 + return (static_cast<CClientRepository*>(this))->Set(aKey, aValue);
1.335 + }
1.336 +
1.337 +
1.338 +/** Reads a descriptor setting.
1.339 +@param aKey Key of setting to be read.
1.340 +@param aValue Returns the value of the setting if it is a descriptor.
1.341 +@return
1.342 + KErrNone if successful,
1.343 + KErrAbort if in a transaction that has previously failed
1.344 + KErrPermissionDenied if caller fails capability check,
1.345 + KErrNotFound if the setting does not exist,
1.346 + KErrArgument if the setting exists but is not a descriptor,
1.347 + KErrOverflow if the descriptor is too small to receive the value in the repository,
1.348 + plus other system-wide error codes.
1.349 +@post Transactions fail only on those "other system-wide error codes".
1.350 +@capability Dependent Caller must satisfy the read access policy of that key in the repository.
1.351 +*/
1.352 +EXPORT_C TInt CRepository::Get(TUint32 aKey, TDes16& aValue)
1.353 + {
1.354 + return (static_cast<CClientRepository*>(this))->Get(aKey, aValue);
1.355 + }
1.356 +
1.357 +/** Reads a descriptor setting.
1.358 +@param aKey Key of setting to be read.
1.359 +@param aValue Returns the value of the setting if it is a descriptor.
1.360 +@param aActualLength Returns the actual length of the setting if it is a descriptor.
1.361 +@return
1.362 + KErrNone if successful,
1.363 + KErrAbort if in a transaction that has previously failed
1.364 + KErrPermissionDenied if caller fails capability check,
1.365 + KErrNotFound if the setting does not exist,
1.366 + KErrArgument if the setting exists but is not a descriptor,
1.367 + KErrOverflow if the descriptor is too small to receive the value in the repository,
1.368 + plus other system-wide error codes.
1.369 +@post Transactions fail only on those "other system-wide error codes".
1.370 +@capability Dependent Caller must satisfy the read access policy of that key in the repository.
1.371 +*/
1.372 +EXPORT_C TInt CRepository::Get(TUint32 aKey, TDes16& aValue, TInt& aActualLength)
1.373 + {
1.374 + return (static_cast<CClientRepository*>(this))->Get(aKey, aValue, aActualLength);
1.375 + }
1.376 +
1.377 +/** Sets an existing descriptor setting to a new value or creates a new setting
1.378 +with a descriptor value if it doesn't exist.
1.379 +@param aKey Key of setting to be written to.
1.380 +@param aValue Value to be written.
1.381 +@return
1.382 + KErrNone if successful,
1.383 + KErrAbort if in a transaction that has previously failed
1.384 + KErrPermissionDenied if caller fails capability check,
1.385 + KErrArgument if aValue is longer than KMaxUnicodeStringLength or
1.386 + the setting exists but is not a descriptor,
1.387 + plus other system-wide error codes.
1.388 +@post
1.389 + Transactions fail on all error conditions.
1.390 + Outside transactions: on success the new value is persistent,
1.391 + on failure the repository is unmodified.
1.392 +@capability Dependent Caller must satisfy the write access policy of that key in the repository.
1.393 +*/
1.394 +EXPORT_C TInt CRepository::Set(TUint32 aKey, const TDesC16& aValue)
1.395 + {
1.396 + return (static_cast<CClientRepository*>(this))->Set(aKey, aValue);
1.397 + }
1.398 +
1.399 +/** Reads the metadata bound to a key
1.400 +@param aKey The key
1.401 +@param aMeta Returns the metadata value for the key
1.402 +@return
1.403 + KErrNone if successful,
1.404 + KErrAbort if in a transaction that has previously failed
1.405 + KErrPermissionDenied if caller fails capability check,
1.406 + KErrNotFound if the setting does not exist,
1.407 + plus other system-wide error codes.
1.408 +@post Transactions fail only on those "other system-wide error codes".
1.409 +@capability Dependent Caller must satisfy the read access policy of that key in the repository.
1.410 +*/
1.411 +EXPORT_C TInt CRepository::GetMeta(TUint32 aKey, TUint32& aMeta)
1.412 + {
1.413 + return (static_cast<CClientRepository*>(this))->GetMeta(aKey, aMeta);
1.414 + }
1.415 +
1.416 +/** Moves all the settings that exist and match the specification:
1.417 + (oldkey & mask) == (sourcePartialKey & mask)
1.418 +to new locations where
1.419 + (newkey & mask) == (targetPartialKey & mask).
1.420 +For those keys that match the source specification, those bits in the key for
1.421 +which the corresponding mask bit is zero remain unchanged. All remaining bits
1.422 +change from (sourcePartialKey & mask) to (targetPartialKey & mask).
1.423 +Both partial keys are guaranteed to be masked before use.
1.424 +Examples of use:
1.425 +- To move a single key from oldKey to newKey.
1.426 + Move(oldKey, newKey, 0xFFFFFFFF, errorKey);
1.427 +- To move all keys from 0 to 0xFF to be from 0x100 to 0x1FF:
1.428 + Move(0, 0x100, 0xFFFFFF00, errorKey);
1.429 + (digits from 0 to 0xFF would be ignored if given in the partial keys)
1.430 +- To move all keys matching 0x5B??3A?6 to 0xDC??44?F:
1.431 + Move(0x5B003A06, 0xDC00440F, 0xFF00FF0F, errorKey);
1.432 +
1.433 +@param aSourcePartialKey
1.434 + Contains a bit pattern that all the source keys which must at least partially
1.435 + match.
1.436 +@param aMask
1.437 + Has bits set for all the bits in aPartialKey that must match the keys being moved.
1.438 +@param aTargetPartialKey
1.439 + Contains a bit pattern that all the target keys which must at least partially
1.440 + match.
1.441 +@param aErrorKey on failure, contains the key or partial key involved in the error
1.442 + or KUnspecifiedKey if failure could not be attributed to any key.
1.443 +@return
1.444 + KErrNone if successful,
1.445 + KErrAbort if in a transaction that has previously failed
1.446 + KErrNotFound if no items were found in the source range.
1.447 + KErrPermissionDenied if caller fails capability check,
1.448 + KErrAlreadyExists if an existing setting is using any intended target key.
1.449 + plus other system-wide error codes.
1.450 +@post
1.451 + Transactions fail on all error conditions except KErrNotFound.
1.452 + Outside transactions: on success the changes are persistent, on failure the
1.453 + repository is unmodified.
1.454 +@capability Dependent Caller must satisfy the read and write policies of all settings found in the
1.455 + source range, and write policies on all intended target keys.
1.456 +*/
1.457 +EXPORT_C TInt CRepository::Move (TUint32 aSourcePartialKey, TUint32 aTargetPartialKey,
1.458 + TUint32 aMask, TUint32 &aErrorKey)
1.459 + {
1.460 + return (static_cast<CClientRepository*>(this))->Move(aSourcePartialKey, aTargetPartialKey, aMask, aErrorKey);
1.461 + }
1.462 +
1.463 +
1.464 +/** Finds all the settings that exist and match the specification given by
1.465 +aPartialKey and aMask.
1.466 +Matches occur whenever (key & mask) == (partialKey & mask).
1.467 +The partial key is guaranteed to be masked before use.
1.468 +@param aPartialKey
1.469 + Contains a bit pattern that all the keys returned must at least partially
1.470 + match.
1.471 +@param aMask
1.472 + Has bits set for all the bits in aPartialKey that must match the returned
1.473 + keys.
1.474 +@param aFoundKeys All the keys found.
1.475 +@return
1.476 + KErrNone if successful,
1.477 + KErrAbort if in a transaction that has previously failed
1.478 + KErrNotFound if no items were found in the source range,
1.479 + plus other system-wide error codes.
1.480 +@post Transactions fail only on those "other system-wide error codes".
1.481 +*/
1.482 +EXPORT_C TInt CRepository::FindL(TUint32 aPartialKey, TUint32 aMask,
1.483 + RArray<TUint32>& aFoundKeys)
1.484 + {
1.485 + return (static_cast<CClientRepository*>(this))->FindL(aPartialKey, aMask, aFoundKeys);
1.486 + }
1.487 +
1.488 +
1.489 +/** Finds all the settings that contain a given integer and match the
1.490 +specification given by aPartialKey and aMask.
1.491 +@param aPartialKey
1.492 + Contains a bit pattern that all the keys returned must at least partially
1.493 + match.
1.494 +@param aMask
1.495 + Has bits set for all the bits in aPartialKey that must match the returned
1.496 + keys.
1.497 +@param aValue Settings for the keys found will be integers with value aValue.
1.498 +@param aFoundKeys All the keys found.
1.499 + For each key k in aFoundKeys, (k & aMask) == (aPartialKey & aMask) and
1.500 + the setting with key k is an integer aValue.
1.501 +@see FindL()
1.502 +@return
1.503 + KErrNone if successful,
1.504 + KErrAbort if in a transaction that has previously failed
1.505 + KErrPermissionDenied if caller fails capability check,
1.506 + KErrNotFound if capability check passed but no matching items are found,
1.507 + plus other system-wide error codes.
1.508 +@post Transactions fail only on those "other system-wide error codes".
1.509 +@capability Dependent Caller must satisfy the read policies of all settings found in the source range.
1.510 +*/
1.511 +EXPORT_C TInt CRepository::FindEqL(TUint32 aPartialKey, TUint32 aMask,
1.512 + TInt aValue, RArray<TUint32>& aFoundKeys)
1.513 + {
1.514 + return (static_cast<CClientRepository*>(this))->FindEqL(aPartialKey, aMask, aValue, aFoundKeys);
1.515 + }
1.516 +
1.517 +
1.518 +/** Finds all the settings that contain a given floating point value and match
1.519 +the specification given by aPartialKey and aMask.
1.520 +@param aPartialKey
1.521 + Contains a bit pattern that all the keys returned must at least partially
1.522 + match.
1.523 +@param aMask
1.524 + Has bits set for all the bits in aPartialKey that must match the returned
1.525 + keys.
1.526 +@param aValue
1.527 + Settings for the keys found will be floating point values with value aValue.
1.528 +@param aFoundKeys All the keys found.
1.529 + For each key k in aFoundKeys, (k & aMask) == (aPartialKey & aMask) and
1.530 + the setting with key k is a floating point value aValue.
1.531 +@see FindL()
1.532 +@return
1.533 + KErrNone if successful,
1.534 + KErrAbort if in a transaction that has previously failed
1.535 + KErrPermissionDenied if caller fails capability check,
1.536 + KErrNotFound if capability check passed but no matching items are found,
1.537 + plus other system-wide error codes.
1.538 +@post Transactions fail only on those "other system-wide error codes".
1.539 +@capability Dependent Caller must satisfy the read policies of all settings found in the source range.
1.540 +*/
1.541 +EXPORT_C TInt CRepository::FindEqL(TUint32 aPartialKey, TUint32 aMask,
1.542 + const TReal& aValue, RArray<TUint32>& aFoundKeys)
1.543 + {
1.544 + return (static_cast<CClientRepository*>(this))->FindEqL(aPartialKey, aMask, aValue, aFoundKeys);
1.545 + }
1.546 +
1.547 +
1.548 +/** Finds all the settings that contain a given string value and match the
1.549 +specification given by aPartialKey and aMask.
1.550 +@param aPartialKey
1.551 + Contains a bit pattern that all the keys returned must at least partially
1.552 + match.
1.553 +@param aMask
1.554 + Has bits set for all the bits in aPartialKey that must match the returned
1.555 + keys.
1.556 +@param aValue
1.557 + Settings for the keys found will be string values with value aValue.
1.558 +@param aFoundKeys All the keys found.
1.559 + For each key k in aFoundKeys, (k & aMask) == (aPartialKey & aMask) and
1.560 + the setting with key k is a string value aValue.
1.561 +@see FindL()
1.562 +@return
1.563 + KErrNone if successful,
1.564 + KErrAbort if in a transaction that has previously failed
1.565 + KErrPermissionDenied if caller fails capability check,
1.566 + KErrNotFound if capability check passed but no matching items are found,
1.567 + plus other system-wide error codes.
1.568 +@post Transactions fail only on those "other system-wide error codes".
1.569 +@capability Dependent Caller must satisfy the read policies of all settings found in the source range.
1.570 +*/
1.571 +EXPORT_C TInt CRepository::FindEqL(TUint32 aPartialKey, TUint32 aMask,
1.572 + const TDesC8& aValue, RArray<TUint32>& aFoundKeys)
1.573 + {
1.574 + return (static_cast<CClientRepository*>(this))->FindEqL(aPartialKey, aMask, aValue, aFoundKeys);
1.575 + }
1.576 +
1.577 +
1.578 +/** Finds all the settings that contain a given string value and match the
1.579 +specification given by aPartialKey and aMask.
1.580 +@param aPartialKey
1.581 + Contains a bit pattern that all the keys returned must at least partially
1.582 + match.
1.583 +@param aMask
1.584 + Has bits set for all the bits in aPartialKey that must match the returned
1.585 + keys.
1.586 +@param aValue
1.587 + Settings for the keys found will be string values with value aValue.
1.588 +@param aFoundKeys All the keys found.
1.589 + For each key k in aFoundKeys, (k & aMask) == (aPartialKey & aMask) and
1.590 + the setting with key k is a string value aValue.
1.591 +@see FindL()
1.592 +@return
1.593 + KErrNone if successful,
1.594 + KErrAbort if in a transaction that has previously failed
1.595 + KErrPermissionDenied if caller fails capability check,
1.596 + KErrNotFound if capability check passed but no matching items are found,
1.597 + plus other system-wide error codes.
1.598 +@post Transactions fail only on those "other system-wide error codes".
1.599 +@capability Dependent Caller must satisfy the read policies of all settings found in the source range.
1.600 +*/
1.601 +EXPORT_C TInt CRepository::FindEqL(TUint32 aPartialKey, TUint32 aMask,
1.602 + const TDesC16& aValue, RArray<TUint32>& aFoundKeys)
1.603 + {
1.604 + return (static_cast<CClientRepository*>(this))->FindEqL(aPartialKey, aMask, aValue, aFoundKeys);
1.605 + }
1.606 +
1.607 +
1.608 +/** Finds all the settings that match the specification given by aPartialKey
1.609 +and aMask, but are either not integer values or do not have the given value.
1.610 +@param aPartialKey
1.611 + Contains a bit pattern that all the keys returned must at least partially
1.612 + match.
1.613 +@param aMask
1.614 + Has bits set for all the bits in aPartialKey that must match the returned
1.615 + keys.
1.616 +@param aValue
1.617 + Settings for the keys found will be settings that either contain values
1.618 + that are not integers or integers other than aValue.
1.619 +@param aFoundKeys All the keys found.
1.620 + For each key k in aFoundKeys, (k & aMask) == (aPartialKey & aMask) and
1.621 + the setting with key k is either not an integer or an integer not equal to
1.622 + aValue.
1.623 +@see FindL()
1.624 +@return
1.625 + KErrNone if successful,
1.626 + KErrAbort if in a transaction that has previously failed
1.627 + KErrPermissionDenied if caller fails capability check,
1.628 + KErrNotFound if capability check passed but no non-matching items are found,
1.629 + plus other system-wide error codes.
1.630 +@post Transactions fail only on those "other system-wide error codes".
1.631 +@capability Dependent Caller must satisfy the read policies of all settings found in the source range.
1.632 +*/
1.633 +EXPORT_C TInt CRepository::FindNeqL(TUint32 aPartialKey, TUint32 aMask,
1.634 + TInt aValue, RArray<TUint32>& aFoundKeys)
1.635 + {
1.636 + return (static_cast<CClientRepository*>(this))->FindNeqL(aPartialKey, aMask, aValue, aFoundKeys);
1.637 + }
1.638 +
1.639 +
1.640 +/** Finds all the settings that match the specification given by aPartialKey
1.641 +and aMask, but are either not floating point values or do not have the given value.
1.642 +@param aPartialKey
1.643 + Contains a bit pattern that all the keys returned must at least partially
1.644 + match.
1.645 +@param aMask
1.646 + Has bits set for all the bits in aPartialKey that must match the returned
1.647 + keys.
1.648 +@param aValue
1.649 + Settings for the keys found will be settings that either contain values
1.650 + that are not floating point or floating point values other than aValue.
1.651 +@param aFoundKeys All the keys found.
1.652 + For each key k in aFoundKeys, (k & aMask) == (aPartialKey & aMask) and
1.653 + the setting with key k is either not a floating point value or a floating
1.654 + point value not equal to aValue.
1.655 +@see FindL()
1.656 +@return
1.657 + KErrNone if successful,
1.658 + KErrAbort if in a transaction that has previously failed
1.659 + KErrPermissionDenied if caller fails capability check,
1.660 + KErrNotFound if capability check passed but no non-matching items are found,
1.661 + plus other system-wide error codes.
1.662 +@post Transactions fail only on those "other system-wide error codes".
1.663 +@capability Dependent Caller must satisfy the read policies of all settings found in the source range.
1.664 +*/
1.665 +EXPORT_C TInt CRepository::FindNeqL(TUint32 aPartialKey, TUint32 aMask,
1.666 + const TReal& aValue, RArray<TUint32>& aFoundKeys)
1.667 + {
1.668 + return (static_cast<CClientRepository*>(this))->FindNeqL(aPartialKey, aMask, aValue, aFoundKeys);
1.669 + }
1.670 +
1.671 +
1.672 +/** Finds all the settings that match the specification given by aPartialKey
1.673 +and aMask, but are either not string values or do not match the given string.
1.674 +@param aPartialKey
1.675 + Contains a bit pattern that all the keys returned must at least partially
1.676 + match.
1.677 +@param aMask
1.678 + Has bits set for all the bits in aPartialKey that must match the returned
1.679 + keys.
1.680 +@param aValue
1.681 + Settings for the keys found will be settings that either contain values
1.682 + that are not strings or strings with value other than aValue.
1.683 +@param aFoundKeys All the keys found.
1.684 + For each key k in aFoundKeys, (k & aMask) == (aPartialKey & aMask) and
1.685 + the setting with key k is either not a string value or a string value not
1.686 + equal to aValue.
1.687 +@see FindL()
1.688 +@return
1.689 + KErrNone if successful,
1.690 + KErrAbort if in a transaction that has previously failed
1.691 + KErrPermissionDenied if caller fails capability check,
1.692 + KErrNotFound if capability check passed but no non-matching items are found,
1.693 + plus other system-wide error codes.
1.694 +@post Transactions fail only on those "other system-wide error codes".
1.695 +@capability Dependent Caller must satisfy the read policies of all settings found in the source range.
1.696 +*/
1.697 +EXPORT_C TInt CRepository::FindNeqL(TUint32 aPartialKey, TUint32 aMask,
1.698 + const TDesC8& aValue, RArray<TUint32>& aFoundKeys)
1.699 + {
1.700 + return (static_cast<CClientRepository*>(this))->FindNeqL(aPartialKey, aMask, aValue, aFoundKeys);
1.701 + }
1.702 +
1.703 +/** Finds all the settings that match the specification given by aPartialKey
1.704 +and aMask, but are either not string values or do not match the given string.
1.705 +@param aPartialKey
1.706 + Contains a bit pattern that all the keys returned must at least partially
1.707 + match.
1.708 +@param aMask
1.709 + Has bits set for all the bits in aPartialKey that must match the returned
1.710 + keys.
1.711 +@param aValue
1.712 + Settings for the keys found will be settings that either contain values
1.713 + that are not strings or strings with value other than aValue.
1.714 +@param aFoundKeys All the keys found.
1.715 + For each key k in aFoundKeys, (k & aMask) == (aPartialKey & aMask) and
1.716 + the setting with key k is either not a string value or a string value not
1.717 + equal to aValue.
1.718 +@see FindL()
1.719 +@return
1.720 + KErrNone if successful,
1.721 + KErrAbort if in a transaction that has previously failed
1.722 + KErrPermissionDenied if caller fails capability check,
1.723 + KErrNotFound if capability check passed but no non-matching items are found,
1.724 + plus other system-wide error codes.
1.725 +@post Transactions fail only on those "other system-wide error codes".
1.726 +@capability Dependent Caller must satisfy the read policies of all settings found in the source range.
1.727 +*/
1.728 +EXPORT_C TInt CRepository::FindNeqL(TUint32 aPartialKey, TUint32 aMask,
1.729 + const TDesC16& aValue, RArray<TUint32>& aFoundKeys)
1.730 + {
1.731 + return (static_cast<CClientRepository*>(this))->FindNeqL(aPartialKey, aMask, aValue, aFoundKeys);
1.732 + }
1.733 +
1.734 +
1.735 +/** Requests a notification if the value of a given setting changes.
1.736 +Only one notification can be received per call to NotifyRequest.
1.737 +Only one notification per setting per CRepository may be active at any one
1.738 +time.
1.739 +@param aKey The key setting to be informed about.
1.740 +@param aStatus The object that will receive the notification. On a successful
1.741 + outcome, this will contain the Uid of the changed setting.
1.742 + If there is an existing notification on the same setting and same session, aStatus
1.743 + will be set to KErrAlreadyExists and the return value will be KErrNone.
1.744 +@return
1.745 + KErrNone if successful or if aStatus is set to KErrAlreadyExists.
1.746 + KErrPermissionDenied if caller fails capability check.
1.747 + KErrNotFound if the requested setting does not exist.
1.748 +@capability Note The caller must satisfy the relevant access policies for the repository
1.749 +*/
1.750 +EXPORT_C TInt CRepository::NotifyRequest(TUint32 aKey, TRequestStatus& aStatus)
1.751 + {
1.752 + return (static_cast<CClientRepository*>(this))->NotifyRequest(aKey, aStatus);
1.753 + }
1.754 +
1.755 +
1.756 +/** Cancels a notification previously requested from the two-argument overload
1.757 +of NotifyRequest.
1.758 +@param aKey The parameter to the previous call to NotifyRequest to be cancelled.
1.759 +@return KErrNone The method always returns KErrNone.
1.760 +*/
1.761 +EXPORT_C TInt CRepository::NotifyCancel(TUint32 aKey)
1.762 + {
1.763 + //We deliberately ignore the return value from the server and return KErrNone because
1.764 + //it is incorrect for a cancel function to return an error code - if there is no
1.765 + //outstanding notification then the cancel should do nothing.
1.766 + (void)(static_cast<CClientRepository*>(this))->NotifyCancel(aKey);
1.767 + return KErrNone;
1.768 + }
1.769 +
1.770 +
1.771 +/** Cancels all uncompleted notifications from this CRepository.
1.772 +@return KErrNone The method always returns KErrNone.
1.773 +*/
1.774 +EXPORT_C TInt CRepository::NotifyCancelAll()
1.775 + {
1.776 + //We deliberately ignore the return value from the server and return KErrNone because
1.777 + //it is incorrect for a cancel function to return an error code - if there is no
1.778 + //outstanding notification then the cancel should do nothing.
1.779 + (void)(static_cast<CClientRepository*>(this))->NotifyCancelAll();
1.780 + return KErrNone;
1.781 + }
1.782 +
1.783 +
1.784 +/** Requests a notification if the value of a given setting changes.
1.785 +Only one notification can be received per call to NotifyRequest.
1.786 +Only one notification per setting per CRepository may be active at any one
1.787 +time.
1.788 +@param aPartialKey The partial key setting to be informed about.
1.789 +@param aMask The mask to be used with the partial key.
1.790 +@param aStatus The object that will receive the notification. On a successful
1.791 + outcome, this will contain the Uid of the changed setting.
1.792 + On error the error code is stored in aStatus and KErrNone is returned.
1.793 +@return
1.794 + KErrNone The method always returns KErrNone.
1.795 +@capability Note The caller must satisfy the relevant access policies for the repository
1.796 +*/
1.797 +EXPORT_C TInt CRepository::NotifyRequest(TUint32 aPartialKey, TUint32 aMask,
1.798 + TRequestStatus& aStatus)
1.799 + {
1.800 + return (static_cast<CClientRepository*>(this))
1.801 + ->NotifyRequest(aPartialKey, aMask, aStatus);
1.802 + }
1.803 +
1.804 +
1.805 +/** Cancels a notification previously requested from the three-argument overload
1.806 +of NotifyRequest.
1.807 +@param aPartialKey The parameter to the previous call to NotifyRequest to be cancelled.
1.808 +@param aMask The mask to be used with the partial key
1.809 +@return KErrNone The method always returns KErrNone.
1.810 +*/
1.811 +EXPORT_C TInt CRepository::NotifyCancel(TUint32 aPartialKey, TUint32 aMask)
1.812 + {
1.813 + (void)(static_cast<CClientRepository*>(this))->NotifyCancel(aPartialKey, aMask);
1.814 + return KErrNone;
1.815 + }
1.816 +
1.817 +
1.818 +/** Resets the whole repository to the state of the initialization file
1.819 +originally used to set it up. Not currently supported in transactions.
1.820 +@return
1.821 + KErrNone if successful,
1.822 + KErrNotSupported if this client session is in a transaction
1.823 + plus other system-wide error codes.
1.824 +@post Fails transaction if called when session is in one.
1.825 +@capability Dependent The caller must satisfy the relevant access policies for the repository
1.826 +*/
1.827 +EXPORT_C TInt CRepository::Reset()
1.828 + {
1.829 + return (static_cast<CClientRepository*>(this))->Reset();
1.830 + }
1.831 +
1.832 +
1.833 +/** Resets the a setting within the repository to the state of the setting
1.834 +described by the initialization file originally used to set the repository up.
1.835 +Not currently supported in transactions.
1.836 +@param aKey Key of setting to be reset.
1.837 +@return
1.838 + KErrNone if successful,
1.839 + KErrNotSupported if this client session is in a transaction
1.840 + plus other system-wide error codes.
1.841 +@post Fails transaction if called when session is in one.
1.842 +@capability Note The caller must satisfy the relevant access policies for the repository
1.843 +*/
1.844 +EXPORT_C TInt CRepository::Reset(TUint32 aKey)
1.845 + {
1.846 + return (static_cast<CClientRepository*>(this))->Reset(aKey);
1.847 + }
1.848 +
1.849 +
1.850 +/** Attempts to starts a transaction in the given mode.
1.851 +Consistency and persistence of all values read and written during the transaction
1.852 +is only guaranteed after a successful return from CommitTransaction.
1.853 +@param aMode transaction mode: EConcurrentReadWriteTransaction (standard),
1.854 + EReadTransaction or EReadWriteTransaction.
1.855 +@return KErrNone if successful - guaranteed for EConcurrentReadWriteTransaction,
1.856 + KErrLocked for other transaction types if read or write locks held by other clients
1.857 + prevent transaction from starting.
1.858 +@see CRepository::TTransactionMode
1.859 +@pre Must not be in a transaction.
1.860 +@post If it returns KErrNone: in a transaction; Any other error code: not in a transaction.
1.861 +@panic CENREPCLI 3 Panics client if this session is already in a transaction.
1.862 +*/
1.863 +EXPORT_C TInt CRepository::StartTransaction(TTransactionMode aMode)
1.864 + {
1.865 + return (static_cast<CClientRepository*>(this))->StartTransaction(aMode);
1.866 + }
1.867 +
1.868 +
1.869 +/** Attempts to starts a transaction in the given mode asynchronously to
1.870 +allow client to avoid being blocked by server activity before starting.
1.871 +Consistency and persistence of all values read and written during the transaction
1.872 +is only guaranteed after a successful return from CommitTransaction.
1.873 +Use CancelTransaction to cancel asynchronous request.
1.874 +@param aMode transaction mode: EConcurrentReadWriteTransaction (standard),
1.875 + EReadTransaction or EReadWriteTransaction.
1.876 +@see CRepository::TTransactionMode
1.877 +@param aStatus On completion of asynchronous request: KErrNone if successful -
1.878 + guaranteed for EConcurrentReadWriteTransaction unless cancelled,
1.879 + KErrLocked for other transaction types if read or write locks held by other clients
1.880 + prevent transaction from starting.
1.881 +@pre Must not be in a transaction.
1.882 +@post If it completes with KErrNone and request not cancelled: in a transaction;
1.883 + Any other error code or request cancelled: not in a transaction.
1.884 +@panic CENREPCLI 3 Panics client if this session is already in a transaction.
1.885 +*/
1.886 +EXPORT_C void CRepository::StartTransaction(TTransactionMode aMode, TRequestStatus& aStatus)
1.887 + {
1.888 + (static_cast<CClientRepository*>(this))->StartTransaction(aMode, aStatus);
1.889 + }
1.890 +
1.891 +
1.892 +/** Commits a transaction. A successful return guarantees the consistency and
1.893 +persistence of all values read and written during the transaction.
1.894 +@return KErrNone on success, or error code giving first reason for failing.
1.895 + If KErrLocked is returned for EConcurrentReadWriteTransaction, transaction
1.896 + was interrupted by another client committing changes and should be repeated.
1.897 +@param aKeyInfo
1.898 + On success: returns the number of keys whose values were modified.
1.899 + On failure: returns the key or partial key involved in the first error, or
1.900 + KUnspecifiedKey if failure could not be attributed to any key.
1.901 +@pre Must be in a transaction.
1.902 +@post Not in a transaction. On success, changes have been made persistent. On failure,
1.903 + transaction changes have been rolled back.
1.904 +@panic CENREPCLI 4 Panics client if this session is not in a transaction.
1.905 +*/
1.906 +EXPORT_C TInt CRepository::CommitTransaction(TUint32& aKeyInfo)
1.907 + {
1.908 + return (static_cast<CClientRepository*>(this))->CommitTransaction(aKeyInfo);
1.909 + }
1.910 +
1.911 +
1.912 +/** Commits a transaction asynchronously to allow client to avoid being blocked
1.913 +during the persist operation and other server activity. A successful return guarantees
1.914 +the consistency and persistence of all values read and written during the transaction.
1.915 +Use CancelTransaction to cancel asynchronous request.
1.916 +@param aKeyInfo
1.917 + A descriptor to receive a TUint32 value, e.g. TTransactionKeyInfoBuf, which
1.918 + client must ensure remains in scope for the duration of the asynchronous request.
1.919 + On success: returns the number of keys whose values were modified.
1.920 + On failure: returns the key or partial key involved in the first error, or
1.921 + KUnspecifiedKey if failure could not be attributed to any key.
1.922 +@see CRepository::TTransactionKeyInfoBuf
1.923 +@param aStatus Completion status of asynchronous request:
1.924 + On success (if not cancelled): KErrNone;
1.925 + On failure: error code giving first reason for failing.
1.926 + If KErrLocked is returned for EConcurrentReadWriteTransaction, transaction
1.927 + was interrupted by another client committing changes and should be repeated.
1.928 +@pre Must be in a transaction.
1.929 +@post Cannot assume that transaction is "pending commit" as may have completed already.
1.930 + Once request is complete, session is not in a transaction: on success, changes
1.931 + have been made persistent; on failure, transaction changes have been rolled back.
1.932 +@panic CENREPCLI 4 Panics client if this session is not in a transaction.
1.933 +*/
1.934 +EXPORT_C void CRepository::CommitTransaction(TDes8& aKeyInfo, TRequestStatus& aStatus)
1.935 + {
1.936 + (static_cast<CClientRepository*>(this))->CommitTransaction(aKeyInfo, aStatus);
1.937 + }
1.938 +
1.939 +
1.940 +/** Cancels the current transaction with rollback: discards any uncommitted changes.
1.941 +If the transaction is pending start or commit asynchronously, the request is
1.942 +completed with KErrCancel (unless it had already completed).
1.943 +@post Not in a transaction.
1.944 +*/
1.945 +EXPORT_C void CRepository::CancelTransaction()
1.946 + {
1.947 + (static_cast<CClientRepository*>(this))->CancelTransaction();
1.948 + }
1.949 +
1.950 +
1.951 +/** Pushes onto the CleanupStack a TCleanupItem that calls CancelTransaction if
1.952 +activated by a Leave or PopAndDestroy. Important for releasing transaction resources
1.953 +including caches and read/write locks held over the repository.
1.954 +@post CleanupStack has another item on it which must be popped later with
1.955 +CleanupStack::Pop() or similar.
1.956 +*/
1.957 +EXPORT_C void CRepository::CleanupCancelTransactionPushL()
1.958 + {
1.959 + (static_cast<CClientRepository*>(this))->CleanupCancelTransactionPushL();
1.960 + }
1.961 +
1.962 +
1.963 +/** Sets the active transaction to a failed state, releasing cache and locks but
1.964 +keeping it open. Has no effect when not in an active transaction, including when it
1.965 +has already failed or when pending asynchronous start or commit request completion.
1.966 +Use in preference to CancelTransaction whenever it is inappropriate to close the
1.967 +transaction at the time.
1.968 +@post
1.969 + If previously in an active transaction: It is marked as failed. All uncommitted
1.970 + changes are discarded. Transaction resources including cache and read/write locks
1.971 + are released in the repository. All subsequent operations in the transaction fail
1.972 + until it is closed by CancelTransaction or CommitTransaction. CommitTransaction
1.973 + will fail and return KErrAbort.
1.974 +*/
1.975 +EXPORT_C void CRepository::FailTransaction()
1.976 + {
1.977 + (static_cast<CClientRepository*>(this))->FailTransaction();
1.978 + }
1.979 +
1.980 +
1.981 +/** Pushes onto the CleanupStack a TCleanupItem that calls FailTransaction if
1.982 +activated by a Leave or PopAndDestroy.
1.983 +@post CleanupStack has another item on it which must be popped later with
1.984 +CleanupStack::Pop() or similar.
1.985 +*/
1.986 +EXPORT_C void CRepository::CleanupFailTransactionPushL()
1.987 + {
1.988 + (static_cast<CClientRepository*>(this))->CleanupFailTransactionPushL();
1.989 + }