Migrating to Publish and Subscribe

The functionality provided by System Agent has been replaced by Publish & Subscribe, which is now the recommended way of setting and retrieving global information and for requesting notification when such global values are published.

This section deals with some of the issues relating to the migration.

• Identify and mark all references to System Agent APIs. These will be replaced with references to the RProperty class. Properties are defined, retrieved, published etc. through member functions of this class.

• Replace System Agent header files with the single header file e32property.h. This is where the RProperty class is declared.

• To define a property, which is equivalent to the original System Agent property, call RProperty::Define(), and specify:

  • the UID of the category

  • the property's UID as the "aKey" parameter

  • RProperty::EInt as the "aAttr" parameter

  System agent initialises the created property with the value KErrUnknown. Clients can emulate this or choose a different value.

• To get the property value, use the RProperty::Get() member function.

• To set the property value, use RProperty::Set() member function.

• To delete a property, use RProperty::Delete() supplying the same category UID and key as was supplied when the property was defined.

Clients wishing to emulate System Agent exactly to support their own clients who may have already migrated to Publish & Subscribe in an earlier release, and who may be using a property category UID of KUidSystemCategory, will need to have ReadDeviceData & WriteDeviceData capabilities assigned to their binaries and their clients binaries to be able to access these system properties

A client makes a request for notification of changes to property using RProperty::Subscribe() and cancels a notification request using RProperty::Cancel(). There are some important differences between the System Agent notification requests and RProperty notifications requests:

• Publish & Subscribe will always notify the client when they or some other client calls RProperty::Set() on monitored property, even if the property value has not changed.

• The RProperty class does not support conditional notification, as represented by the System Agent TSysAgentConditionType enum. The migrating client will need to implement this feature itself.

System Agent offers functionality to get and set an array of properties, but RProperty does not provide this functionality.

To speed up the getting and setting of a property's values use RProperty::Attach() and the instance based (non-static) Get() and Set() member functions.