Purpose

Contact Presence API provides an interface for accessing a messaging services availability status icon for a Phonebook contact. The availability icon changes when the presence status of the contact's buddies changes in the corresponding messaging systems, such as in Instant Messaging or VoIP. Contact Presence API supports two kind of presence information; a common availability icon for contact and service specific presence icons. The common presence icon is generic for a Phonebook contact and it is a union of separate service statuses. Each service has its own set of branded icons for various states. There are also two common traffic light icons, one for available state and another for unavailable state. Those common traffic light icons are used for common presence status in certain cases explained below.

The logic of icon composing is the following one:

  • When the user is not logged in any service or when there is no presence data for a buddy then no icon is returned.

  • When the user is connect to one service and there is presence data for a buddy then a service specific icon is returned.

  • When the user is connected to multiple services and only one service state is available then that service specific available icon is returned.

  • When the user is connected to multiple services and all service states are unavailable then generic unavailable traffic light is returned.

  • When the user is connected to multiple services and two or more services are available then generic available traffic light is returned.

Notice that a service must be installed properly in the mobile device before Contact Presence API really starts to work. It is not enough just to add a contact field for a buddy but Service Provider Settings table and Branding Server must be configured properly and the Service Provider application has to write presence status into presence cache in the mobile device.

Constraints

This API is valid for all platforms running on S60 release 5.1 or later.

Classification and release information

This API is a domain API and was first published in S60 release 5.1. This document is valid from S60 release 5.1 onwards.

Emulator support

This API is fully supported in the WINS/WINSCW emulator environment.

API description

Contact Presence API supports two kinds of presence information; a common availability icon for a contact and a service specific presence icons. Both of those presence statuses are fetched in two phases. First you get presence status information that identifies the presence icon stored in the Branding Server or in a file system. Second you can access the actual icon data based on the branding information. The icon is either a branded icon provided by the single service provider or sometimes a common “traffic light” icon. The common "traffic light" icons are stored in a file system and service specific icons are stored under Branding Server. The usage of the API is similar in both use cases and the user does not need to know where the icon is stored.

The API provides the subscription type of the access method to common presence status. First you get the initial state of the service if there is any information available and after that you get all the status changes when they happen in messaging services. Service specific presence statuses cannot be subscribed but it is possible to get all of the service statuses at once. All the methods except cancel methods are asynchronous.

Logically Contact Presence API is a library API which provides interfaces that are used by the client in the context of the client’s thread. Technically this is a method call API (interface uses only local objects). The implementation units are delivered in a DLL so that multiple clients can share the same implementation. Notice that other DLLs that are statically linked to this DLL use client-server APIs, such as Branding Server and Presence Cache Server.

Use cases

  • Get service specific presence statuses

  • Subscribe common presence status

  • Get actual presence icon

API class structure

Contact Presence API consists of the interface classes TContactPresenceFactory , MContactPresence, MContactPresenceInfo, and MContactPresenceObs. The client initiates this interface by calling a factory method in TContactPresenceFactory to create the MContactPresence entity. A client application has to implement callback methods defined in the MContactPresenceObs class in order to receive observer callbacks for asynchronous requests.

Contact Presence API classes


Contact Presence API classes

Related APIs
  • MContactPresence
  • MContactPresenceInfo
  • MContactPresenceObs
  • TContactPresenceFactory

Using the Contact Presence API

Client applications need to import contactpresence.lib in their project make files. After that including the API header files contactpresencefactory.h, mcontactpresence.h, mcontactpresenceinfo.h, and mcontactpresenceobs.h is necessary. To get Phonebook contact links the client needs to import vpbkeng.lib and include the corresponding header files.

Initialization and deletion

You have to create an instance of the MContactPresence entity first. There are two versions of the NewContactPresenceL method in TContactPresenceFactory. The first version creates the CVPbkContactManager entity internally for you and the second version takes that class as input parameter and that can be used if a client application already has Phonebook contact manager entity. A client application has to implement the MContactPresenceObs class methods.

In the class declaration:

    CPtrC8Array*                                iLinkArray;
    MContactPresence*                           iContactPresence;
    CContactPresenceApiHandler*                 iContactPresenceHandler;

    class CContactPresenceApiHandler : public CBase, public MContactPresenceObs

In the class implementation:

    #include <contactpresencefactory.h>
    #include <mcontactpresence.h>

    iContactPresence = TContactPresenceFactory::NewContactPresenceL( *iContactPresenceHandler ); 

You can delete the MContactPresence entity by calling the Close method. After that you can delete your MContactPresenceObs implementation safely.

    if( iContactPresence )
        {
        iContactPresence->Close();
        iContactPresence = NULL;
        }
    delete iContactPresenceHandler;
    iContactPresenceHandler = NULL;

Related APIs
  • CVPbkContactManager
  • Close
  • MContactPresence
  • MContactPresenceObs
  • NewContactPresenceL
  • TContactPresenceFactory

Subscribe common presence status

You have to first get the service status information for a Phonebook contact link before you can access the actual service status icon. You start to listen to changes in service status by calling the SubscribePresenceInfoL method with array of contact links. You can repeat the subscription request many times and it is up to you whether you want to subscribe multiple contact links at once having multiple entities in the input array or whether you want to subscribe contacts one by one having only one element in the input array each time.

iContactPresence->SubscribePresenceInfoL( *iLinkArray );

You get the initial state of the service status if there is any in Presence Cache. After that any time the status of the contact link changes your callback method is called again. If you get zero length brand ID and element ID, then services are not working anymore and your application does not show any icon. Presence status is send to the callback method ReceiveIconInfoL. There is a simple example of the callback method implementation below. If you have subscribed to multiple contacts then you use the aPackedLink parameter to map the status to the right Phonebook contact.

    void CContactPresenceApiHandler::ReceiveIconInfoL( 
        const TDesC8& /*aPackedLink*/, const TDesC8& aBrandId, const TDesC8& aElementId )
        {
        TBuf<50> brand;
        TBuf<50> element;
        brand.Copy(aBrandId);
        element.Copy(aElementId); 
    
        iTesterMain.RequestComplete( KErrNone );    
        }

You can cancel the subscription of getting status information any time by calling cancel method.

    iContactPresence->CancelSubscribePresenceInfo( *iLinkArray );

Related APIs
  • ReceiveIconInfoL
  • SubscribePresenceInfoL
  • aPackedLink

Get service specific presence statuses

You get all service presence statuses at once by calling GetPresneceInfoL.

TInt opId = iContactPresence->GetPresenceInfoL( iLinkArray->At(0) );

The response is sent to the callback method ReceiveIconInfosL

void CContactPresenceApiHandler::ReceiveIconInfosL(
    const TDesC8& /*aPackedLink*/,
    RPointerArray <MContactPresenceInfo>& aInfoArray,
    TInt aOpId )   
    {
    TInt ret = KErrNone;
    TBuf<50> brand;
    TBuf<50> element;
    TBuf<50> service;     
    TInt myId = aOpId;
    TInt counter = aInfoArray.Count();
    MContactPresenceInfo* info = NULL;    
    for ( TInt i = 0; i < counter; i++ )
        {
        info = aInfoArray[i];
        brand.Copy( info->BrandId());
        element.Copy( info->ElementId());
        service.Copy( info->ServiceName());
        }

    iTesterMain.RequestComplete( ret );    
    }
Related APIs
  • GetPresneceInfoL
  • ReceiveIconInfosL

Get actual status icon

After you have received service status information you can get the actual status icon presenting the proper status. The method returns an operation ID that you can use to cancel the operation later. Before you get the icon you may want to set the size of the icon proper for your purposes.

    iContactPresence->SetPresenceIconSize( TSize(15,15) );
    TInt opId = iContactPresence->GetPresenceIconFileL( KECEDefaultBrandId_test, KElementIdExists );

Notice that this method is not subscription but a 'get once' type of request. You may still want to cancel the request immediately in the following way.

    iContactPresence->CancelOperation( opId );

The status icon is received by the callback method. Notice that to improve the performance it is the responsibility of the client application to cache the icons and get the icons from Contact Presence API only when needed. The amount of various icons is not very high since each service has maximum three icons (available, busy, unavailable) plus and there are only two common traffic lights icons (available, unavailable).

Error handling

Methods in MContactPresence do not return error codes but they may leave on the system errors, such as in low memory situation or if the input parameters are invalid, e.g. if the contact link parameter is invalid. Those errors must be TRAPped in the application. Because the methods are asynchronous, errors that take place later in the processing are informed by using a callback method. There are two callback methods for purpose, namely PresenceSubscribeError and ErrorOccured. Below there are simple examples of implementation of these methods. In the first case it is known that you do not get any further status information for the specified contact link anymore and thus you must rerun the subscription request with a proper contact link. In the second case, getting an icon is failed for some reason.

    void CContactPresenceApiHandler::PresenceSubscribeError( const TDesC8& /*aContactLink*/, TInt /*aStatus*/ )
        {    
        iTesterMain.RequestComplete( KErrGeneral );          
        }

    void CContactPresenceApiHandler::ErrorOccured( TInt /*aOpId*/, TInt /*aStatus*/ )
        {
        iTesterMain.RequestComplete( KErrNone );
        }

Related APIs
  • ErrorOccured
  • MContactPresence
  • PresenceSubscribeError

Memory overhead

Contact Presence API DLL itself does not allocate very big amount of memory but other DLLs that it calls allocate most of the memory needed. The amount of memory required depends on the number of contacts subscribed and about how many buddies each contact has. Creation of MContactPresence requires about 30 kilobytes RAM and subscribing contact information consumes about 2 kilobytes overhead for each contact link. Getting icons requires also RAM that depends on the icon file. The icon file ownership is transferred to a client application in the callback method and thus extra memory is not allocated for a long time in this case. Contact Presence API implementation accesses servers like Branding Server and Presence Cache server that also requires few kilobytes RAM to run.

Related APIs
  • MContactPresence

Extensions to the API

There is no extension mechanism for this API.

Limitations of the API

The API functionality cannot be limited.

Glossary

Abbreviations

API Application Programming Interface

IM

Instant Messaging

VoIP

Voice over Internet Protocol

Definitions

Buddy A Phonebook contact field (URI) to identify a messaging service user e.g. sip:dave@example.com

Branding Server

The Branding Server is a client/server-component that provides interfaces for storing and fetching data based on given brand. Typical brand variated data is bitmaps, texts or flag values. Branding Server stores the data in a file store under its own private folder and so the data is protected by platform security.

Client Application

Software that uses Contact Presence API

Messaging Service

Network service to allow to contact other users, like VoIP and IM

Phonebook

The Phonebook software and its data storage in a mobile device.

Presence cache

Storage where service applications write presence status in a mobile device.

Presence status

Dynamic availability status information of the user of the Messaging service.

Service Provider Settings

Service Provider Settings (SPS) is a static DLL. SPS provides the means to create and modify entries to service table, which contains the top level configuration of converged services. The configured converged services and sub-services are stored in Converged Service Table, which is located in Central Repository