RProperty Class Reference

#include <e32property.h>

class RProperty : public RHandleBase

Inherits from

Public Member Enumerations
enumanonymous { KMaxPropertySize }
enumanonymous { KMaxLargePropertySize }
enumTType { EInt, EByteArray, EText, ELargeByteArray, ..., ETypeMask }
Public Member Functions
IMPORT_C TIntAttach(TUid, TUint, TOwnerType)
IMPORT_C voidCancel()
IMPORT_C TIntDefine(TUid, TUint, TInt, TInt)
IMPORT_C TIntDefine(TUid, TUint, TInt, const TSecurityPolicy &, const TSecurityPolicy &, TInt)
IMPORT_C TIntDefine(TUint, TInt, const TSecurityPolicy &, const TSecurityPolicy &, TInt)
IMPORT_C TIntDelete(TUid, TUint)
IMPORT_C TIntDelete(TUint)
IMPORT_C TIntGet(TUid, TUint, TInt &)
IMPORT_C TIntGet(TUid, TUint, TDes8 &)
IMPORT_C TIntGet(TUid, TUint, TDes16 &)
IMPORT_C TIntGet(TInt &)
IMPORT_C TIntGet(TDes8 &)
IMPORT_C TIntGet(TDes16 &)
IMPORT_C TIntSet(TUid, TUint, TInt)
IMPORT_C TIntSet(TUid, TUint, const TDesC8 &)
IMPORT_C TIntSet(TUid, TUint, const TDesC16 &)
IMPORT_C TIntSet(TInt)
IMPORT_C TIntSet(const TDesC8 &)
IMPORT_C TIntSet(const TDesC16 &)
IMPORT_C voidSubscribe(TRequestStatus &)
Inherited Attributes
RHandleBase::iHandle
Inherited Enumerations
RHandleBase:TAttributes
Inherited Functions
RHandleBase::Attributes()const
RHandleBase::BTraceId()const
RHandleBase::Close()
RHandleBase::DoExtendedClose()
RHandleBase::Duplicate(const RThread &,TOwnerType)
RHandleBase::FullName()const
RHandleBase::FullName(TDes &)const
RHandleBase::Handle()const
RHandleBase::HandleInfo(THandleInfo *)
RHandleBase::Name()const
RHandleBase::NotifyDestruction(TRequestStatus &)
RHandleBase::Open(const TFindHandleBase &,TOwnerType)
RHandleBase::OpenByName(const TDesC &,TOwnerType,TInt)
RHandleBase::RHandleBase()
RHandleBase::RHandleBase(TInt)
RHandleBase::SetHandle(TInt)
RHandleBase::SetHandleNC(TInt)
RHandleBase::SetReturnedHandle(TInt)
RHandleBase::SetReturnedHandle(TInt,RHandleBase &)

Detailed Description

User side interface to Publish & Subscribe.

The class defines a handle to a property, a single data value representing an item of state information. Threads can publish (change) a property value through this handle. Threads can also subscribe (request notification of changes) to a property value through this handle; they can also retrieve the current property value.

Member Enumeration Documentation

Enum anonymous

The largest supported property value, in bytes, for byte-array (binary) types and text types.

EnumeratorValueDescription
KMaxPropertySize512

Enum anonymous

The largest supported property value, in bytes, for large byte-array (binary) types and large text types.

EnumeratorValueDescription
KMaxLargePropertySize65535

Enum TType

Property type attribute.

EnumeratorValueDescription
EInt

Integral property type.

EByteArray

Byte-array (binary data) property type. This type provides real-time guarantees but is limited to a maximum size of 512 bytes.

See also: KMaxPropertySize

ETextEByteArray

Text property type. This is just a programmer friendly view of a byte-array property, and is implemented in the same way as EByteArray.

ELargeByteArray

Large byte-array (binary data) property type. This type provides no real-time guarantees but supports properties of up to 65536 bytes.

See also: KMaxLargePropertySize

ELargeTextELargeByteArray

Large text property type. This is just a programmer friendly view of a byte-array property, and is implemented in the same way as EByteArray.

ETypeLimit

Upper limit for TType values. It is the maximal legal TType value plus 1.

ETypeMask0xff

Bitmask for TType values coded within TInt attributes.

Member Function Documentation

Attach ( TUid, TUint, TOwnerType )

IMPORT_C TIntAttach(TUidaCategory,
TUintaKey,
TOwnerTypeaType = EOwnerProcess
)

Attaches to the specified property.

The function creates a handle (this object) to the specified property. This allows the caller to subscribe for notification of changes to this property, and to faster and real-time property access methods.

If the specified property does not exist, then this operation will still succeed. However, memory allocation will be required. Note that this invalidates any real-time guarantee, i.e. the guarantee that the operation completes within a bounded time.

ParameterDescription
aCategoryThe UID that identifies the property category.
aKeyThe property sub-key, i.e. the key that identifies the specific property within the category.
aTypeThe ownership of this property handle. By default, ownership is vested in the current process, but can be vested in the current thread by specifying EOwnerThread.

Returns: KErrNone, if successful; KErrNoMemory, if memory allocation is required, and there is insufficient available.

Cancel ( )

IMPORT_C voidCancel()

Cancels an outstanding subscription request for this property handle.

If the request has not already completed, then it completes with KErrCancel.

Define ( TUid, TUint, TInt, TInt )

IMPORT_C TIntDefine(TUidaCategory,
TUintaKey,
TIntaAttr,
TIntaPreallocate = 0
)[static]

NOTE - The use of this method is deprecated.

Defines a property with the specified category ID. This method should only be used to specify a category different from the creating process's secure ID in exceptional circumstances. In most cases the overload:

RProperty::Define(TUint aKey, TInt aAttr, const TSecurityPolicy& aReadPolicy, const TSecurityPolicy& aWritePolicy, TInt aPreallocate)

should be used. For details see the document located at:

Symbian OS guide Base Using User Library (E32) Publish and Subscribe Security issues

Defines the attributes and access control for a property. This can only be done once for each property. Subsequent attempts to define the same property will return KErrAlreadyExists.

Only processes with the write-system-data capability are allowed to define properties either in the system category (KUidSystemCategory) or with aCategory < KUidSecurityThresholdCategoryValue. Any attempt to define a property with these categories by a process with insufficient capabilities will fail with a KErrPermissionDenied error.

Following the property's definition, it will have a default value, 0 for integer properties and zero-length data for byte-array and text properties. Pending subscriptions for this property will not be completed until a new value is published.

capability
WriteDeviceData if aCategory==KUidSystemCategoryValue.
capability
WriteDeviceData if aCategory not equal to the current process's Secure ID and aCategory<KUidSecurityThresholdCategoryValue.

See also: KUidSecurityThresholdCategoryValue

Deprecated

Use RProperty::Define(TUint aKey, TInt aAttr, const TSecurityPolicy &aReadPolicy, const TSecurityPolicy &aWritePolicy, TInt aPreallocated=0) instead.

ParameterDescription
aCategoryThe UID that identifies the property category.
aKeyThe property sub-key, i.e. the key that identifies the specific property within the category.
aAttrThis describes the property type, a TType value; persistence, as defined by the KPersistent bit, may be ORed in.
aPreallocateThe number of bytes to be pre-allocated for variable sized properties. Pre-allocating enough space ensures that a variable sized property can be set in 'real-time', (i.e. the time to set the property is bounded).

Returns: KErrNone, if successful; KErrArgument, if the wrong type or attribute was specified; KErrArgument, if aType is TInt and aPreallocate is not 0; KErrTooBig, if aPreallocate is greater than KMaxPropertySize; KErrPermissionDenied, if an attempt is made to define a property in the system category by a process with insufficient capabilities.

Define ( TUid, TUint, TInt, const TSecurityPolicy &, const TSecurityPolicy &, TInt )

IMPORT_C TIntDefine(TUidaCategory,
TUintaKey,
TIntaAttr,
const TSecurityPolicy &aReadPolicy,
const TSecurityPolicy &aWritePolicy,
TIntaPreallocated = 0
)[static]

Defines a property with the specified category ID. This method should only be used to specify a category different from the creating process's secure ID in exceptional circumstances. In most cases the overload:

RProperty::Define(TUint aKey, TInt aAttr, const TSecurityPolicy& aReadPolicy, const TSecurityPolicy& aWritePolicy, TInt aPreallocate)

should be used. For details see the document located at:

Symbian OS guide Base Using User Library (E32) Publish and Subscribe Security issues

Defines the attributes and access control for a property. This can only be done once for each property. Subsequent attempts to define the same property will return KErrAlreadyExists.

Only processes with the write-system-data capability are allowed to define properties either in the system category (KUidSystemCategory) or with aCategory < KUidSecurityThresholdCategoryValue. Any attempt to define a property with these categories by a process with insufficient capabilities will fail with a KErrPermissionDenied error.

Following the property's definition, it will have a default value, 0 for integer properties and zero-length data for byte-array and text properties. Pending subscriptions for this property will not be completed until a new value is published.

capability
WriteDeviceData if aCategory==KUidSystemCategoryValue.
capability
WriteDeviceData if aCategory not equal to the current process's Secure ID and aCategory<KUidSecurityThresholdCategoryValue.

See also: KUidSecurityThresholdCategoryValue

ParameterDescription
aCategoryThe UID that identifies the property category. This must either be the current process's Secure ID, or KUidSystemCategoryValue.
aKeyThe property sub-key, i.e. the key that identifies the specific property within the category.
aAttrThis describes the property type, a TType value; persistence, as defined by the KPersistent bit, may be ORed in.
aReadPolicyA security policy defining the security attributes a process must have in order to read this value.
aWritePolicyA security policy defining the security attributes a process must have in order to write this value.
aPreallocatedThe number of bytes to be pre-allocated for variable sized properties. Pre-allocating enough space ensures that a variable sized property can be set in 'real-time', (i.e. the time to set the property is bounded).

Returns: KErrNone, if successful; KErrArgument, if the wrong type or attribute was specified; KErrArgument, if aType is TInt and aPreallocate is not 0; KErrTooBig, if aPreallocate is greater than KMaxPropertySize; KErrPermissionDenied, if an attempt is made to define a property in the system category by a process with insufficient capabilities, or the category secified wasn't the same as the current process's Secure ID.

Define ( TUint, TInt, const TSecurityPolicy &, const TSecurityPolicy &, TInt )

IMPORT_C TIntDefine(TUintaKey,
TIntaAttr,
const TSecurityPolicy &aReadPolicy,
const TSecurityPolicy &aWritePolicy,
TIntaPreallocated = 0
)[static]

Defines a property.

Defines the attributes and access control for a property. This can only be done once for each property. Subsequent attempts to define the same property will return KErrAlreadyExists.

The category ID for the property will be the same as the current processes Secure ID.

Following the property's definition, it will have a default value, 0 for integer properties and zero-length data for byte-array and text properties. Pending subscriptions for this property will not be completed until a new value is published.

ParameterDescription
aKeyThe property sub-key, i.e. the key that identifies the specific property within the category.
aAttrThis describes the property type, a TType value; persistence, as defined by the KPersistent bit, may be ORed in.
aReadPolicyA security policy defining the security attributes a process must have in order to read this value.
aWritePolicyA security policy defining the security attributes a process must have in order to write this value.
aPreallocatedThe number of bytes to be pre-allocated for variable sized properties. Pre-allocating enough space ensures that a variable sized property can be set in 'real-time', (i.e. the time to set the property is bounded).

Returns: KErrNone, if successful; KErrArgument, if the wrong type or attribute was specified; KErrArgument, if aType is TInt and aPreallocate is not 0; KErrTooBig, if aPreallocate is greater than KMaxPropertySize;

Delete ( TUid, TUint )

IMPORT_C TIntDelete(TUidaCategory,
TUintaKey
)[static]

Deletes a property.

This can only be called by the property owner, as defined by the process Security ID; any attempt by another process to delete the property will fail.

Any pending subscriptions for this property will be completed with KErrNotFound. Any new request will not complete until the property is defined and published again.

ParameterDescription
aCategoryThe UID that identifies the property category.
aKeyThe property sub-key, i.e. the key that identifies the specific property within the category.

Returns: KErrNone, if successful; KErrPermissionDenied, if a process that is not the owner of the property attempts to delete it. KErrNotFound, if the property has not been defined.

Delete ( TUint )

IMPORT_C TIntDelete(TUintaKey)[static]

Deletes a property.

The category ID for the property will be the same as the current processes Secure ID.

Any pending subscriptions for this property will be completed with KErrNotFound. Any new request will not complete until the property is defined and published again.

ParameterDescription
aKeyThe property sub-key, i.e. the key that identifies the specific property within the category.

Returns: KErrNone, if successful; KErrNotFound, if the property has not been defined.

Get ( TUid, TUint, TInt & )

IMPORT_C TIntGet(TUidaCategory,
TUintaKey,
TInt &aValue
)[static]

Gets an integer property.

The function gets the integer value of the specified property.

The Platform Security attributes of the current process are checked against the Read Policy which was specified when the property was defined. If this check fails the action taken is determined by the system wide Platform Security configuration. If PlatSecDiagnostics is ON, then a diagnostic message is emitted. If PlatSecEnforcement is OFF, then this function will return KErrNone even though the check failed.

ParameterDescription
aCategoryThe UID that identifies the property category.
aKeyThe property sub-key, i.e. the key that identifies the specific property within the category.
aValueA reference to the variable where the property value will be reported.

Returns: KErrNone, if successful; KErrPermissionDenied, if the caller process doesn't pass the Read Policy; KErrNotFound, if the property has not been defined; KErrArgument, if the property is not of integral type.

Get ( TUid, TUint, TDes8 & )

IMPORT_C TIntGet(TUidaCategory,
TUintaKey,
TDes8 &aValue
)[static]

Gets a binary property.

The function gets the byte-array (binary) value of the specified property.

The Platform Security attributes of the current process are checked against the Read Policy which was specified when the property was defined. If this check fails the action taken is determined by the system wide Platform Security configuration. If PlatSecDiagnostics is ON, then a diagnostic message is emitted. If PlatSecEnforcement is OFF, then this function will return KErrNone even though the check failed.

ParameterDescription
aCategoryThe UID that identifies the property category.
aKeyThe property sub-key, i.e. the key that identifies the specific property within the category.
aValueA reference to the buffer descriptor where the property value will be reported.

Returns: KErrNone if successful; KErrPermissionDenied, if the caller process doesn't pass the Read Policy; KErrNotFound, if the property has not been defined; KErrArgument, if the property is not a byte-array (binary) type; KErrOverflow, if the supplied buffer is too small to contain the full property value, and note that the buffer aDes contains the truncated property value.

Get ( TUid, TUint, TDes16 & )

IMPORT_C TIntGet(TUidaCategory,
TUintaKey,
TDes16 &aValue
)[static]

Gets a text property.

The function gets the text value of the specified property.

The Platform Security attributes of the current process are checked against the Read Policy which was specified when the property was defined. If this check fails the action taken is determined by the system wide Platform Security configuration. If PlatSecDiagnostics is ON, then a diagnostic message is emitted. If PlatSecEnforcement is OFF, then this function will return KErrNone even though the check failed.

ParameterDescription
aCategoryThe UID that identifies the property category.
aKeyThe property sub-key, i.e. the key that identifies the specific property within the category.
aValueA reference to the buffer descriptor where the property value will be reported.

Returns: KErrNone, if successful; KErrPermissionDenied, if the caller process doesn't pass the Read Policy; KErrNotFound, if the property has not been defined; KErrArgument, if the property is not a text type; KErrOverflow, if the supplied buffer is too small to contain the full property value, and note that the buffer aDes contains the truncated property value.

Get ( TInt & )

IMPORT_C TIntGet(TInt &aValue)

Gets the integer value of this property.

The implementation guarantees that this call has a bounded response time.

ParameterDescription
aValueA reference to the variable where the property value will be reported.

Returns: KErrNone, if successful; KErrPermissionDenied, if the caller process doesn't pass the Read Policy; KErrNotFound, if the property has not been defined; KErrArgument, if the property is not of integral type.

Get ( TDes8 & )

IMPORT_C TIntGet(TDes8 &aValue)

Gets the byte-array (binary) value of this property.

The implementation guarantees that this call has a bounded response time.

ParameterDescription
aValueA reference to the buffer descriptor where the property value will be reported.

Returns: KErrNone, if successful; KErrPermissionDenied, if the caller process doesn't pass the Read Policy; KErrNotFound, if the property has not been defined; KErrArgument, if the property is not a byte-array (binary) type. KErrOverflow, if the supplied buffer is too small to contain the full property value, and note that the buffer aDes contains the truncated property value.

Get ( TDes16 & )

IMPORT_C TIntGet(TDes16 &aValue)

Gets the text value of this property.

The implementation guarantees that this call has a bounded response time.

ParameterDescription
aValueA reference to the buffer descriptor where the property value will be reported.

Returns: KErrNone, if successful; KErrPermissionDenied, if the caller process doesn't pass the Read Policy; KErrNotFound, if the property has not been defined; KErrArgument, if the property is not a text type; KErrOverflow, if the supplied buffer is too small to contain the full property value, and note that the buffer aDes contains the truncated property value.

Set ( TUid, TUint, TInt )

IMPORT_C TIntSet(TUidaCategory,
TUintaKey,
TIntaValue
)[static]

Sets an integer property.

The function publishes a new integral property value.

Any pending subscriptions for this property will be completed.

The Platform Security attributes of the current process are checked against the Write Policy which was specified when the property was defined. If this check fails the action taken is determined by the system wide Platform Security configuration. If PlatSecDiagnostics is ON, then a diagnostic message is emitted. If PlatSecEnforcement is OFF, then this function will return KErrNone even though the check failed.

ParameterDescription
aCategoryThe UID that identifies the property category.
aKeyThe property sub-key, i.e. the key that identifies the specific property within the category.
aValueThe new property value.

Returns: KErrNone, if successful; KErrPermissionDenied, if the caller process doesn't pass the Write Policy; KErrNotFound, if the property has not been defined; KErrArgument, if the property is not of integral type.

Set ( TUid, TUint, const TDesC8 & )

IMPORT_C TIntSet(TUidaCategory,
TUintaKey,
const TDesC8 &aValue
)[static]

Sets a binary property.

The function Publishes a new byte-array (binary) value for the specified property.

Any pending subscriptions for this property will be completed.

Note that if the new property value requires more storage space than is currently allocated, then memory allocation will be required. This invalidates any real-time guarantee, i.e. the guarantee that the operation will complete within a bounded time.

The Platform Security attributes of the current process are checked against the Write Policy which was specified when the property was defined. If this check fails the action taken is determined by the system wide Platform Security configuration. If PlatSecDiagnostics is ON, then a diagnostic message is emitted. If PlatSecEnforcement is OFF, then this function will return KErrNone even though the check failed.

ParameterDescription
aCategoryThe UID that identifies the property category.
aKeyThe property sub-key, i.e. the key that identifies the specific property within the category.
aValueA reference to the descriptor containing the new property value.

Returns: KErrNone, if successful; KErrPermissionDenied, if the caller process doesn't pass the Write Policy; KErrNotFound, if the property has not been defined; KErrArgument, if the property is not a byte-array (binary) type; KErrNoMemory, if memory allocation is required, and there is insufficient available.

Set ( TUid, TUint, const TDesC16 & )

IMPORT_C TIntSet(TUidaCategory,
TUintaKey,
const TDesC16 &aValue
)[static]

Sets a text property.

The function publishes a new text value for the specified property.

Any pending subscriptions for this property will be completed.

Note that if the new property value requires more storage space than is currently allocated, then memory allocation will be required. This invalidates any real-time guarantee, i.e. the guarantee that the operation will complete within a bounded time.

The Platform Security attributes of the current process are checked against the Write Policy which was specified when the property was defined. If this check fails the action taken is determined by the system wide Platform Security configuration. If PlatSecDiagnostics is ON, then a diagnostic message is emitted. If PlatSecEnforcement is OFF, then this function will return KErrNone even though the check failed.

ParameterDescription
aCategoryThe UID that identifies the property category.
aKeyThe property sub-key, i.e. the key that identifies the specific property within the category.
aValueA reference to the descriptor containing the new property value.

Returns: KErrNone, if successful; KErrPermissionDenied, if the caller process doesn't pass the Write Policy; KErrNotFound, if the property has not been defined; KErrArgument, if the property is not a text type; KErrNoMemory, if memory allocation is required, and there is insufficient available; KErrTooBig, if the property is larger than KMaxPropertySize;

Set ( TInt )

IMPORT_C TIntSet(TIntaValue)

Sets a new integer value for this property.

The function publishes the attached new integral property value, and any pending subscriptions for this property are completed.

The implementation guarantees that this call has a bounded response time.

ParameterDescription
aValueThe property new value.

Returns: KErrNone, if successful; KErrPermissionDenied, if the caller process doesn't pass the Write Policy; KErrNotFound, if the property has not been defined; KErrArgument, if the property is not of integral type.

Set ( const TDesC8 & )

IMPORT_C TIntSet(const TDesC8 &aValue)

Sets the byte-array (binary) property.

The function publishes the attached new binary property value, and any pending subscriptions for this property are completed.

The implementation guarantees that this call has a bounded response time only if the new property value requires no more storage space than is currently allocated. If more memory needs to be allocated, then this invalidates the real-time guarantee.

ParameterDescription
aValueA reference to the descriptor containing the property new value.

Returns: KErrNone, if successful; KErrPermissionDenied, if the caller process doesn't pass the Write Policy; KErrNotFound, if the property has not been defined; KErrArgument, if the property is not a byte-array (binary) type; KErrNoMemory, if memory allocation is required, and there is insufficient available. KMaxPropertySize, if the property is larger than KErrTooBig.

Set ( const TDesC16 & )

IMPORT_C TIntSet(const TDesC16 &aValue)

Sets the text property

The function publishes the attached new text property value, and any pending subscriptions for this property are completed.

The implementation guarantees that this call has a bounded response time only if the new property value requires no more storage space than is currently allocated. If more memory needs to be allocated, then this invalidates the real-time guarantee.

ParameterDescription
aValueA reference to the descriptor containing the property new value.

Returns: KErrNone, if successful; KErrPermissionDenied, if the caller process doesn't pass the Write Policy; KErrNotFound, if the property has not been defined; KErrArgument, if the property is not a byte-array (binary) type; KErrNoMemory, if memory allocation is required, and there is insufficient available. KMaxPropertySize, if the property is larger than KErrTooBig.

Subscribe ( TRequestStatus & )

IMPORT_C voidSubscribe(TRequestStatus &aRequest)

Subscribes to a property.

The function issues an asynchronous request to be notified when the property is changed. The calling thread is signalled, and the specified request status object is updated when the property is next changed.

The property may change several times before the subscribing thread can deal with a notification request completion. To ensure that the subscriber does not miss updates, it should re-issue a subscription request before retrieving the current value and acting on it.

If the property has not been defined, the request does not complete until the property is subsequently defined and published. When defined, if the caller process doesn't pass the Read Policy, then the request completes with KErrPermissionDenied.

If the property is already defined, and the caller process doesn't pass the Read Policy, then the request completes immediately with KErrPermissionDenied.

When Read Policy checks fail the action taken is determined by the system wide Platform Security configuration. If PlatSecDiagnostics is ON, then a diagnostic message is emitted. If PlatSecEnforcement is OFF, then the request will complete successfully even though the check failed.

If an outstanding request is cancelled through a call to Cancel(), then it completes with KErrCancel.

panic
KERN-EXEC 9 if there is already a subscription on this property handle; only one subscription per RProperty is allowed.
ParameterDescription
aRequestThe request status object to be signalled on update.