LTSY for Dispatcher Tutorial

This topic describes how to implement a Licensee TSY for the Common TSY with the Dispatch layer.

Developers implementing the LTSY can start from the skeleton code at ../ctsydispatcher/ltsyskeleton_using_dispatcher/...

The skeleton is a list of source files with empty implementations. The skeleton is for guidance and the implementation depends on the requirements of the handset manufacturer. The skeleton code contains mock test code for testing purpose. The skeleton code can be conditionally recompiled to remove the calls into the Mock test component, thus allowing the developer to run the existing tests against the actual LTSY implementation they are creating with minimal changes. Check the header file comments for mock test code. The request handlers that must be implemented by the LTSY are declared in mltsydispatchcallcontrolinterface.h.

  1. Start developing the LTSY from the skeleton code

  2. Implement the different interfaces based on functional units. The required interface implementations depend the baseband.

  3. The interfaces are split into different functional units. Implement a call-back function for every asynchronous dispatcher call.

  4. If the methods used to receive the baseband notification use blocking API calls, create a new thread to receive the notification information in the LTSY.

  5. Remove the Symbian test macros

  6. The LTSY must map the baseband error codes to Symbian error codes defined in the header files exterror.h and gsmerror.h.

LTSY example

A sample LTSY implementation to dial a voice call is given below.

Implementing MLtsyDispatchCallControlDialVoice::HandleDialVoiceReqL() interface:

virtual TInt HandleDialVoiceReqL(RMobilePhone::TMobilePhoneALSLine aCallLine,
RMobilePhone::TMobileAddress&amp, aDialledParty, 
RMobileCall::TMobileCallParamsV1&amp, aCallParamsV1, TBool aIsIsvCall, 
RMobileCall::TCallParamOrigin aCallOrigin) = 0;

     * The CTSY Dispatcher shall invoke this function on receiving the EEtelCallDial
     * request from the CTSY for dialling a voice call.
     * It is a request call that is completed by invoking
     * CCtsyDispatcherCallback::CallbackCallControlDialVoiceComp
     * Implementation of this interface should 
     * dial the requested voice call and complete the callback to indicate
     * that an attempt to dial the call has been made.  The callback function is used
     * to indicate the outcome of this attempt to initiate the dialling process.
     * @param aCallLine The line to use to dial the call. This parameter can have
     * one of two possible values RMobilePhone::EAlternateLinePrimary to use the 
     * primary voice line or RMobilePhone::EAlternateLineAuxiliary to use the 
     * auxiliary voice line. 
     * @param aDialledParty Details about the dialled party including the phone
     * number to dial.
     * @param aCallParamsV1 The call parameters of the call to dial. If aIsIsvCall 
     * is set to ETrue, only the field RMobileCall::TMobileCallParamsV1::iIdRestrict 
     * and RMobileCall::TMobileCallParamsV1::iAutoRedial fields are valid.  
     * @param aIsIsvCall Indicates whether the call originated from a third party
     * application which would have used the CTelephony class to dial the call. 
     * This information is provided in case the LTSY wishes to do special handling
     * for third party calls, for example, not allow third party applications to
     * place emergency calls. See also 
     * MLtsyDispatchCallControlQueryIsEmergencyNumber::HandleQueryIsEmergencyNumberSyncL
     * See also: CTelephony::DialNewCall and RMobileCall::DialISV
     * @param aCallOrigin The origin of the dial request.  For example, whether the dial  came from an Etel client or the SIM or another source. 
     * @return KErrNone on success; KErrNotSupported if the LTSY does not  support handling of this request or another error code 
     *indicating the failure otherwise.

Call back function to complete the call dial request:

EXPORT_C void CCtsyDispatcherCallback::CallbackCallControlDialVoiceComp(
    TInt aError, TInt aCallId)

 * Callback function to be used by the Licensee LTSY to complete a pending
 * MLtsyDispatchCallControlDialVoice::HandleDialVoiceReqL
 * When a dial attempt is made via the above mentioned interface, the LTSY has the 
 * responsibility of allocating a unique Call ID to the call.  For more 
 * information, see the documentation on aCallId below.  
 * @param aError The error code to be returned to the CTSY Dispatcher by the LTSY
 * indicating the outcome of the attempt to dial the requested call.  This should
 * be KErrNone if the dialling process could be started successfully.  Otherwise
 * another error code to indicate the failure should be returned.
 * @param aCallId The call ID of the call that the dial attempt refers to which
 * has been allocated by the LTSY.  This should be a number between 1 and 
 * KMaxCallIdValue and should be unique across all call modes (voice, data etc.).  
 * For example, if a request for a voice call is made and the LTSY allocates 
 * this call an ID of 1 and a request for a data call is requested, the LTSY 
 * should allocate a Call ID which is not the same as that already allocated for 
 * the first voice call.

To indicate call status change notifications, use the following callback:

EXPORT_C void CCtsyDispatcherCallback::CallbackCallControlNotifyCallStatusChangeInd(
    TInt aCauseCode, TInt aCallId, RMobileCall::TMobileCallStatus aMobileCallStatus)

 * Used by an LTSY to indicate to the CTSY that there has been a change in the 
 * status of a call. For example, if the CTSY has previously made a dial request 
 * to make a voice call, the LTSY can call this API to notify the CTSY 
 * of progress of the call through the dialling, connecting and connected states.
 * The aCauseCode parameter should be used to indicate the reason for the change 
 * in status of a call.
 * In the case of a call going idle (aMobileCallStatus = RMobileCall::EStatusIdle)
 * specific cause codes need to be returned to the Common TSY to indicate
 * specific causes of status changes:
 * To indicate that an active call has been released normally by either party,
 * set aCauseCode = KErrGsmCCNormalCallClearing.
 * To indicate that a mobile originated call that is being dialled has gone
 * idle because the remote party has rejected the call, set
 * aCauseCode = KErrGsmCCCallRejected or another error code (which is != KErrNone)
 * to indicate the reason for rejection.
 * If a mobile originated call is being dialled and the user cancels dialling,
 * causing the call to go idle, set aCauseCode = KErrGsmCCNormalCallClearing.
 * When an incoming call goes idle because the client has rejected it
 * (done using RCall::HangUp on the ringing call), set
 * aCauseCode = KErrGsmCCUserBusy.
 * @param aCauseCode The cause of the change in call status. 
 * @param aCallId The Call ID of the call whose status has changed.
 * @param aMobileCallStatus The new status of the call refered to by aCallId.
 * @see RMobileCall::NotifyMobileCallStatusChange

Implement other functions supported by the baseband and it is the responsibility of the LTSY to return appropriate error code in the call back function if it fails to establish a call.

Build and run the components.

  1. Unzip code to your target disk for example M:\.

  2. To build the CTSY, in the command prompt window, change directory to M:\ \ctsy\group

  3. This directory should contain a file called “bld.inf”

  4. Type

    bldmake bldfiles

    If there are no errors, the command should give no output and the user is returned to the command prompt.

  5. Build the Mock SY, type

    abld test build winscw udeb

    This builds the CTSY with and without Dispatcher. The build tools are invoked and output scrolls up the screen. There should be no build errors.

    To build the CTSYDispatcher, in the command prompt window, change directory to M:\ \ctsydispatcher\group\

    and repeat the above.

  6. Testing the components

    1. Return to the CTSY directory, build the test components which consists of the LTSY Stub by typing

      abld test build winscw udeb

      This command builds the test components associated with the project for the WINSCW debug target. Output scrolls up the screen and the user will be returned to the command prompt with no errors.

    2. To build the CommonstkTSY, in the command prompt window, change directory to M:\ \commonstkTSY\group and repeat the above command

    3. To build the CTSYDispatcher, in the command prompt window, change directory to M:\ \ctsydispatcher\group\ and repeat the above command

  7. To confirm that the production and test components have been built correctly, look inside the directory containing the WINSCW debug binaries:


    where M:\ is the drive containing the CBR environment), sort the files by most recently modified date first and check that the following binaries have been created

    • customapi.dll – CTSY Custom API (with or without Dispatcher)

    • commontsy.dll – common TSY without Dispatcher.

    • commontsyfordispatcher.dll – common TSY with Dispatcher

    • phonetsy.tsy – phone TSY without Dispatcher

    • phonetsywithdispatcher.tsy – phone TSY with Dispatcher

    • licenseetsy.dll – licensee TSY for testing common TSY without Dispatcher

    • licenseeskeletontsy.dll – licensee TSY for test common TSY with Dispatcher

  8. Running the tests application

    1. Edit the file M:\epoc32\data\epoc.ini with a text editor and add the following line

      startupmode 1
    2. Enable logging of the CTSY and the LTSY Stub by copying the file

      commsdbg.ini to M:\epoc32\winscw\c\logs
    3. run the test framework