CMS Contactor API
Changes in CMS Contactor API documentation
| Version |
Date |
Status |
|
1.0
|
21.04.2009
|
Approved
|
Purpose
The purpose of CMS Contactor API is to provide API for launching and implementing
Instant Messaging service provider.
Constraints
This API is valid for all platforms running on Symbian OS 9.3 or later.
CMS Contactor API requires the UI framework (
CCoeEnv).
Related APIs
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
CMS Contactor API offers an interface to launch and implement Instant Messaging
service for a specific buddy. CMS Contactor API is an ECOM plug-in that is
loaded by an application who wants to start Instant Messaging with a specific
buddy. A buddy is identified with URI in XspId format.
The API is Framework API that provides a base class for service providers
to implement Instant Messaging service loader.
Technical type of the API is Method call (interface uses only local objects).
Use cases
The use cases are
API class structure
CMS Contactor API consists of the interface classes
CCmsContactorImPluginBase and MCmsContactorImPluginApi.
Related APIs
CCmsContactorImPluginBaseMCmsContactorImPluginApi
Using the CMS Contactor API
Launch a service
Below is an example of launching Instant Messaging service. Our sample
Instant Messaging service plug-in uses ECOM implementation UID 0xEF00F000.
Real Instant Messaging service provider plug-in implementation UID must be
unique and reserved, like any other unique UID.
TUid destructorId;
_LIT( KMyTesterUser, "im.tester@im.demo.com");
CCmsContactorImPluginBase* myPlugin;
// sample plugin UID, real implementation must have a unique UID
const TInt KMySamplePluginUid = 0xEF00F000;
TAny* volatile implementation =
REComSession::CreateImplementationL( TUid::Uid( KMySamplePluginUid ),
destructorId );
myPlugin = reinterpret_cast< CCmsContactorImPluginBase* >( implementation );
myPlugin->SetDestructorId( destructorId );
myPlugin->ExecuteL( KMyTesterUser );
delete myPlugin;
Implement Instant Messaging ECOM plug-in loader
CMS Contactor API provides base classes for Instant Messaging service provider
to implement ECOM loader that loads plug-in DLL and implements the
ExecuteL method
that takes XspId as an input parameter. The service is the
service name in SP Settings table. Based on this information the service provider
third party plug-in software starts to run.
The service provider must implement the base class
CCmsContactorImPluginBase that
handles ECOM loading and MCmsContactorImPluginApi class that
defines the ExecuteL method. The implementation UID of the
ECOM plug-in must match with the content of SP settings table. Interface UID
must be CMS_CONTACTOR_INTERFACE_UID defined in cmscontactorimpluginifids.hrh.
#include <ecom/registryinfov2.rh >
#include "cmscontactorimpluginifids.hrh"
// ---------------------------------------------------------------------------
// ECOM registery info for CMS contactor Plugin
// ---------------------------------------------------------------------------
//
RESOURCE REGISTRY_INFO theInfo
{
resource_format_version = RESOURCE_FORMAT_VERSION_2;
dll_uid = 0xEF00F001;
interfaces =
{
INTERFACE_INFO
{
// implemented interface
interface_uid = CMS_CONTACTOR_INTERFACE_UID;
implementations =
{
IMPLEMENTATION_INFO
{
implementation_uid = 0xEF00F000;
version_no = 1;
display_name = "IMLauncherSample";
default_data = "Launch";
opaque_data = "";
}
};
}
};
}
This is an example of the plug-in.
class CImSamplePlugin: public CCmsContactorImPluginBase
{
public:
static CImSamplePlugin* NewL();
static CImSamplePlugin* NewLC();
virtual ~CImSamplePlugin();
private:
CImSamplePlugin();
void ConstructL();
public:
// from base class MCmsContactorImPluginApi
/**
* Defined in a base class
*/
void ExecuteL( const TDesC& aXspId);
};
void CImSamplePlugin::ExecuteL( const TDesC& aXspId )
{
// launch the UI
const TUid myAppUid = { _UID3 };
const TUid myViewUid = { 0x00000001 };
CEikonEnv* env = CEikonEnv::Static();
CEikAppUi* appUi = env->EikAppUi();
TVwsViewId id;
id.iAppUid.iUid = _UID3;
id.iViewUid.iUid = 1;
TUid customUid;
customUid.iUid = 1;
HBufC8* tempBuffer = HBufC8::NewLC( aXspId.Length() );
TPtr8 testBuff = tempBuffer->Des();
testBuff.Append( aXspId );
appUi->ActivateViewL( TVwsViewId( myAppUid, myViewUid ), customUid, testBuff );
CleanupStack::PopAndDestroy( tempBuffer );
}
Related APIs
CCmsContactorImPluginBaseExecuteLMCmsContactorImPluginApiXspId
Error handling
Normal error case handling.
Memory overhead
The CMS Contactor API itself frees all allocated memory after
ExecuteServiceL is
executed. Thus the amount of RAM depends very much on which service you launch
and how long that service is running.
Related APIs
Glossary
Abbreviations
|
CMS
|
Contact Method Selector
|
|
IM
|
Instant Messaging
|
Definitions
|
XspId
|
The XspId is URI in a format <service_name>:<:user_id>.
|