Class RProperty

class RProperty : public RHandleBase;

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.

Derivation

• RHandleBase - A handle to an object.

• RProperty - User side interface to Publish & Subscribe.

Members

Defined in RProperty:

• Attach(TUid,TUint,TOwnerType)Attaches to the specified property.
• Cancel()Cancels an outstanding subscription request for this property handle.
• Define(TUid,TUint,TInt,TInt)Defines a property.
• Delete(TUid,TUint)Deletes a property.
• Delete(TUint)Deletes a property.
• EByteArrayByte-array (binary data) property type. This type provides real-time guarantees ...
• EIntIntegral property type.
• ELargeByteArrayLarge byte-array (binary data) property type. This type provides no real-time gu...
• ELargeTextLarge text property type. This is just a programmer friendly view of a byte-arra...
• ETextText property type. This is just a programmer friendly view of a byte-array prop...
• ETypeLimitUpper limit for TType values. It is the maximal legal TType value plus 1.
• ETypeMaskBitmask for TType values coded within TInt attributes.
• Get(TDes16 &)Gets the text value of this property.
• Get(TDes8 &)Gets the byte-array (binary) value of this property.
• Get(TInt &)Gets the integer value of this property.
• Get(TUid,TUint,TDes16 &)Gets a text property.
• Get(TUid,TUint,TDes8 &)Gets a binary property.
• Get(TUid,TUint,TInt &)Gets an integer property.
• KMaxLargePropertySize
• KMaxPropertySize
• Set(TInt)Sets a new integer value for this property.
• Set(TUid,TUint,TInt)Sets an integer property.
• Set(TUid,TUint,const TDesC16 &)Sets a text property.
• Set(TUid,TUint,const TDesC8 &)Sets a binary property.
• Set(const TDesC16 &)Sets the text property
• Set(const TDesC8 &)Sets the byte-array (binary) property.
• Subscribe(TRequestStatus &)Subscribes to a property.
• TTypeProperty type attribute.
• anonymousThe largest supported property value, in bytes, for byte-array (binary) types an...
• anonymousThe largest supported property value, in bytes, for large byte-array (binary) ty...

Inherited from RHandleBase:

• Attributes()const
• BTraceId()constReturns a unique object identifier for use with BTrace
• Close()Closes the handle.
• Duplicate(const RThread &,TOwnerType)Creates a valid handle to the kernel object for which the specified thread alrea...
• FullName()constGets the full name of the handle.
• FullName(TDes &)constGets the full name of the handle.
• Handle()constRetrieves the handle-number of the object associated with this handle.
• HandleInfo(THandleInfo *)Gets information about the handle.
• Name()constGets the name of the handle.
• Open(const TFindHandleBase &,TOwnerType)Opens a handle to a kernel side object found using a find-handle object.
• RHandleBase(TInt)Copy constructor.
• SetHandle(TInt)Sets the handle-number of this handle to the specified value.
• SetHandleNC(TInt)Sets the handle-number of this handle to the specified value, and marks it as no...
• SetReturnedHandle(TInt)Sets the handle-number of this handle to the specified value.
• iHandle

IMPORT_C static TInt Define(TUid aCategory, TUint aKey, TInt aAttr, TInt aPreallocate=0);

Description

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.

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

Following definition, the property has 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.

Parameters

Return value

See also:

• KUidSecurityThresholdCategoryValue...

IMPORT_C static TInt Delete(TUid aCategory, TUint aKey);

Description

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.

Parameters

Return value

IMPORT_C static TInt Delete(TUint aKey);

Description

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.

Parameters

Return value

IMPORT_C static TInt Get(TUid aCategory, TUint aKey, TInt &aValue);

Description

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.

Parameters

Return value

IMPORT_C static TInt Get(TUid aCategory, TUint aKey, TDes8 &aValue);

Description

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.

Parameters

Return value

IMPORT_C static TInt Get(TUid aCategory, TUint aKey, TDes16 &aValue);

Description

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.

Parameters

Return value

IMPORT_C static TInt Set(TUid aCategory, TUint aKey, TInt aValue);

Description

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.

Parameters

Return value

IMPORT_C static TInt Set(TUid aCategory, TUint aKey, const TDesC8 &aValue);

Description

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.

Parameters

Return value

IMPORT_C static TInt Set(TUid aCategory, TUint aKey, const TDesC16 &aValue);

Description

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.

Parameters

Return value

IMPORT_C TInt Attach(TUid aCategory, TUint aKey, TOwnerType aType=EOwnerProcess);

Description

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.

Parameters

Return value

IMPORT_C void Subscribe(TRequestStatus &aRequest);

Description

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 RProperty::Cancel(), then it completes with KErrCancel.

Parameters

Panic codes

IMPORT_C void Cancel();

Description

Cancels an outstanding subscription request for this property handle.

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

IMPORT_C TInt Get(TInt &aValue);

Description

Gets the integer value of this property.

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

Parameters

Return value

IMPORT_C TInt Get(TDes8 &aValue);

Description

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

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

Parameters

Return value

IMPORT_C TInt Get(TDes16 &aValue);

Description

Gets the text value of this property.

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

Parameters

Return value

IMPORT_C TInt Set(TInt aValue);

Description

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.

Parameters

Return value

IMPORT_C TInt Set(const TDesC8 &aValue);

Description

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.

Parameters

Return value

IMPORT_C TInt Set(const TDesC16 &aValue);

Description

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.

Parameters

Return value

n/a

Description

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

n/a

Description

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

TType

Description

Property type attribute.