<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept xml:lang="en" id="GUID-B89575A8-5F36-59FA-9FA3-48E2985E54C9"><title>Dispatch Layer</title><shortdesc>This topic describes the dispatch layer of the Common TSY. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody><p>The dispatch layer is a shim between the Common TSY and the Licensee TSY. The dispatch layer is implemented by the library <codeph>ctsydispatcher.dll</codeph>. </p> <p>The dispatch layer provides: </p> <ul><li id="GUID-D5446064-895F-5348-B1F4-DEE76FC69155"><p>An interface based on the functional units of the common TSY. </p> </li> <li id="GUID-AE93688F-11BD-5E3D-969F-693364276329"><p>Packing and unpacking of the messages between the Common TSY and the Licensee TSY </p> </li> <li id="GUID-8A475921-152F-5EC5-97A6-20CEC26F8C60"><p>Simple input and output parameters for the Licensee TSY </p> </li> <li id="GUID-8F99EF64-16A1-5BFC-8CA3-145DF45222C7"><p>Call-back functions for the Licensee TSY to send the updates and status messages to the Common TSY. </p> </li> </ul> <section><title>Message Manager </title> <p>The messages from the CTSY are passed to the dispatch layer by the <xref href="GUID-5C84AC6D-36A5-3439-990A-CD781990755F.dita"><apiname>CMmMessageManagerBase</apiname></xref> functions. </p> </section> <section><title>Message Router</title> <p>The message router receives the request messages from the CTSY and forwards them to the appropriate dispatcher. The dispatch layer contains many dispatcher classes based on the functional units. </p> </section> <section id="GUID-162746DD-E2E2-548F-8026-5C4281BF0CC5"><title>Dispatcher Classes</title> <p>The Common TSY with the dispatch layer decreases the time to develop a Licensee TSY. The dispatch layer contains the <xref href="GUID-A833178C-8682-3BE0-B8E2-704D38B43260.dita"><apiname>CMessageRouter</apiname></xref> and provides the factory class <xref href="GUID-C174E22A-FDDE-3221-96F8-7D4857685765.dita"><apiname>CLtsyFactoryV1</apiname></xref>. The dispatch layer also contains the dispatchers. </p> <p>The main role of the dispatcher is to handle the messages between the message router and the LTSY. The factory class is responsible for creating the required handlers. The dispatcher is responsible for packing the call-back messages from the LTSY and unpacking the messages from the message router for passage to the LTSY. There is a dispatcher class for each functional unit such as SMS, Phone or Cell Broadcast. The following table describes the dispatcher class for each functional unit: </p> <table id="GUID-F56DA6FA-4BC0-5D20-959F-D2EED10DD437"><tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/><thead><row><entry>Functional Unit</entry> <entry>Dispatcher class name</entry> </row> </thead> <tbody><row><entry><p>Call Control </p> </entry> <entry><p> <xref href="GUID-F8259252-D4AA-3CDD-A5BA-A989CE2D0DED.dita"><apiname>CCallControlDispatcher</apiname></xref>  </p> </entry> </row> <row><entry><p>Phone </p> </entry> <entry><p> <xref href="GUID-1A334DF3-7F9F-3AA0-A9B0-1BD8FDDAB266.dita"><apiname>CPhoneDispatcher</apiname></xref>  </p> </entry> </row> <row><entry><p>Security </p> </entry> <entry><p> <xref href="GUID-F749FCEE-5329-3153-B098-E72169A11E9E.dita"><apiname>CSecurityDispatcher</apiname></xref>  </p> </entry> </row> <row><entry><p>Cell Broadcast </p> </entry> <entry><p> <xref href="GUID-CBB02AC5-7B2B-35F6-BA63-E7FD5817043E.dita"><apiname>CCellBroadcastDispatcher</apiname></xref>  </p> </entry> </row> <row><entry><p>Own Number Phonebook Store </p> </entry> <entry><p> <xref href="GUID-BDADFE44-05BB-39A2-88B4-5D25D7292D6A.dita"><apiname>CPhonebookOnDispatcher</apiname></xref>  </p> </entry> </row> <row><entry><p>Phonebook store </p> </entry> <entry><p> <xref href="GUID-91FEED1E-4427-373E-906E-B821793793E9.dita"><apiname>CPhonebookDispatcher</apiname></xref>  </p> </entry> </row> <row><entry><p>Emergency Number Phonebook Store </p> </entry> <entry><p> <xref href="GUID-CDB57F73-06A5-308E-B575-E54DA042A648.dita"><apiname>CPhonebookEnDispatcher</apiname></xref>  </p> </entry> </row> <row><entry><p>SIM </p> </entry> <entry><p> <xref href="GUID-E0B6CFCC-7698-300A-8B47-71A41E73F764.dita"><apiname>CSimDispatcher</apiname></xref>  </p> </entry> </row> <row><entry><p>SMS </p> </entry> <entry><p> <xref href="GUID-CC30E7AD-B999-36BE-B34A-656796E35981.dita"><apiname>CSmsDispatcher</apiname></xref>  </p> </entry> </row> <row><entry><p>Multiparty Call </p> </entry> <entry><p> <xref href="GUID-DC362538-01D4-3C04-9078-190878B155A5.dita"><apiname>CCallControlMultipartyDispatcher</apiname></xref>  </p> </entry> </row> <row><entry><p>Supplementary Services </p> </entry> <entry><p> <xref href="GUID-110285FA-074E-37AF-961E-3E398313ADF2.dita"><apiname>CSupplementaryServicesDispatcher</apiname></xref>  </p> </entry> </row> <row><entry><p>Packet Data Services </p> </entry> <entry><p> <xref href="GUID-A92D9B8B-9CE5-3A2F-AF3E-F47257D3D68A.dita"><apiname>CPacketServicesDispatcher</apiname></xref>  </p> </entry> </row> <row><entry><p>SIM Application Toolkit </p> </entry> <entry><p> <xref href="GUID-FE2C28F2-7F09-3F9A-A8B8-887B66408D74.dita"><apiname>CSatDispatcher</apiname></xref>  </p> </entry> </row> </tbody> </tgroup> </table> <fig id="GUID-19D474AD-4B7B-5160-AA33-3EDD37D73C1B"><title>

             Example Sequence flow between the CTSY Dispatcher and LTSY 

          </title> <image href="GUID-BCD83E02-9645-530C-8BD9-CCA1B8756842_d0e54222_href.png" placement="inline"/></fig> <p> <xref href="GUID-E6BE8260-066E-3E95-856A-7CE50D955E71.dita"><apiname>CCtsyDispatcherCallback</apiname></xref> class provides the methods to the LTSY to send the status and service complete messages to the CTSY. </p> </section> <section><title>CTSY Requests</title> <ol id="GUID-68B4FB4D-7206-5117-ADF0-E8DAF841B421"><li id="GUID-F7BBA32A-A15D-5F27-9640-9367C425CADA"><p>The dispatch layer provides the interface between the CTSY and LTSY. </p> </li> <li id="GUID-C38905CD-9823-54C4-AD09-40943E951568"><p>The telephony client requests the services from the telephony server. </p> <p>The telephony applications request the telephony services like request for a voice call, data call or a fax call. </p> </li> <li id="GUID-768ECE92-7F5A-5A58-AF97-BB1D45FB1C88"><p>The telephony server sends the request to the CTSY. </p> </li> <li id="GUID-8AF0F109-51A2-5781-9A6A-8663FBDE76B2"><p>The CTSY sends the requests to the dispatch layer. </p> </li> <li id="GUID-A4A5ACBD-AE49-5293-AAC4-B07052EFF067"><p>The dispatch layer unpacks the request message and calls the methods in the LTSY to service the telephony client request. </p> </li> </ol> <p>The LTSY must implement the interfaces of the dispatch layer to accept the client requests. The implementation depends on the baseband design. If a telephony client request is not available or not implemented in the device <xref href="GUID-F89DA3F0-2A48-3F9B-8F08-29350E92D0E4.dita"><apiname>KErrNotSupported</apiname></xref> or a similar error is returned to the clients. </p> <p>The functions calls to the LTSY have a standard convention: </p> <codeblock id="GUID-6A379B2B-D4D1-5828-BE9C-3164BFF09A52" xml:space="preserve">TInt Handle&lt;FuncDesc&gt;&lt;Type&gt;(&lt;arg list&gt;); </codeblock> <ul><li id="GUID-4C4BC6B3-CC3E-5810-B2D0-DF39A6381807"><p> <xref href="GUID-7A2A43EC-6125-3BFE-834B-23C37F7B40D5.dita"><apiname>TInt</apiname></xref> is the return code </p> </li> <li id="GUID-90C415B6-4094-593F-9CFD-B45CF72C9A76"><p> <codeph>FuncDec</codeph> describes the function call </p> </li> <li id="GUID-D6FD8D94-E9B0-5493-AF10-4C6FA5B79AFB"><p> <codeph>Type</codeph> is <b>Sync</b> for synchronous calls or <b>Req</b> for asynchronous request messages. </p> </li> </ul> </section> <section><title>Call-back Functions</title> <p>The <xref href="GUID-E6BE8260-066E-3E95-856A-7CE50D955E71.dita"><apiname>CCtsyDispatcherCallback</apiname></xref> class functions provide the interface for the LTSY to communicate with the dispatch layer. A pointer to this instance is passed to the LTSY. All <codeph>Req</codeph> type calls from the dispatch layer must be accompanied by a call-back function call. The call-back functions are called by the LTSY to notify completion of a request or to update a status. The dispatch layer packs the request messages with the data. The data contains the request command parameters from the telephony server client. An example of a request command is to dial a number. </p> <p>The call-back functions have a standard name convention: </p> <codeblock id="GUID-DF7213F5-C6F0-56F1-9BFC-1EFD9A2C86CA" xml:space="preserve">void Callback&lt;FuncDesc&gt;&lt;Type&gt;(&lt;arg list&gt;); </codeblock> <ul><li id="GUID-95B95C7D-D575-592C-81F5-7B08D06809F7"><p> <codeph>FuncDesc</codeph> is the description of the call-back function such as <codeph>GetHomeNetwork</codeph>. </p> </li> <li id="GUID-37EB2A20-1003-5D27-AEB2-96F234FDC6B7"><p> <codeph>Type</codeph> is either <b>Comp</b> or <b>Ind</b>. <codeph/>  </p> <p> <codeph>Comp</codeph> is used in the call-back functions that notify a request is complete. <codeph>Ind</codeph> is used in the call-back functions that notify events to the CTSY. The call-back function with <codeph>IND</codeph> prefix are unsolicited. </p> </li> </ul> </section> </conbody></concept>