<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-FE910347-7CC1-5241-B443-88AD3F5A96EF" xml:lang="en"><title>Using

Publish and Subscribe</title><shortdesc>This topic explains the operations that can be performed using

publish and subscribe.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<ul>

<li id="GUID-AE4CAAA9-9EB2-5AA0-ACB9-073EAAA9D2C1"><p> <xref href="GUID-FE910347-7CC1-5241-B443-88AD3F5A96EF.dita#GUID-FE910347-7CC1-5241-B443-88AD3F5A96EF/GUID-383A6127-FCE0-5B0E-BD54-3AAFEB097AC9">Creating and closing a handle to a property</xref>  </p> </li>

<li id="GUID-3F0622EC-8490-585A-8CA8-09A3925E842E"><p> <xref href="GUID-FE910347-7CC1-5241-B443-88AD3F5A96EF.dita#GUID-FE910347-7CC1-5241-B443-88AD3F5A96EF/GUID-75BCC783-8DA2-519F-9E4A-B597BDC90E79">Defining a property</xref>  </p> </li>

<li id="GUID-D6C38BDD-02CD-5D9F-8872-DD621D58DB85"><p> <xref href="GUID-FE910347-7CC1-5241-B443-88AD3F5A96EF.dita#GUID-FE910347-7CC1-5241-B443-88AD3F5A96EF/GUID-D942B400-37F8-5C02-AC95-2BD195D3348D">Deleting a property</xref>  </p> </li>

<li id="GUID-ED1DE72F-9111-51A5-9AB2-D7112D947465"><p> <xref href="GUID-FE910347-7CC1-5241-B443-88AD3F5A96EF.dita#GUID-FE910347-7CC1-5241-B443-88AD3F5A96EF/GUID-3B2B63B8-EB2A-5845-A738-A10012A7C896">Publishing a property value</xref>  </p> </li>

<li id="GUID-360F7C12-4909-52EE-9468-E40A3ABC944A"><p> <xref href="GUID-FE910347-7CC1-5241-B443-88AD3F5A96EF.dita#GUID-FE910347-7CC1-5241-B443-88AD3F5A96EF/GUID-CD731DD7-E833-5C67-9B90-0357C9552450">Retrieving a property value</xref>  </p> </li>

<li id="GUID-57301501-34C1-5BE1-9AAB-36F97DBCF5C0"><p> <xref href="GUID-FE910347-7CC1-5241-B443-88AD3F5A96EF.dita#GUID-FE910347-7CC1-5241-B443-88AD3F5A96EF/GUID-A17955E9-FC4C-5FF9-8CC4-2425931E1DEB">Subscribing to, and unsubscribing from, a property</xref>  </p> </li>

<li id="GUID-AAA0B4BB-4B01-5F5E-8617-6D02B36DCEF2"><p> <xref href="GUID-FE910347-7CC1-5241-B443-88AD3F5A96EF.dita#GUID-FE910347-7CC1-5241-B443-88AD3F5A96EF/GUID-EF683969-CED9-5986-938D-3D887E3B39BD">Usage patterns</xref>  </p> </li>

<li id="GUID-E2D3A0BE-1FD9-5B56-928A-4265940E0DEA"><p> <xref href="GUID-FE910347-7CC1-5241-B443-88AD3F5A96EF.dita#GUID-FE910347-7CC1-5241-B443-88AD3F5A96EF/GUID-2B022BE9-2004-54E8-962E-5AB38DDC4222">Making efficient use of the user side API</xref>  </p> </li>

</ul>

<section id="GUID-383A6127-FCE0-5B0E-BD54-3AAFEB097AC9"><title>Creating and

closing a handle to a property</title> <p>Some property operations require

a reference to the property to be established first. This is done using the <xref href="GUID-C4776034-D190-3FC4-AF45-C7F195093AC3.dita#GUID-C4776034-D190-3FC4-AF45-C7F195093AC3/GUID-3F65DD85-6061-3370-9618-ECC0400323D1"><apiname>RProperty::Attach()</apiname></xref> member

function. After a call to this function, the <xref href="GUID-C4776034-D190-3FC4-AF45-C7F195093AC3.dita"><apiname>RProperty</apiname></xref> object

acts like a standard handle to a kernel resource. When this handle is no longer

required, it can be released in the standard way by calling the inherited <xref href="GUID-727D2B62-09A9-3CBC-AB6F-591E52EC68EB.dita#GUID-727D2B62-09A9-3CBC-AB6F-591E52EC68EB/GUID-4B2775FD-AB61-3850-86C5-780CE8C97573"><apiname>RHandleBase::Close()</apiname></xref> member

function. </p> <p>Note that releasing the handle does not cause the property

to disappear. This only happens if the property is deleted. </p> <p>Note also

that it is quite legitimate to attach to a property that has not been defined,

and in this case no error will be returned either. This enables the lazy definition

of properties as used in some of the usage patterns. </p> <codeblock id="GUID-A836D288-8511-5CED-B3F9-42B60569EE27" xml:space="preserve">// attach to the ‘counter’ property

RProperty counter;

TInt r=counter.Attach(KMyPropertyCat,EMyPropertyName,EOwnerThread);

User::LeaveIfError(r);

// use the counter object...

// when finished, release the handle

counter.Close();

    </codeblock> </section>

<section id="GUID-75BCC783-8DA2-519F-9E4A-B597BDC90E79"><title>Defining a

property</title> <p>A property is defined using the <xref href="GUID-C4776034-D190-3FC4-AF45-C7F195093AC3.dita#GUID-C4776034-D190-3FC4-AF45-C7F195093AC3/GUID-58C54D2A-91E0-359B-AA31-69C6C4050173"><apiname>RProperty::Define()</apiname></xref> function,

specifying the attributes of that property. </p> <p>A property does not need

to be defined before it can be accessed. This supports programming patterns

where both publishers and subscribers may define the property. Note, however

that for security reasons, there are restrictions on the category that can

be used when defining a property; see <xref href="GUID-DAF86036-CC40-5F26-9F15-2F2093F59C03.dita">security

issues</xref> for more information. </p> <p>Once defined, a property persists

in the kernel until the system reboots, or the property is explicitly deleted.

Its lifetime is not tied to that of the thread or process that originally

defined it. This means that, when defining a property, it is important to

check the return code from the call <codeph>RProperty::Define()</codeph> to

deal with the possibility that the property has previously been defined, but

not deleted. </p> <p>The following code shows the definition of two properties: </p> <codeblock id="GUID-1F3E05DB-A34B-5D79-8512-52CAD86B0A2D" xml:space="preserve">enum TMyPropertyKeys={EMyPropertyCounter,EMyPropertyName};

static _LIT_SECURITY_POLICY_PASS(KAllowAllPolicy);

static _LIT_SECURITY_POLICY_C1(KPowerMgmtPolicy,ECapabilityPowerMgmt);

// define first property to be integer type

TInt r=RProperty::Define(EMyPropertyCounter,RProperty::EInt,KAllowAllPolicy,KPowerMgmtPolicy);

if (r!=KErrAlreadyExists)

    {

    User::LeaveIfError(r);

    }

// define second property to be a byte array, allocating 100 bytes

r=RProperty::Define(EMyPropertyName,RProperty::EByteArray,KAllowAllPolicy,KPowerMgmtPolicy,100);

if (r!=KErrAlreadyExists)

    {

    User::LeaveIfError(r);

    }

. . .

    </codeblock> <p>Once defined, a property value can change, but the property

type cannot. Byte-array type properties can also change length provided the

length does not exceed the maximum value of 512 bytes. The limit on the size

of a property ensures some limit on RAM usage. </p> <p>The API allows byte-array

and Unicode text type properties to be pre-allocated when they are defined.

This means that the time taken to set the values is bounded. However, if the

length of these property types subsequently increases, then memory allocation

may take place, and no guarantees can then be made on the time taken to set

them. </p> <p>There are further <xref href="GUID-DAF86036-CC40-5F26-9F15-2F2093F59C03.dita">security

issues</xref> to be considered when defining a property. You need to provide

two security policies - one to govern which processes can publish the property

value, and the other to govern which processes can retrieve the property value.

Security policies are instances of <xref href="GUID-81A285F6-3F87-3E77-9426-61BB16BC7109.dita"><apiname>TSecurityPolicy</apiname></xref> objects,

although for efficiency reasons, you will almost always use the <codeph>_LIT_SECURITY_POLICY_...</codeph> macros

to generate constant objects that behave like <codeph>TSecurityPolicy</codeph> objects.

The API reference for <xref href="GUID-81A285F6-3F87-3E77-9426-61BB16BC7109.dita"><apiname>TSecurityPolicy</apiname></xref> provides far more

detail on this. </p> <p>In this example, all processes will be allowed to

retrieve the property value, but only those processes having the power management

system capability (<xref href="GUID-76F4383B-4EA5-391A-A271-A8F65ED77EC0.dita"><apiname>ECapabilityPowerMgmt</apiname></xref>) will be allowed

to publish the property value. </p> <p>Note that a process that defines a

property does not have automatic rights of access to that property, other

than to delete it. If the defining process also wishes to publish and/or subscribe

to that property, then it must ensure that it satisfies the security policies

that it itself has put in place when defining the property. </p> </section>

<section id="GUID-D942B400-37F8-5C02-AC95-2BD195D3348D"><title>Deleting a

property</title> <p>A defined property is deleted by calling <xref href="GUID-C4776034-D190-3FC4-AF45-C7F195093AC3.dita#GUID-C4776034-D190-3FC4-AF45-C7F195093AC3/GUID-226BC411-A2D2-30D1-BD86-9DDBD855C1E4"><apiname>RProperty::Delete()</apiname></xref>.

Any outstanding subscriptions for this property will complete with <xref href="GUID-5E653C17-372C-32E1-A1B2-9E69A9991C40.dita"><apiname>KErrNotFound</apiname></xref>.

Only the process with the correct secure ID is allowed to delete it. </p> <p>For

example, extending the code fragment introduced above: </p> <codeblock id="GUID-D4CC3017-D17D-5E7C-AC57-0DBD8B789349" xml:space="preserve">enum TMyPropertyKeys={EMyPropertyCounter,EMyPropertyName};

// define first property to be integer type

TInt r=RProperty::Define(EMyPropertyCounter,RProperty::EInt);

if (r!=KErrAlreadyExists)

    {

    User::LeaveIfError(r);

    }

// define second property to be a byte array, allocating 100 bytes

r=RProperty::Define(EMyPropertyName,RProperty::EByteArray,100);

if (r!=KErrAlreadyExists)

    {

    User::LeaveIfError(r);

    }

. . .

// much later on

. . .

// delete the ‘name’ property

r=RProperty::Delete(EMyPropertyName);

if (r!=KErrNotFound)

    {

    User::LeaveIfError(r);

    }

    </codeblock> </section>

<section id="GUID-3B2B63B8-EB2A-5845-A738-A10012A7C896"><title>Publishing

a property value</title> <p>A property is published using the <codeph>RProperty::Set()</codeph> family

of functions. Properties can be published: </p> <ul>

<li id="GUID-3A136703-587F-55B9-9EE6-EE512845956A"><p>using a previously attached <xref href="GUID-C4776034-D190-3FC4-AF45-C7F195093AC3.dita"><apiname>RProperty</apiname></xref> handle, </p> </li>

</ul> <p>or </p> <ul>

<li id="GUID-126B0DC1-D4FC-520C-9583-50E64CBC7B80"><p>by specifying the property

category and key with the new value. </p> </li>

</ul> <p>The former mode is guaranteed to have bounded execution time, suitable

for high-priority, real-time tasks, except when publishing a byte-array property

that requires the allocation of a larger space for the new value. </p> <p>The

latter mode offers no real-time guarantees. </p> <p>Property values are written

atomically. This means that it is not possible for threads reading a property

to get a garbled value. </p> <p>All outstanding subscriptions for a property

are completed when the value is published, even if it is exactly the same

as the existing value. This means that a property can be used as a simple

broadcast notification service. </p> <p>Publishing a property that is not

defined is not necessarily a programming error. The <codeph>Set()</codeph> functions

just return an error. If this is not expected for any particular usage, then

the error must be checked and processed by the caller. </p> <p>See the code

fragment in the section <xref href="GUID-FE910347-7CC1-5241-B443-88AD3F5A96EF.dita#GUID-FE910347-7CC1-5241-B443-88AD3F5A96EF/GUID-CD731DD7-E833-5C67-9B90-0357C9552450">Retrieving

a property value</xref>  </p> </section>

<section id="GUID-CD731DD7-E833-5C67-9B90-0357C9552450"><title>Retrieving

a property value</title> <p>The current value of a property is read using

the <codeph>RProperty::Get()</codeph> family of functions. Properties can

be retrieved: </p> <ul>

<li id="GUID-81AD34BF-9A45-5DEE-AD20-AA908F5BF94A"><p>using a previously attached <xref href="GUID-C4776034-D190-3FC4-AF45-C7F195093AC3.dita"><apiname>RProperty</apiname></xref> handle, </p> </li>

</ul> <p>or </p> <ul>

<li id="GUID-1163D9F2-BDEA-55E1-B6FB-D9A353F4D53E"><p>by specifying the property

category and key with the new value. </p> </li>

</ul> <p>The former mode is guaranteed to have bounded execution time, suitable

for high-priority, real-time tasks. </p> <p>The latter mode offers no real-time

guarantees. </p> <p>Property values are read atomically. This means that it

is not possible for threads reading a property to get a garbled value. </p> <p>Retrieving

a property that is not defined is not necessarily a programming error. The <codeph>Get()</codeph> functions

just return an error. If this is not expected for any particular usage, then

the error must be checked and processed by the caller. </p> <p>Integer properties

must be accessed using the overloads that take an integer or integer reference

value, whereas byte-array properties can be accessed using the overloads that

take a descriptor reference. </p> <p>The following code fragment shows publication

and retrieval of a property. Note that it uses the idea of attaching to a

property. Note also that it contains a race condition, especially if another

thread is executing the same sequence to increment the ‘counter’ value. </p> <codeblock id="GUID-27B8D567-DD92-5FD6-B2E3-AF343C1116B1" xml:space="preserve">const TUid KMyPropertyCat={0x10012345};

enum TMyPropertyKeys={EMyPropertyCounter,EMyPropertyName};

// attach to the ‘counter’ property

RProperty counter;

TInt r=counter.Attach(KMyPropertyCat,EMyPropertyCounter,EOwnerThread);

User::LeaveIfError(r);

// publish a new name value

TFileName n;

RProcess().Filename(n);

r=RProperty::Set(KMyPropertyCat,EMyPropertyName,n);

User::LeaveIfError(r);

// retrieve the first 10 characters of the name value

TBuf<10> name;

r=RProperty::Get(KMyPropertyCat,EMyPropertyName,name);

if (r!=KErrOverflow)

    {

    User::LeaveIfError(r);

    }

// retrieve and publish a new value using the attached ‘counter’ property

TInt count;

r=counter.Get(count);

if (r==KErrNone)

    {

    r=counter.Set(++count);

    }

User::LeaveIfError(r);

// when finised, release the handle

counter.Close();

    </codeblock> </section>

<section id="GUID-A17955E9-FC4C-5FF9-8CC4-2425931E1DEB"><title>Subscribing

to, and unsubscribing from, a property</title> <p>Subscribing to a property

is the act of making an asynchronous request to be notified of a change to

that property. </p> <p>A thread makes a request for notification of a change

to a property by calling the <xref href="GUID-C4776034-D190-3FC4-AF45-C7F195093AC3.dita#GUID-C4776034-D190-3FC4-AF45-C7F195093AC3/GUID-21A2FEB7-AAF1-3AC0-84B9-AB30E6CFFF99"><apiname>RProperty::Subscribe()</apiname></xref> member

function on an already attached property object. Only one subscription request

can be outstanding at any one time for a <xref href="GUID-C4776034-D190-3FC4-AF45-C7F195093AC3.dita"><apiname>RProperty</apiname></xref> instance. </p> <p>An

outstanding subscription request can be cancelled by calling the <xref href="GUID-C4776034-D190-3FC4-AF45-C7F195093AC3.dita#GUID-C4776034-D190-3FC4-AF45-C7F195093AC3/GUID-326D75D3-9D54-3BD2-8B78-FAD1EEA1A1A5"><apiname>RProperty::Cancel()</apiname></xref> member

function. This is unsubscribing from the property. </p> <p>Subscribing to

a property is a single request to be notified when the property is next updated,

it does not generate an ongoing sequence of notifications for every change

to that property's value. Neither does it provide the caller with the new

value. In essence, the act of notification should be interpreted as “Property

X has changed” rather than “Property X has changed to Y”. This means that

the new value must be explicitly retrieved, if required. As a result, multiple

updates may be collapsed into one notification, and subscribers may not have

visibility of all intermediate values. </p> <p>This might appear to introduce

a window of opportunity for a subscriber to be out of synchronisation with

the property value – in particular, if the property is updated again before

the subscriber thread has had the chance to process the original notification.

However, a simple programming pattern, outlined in the second example below

ensures this does not happen. The principle is that, before dealing with a

subscription completion event, an active object should re-issue the subscription

request. </p> <p>Note that if the property has not been defined, then a subscription

request does not complete until the property is subsequently defined and published.

Note that the request will complete with <xref href="GUID-213DE05E-24F7-3E94-9B35-F4A72B3EBFD8.dita"><apiname>KErrPermissionDenied</apiname></xref> if

the subscribing process does not have sufficient capability as defined by

the <xref href="GUID-81A285F6-3F87-3E77-9426-61BB16BC7109.dita"><apiname>TSecurityPolicy</apiname></xref> object supplied by the process defining

the property. </p> <p>If the property is already defined, then the request

completes immediately with <xref href="GUID-213DE05E-24F7-3E94-9B35-F4A72B3EBFD8.dita"><apiname>KErrPermissionDenied</apiname></xref> if the

subscribing process does not have sufficient capability. </p> <codeblock id="GUID-F8AB71E9-1EB4-5EFB-9D1F-38625F782BA6" xml:space="preserve">const TUid KMyPropertyCat={0x10012345};

enum TMyPropertyKeys={EMyPropertyCounter,EMyPropertyName};

// attach to the ‘counter’ property

RProperty counter;

TInt r=counter.Attach(KMyPropertyCat,EMyPropertyCounter,EOwnerThread);

User::LeaveIfError(r);

// wait for the previously attached ‘counter’ property to be updated

TRequestStatus s;

counter.Subscribe(s);

User::WaitForRequest(s);

// Notification complete, retrieve the counter value.

TInt count;

counter.Get(count);

. . .

    </codeblock> <codeblock id="GUID-5E726809-0060-5E76-A0D5-4AE73155724A" xml:space="preserve">const TUid KMyPropertyCat={0x10012345};

enum TMyPropertyKeys={EMyPropertyCounter,EMyPropertyName};

// Active object that tracks changes to the ‘name’ property

class CPropertyWatch : public CActive

    {

    enum {EPriority=0};

public:

    static CPropertyWatch* NewL();

private:

    CPropertyWatch();

    void ConstructL();

    ~CPropertyWatch();

    void RunL();

    void DoCancel();

private:

    RProperty iProperty;

    };

CPropertyWatch* CPropertyWatch::NewL()

    {

    CPropertyWatch* me=new(ELeave) CPropertyWatch;

    CleanupStack::PushL(me);

    me->ConstructL();

    CleanupStack::Pop(me);

    return me;

    }

CPropertyWatch::CPropertyWatch()

    :CActive(EPriority)

    {}

void CPropertyWatch::ConstructL()

    {

    User::LeaveIfError(iProperty.Attach(KMyPropertyCat,KMyPropertyName));

    CActiveScheduler::Add(this);

    // initial subscription and process current property value

    RunL();

    }

CPropertyWatch::~CPropertyWatch()

    {

    Cancel();

    iProperty.Close();

    }

void CPropertyWatch::DoCancel()

    {

    iProperty.Cancel();

    }

void CPropertyWatch::RunL()

    {

    // resubscribe before processing new value to prevent missing updates

    iProperty.Subscribe(iStatus);

    SetActive();

    // property updated, get new value

    TFileName n;

    if (iProperty.Get(n)==KErrNotFound)

        {

        // property deleted, do necessary actions here...

        NameDeleted();

        }

    else

        {

        // use new value ...

        NameChanged(n);

        }

    }

    </codeblock> </section>

<section id="GUID-EF683969-CED9-5986-938D-3D887E3B39BD"><title>Usage patterns</title> <p>There

are three usage patterns that can easily be identified, labelled as: standard

state, pure event distribution, and speculative publishing. </p> <p id="GUID-0DFB902E-FCE1-52CF-8523-C7AE7B6768CE"><b>Standard state</b> </p> <p>This

pattern is used for events and state that are known to be used widely in the

system. Examples of this might be battery level and signal strength, which

are important in every phone. </p> <p>The publisher calls <xref href="GUID-C4776034-D190-3FC4-AF45-C7F195093AC3.dita#GUID-C4776034-D190-3FC4-AF45-C7F195093AC3/GUID-58C54D2A-91E0-359B-AA31-69C6C4050173"><apiname>RProperty::Define()</apiname></xref> to

create the appropriate property. For byte array or text properties, a size

sufficient for all possible values should be reserved. An error of <xref href="GUID-D1D25122-F2B8-3C78-8599-84905BFD47B8.dita"><apiname>KErrAlreadyExists</apiname></xref> should

be ignored. The publisher then publishes the property values as, and when,

appropriate. If the <codeph>RProperty::Set()</codeph> call fails, this should

be treated as a serious error, since it indicates that important system state

is not getting through. Appropriate action might include panicking or rebooting

the system. Subscribers will use <xref href="GUID-C4776034-D190-3FC4-AF45-C7F195093AC3.dita#GUID-C4776034-D190-3FC4-AF45-C7F195093AC3/GUID-21A2FEB7-AAF1-3AC0-84B9-AB30E6CFFF99"><apiname>RProperty::Subscribe()</apiname></xref> to

request notification, and <codeph>RProperty::Get()</codeph> to retrieve the

property value on notification. </p> <p>The memory to store the property value

will be permanently allocated, even if it turns out that no-one in the system

needs that value. This does ensure that the value can always be published,

even if the system is in an out of memory situation. For this reason, this

approach should be limited to widely used and important state. The <xref href="GUID-FE910347-7CC1-5241-B443-88AD3F5A96EF.dita#GUID-FE910347-7CC1-5241-B443-88AD3F5A96EF/GUID-01254366-696D-598F-9670-6A178F4E69F7">Speculative publishing</xref> pattern offers an approach for dealing with

less important state. </p> <p id="GUID-F2A60E64-C279-5E08-8AA8-52DF1EEA32BD"><b>Pure event distribution</b> </p> <p>This

pattern is used when events need to be distributed, not values. </p> <p>The

publisher of the event simply uses an integer property, and calls RProperty::Set()

with any value. Even if the value of the property is not changed by this operation,

all subscribers will be notified that a Set() has occurred, and by implication

that the related event has occurred. </p> <p>Subscribers will be able to detect

that an event has occurred, but will get no other information. The minimum

possible memory is wasted on storage for the dummy value. </p> <p id="GUID-01254366-696D-598F-9670-6A178F4E69F7"><b>Speculative publishing</b> </p> <p>This

pattern is used when it is not known whether a value will be of interest to

others or not. Unlike the <xref href="GUID-FE910347-7CC1-5241-B443-88AD3F5A96EF.dita#GUID-FE910347-7CC1-5241-B443-88AD3F5A96EF/GUID-0DFB902E-FCE1-52CF-8523-C7AE7B6768CE">standard

state</xref> pattern, the publisher of the event does not call <xref href="GUID-C4776034-D190-3FC4-AF45-C7F195093AC3.dita#GUID-C4776034-D190-3FC4-AF45-C7F195093AC3/GUID-58C54D2A-91E0-359B-AA31-69C6C4050173"><apiname>RProperty::Define()</apiname></xref> to

create the property. Instead, it simply calls <codeph>RProperty::Set()</codeph> as

appropriate, and ignores any <xref href="GUID-5E653C17-372C-32E1-A1B2-9E69A9991C40.dita"><apiname>KErrNotFound</apiname></xref> error. </p> <p>When

other code in the system, i.e. a potential subscriber, is interested in the

state, it calls <xref href="GUID-C4776034-D190-3FC4-AF45-C7F195093AC3.dita#GUID-C4776034-D190-3FC4-AF45-C7F195093AC3/GUID-58C54D2A-91E0-359B-AA31-69C6C4050173"><apiname>RProperty::Define()</apiname></xref> to create the property

and allocate the memory for the value. An error of <xref href="GUID-D1D25122-F2B8-3C78-8599-84905BFD47B8.dita"><apiname>KErrAlreadyExists</apiname></xref> should

be ignored, as this only indicates that some other code in the system is also

interested in the value and has already created the property. </p> <p>The

subscriber then calls <xref href="GUID-C4776034-D190-3FC4-AF45-C7F195093AC3.dita#GUID-C4776034-D190-3FC4-AF45-C7F195093AC3/GUID-21A2FEB7-AAF1-3AC0-84B9-AB30E6CFFF99"><apiname>RProperty::Subscribe()</apiname></xref> and <codeph>RProperty::Get()</codeph> as

usual to interact with the property. On the first <codeph>Get()</codeph>,

the subscriber may retrieve the property default value (zero, or a zero length

descriptor). This must be substituted with a sensible default value for the

property in question. </p> <p>Using this pattern, no memory is wasted on properties

that have no subscribers, while the publisher code is simpler as there is

no need for configuration as to which properties to publish. </p> <p>The publisher,

however, wastes some time attempting to publish unneeded values, but this

should not be an issue unless the value is very frequently updated. </p> <p>Where

events are published very infrequently, the subscriber could have a dummy

value for a long time, until the next publish event updates the value. Often

this is not a problem as a default value can be substituted. For example a

full/empty indicator for a battery level, none for signal strength etc. This

pattern is unlikely to be useful if there is no suitable default value. </p> </section>

<section id="GUID-2B022BE9-2004-54E8-962E-5AB38DDC4222"><title>Making efficient

use of the user side API</title> <p>While the Publish and Subscribe API, as

represented by <xref href="GUID-C4776034-D190-3FC4-AF45-C7F195093AC3.dita"><apiname>RProperty</apiname></xref> is designed to be efficient, there

are certain usage patterns that can improve performance. </p> <p><b>Use

the attached version of the API calls if possible</b> </p> <p>If you intend

to call <codeph>Set()</codeph> or <codeph>Get()</codeph> repeatedly, it is

preferable to use the attached forms of the calls. The attached forms are

the ones that do not take a UID/Key parameter, and that can only be called

after calling <xref href="GUID-C4776034-D190-3FC4-AF45-C7F195093AC3.dita#GUID-C4776034-D190-3FC4-AF45-C7F195093AC3/GUID-3F65DD85-6061-3370-9618-ECC0400323D1"><apiname>RProperty::Attach()</apiname></xref>. The attached variants

are constant time operations, and execute much faster than the corresponding

unattached versions. </p> <p><b>Only

preallocate space if the publishing is time critical</b> </p> <p>For byte-array

and text properties, it is possible to pre-allocate space for the data. Doing

this results in <codeph>Set()</codeph> operations that do not exceed the preallocated

space, avoiding the need to do a memory allocation. However, if the data is

shorter than the reserved space, the excess is wasted. Since <codeph>Set()</codeph> automatically

extends the data area if needed, then the only reason to pre-allocate space

is if the <codeph>Set()</codeph> operation has to be real-time, i.e. has to

have known execution time. </p> <p><b>Always

consider using Speculative Publishing</b> </p> <p>Even in situations where

the <xref href="GUID-FE910347-7CC1-5241-B443-88AD3F5A96EF.dita#GUID-FE910347-7CC1-5241-B443-88AD3F5A96EF/GUID-0DFB902E-FCE1-52CF-8523-C7AE7B6768CE">Standard

State</xref> pattern may seem appropriate, speculative publishing may be a

better choice, specially for low-level components that know little about how

they are used or what the wider system configuration may be. The onus is then

on the UI/Policy layer to ensure that the appropriate properties are defined

early on in device boot according to policy rules it can define. This ensures

that the policy layers in the system maintain control and can implement a

wide variety of policies. </p> <p>Standard state is only relevant for properties

that are essential to every Symbian device. Battery level probably falls into

this category, signal strength may well not. </p> <p><b>Define the expected update frequency</b> </p> <p>When a property is changed,

all subscribers are notified. This leads to their threads running to service

the notification. If a property changes value frequently, it would be wasteful

for subscribers to perform substantial processing for each notification. </p> <p>Take

a property representing signal strength as an example. Potentially, this could

be updated several times a second. If a change in value were only used to

update the UI signal bar, it would not be harmful. However, if it were used

by many entities for serious processing (e.g. polling for email, sending unsent

SMSes, re-connecting to the internet), then such frequent updates would have

a severe effect on battery life. </p> <p>Nevertheless, it is obviously desirable

for many parts of a phone OS to know about the state of network coverage,

and to take appropriate action. In cases like this, it may be worth the publisher

defining multiple properties with associated update characteristics. For example,

raw signal strength (updated > 1 time/sec), periodic signal strength (updated

once every 10s) and network coverage (updated only when moving between some

signal and none). Each subscriber can then monitor the appropriate notification

and so reduce the number of threads that run when the underlying value changes. </p> </section>