Presence Cache API
Changes in Presence Cache API documentation
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.
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.
Related APIs
MPresenceBuddyInfo2MPresenceCacheReadHandler2MPresenceCacheReader2MPresenceCacheWriteHandler2MPresenceCacheWriter2
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
MPresenceBuddyInfo2WritePresenceL
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
HandlePresenceWriteLMPresenceCacheWriteHandler2MPresenceCacheWriter2WriteMultiplePresenceL
Related APIs
MPresenceBuddyInfo2MPresenceCacheWriter2
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
MPresenceCacheReader2PresenceInfoLC
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
AllBuddiesPresenceInServiceHandlePresenceReadLMPresenceCacheReadHandler2MPresenceCacheReader2
Related APIs
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
HandlePresenceNotificationLMPresenceCacheReadHandler2MPresenceCacheReader2SubscribePresenceBuddyChangeL
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
DeletePresenceLDeleteServiceMPresenceCacheWriter2
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>
|