Purpose

Presence Cache API provides an interface to read, write and subscribe presence status data stored in Presence Cache server. This enables applications to share the same presence data status. There are few well known keys but it is possible to extend the data model and write new key-value pairs of data. The data stored is in 8-bit format and thus you can write and read for example status texts and bit maps.

Constraints

This API is valid for all platforms running on Symbian 9.3 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

Presence Cache API provides an interface to read, write and subscribe presence status data stored in Presence Cache server. There are few well known keys but it is possible to extend the data model and write new key-value pairs of data. This enables service providers to have data extensions for their presence protocol specific data. The data stored is in 8-bit format and thus you can write and read for example status texts and bit maps. Buddies are identified by identity field that must be in XspId format.

Logically Presence Cache API is a Library API which provides standalone implementation units that are used by the client. The provided implementation is used in the context of the client’s thread. The implementation units are delivered in a DLL so that many clients can share the same implementation. Technically Presence Cache API is a client-server interface.

Notice that the data is not written in a permanent storage and when the last client closes its connection to the server, the data is lost.

Use cases

  • Write presence data

  • Read presence data

  • Subscribe presence data changes

  • Delete service presence data

API class structure

Presence Cache API consists of interface classes MPresenceCacheReader2, MPresenceCacheWriter2, MPresenceCacheReadHandler2, MPresenceCacheWriteHandler2 and MPresenceBuddyInfo2. There are both synchronous and asynchronous methods in the API. A client application has to implement callback methods defined in MPresenceCacheReadHandler2 and MPresenceCacheWriteHandler2 in order to receive responses for asynchronous methods. The MPresenceBuddyInfo2 class defines the data model used in Presence Cache. It is basically a storage for key-value pair data but it also provides wrappers for well known keys. It is still possible to write any key-value pair data into cache and thus presence service providers can have data extensions for their presence protocol specific data.

API class structure


API class structure

Related APIs
  • MPresenceBuddyInfo2
  • MPresenceCacheReadHandler2
  • MPresenceCacheReader2
  • MPresenceCacheWriteHandler2
  • MPresenceCacheWriter2

Using the Presence Cache API

Write presence data

The class MPresenceCacheWriter2 provides methods to write presence data. Construction of MPresenceCacheWriter2 opens the connection to the Presence Cache server. The availability information and buddy identity fields are mandatory data in Presence Cache; without those the data is meaningless. Other data fields are optional. The MPresenceBuddyInfo2 class entity must contain all the data that is wanted to be stored in a cache hence there is no partial write operation. All the write operations replace buddy's old presence status totally.

  MPresenceCacheWriter2* iWriter;
  iWriter = MPresenceCacheWriter2::CreateWriterL();

Write synchronously

You can write presence data by creating the MPresenceBuddyInfo2 class entity, add data there, and then write the buddy information into cache by WritePresenceL.

  _LIT( KBuddyId, "ovi:user@nokia.com" );
  _LIT( KAvailability, "busy" );
  _LIT( KMyExtensionKey, "x-location");

  MPresenceBuddyInfo2* buddy = MPresenceBuddyInfo2::NewLC();
  // mandatory well known keys
  buddy->SetIdentityL( KBuddyId );
  buddy->SetAvailabilityL( MPresenceBuddyInfo2::EBusy, KAvailability);
  // own extension key
  buddy->SetAnyFieldL( KMyExtensionKey, my8byteBuffer )
  // write into cache
  iWriter->WritePresenceL( buddy ); 
  CleanupStack::PopAndDestroy( ); // buddy   

Related APIs
  • MPresenceBuddyInfo2
  • WritePresenceL

Write asynchronously

You can write presence data of multiple buddies asynchronously using the method WriteMultiplePresenceL. The request completes in the callback method HandlePresenceWriteL defined in the class MPresenceCacheWriteHandler2. There can exist maximum one asynchronous write request per MPresenceCacheWriter2 instance at a time.

Related APIs
  • HandlePresenceWriteL
  • MPresenceCacheWriteHandler2
  • MPresenceCacheWriter2
  • WriteMultiplePresenceL
Related APIs
  • MPresenceBuddyInfo2
  • MPresenceCacheWriter2

Read presence data

The class MPresenceCacheReader2 provides methods to read presence data. Construction of MPresenceCacheReader2 opens the connection to the Presence Cache server.

    MPresenceCacheReader2* iReader;
    iReader = MPresenceCacheReader2::CreateReaderL();

Read synchronously

You can read presence data by calling PresenceInfoLC in the class MPresenceCacheReader2.

    // Read from server
    MPresenceBuddyInfo2* buddy = iReader->PresenceInfoLC(KBuddyId);
    // Access data fields
    if ( buddy->BuddyId().Compare(KBuddyId) )
        {
        return KErrGeneral;
        }
    if ( buddy->Availability() != MPresenceBuddyInfo2::EBusy )
        {
        return KErrGeneral;
        }    
    if ( buddy->AvailabilityText().Compare(KAvailability) )
        {
        return KErrGeneral;
        } 
    if ( buddy->GetAnyField( KMyExtensionKey ).CompareF( my8byteBuffer ))
        {
        return KErrGeneral;            
        }    

Related APIs
  • MPresenceCacheReader2
  • PresenceInfoLC

Read asynchronously

You can read asynchronously by calling AllBuddiesPresenceInService. The request sends responses to the method HandlePresenceReadL in MPresenceCacheReadHandler2. If there are very many buddies in the service then the callback is called multiple times, i.e. the response may be sent in multiple data chunks. There can exist maximum one asynchronous read request per MPresenceCacheReader2 instance at a time

Related APIs
  • AllBuddiesPresenceInService
  • HandlePresenceReadL
  • MPresenceCacheReadHandler2
  • MPresenceCacheReader2
Related APIs
  • MPresenceCacheReader2

Subscribe presence data changes

You can subscribe changes of buddy's presence status by calling SubscribePresenceBuddyChangeL in MPresenceCacheReader2. The callback method HandlePresenceNotificationL in MPresenceCacheReadHandler2 is always called when the presence status changes. Below is an example on how to subscribe.

    TInt error = iReader->SetObserverForSubscribedNotifications( this );
    if ( error )
        {
        return KErrGeneral;
        }
    
    error = iReader->SubscribePresenceBuddyChangeL( KBuddyId );  
    if ( error )
        {
        return KErrGeneral;
        } 

The responses are handled below.

void CMyTester::HandlePresenceNotificationL(TInt aErrorCode,
        MPresenceBuddyInfo2* aPresenceBuddyInfo)
    {    
    TInt ret = KErrNone; 
    TBuf<100> testBuffer;

    if ( !aPresenceBuddyInfo )
        {
        ret = aErrorCode;
        RequestComplete( ret );      
        return;
        }
    MPresenceBuddyInfo2::TAvailabilityValues avaVal =  aPresenceBuddyInfo->Availability();
    testBuffer = aPresenceBuddyInfo->BuddyId();
    // Ownership is taken, we delete the parameter
    delete aPresenceBuddyInfo;
             
    RequestComplete( ret );    
    return;
    }
Related APIs
  • HandlePresenceNotificationL
  • MPresenceCacheReadHandler2
  • MPresenceCacheReader2
  • SubscribePresenceBuddyChangeL

Delete presence data

The class MPresenceCacheWriter2 provides methods to delete single buddy's presence status data in the cache or delete all buddies under a specific service. DeleteService deletes entire service and is useful if a service is uninstalled or if service protocol has totally lost data connection to a remote service. DeletePresenceL deletes all presence data belonging to a specific buddy.

    // Delete one buddy
    TInt ret = iWriter->DeletePresenceL( KBuddyId );  

    // Delete OVI service
    _LIT( KService, "OVI" );
    ret = iWriter->DeleteService( KService );

Related APIs
  • DeletePresenceL
  • DeleteService
  • MPresenceCacheWriter2

Error handling

Presence Cache API methods use regular error codes only defined in e32err.h.

Memory overhead

Presence Cache API client side does not consume very much memory. Regular client-server framework memory overhead is required. The amount of memory that server side consumes depends on how many buddies are stored, how much they contain data and how many presence subscribers exist.

Glossary

Abbreviations

API Application Programming Interface

Definitions

Buddy Messaging service user, usually a Phonebook contact field. Defined in XspId format.

Phonebook

Phonebook software and its data storage in a mobile device.

Presence status

Dynamic buddy's service status information, such as availability status.

XspId

URI in format <service_name>:<user_id>