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
  • CCoeEnv

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

  • Launch a service

  • Implement Instant Messaging ECOM plug-in loader

API class structure

CMS Contactor API consists of the interface classes CCmsContactorImPluginBase and MCmsContactorImPluginApi.

API class structure


API class structure

Related APIs
  • CCmsContactorImPluginBase
  • MCmsContactorImPluginApi

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
  • CCmsContactorImPluginBase
  • ExecuteL
  • MCmsContactorImPluginApi
  • XspId

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
  • ExecuteServiceL

Glossary

Abbreviations

CMS Contact Method Selector

IM

Instant Messaging

Definitions

XspId The XspId is URI in a format <service_name>:<:user_id>.