Purpose

IM Application Launch API is an API that the application must implement in order to receive application startup requests in case a new message is coming when the application is not running but the user is logged in to the remote server. This is an ECom API. The application must implement it as an ECom plug-in. Note that the server has to send the correct identification in the message for the ECom plug-in to be loaded.

Constraints

This API is valid for all platforms running Symbian OS v8.0 or later versions.

API description

The interface includes the asynchronous methods for launching the application and canceling the launch. The interface is implemented by the ECom plug-ins. Application ID is used for routing the messages. Application ID has to be registered as mentioned in the IM API. Only that application which has registered using a certain ID can receive the message sent by the server (with the same ID).

API class structure

CImLauncherPlugin is an ECom interface implemented by the user application plug-in. This provides two methods, StartApplicationL() to start the application implemented by the user application plug-in and CancelStartApplication() to cancel the start implemented by the user application plug-in.

Related APIs
  • CImLauncherPlugin
  • CancelStartApplication()
  • StartApplicationL()

Using IM Application Launch API

Receiving an orphaned message

Initially the user is logged in (CSP session exists), and the user application which receives the instant message is running. This user application has registered itself using an ID as specified in IM API. Now if the user application stops running (but the user is logged in to the remote server) and if the server sends an instant message, the ECom plug-in is loaded. This plug-in must start the user application again. This application must implement the APIs mentioned in IM API to receive the messages. Once the application starts, it starts receiving the instant messages. All pending messages are sent to the application. Since the whole process may take some time, the user application can use appropriate mechanism to inform the user.

Receiving an orphaned message when application start is ongoing

An instant message is received and it triggers the application start and the start is ongoing. In case of different Application ID, the request is queued too. In case of the same Application ID, the user application is started and both instant messages are received. In case of a different user ID, both user applications are started and each receives its instant message. After the application is started successfully, all orphaned messages are received by the application. If the Application ID was different from the Application ID, which triggered the ongoing launching, the new launching is initiated starting the application registered with that Application ID.

Launching the application which handles the instant message received by the IM protocol stack

The plug-in for launching the user application implements the ECom interface for launching the user application. Upon the process creation, a string can be passed to the launcher process as a parameter. The string is the actual Application ID of the user application.

In order to launch the application which handles the instant message received by the IM protocol stack, an ECom plug-in needs to be installed which implements the following interface from imlaucherplugin.h include file.

Creating a resource file

ECom plug-in resource file has the Application ID in the default_data field.

        //Example resource file
// 101FB0CD.RSS
#include "RegistryInfo.rh"

// Declares info for two implementations
RESOURCE REGISTRY_INFO theInfo
    {
    // UID for the DLL
    dll_uid = 0x101FB0CD;
    // Declare array of interface info
    interfaces = 
        {
        INTERFACE_INFO
            {
            // UID of interface that is implemented
            interface_uid = 0x101FB0CC;
            implementations = 
                {
                IMPLEMENTATION_INFO
            {
            implementation_uid = 0x101FB0D1;
            version_no = 1;
            display_name = "Test launcher plugin";
            default_data = "Default";
            opaque_data = "";
            }
        };
        }
    };
  }
          

Example code:

The following example code is an implementation of two interfaces StartApplicationL and CancelStartApplication. The first one connects to the server which provides access to a cached list of the applications on the device and starts the application chat.app. The latter one cancels the start of chat.app

        // Implementation of StartApplicationL
//aSAP and aUserId can also be used as per the requirement
void CTestPlugin::StartApplicationL(TRequestStatus& aStatus)
    {
    // The application file which is going to be started
    _LIT(KAppName, "z:\\System\\Apps\\Chat\\chat.app");
    iStatus = &aStatus;
    CApaCommandLine* cmdLine=CApaCommandLine::NewLC();
    cmdLine->SetLibraryNameL(KAppName);
    cmdLine->SetCommandL(EApaCommandRun);
    RApaLsSession ls;
    TInt result( ls.Connect() );
    if (result == KErrNone)
       {
       ls.StartApp(*cmdLine);
       }

    CleanupStack::PopAndDestroy(); // commandline

    // Return the result to the service user
    User::RequestComplete(iStatus, result);
    }

            
            
            
            
            
            // Implementation of CancelStartApplication 
void CTestPlugin::CancelStartApplication()
     {
     User::RequestComplete(iStatus, KErrCancel);
     }
          
Related APIs
  • CancelStartApplication
  • StartApplicationL

Memory and error handling

Error handling

All basic Symbian platform errors and also API errors cause a leave in the interface code. For example, an out of memory situation causes a leave.

Memory overhead

IM Application Launch API does not consume memory significantly after creating the object. The plug-in is installed in RAM and the memory consumption depends on the implementation.

Glossary

Abbreviations

CSP Client Server Protocol

API

Application Programming Interface

DLL

Dynamic Link Library

ID

Identifier

IM

Instant Message

Definitions

Client application An application, which uses the IM SDK API library. Also called client.

ECom

A generic framework for specifying plug-in interfaces, and for calling and writing plug-ins.

Application ID

Unique identification of the application. e.g. MyMessagingApplicationv2.0

User ID

Identifier of the user defined in the used protocol, e.g. WV user ID – wv: user1@mydomain.com.

Orphan message

WV message of SAP, received when there is no application to handle that message

References

ECom Plug-in Architecture