1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/kernelhwsrv/kernel/eka/euser/us_property.cpp Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,754 @@
1.4 +// Copyright (c) 2002-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 the License "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 +// e32\euser\us_property.cpp
1.18 +//
1.19 +//
1.20 +
1.21 +#include "us_std.h"
1.22 +
1.23 +/**
1.24 +Defines a property with the specified category ID. This method should only be
1.25 +used to specify a category different from the creating process's secure ID in
1.26 +exceptional circumstances. In most cases the overload:
1.27 +
1.28 +RProperty::Define(TUint aKey, TInt aAttr, const TSecurityPolicy& aReadPolicy, const TSecurityPolicy& aWritePolicy, TInt aPreallocate)
1.29 +
1.30 +should be used. For details see the document located at:
1.31 +
1.32 +Symbian OS guide » Base » Using User Library (E32) » Publish and Subscribe » Security issues
1.33 +
1.34 +Defines the attributes and access control for a property. This can only be done
1.35 +once for each property. Subsequent attempts to define the same property will return
1.36 +KErrAlreadyExists.
1.37 +
1.38 +Only processes with the write-system-data capability are allowed to define
1.39 +properties either in the system category (KUidSystemCategory) or with
1.40 +aCategory < KUidSecurityThresholdCategoryValue. Any attempt to define
1.41 +a property with these categories by a process with insufficient capabilities
1.42 +will fail with a KErrPermissionDenied error.
1.43 +
1.44 +Following the property's definition, it will have a default value, 0 for integer
1.45 +properties and zero-length data for byte-array and text properties.
1.46 +Pending subscriptions for this property will not be completed until a new
1.47 +value is published.
1.48 +
1.49 +@param aCategory The UID that identifies the property category.
1.50 + This must either be the current process's Secure ID, or
1.51 + KUidSystemCategoryValue.
1.52 +@param aKey The property sub-key, i.e. the key that identifies the
1.53 + specific property within the category.
1.54 +@param aAttr This describes the property type, a TType value;
1.55 + persistence, as defined by the KPersistent bit, may
1.56 + be ORed in.
1.57 +@param aReadPolicy A security policy defining the security attributes a
1.58 + process must have in order to read this value.
1.59 +@param aWritePolicy A security policy defining the security attributes a
1.60 + process must have in order to write this value.
1.61 +@param aPreallocate The number of bytes to be pre-allocated for variable
1.62 + sized properties. Pre-allocating enough space ensures that
1.63 + a variable sized property can be set in 'real-time',
1.64 + (i.e. the time to set the property is bounded).
1.65 +
1.66 +@return KErrNone, if successful;
1.67 + KErrArgument, if the wrong type or attribute was specified;
1.68 + KErrArgument, if aType is TInt and aPreallocate is not 0;
1.69 + KErrTooBig, if aPreallocate is greater than KMaxPropertySize;
1.70 + KErrPermissionDenied, if an attempt is made to define a property in
1.71 + the system category by a process with insufficient capabilities, or
1.72 + the category secified wasn't the same as the current process's Secure ID.
1.73 +
1.74 +@capability WriteDeviceData if aCategory==KUidSystemCategoryValue.
1.75 +@capability WriteDeviceData if aCategory not equal to the current process's
1.76 + Secure ID and aCategory<KUidSecurityThresholdCategoryValue.
1.77 +
1.78 +
1.79 +@see KUidSecurityThresholdCategoryValue
1.80 +
1.81 +@publishedPartner
1.82 +@released
1.83 +*/
1.84 +EXPORT_C TInt RProperty::Define(TUid aCategory, TUint aKey, TInt aAttr, const TSecurityPolicy& aReadPolicy, const TSecurityPolicy& aWritePolicy, TInt aPreallocate)
1.85 + {
1.86 + if(aPreallocate < 0)
1.87 + return KErrArgument;
1.88 + if(aPreallocate > KMaxLargePropertySize)
1.89 + return KErrTooBig;
1.90 +
1.91 + TPropertyInfo info;
1.92 + info.iType = (RProperty::TType)(aAttr & RProperty::ETypeMask);
1.93 + info.iAttr = (aAttr & ~RProperty::ETypeMask);
1.94 + info.iSize = (TUint16) aPreallocate;
1.95 + info.iReadPolicy = aReadPolicy;
1.96 + info.iWritePolicy = aWritePolicy;
1.97 + return(Exec::PropertyDefine(TUint(aCategory.iUid), aKey, &info));
1.98 + }
1.99 +
1.100 +
1.101 +/**
1.102 +Defines a property.
1.103 +
1.104 +Defines the attributes and access control for a property. This can only be done
1.105 +once for each property. Subsequent attempts to define the same property will return
1.106 +KErrAlreadyExists.
1.107 +
1.108 +The category ID for the property will be the same as the current processes Secure ID.
1.109 +
1.110 +Following the property's definition, it will have a default value, 0 for integer
1.111 +properties and zero-length data for byte-array and text properties.
1.112 +Pending subscriptions for this property will not be completed until a new
1.113 +value is published.
1.114 +
1.115 +@param aKey The property sub-key, i.e. the key that identifies the
1.116 + specific property within the category.
1.117 +@param aAttr This describes the property type, a TType value;
1.118 + persistence, as defined by the KPersistent bit, may
1.119 + be ORed in.
1.120 +@param aReadPolicy A security policy defining the security attributes a
1.121 + process must have in order to read this value.
1.122 +@param aWritePolicy A security policy defining the security attributes a
1.123 + process must have in order to write this value.
1.124 +@param aPreallocate The number of bytes to be pre-allocated for variable
1.125 + sized properties. Pre-allocating enough space ensures that
1.126 + a variable sized property can be set in 'real-time',
1.127 + (i.e. the time to set the property is bounded).
1.128 +
1.129 +@return KErrNone, if successful;
1.130 + KErrArgument, if the wrong type or attribute was specified;
1.131 + KErrArgument, if aType is TInt and aPreallocate is not 0;
1.132 + KErrTooBig, if aPreallocate is greater than KMaxPropertySize;
1.133 +
1.134 +@publishedPartner
1.135 +@released
1.136 +*/
1.137 +EXPORT_C TInt RProperty::Define(TUint aKey, TInt aAttr, const TSecurityPolicy& aReadPolicy, const TSecurityPolicy& aWritePolicy, TInt aPreallocate)
1.138 + {
1.139 + TUid category = {-1};
1.140 + return Define(category, aKey, aAttr, aReadPolicy, aWritePolicy, aPreallocate);
1.141 + }
1.142 +
1.143 +
1.144 +
1.145 +/**
1.146 +NOTE - The use of this method is deprecated.
1.147 +
1.148 +Defines a property with the specified category ID. This method should only be
1.149 +used to specify a category different from the creating process's secure ID in
1.150 +exceptional circumstances. In most cases the overload:
1.151 +
1.152 +RProperty::Define(TUint aKey, TInt aAttr, const TSecurityPolicy& aReadPolicy, const TSecurityPolicy& aWritePolicy, TInt aPreallocate)
1.153 +
1.154 +should be used. For details see the document located at:
1.155 +
1.156 +Symbian OS guide » Base » Using User Library (E32) » Publish and Subscribe » Security issues
1.157 +
1.158 +Defines the attributes and access control for a property. This can only be done
1.159 +once for each property. Subsequent attempts to define the same property will
1.160 +return KErrAlreadyExists.
1.161 +
1.162 +Only processes with the write-system-data capability are allowed to define
1.163 +properties either in the system category (KUidSystemCategory) or with
1.164 +aCategory < KUidSecurityThresholdCategoryValue. Any attempt to define
1.165 +a property with these categories by a process with insufficient capabilities
1.166 +will fail with a KErrPermissionDenied error.
1.167 +
1.168 +Following the property's definition, it will have a default value, 0 for integer
1.169 +properties and zero-length data for byte-array and text properties.
1.170 +Pending subscriptions for this property will not be completed until a new
1.171 +value is published.
1.172 +
1.173 +@param aCategory The UID that identifies the property category.
1.174 +@param aKey The property sub-key, i.e. the key that identifies the
1.175 + specific property within the category.
1.176 +@param aAttr This describes the property type, a TType value;
1.177 + persistence, as defined by the KPersistent bit, may
1.178 + be ORed in.
1.179 +@param aPreallocate The number of bytes to be pre-allocated for variable
1.180 + sized properties. Pre-allocating enough space ensures that
1.181 + a variable sized property can be set in 'real-time',
1.182 + (i.e. the time to set the property is bounded).
1.183 +
1.184 +@return KErrNone, if successful;
1.185 + KErrArgument, if the wrong type or attribute was specified;
1.186 + KErrArgument, if aType is TInt and aPreallocate is not 0;
1.187 + KErrTooBig, if aPreallocate is greater than KMaxPropertySize;
1.188 + KErrPermissionDenied, if an attempt is made to define a property in
1.189 + the system category by a process with insufficient capabilities.
1.190 +
1.191 +@capability WriteDeviceData if aCategory==KUidSystemCategoryValue.
1.192 +@capability WriteDeviceData if aCategory not equal to the current process's
1.193 + Secure ID and aCategory<KUidSecurityThresholdCategoryValue.
1.194 +
1.195 +@see KUidSecurityThresholdCategoryValue
1.196 +@publishedAll
1.197 +@deprecated Use RProperty::Define(TUint aKey, TInt aAttr, const TSecurityPolicy &aReadPolicy, const TSecurityPolicy &aWritePolicy, TInt aPreallocated=0)
1.198 + instead.
1.199 +*/
1.200 +EXPORT_C TInt RProperty::Define(TUid aCategory, TUint aKey, TInt aAttr, TInt aPreallocate)
1.201 + {
1.202 + TPropertyInfo info;
1.203 + info.iType = (RProperty::TType)(aAttr & RProperty::ETypeMask);
1.204 + info.iAttr = (aAttr & ~RProperty::ETypeMask);
1.205 + info.iSize = (TUint16) aPreallocate;
1.206 + info.iReadPolicy = TSecurityPolicy(TSecurityPolicy::EAlwaysPass);
1.207 + info.iWritePolicy = TSecurityPolicy(TSecurityPolicy::EAlwaysPass);
1.208 + return(Exec::PropertyDefine(TUint(aCategory.iUid), aKey, &info));
1.209 + }
1.210 +
1.211 +
1.212 +/**
1.213 +Deletes a property.
1.214 +
1.215 +This can only be called by the property owner, as defined by
1.216 +the process Security ID; any attempt by another process to delete
1.217 +the property will fail.
1.218 +
1.219 +Any pending subscriptions for this property will be completed
1.220 +with KErrNotFound.
1.221 +Any new request will not complete until the property is defined
1.222 +and published again.
1.223 +
1.224 +@param aCategory The UID that identifies the property category.
1.225 +@param aKey The property sub-key, i.e. the key that identifies the
1.226 + specific property within the category.
1.227 +
1.228 +@return KErrNone, if successful;
1.229 + KErrPermissionDenied, if a process that is not the owner of
1.230 + the property attempts to delete it.
1.231 + KErrNotFound, if the property has not been defined.
1.232 +*/
1.233 +EXPORT_C TInt RProperty::Delete(TUid aCategory, TUint aKey)
1.234 + {
1.235 + return(Exec::PropertyDelete(TUint(aCategory.iUid), aKey));
1.236 + }
1.237 +
1.238 +
1.239 +
1.240 +/**
1.241 +Deletes a property.
1.242 +
1.243 +The category ID for the property will be the same as the current processes Secure ID.
1.244 +
1.245 +Any pending subscriptions for this property will be completed
1.246 +with KErrNotFound.
1.247 +Any new request will not complete until the property is defined
1.248 +and published again.
1.249 +
1.250 +@param aKey The property sub-key, i.e. the key that identifies the
1.251 + specific property within the category.
1.252 +
1.253 +@return KErrNone, if successful;
1.254 + KErrNotFound, if the property has not been defined.
1.255 +*/
1.256 +EXPORT_C TInt RProperty::Delete(TUint aKey)
1.257 + {
1.258 + return(Exec::PropertyDelete(KMaxTUint, aKey));
1.259 + }
1.260 +
1.261 +
1.262 +/**
1.263 +Gets an integer property.
1.264 +
1.265 +The function gets the integer value of the specified property.
1.266 +
1.267 +The Platform Security attributes of the current process are checked against
1.268 +the Read Policy which was specified when the property was defined.
1.269 +If this check fails the action taken is determined by the system wide Platform Security
1.270 +configuration. If PlatSecDiagnostics is ON, then a diagnostic message is emitted.
1.271 +If PlatSecEnforcement is OFF, then this function will return KErrNone even though the
1.272 +check failed.
1.273 +
1.274 +@param aCategory The UID that identifies the property category.
1.275 +@param aKey The property sub-key, i.e. the key that identifies the
1.276 + specific property within the category.
1.277 +@param aValue A reference to the variable where the property value will
1.278 + be reported.
1.279 +
1.280 +@return KErrNone, if successful;
1.281 + KErrPermissionDenied, if the caller process doesn't pass the Read Policy;
1.282 + KErrNotFound, if the property has not been defined;
1.283 + KErrArgument, if the property is not of integral type.
1.284 +*/
1.285 +EXPORT_C TInt RProperty::Get(TUid aCategory, TUint aKey, TInt& aValue)
1.286 + {
1.287 + return(Exec::PropertyFindGetI(TUint(aCategory.iUid), aKey, &aValue));
1.288 + }
1.289 +
1.290 +
1.291 +
1.292 +
1.293 +/**
1.294 +Gets a binary property.
1.295 +
1.296 +The function gets the byte-array (binary) value of the specified property.
1.297 +
1.298 +The Platform Security attributes of the current process are checked against
1.299 +the Read Policy which was specified when the property was defined.
1.300 +If this check fails the action taken is determined by the system wide Platform Security
1.301 +configuration. If PlatSecDiagnostics is ON, then a diagnostic message is emitted.
1.302 +If PlatSecEnforcement is OFF, then this function will return KErrNone even though the
1.303 +check failed.
1.304 +
1.305 +@param aCategory The UID that identifies the property category.
1.306 +@param aKey The property sub-key, i.e. the key that identifies the
1.307 + specific property within the category.
1.308 +@param aDes A reference to the buffer descriptor where the property value
1.309 + will be reported.
1.310 +
1.311 +@return KErrNone if successful;
1.312 + KErrPermissionDenied, if the caller process doesn't pass the Read Policy;
1.313 + KErrNotFound, if the property has not been defined;
1.314 + KErrArgument, if the property is not a byte-array (binary) type;
1.315 + KErrOverflow, if the supplied buffer is too small to contain the full
1.316 + property value, and note that the buffer aDes contains the
1.317 + truncated property value.
1.318 +*/
1.319 +EXPORT_C TInt RProperty::Get(TUid aCategory, TUint aKey, TDes8& aDes)
1.320 + {
1.321 + TInt size = aDes.MaxSize();
1.322 + TInt r = Exec::PropertyFindGetB(TUint(aCategory.iUid), aKey, (TUint8*) aDes.Ptr(), size);
1.323 + if (r < 0)
1.324 + {
1.325 + if (r == KErrOverflow)
1.326 + {
1.327 + aDes.SetLength(size);
1.328 + }
1.329 + return r;
1.330 + }
1.331 + aDes.SetLength(r);
1.332 + return KErrNone;
1.333 + }
1.334 +
1.335 +
1.336 +
1.337 +
1.338 +/**
1.339 +Gets a text property.
1.340 +
1.341 +The function gets the text value of the specified property.
1.342 +
1.343 +The Platform Security attributes of the current process are checked against
1.344 +the Read Policy which was specified when the property was defined.
1.345 +If this check fails the action taken is determined by the system wide Platform Security
1.346 +configuration. If PlatSecDiagnostics is ON, then a diagnostic message is emitted.
1.347 +If PlatSecEnforcement is OFF, then this function will return KErrNone even though the
1.348 +check failed.
1.349 +
1.350 +@param aCategory The UID that identifies the property category.
1.351 +@param aKey The property sub-key, i.e. the key that identifies the
1.352 + specific property within the category.
1.353 +@param aDes A reference to the buffer descriptor where the property value
1.354 + will be reported.
1.355 +
1.356 +@return KErrNone, if successful;
1.357 + KErrPermissionDenied, if the caller process doesn't pass the Read Policy;
1.358 + KErrNotFound, if the property has not been defined;
1.359 + KErrArgument, if the property is not a text type;
1.360 + KErrOverflow, if the supplied buffer is too small to contain the full
1.361 + property value, and note that the buffer aDes contains the
1.362 + truncated property value.
1.363 +*/
1.364 +EXPORT_C TInt RProperty::Get(TUid aCategory, TUint aKey, TDes16& aDes)
1.365 + {
1.366 + TInt size = aDes.MaxSize();
1.367 + TInt r = Exec::PropertyFindGetB(TUint(aCategory.iUid), aKey, (TUint8*) aDes.Ptr(), size);
1.368 + if (r < 0)
1.369 + {
1.370 + if (r == KErrOverflow)
1.371 + {
1.372 + aDes.SetLength(size >> 1);
1.373 + }
1.374 + return r;
1.375 + }
1.376 + aDes.SetLength(r >> 1);
1.377 + return KErrNone;
1.378 + }
1.379 +
1.380 +
1.381 +
1.382 +
1.383 +/**
1.384 +Sets an integer property.
1.385 +
1.386 +The function publishes a new integral property value.
1.387 +
1.388 +Any pending subscriptions for this property will be completed.
1.389 +
1.390 +The Platform Security attributes of the current process are checked against
1.391 +the Write Policy which was specified when the property was defined.
1.392 +If this check fails the action taken is determined by the system wide Platform Security
1.393 +configuration. If PlatSecDiagnostics is ON, then a diagnostic message is emitted.
1.394 +If PlatSecEnforcement is OFF, then this function will return KErrNone even though the
1.395 +check failed.
1.396 +
1.397 +@param aCategory The UID that identifies the property category.
1.398 +@param aKey The property sub-key, i.e. the key that identifies the
1.399 + specific property within the category.
1.400 +@param aValue The new property value.
1.401 +
1.402 +@return KErrNone, if successful;
1.403 + KErrPermissionDenied, if the caller process doesn't pass the Write Policy;
1.404 + KErrNotFound, if the property has not been defined;
1.405 + KErrArgument, if the property is not of integral type.
1.406 +*/
1.407 +EXPORT_C TInt RProperty::Set(TUid aCategory, TUint aKey, TInt aValue)
1.408 + {
1.409 + return(Exec::PropertyFindSetI(TUint(aCategory.iUid), aKey, aValue));
1.410 + }
1.411 +
1.412 +
1.413 +
1.414 +
1.415 +/**
1.416 +Sets a binary property.
1.417 +
1.418 +The function Publishes a new byte-array (binary) value for
1.419 +the specified property.
1.420 +
1.421 +Any pending subscriptions for this property will be completed.
1.422 +
1.423 +Note that if the new property value requires more storage space than is
1.424 +currently allocated, then memory allocation will be required.
1.425 +This invalidates any real-time guarantee, i.e. the guarantee that the operation
1.426 +will complete within a bounded time.
1.427 +
1.428 +The Platform Security attributes of the current process are checked against
1.429 +the Write Policy which was specified when the property was defined.
1.430 +If this check fails the action taken is determined by the system wide Platform Security
1.431 +configuration. If PlatSecDiagnostics is ON, then a diagnostic message is emitted.
1.432 +If PlatSecEnforcement is OFF, then this function will return KErrNone even though the
1.433 +check failed.
1.434 +
1.435 +@param aCategory The UID that identifies the property category.
1.436 +@param aKey The property sub-key, i.e. the key that identifies the
1.437 + specific property within the category.
1.438 +@param aDes A reference to the descriptor containing the
1.439 + new property value.
1.440 +
1.441 +@return KErrNone, if successful;
1.442 + KErrPermissionDenied, if the caller process doesn't pass the Write Policy;
1.443 + KErrNotFound, if the property has not been defined;
1.444 + KErrArgument, if the property is not a byte-array (binary) type;
1.445 + KErrNoMemory, if memory allocation is required, and there is
1.446 + insufficient available.
1.447 +*/
1.448 +EXPORT_C TInt RProperty::Set(TUid aCategory, TUint aKey, const TDesC8& aDes)
1.449 + {
1.450 + return(Exec::PropertyFindSetB(TUint(aCategory.iUid), aKey, (TUint8*) aDes.Ptr(), aDes.Size()));
1.451 + }
1.452 +
1.453 +
1.454 +
1.455 +
1.456 +/**
1.457 +Sets a text property.
1.458 +
1.459 +The function publishes a new text value for the specified property.
1.460 +
1.461 +Any pending subscriptions for this property will be completed.
1.462 +
1.463 +Note that if the new property value requires more storage space than is
1.464 +currently allocated, then memory allocation will be required.
1.465 +This invalidates any real-time guarantee, i.e. the guarantee that the operation
1.466 +will complete within a bounded time.
1.467 +
1.468 +The Platform Security attributes of the current process are checked against
1.469 +the Write Policy which was specified when the property was defined.
1.470 +If this check fails the action taken is determined by the system wide Platform Security
1.471 +configuration. If PlatSecDiagnostics is ON, then a diagnostic message is emitted.
1.472 +If PlatSecEnforcement is OFF, then this function will return KErrNone even though the
1.473 +check failed.
1.474 +
1.475 +@param aCategory The UID that identifies the property category.
1.476 +@param aKey The property sub-key, i.e. the key that identifies the
1.477 + specific property within the category.
1.478 +@param aDes A reference to the descriptor containing the
1.479 + new property value.
1.480 +
1.481 +@return KErrNone, if successful;
1.482 + KErrPermissionDenied, if the caller process doesn't pass the Write Policy;
1.483 + KErrNotFound, if the property has not been defined;
1.484 + KErrArgument, if the property is not a text type;
1.485 + KErrNoMemory, if memory allocation is required, and there is
1.486 + insufficient available;
1.487 + KErrTooBig, if the property is larger than KMaxPropertySize;
1.488 +*/
1.489 +EXPORT_C TInt RProperty::Set(TUid aCategory, TUint aKey, const TDesC16& aDes)
1.490 + {
1.491 + return(Exec::PropertyFindSetB(TUint(aCategory.iUid), aKey, (TUint8*) aDes.Ptr(), aDes.Size()));
1.492 + }
1.493 +
1.494 +
1.495 +
1.496 +
1.497 +/**
1.498 +Attaches to the specified property.
1.499 +
1.500 +The function creates a handle (this object) to the specified property.
1.501 +This allows the caller to subscribe for notification of changes to this
1.502 +property, and to faster and real-time property access methods.
1.503 +
1.504 +If the specified property does not exist, then this operation will
1.505 +still succeed. However, memory allocation will be required.
1.506 +Note that this invalidates any real-time guarantee, i.e. the guarantee that
1.507 +the operation completes within a bounded time.
1.508 +
1.509 +@param aCategory The UID that identifies the property category.
1.510 +@param aKey The property sub-key, i.e. the key that identifies the
1.511 + specific property within the category.
1.512 +@param aType The ownership of this property handle.
1.513 + By default, ownership is vested in the current process,
1.514 + but can be vested in the current thread by
1.515 + specifying EOwnerThread.
1.516 +
1.517 +@return KErrNone, if successful;
1.518 + KErrNoMemory, if memory allocation is required, and there is
1.519 + insufficient available.
1.520 +*/
1.521 +EXPORT_C TInt RProperty::Attach(TUid aCategory, TUint aKey, TOwnerType aType)
1.522 + {
1.523 + TInt r = Exec::PropertyAttach(TUint(aCategory.iUid), aKey, aType);
1.524 + if (r < 0)
1.525 + { // error
1.526 + iHandle = 0;
1.527 + return r;
1.528 + }
1.529 + iHandle = r;
1.530 + return KErrNone;
1.531 + }
1.532 +
1.533 +
1.534 +
1.535 +
1.536 +/**
1.537 +Subscribes to a property.
1.538 +
1.539 +The function issues an asynchronous request to be notified when the property
1.540 +is changed. The calling thread is signalled, and the specified request status
1.541 +object is updated when the property is next changed.
1.542 +
1.543 +The property may change several times before the subscribing thread can deal
1.544 +with a notification request completion. To ensure that the subscriber does not
1.545 +miss updates, it should re-issue a subscription request before retrieving
1.546 +the current value and acting on it.
1.547 +
1.548 +If the property has not been defined, the request does not complete until
1.549 +the property is subsequently defined and published. When defined, if the caller
1.550 +process doesn't pass the Read Policy, then the request completes with KErrPermissionDenied.
1.551 +
1.552 +If the property is already defined, and the caller process doesn't pass the Read Policy,
1.553 +then the request completes immediately with KErrPermissionDenied.
1.554 +
1.555 +When Read Policy checks fail the action taken is determined by the system wide Platform Security
1.556 +configuration. If PlatSecDiagnostics is ON, then a diagnostic message is emitted.
1.557 +If PlatSecEnforcement is OFF, then the request will complete successfully even though the
1.558 +check failed.
1.559 +
1.560 +If an outstanding request is cancelled through a call to Cancel(), then it
1.561 +completes with KErrCancel.
1.562 +
1.563 +@param aRequest The request status object to be signalled on update.
1.564 +
1.565 +@panic KERN-EXEC 9 if there is already a subscription on this property handle;
1.566 + only one subscription per RProperty is allowed.
1.567 +*/
1.568 +EXPORT_C void RProperty::Subscribe(TRequestStatus& aRequest)
1.569 + {
1.570 + aRequest = KRequestPending;
1.571 + Exec::PropertySubscribe(iHandle, &aRequest);
1.572 + }
1.573 +
1.574 +
1.575 +
1.576 +
1.577 +/**
1.578 +Cancels an outstanding subscription request for this property handle.
1.579 +
1.580 +If the request has not already completed, then it completes with KErrCancel.
1.581 +*/
1.582 +EXPORT_C void RProperty::Cancel()
1.583 + {
1.584 + Exec::PropertyCancel(iHandle);
1.585 + }
1.586 +
1.587 +
1.588 +
1.589 +
1.590 +/**
1.591 +Gets the integer value of this property.
1.592 +
1.593 +The implementation guarantees that this call has a bounded response time.
1.594 +
1.595 +@param aValue A reference to the variable where the property value
1.596 + will be reported.
1.597 +
1.598 +@return KErrNone, if successful;
1.599 + KErrPermissionDenied, if the caller process doesn't pass the Read Policy;
1.600 + KErrNotFound, if the property has not been defined;
1.601 + KErrArgument, if the property is not of integral type.
1.602 +*/
1.603 +EXPORT_C TInt RProperty::Get(TInt& aValue)
1.604 + {
1.605 + return(Exec::PropertyGetI(iHandle, &aValue));
1.606 + }
1.607 +
1.608 +
1.609 +
1.610 +
1.611 +/**
1.612 +Gets the byte-array (binary) value of this property.
1.613 +
1.614 +The implementation guarantees that this call has a bounded response time.
1.615 +
1.616 +@param aDes A reference to the buffer descriptor where the property value
1.617 + will be reported.
1.618 +
1.619 +@return KErrNone, if successful;
1.620 + KErrPermissionDenied, if the caller process doesn't pass the Read Policy;
1.621 + KErrNotFound, if the property has not been defined;
1.622 + KErrArgument, if the property is not a byte-array (binary) type.
1.623 + KErrOverflow, if the supplied buffer is too small to contain the full
1.624 + property value, and note that the buffer aDes contains the
1.625 + truncated property value.
1.626 +*/
1.627 +EXPORT_C TInt RProperty::Get(TDes8& aDes)
1.628 + {
1.629 + TInt size = aDes.MaxSize();
1.630 + TInt r = Exec::PropertyGetB(iHandle, (TUint8*) aDes.Ptr(), size);
1.631 + if (r < 0)
1.632 + {
1.633 + if (r == KErrOverflow)
1.634 + {
1.635 + aDes.SetLength(size);
1.636 + }
1.637 + return r;
1.638 + }
1.639 + aDes.SetLength(r);
1.640 + return KErrNone;
1.641 + }
1.642 +
1.643 +
1.644 +
1.645 +
1.646 +/**
1.647 +Gets the text value of this property.
1.648 +
1.649 +The implementation guarantees that this call has a bounded response time.
1.650 +
1.651 +@param aDes A reference to the buffer descriptor where the property value
1.652 + will be reported.
1.653 +
1.654 +@return KErrNone, if successful;
1.655 + KErrPermissionDenied, if the caller process doesn't pass the Read Policy;
1.656 + KErrNotFound, if the property has not been defined;
1.657 + KErrArgument, if the property is not a text type;
1.658 + KErrOverflow, if the supplied buffer is too small to contain the full
1.659 + property value, and note that the buffer aDes contains the
1.660 + truncated property value.
1.661 +*/
1.662 +EXPORT_C TInt RProperty::Get(TDes16& aDes)
1.663 + {
1.664 + TInt size = aDes.MaxSize();
1.665 + TInt r = Exec::PropertyGetB(iHandle, (TUint8*) aDes.Ptr(), size);
1.666 + if (r < 0)
1.667 + {
1.668 + if (r == KErrOverflow)
1.669 + {
1.670 + aDes.SetLength(size >> 1);
1.671 + }
1.672 + return r;
1.673 + }
1.674 + aDes.SetLength(r >> 1);
1.675 + return KErrNone;
1.676 + }
1.677 +
1.678 +
1.679 +
1.680 +
1.681 +/**
1.682 +Sets a new integer value for this property.
1.683 +
1.684 +The function publishes the attached new integral property value, and any
1.685 +pending subscriptions for this property are completed.
1.686 +
1.687 +The implementation guarantees that this call has a bounded response time.
1.688 +
1.689 +@param aValue The property new value.
1.690 +
1.691 +@return KErrNone, if successful;
1.692 + KErrPermissionDenied, if the caller process doesn't pass the Write Policy;
1.693 + KErrNotFound, if the property has not been defined;
1.694 + KErrArgument, if the property is not of integral type.
1.695 +*/
1.696 +EXPORT_C TInt RProperty::Set(TInt aValue)
1.697 + {
1.698 + return(Exec::PropertySetI(iHandle, aValue));
1.699 + }
1.700 +
1.701 +
1.702 +
1.703 +
1.704 +/**
1.705 +Sets the byte-array (binary) property.
1.706 +
1.707 +The function publishes the attached new binary property value, and any
1.708 +pending subscriptions for this property are completed.
1.709 +
1.710 +The implementation guarantees that this call has a bounded response time only
1.711 +if the new property value requires no more storage space than is
1.712 +currently allocated. If more memory needs to be allocated, then this
1.713 +invalidates the real-time guarantee.
1.714 +
1.715 +@param aDes A reference to the descriptor containing the property new value.
1.716 +
1.717 +@return KErrNone, if successful;
1.718 + KErrPermissionDenied, if the caller process doesn't pass the Write Policy;
1.719 + KErrNotFound, if the property has not been defined;
1.720 + KErrArgument, if the property is not a byte-array (binary) type;
1.721 + KErrNoMemory, if memory allocation is required, and there is
1.722 + insufficient available.
1.723 + KMaxPropertySize, if the property is larger than KErrTooBig.
1.724 +*/
1.725 +EXPORT_C TInt RProperty::Set(const TDesC8& aDes)
1.726 + {
1.727 + return(Exec::PropertySetB(iHandle, (TUint8*) aDes.Ptr(), aDes.Size()));
1.728 + }
1.729 +
1.730 +
1.731 +
1.732 +
1.733 +/**
1.734 +Sets the text property
1.735 +
1.736 +The function publishes the attached new text property value, and any
1.737 +pending subscriptions for this property are completed.
1.738 +
1.739 +The implementation guarantees that this call has a bounded response time only
1.740 +if the new property value requires no more storage space than is
1.741 +currently allocated. If more memory needs to be allocated, then this
1.742 +invalidates the real-time guarantee.
1.743 +
1.744 +@param aDes A reference to the descriptor containing the property new value.
1.745 +
1.746 +@return KErrNone, if successful;
1.747 + KErrPermissionDenied, if the caller process doesn't pass the Write Policy;
1.748 + KErrNotFound, if the property has not been defined;
1.749 + KErrArgument, if the property is not a byte-array (binary) type;
1.750 + KErrNoMemory, if memory allocation is required, and there is
1.751 + insufficient available.
1.752 + KMaxPropertySize, if the property is larger than KErrTooBig.
1.753 +*/
1.754 +EXPORT_C TInt RProperty::Set(const TDesC16& aDes)
1.755 + {
1.756 + return(Exec::PropertySetB(iHandle, (TUint8*) aDes.Ptr(), aDes.Size()));
1.757 + }