Contact Presence APIChanges in Contact Presence API documentation
PurposeContact 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:
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. API descriptionContact 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
API class structureContact Presence API consists of the interface classes
Related APIs
Using the Contact Presence APIClient 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 deletionYou have to create an instance of the
In the class declaration: In the class implementation: You can delete the
Related APIs
Subscribe common presence statusYou 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
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
You can cancel the subscription of getting status information any time by calling cancel method.
Related APIs
Get service specific presence statusesYou get all service presence statuses at once by calling
The response is sent to the callback method
Related APIs
Get actual status iconAfter 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. 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. 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 handlingMethods in
Related APIs
Memory overheadContact 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
Related APIs
GlossaryAbbreviations
Definitions
Copyright ©2010 Nokia Corporation and/or its subsidiary(-ies). All rights reserved. License: EPL
|