Profiles Engine Wrapper API: API Description

Profiles Engine Wrapper API provides information about existing profiles in the device such as different alert tones, vibrating alert and warning tones. Furthermore it can be used to manipulate the settings of the profiles.

Type of this interface is a normal method call interface. The interface uses local objects for Profiles Engine that provides methods for accessing profiles data. All the methods in the API are synchronous except the method to get the list of available alert tones in the MProEngAlertToneSeeker interface, which is a very long-lasting operation and for that reason the method is asynchronous.

Client application can use Profiles Engine Wrapper API to list currently existing profiles on the device. Listing is provided by Profiles Engine that delivers this information in a Profile Name Array. This array provides read-only access to IDs and names of all profiles. A Profile Name is used to encapsulate the name and the ID of one profile. The name of a profile can be changed through the Profile Name interface but the ID is unchangeable. Profiles Engine can also be used to get or set the current active profile and to access the settings of each profile. Finally the API provides a way to get notifications when the profiles data is modified in any way.

Profiles Engine Wrapper API can be used in applications that need profiles data in any way. For example, the application could be a music player that uses Profiles Engine Wrapper API to get the silent status of the current profile, so that if the profile is silent it does not allow playing any music file. Presumably most of the clients need only read the profiles data. It should be noted, that for modification of Profiles data WriteDeviceData capability is needed.

Use Cases

The main use cases of the Profiles Engine Wrapper API are:

1. Getting the active profile ID

2. Setting the active profile

3. Getting the settings of a profile

   • Special case: getting the active profile settings

4. Modifying the settings of a profile

5. Getting the list of the names of currently existing profiles

6. Getting notifications about changes in Profiles data

7. Getting the listing of media files usable as alert tones

API Class Structure

Profiles Engine Wrapper API contains a number of classes providing functionality of the interface. In the following class diagrams, API classes are grouped together according to their roles and functionality.

The class diagram in Figure 1 shows that ProEngFactory is a factory for MProEngEngine, MProEngAlertToneSeeker and MProEngNotifyHandler. MProEngAlertToneSeeker is used for searching all the media files from the device (and from the memory card) that can be used as alert tones in Profiles. MProEngNotifyHandler notifies the client-implemented observers about changes in Profiles data. As can be seen, there can be at most one observer of each type attached to an instance of MProEngNotifyHandler. Only exception is MProEngProfileObserver the instances of which there can be as many as are profiles currently in the device.

MProEngEngine and its related classes are shown in Figure 2. MProEngEngine is used for getting the settings for any profile. It returns the result in the form of MProEngProfile object. MProEngEngine functions also as a factory for MProEngProfileNameArray objects. This array contains the names and IDs of all the existing profiles. Moreover MProEngEngine can be used to get the ID of the currently active profile and to change the active profile.