Purpose

New sending services can be added into Send menu using this API. This is a partially alternate and simpler method compared to using Messaging Integration API.

Constraints

A service that implements this API is not visible in Message Center.

Classification

This API is a Domain API.

Emulator support

This API is fully supported in the WINS or WINSCW emulator environment.

API description

This Framework API offers a simple way to create ECOM based sending services that are available in the Send menu.

Use cases

The use case explains how to define a new sending service. In practice, this includes implementing the pure virtual functions and setting up the ECOM resource file.

API class structure

Sending service needs to implement the CSendingService interface. It has the following virtual functions: NewL, PopulateServicesListL, ServiceProviderId, CreateAndSendMessageL and destructor.


Related APIs
  • CSendingService
  • CreateAndSendMessageL
  • NewL
  • PopulateServicesListL
  • ServiceProviderId

Using Send UI Plug-in API

Defining a sending service

The class derived from CSendingService is only a service provider. It must have at least one sending service in order to function properly. If there is only one sending service, the same unique identifier can be used for the service provider and the service. The services are defined by CSendingServiceInfo objects, which are inquired through the PopulateServicesListL method.

Defining resources

Sending services requires a UID. Its resources are saved into file NNNNNNNNN.rss. In the below example the file name is 12345678.rss.

#include <RegistryInfo.rh>
#include <SendingServiceInterfaceUids.hrh>

// ---------------------------------------------------------------------------
// Registration info
// ---------------------------------------------------------------------------
//
RESOURCE REGISTRY_INFO theInfo
    {
    dll_uid = 0x12345678; // This is unique in the system
    interfaces = 
        {
        INTERFACE_INFO
            {
            interface_uid = KSendUiSendingServiceInterface;
            implementations = 
                {
                IMPLEMENTATION_INFO
                    {
                    implementation_uid = KMySendingServicePlugingUid;
                    version_no = 1;
                    display_name = "";
                    default_data = "";
                    opaque_data = "";
                    }
                };
            }
        };
    }

Implementing pure virtual methods

A sending service provider is given TSendingParams class in construction. This class contains reference to CCoeEnv and CSendUiSingleton classes. CSendUiSingleton class contains common access point to CClientMtmRegistry, CMtmUiRegistry, CMtmUiDataRegistry and CMsvSession. If any of these are required by your class, then it is recommended to use the ones provided by CSendUiSingleton to speed up initialization time of your plug-in and to decrease the memory overhead. CSendUiSingleton owns these resources and is responsible for destroying them.

All the following methods are defined pure virtual by CSendingService, thus an implementation is required from the derived class.

PopulateServicesListL

The most important method to get your service visible is PopulateServicesListL, because it provides the information of the provided services. Note that a single CSendingService based class may define multiple services. Below is an example of the PopulateServicesListL method.

void CMySendingServicePlugin::PopulateServicesListL(
    RPointerArray<CSendingServiceInfo>& aList )
    {
        CSendingServiceInfo* serviceInfo = CSendingServiceInfo::NewLC();

    // Set service type. This service provider provides only one service. Same Uid can be used for both
    serviceInfo->SetServiceProviderId( KMySendingServicePluginUid ));
    serviceInfo->SetServiceId( KMySendingServicePluginUid ) );    

    serviceInfo->SetServiceMenuNameL( _L("My Send service") ); // name for Send menu
    serviceInfo->SetServiceNameL( _L("My Send service") ); // name for Write menu
    serviceInfo->SetServiceCapabilities( TSendingCapabilities( 0,0, 0 ) ); // See TSendingCapabilities.h for details.

    aList.Append( serviceInfo );
    CleanupStack::Pop( serviceInfo );        
    }

Sending service provider should fill the parameter array with all provided sending services. The sending service information is included in the CSendingServiceInfo class objects, which is described in Send UI API documentation. Note that sending service should provide localized menu names according to the selected phone language.

ServiceProviderId

Method ServiceProviderId should return KMySendingServicePluginUid which is defined in the resources. All CSendingServiceInfo objects should set their service provider to KMySendingServicePluginUid using the CSendingServiceInfo::SetProviderId method.

const TUid KMySendingServicePluginUid = { 0x12345678}; // Put your unique ID number here
...
TUid CMySendingServicePlugin::ServiceProviderId() const
    {
    return KMySendingServicePluginUid;
    }

CreateAndSendMessageL

Next, implement CreateAndSendMessageL( TUid aServiceUid, const CMessageData* aMessageData, TBool aLaunchEditorEmbedded = ETrue). If your sending service has defined multiple sending services, then the correct one is selected using aServiceUid. The aMessageData parameter contains all message data. Sending service should respect the aLaunchEditorEmbedded value. Naturally, this value is not relevant for services without an editor.

The call CreateAndSendMessageL is blocking. Do not return until your service is ready, because the sending service class is destroyed immediately after return from CreateAndSendMessageL.

void CMySendingServicePlugin::CreateAndSendMessageL(
    TUid aServiceUid,
    const CMessageData* aMessageData,
    TBool aLaunchEditorEmbedded )
    {
    // process the message data
    // return when finished
    }

Destructor

Finally, implement a destructor.

CMySendingServicePlugin::~CMySendingServicePlugin()
    {
    // free all owned resources
    }

Related APIs
  • CClientMtmRegistry
  • CCoeEnv
  • CMsvSession
  • CMtmUiDataRegistry
  • CMtmUiRegistry
  • CSendUiSingleton
  • CSendingService
  • CSendingServiceInfo
  • CSendingServiceInfo::SetProviderId
  • CreateAndSendMessageL
  • KMySendingServicePluginUid
  • PopulateServicesListL
  • ServiceProviderId
  • TSendingParams
  • aLaunchEditorEmbedded
  • aMessageData
  • aServiceUid
Related APIs
  • CSendingService
  • CSendingServiceInfo
  • PopulateServicesListL

Error handling

It is guaranteed that Send UI inquires at least once via PopulateServicesListL for the sending services provided by the plug-in during the first usage of CSendUI, ECOM installation/removal and after change of the system language. If PopulateServicesListL leaves, none of the services provided by the plug-in are visible in the system. A leaving PopulateServicesListL call does not disturb loading of other sending services in the system.

Do not raise KErrPermissionDenied or KErrAccessDenied leave in CreateAndSendMessageL unless there is a need to indicate a problem with capabilities of the host process or sending service provider. See chapter Security considerations for more information.

Related APIs
  • CSendUI
  • CreateAndSendMessageL
  • KErrAccessDenied
  • KErrPermissionDenied
  • PopulateServicesListL

Memory overhead

This interface has minimal memory overhead. Memory overhead depends on the deriving class.

Extensions to the API

None.

Limitations of the API

None.

Security considerations

Send UI first starts a sending service in the process of the hosting application (with host application capabilities). If this fails due to system security restriction of loading ECOM plug-ins, then the same service is started from a process with less capabilities ( NetworkServices, LocalServices, ReadUserData, WriteUserData, UserEnvironment, NetworkControl, ReadDeviceData, WriteDeviceData). If this also fails, Send UI raises User::Leave with an appropriate leave code.

Related APIs
  • User::Leave

Glossary

ECOM EPOC Component Object Model. A mechanism for loading plug-in DLLs.

References

Send UI API Specification Document

Messaging Integration API Specification Document