<?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 id="GUID-FA5782F2-3E30-5EB9-A9E2-843CB9614FD6" xml:lang="en"><title>Licensee
TSY Tutorial </title><shortdesc>This topic describes how to implement a licensee TSY. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<section id="GUID-34A5E710-A1BC-534F-BD8A-FFECCB3845AF"><title>Introduction</title> <p><b>LTSY
functionality</b> </p> <p>The following functionality is implemented by the
device creators in the LTSY. </p> <ul>
<li id="GUID-EF0607D8-9501-5B78-823B-8D0ADF5F396F"><p><xref href="GUID-FA5782F2-3E30-5EB9-A9E2-843CB9614FD6.dita#GUID-FA5782F2-3E30-5EB9-A9E2-843CB9614FD6/GUID-5D167910-A858-52B0-B137-096CD4862CEA">Message Router</xref> </p> </li>
<li id="GUID-A3E2D9C3-6A74-5A00-82F8-E816D4A9591A"><p><xref href="GUID-FA5782F2-3E30-5EB9-A9E2-843CB9614FD6.dita#GUID-FA5782F2-3E30-5EB9-A9E2-843CB9614FD6/GUID-D8518EB6-687A-52E0-AF2A-70FAC33D2E04">Message handler</xref> </p> </li>
<li id="GUID-1B7B1D3A-732D-52ED-9EBD-E6D5E02BD7E7"><p><xref href="GUID-FA5782F2-3E30-5EB9-A9E2-843CB9614FD6.dita#GUID-FA5782F2-3E30-5EB9-A9E2-843CB9614FD6/GUID-56B428BB-5D79-5812-B50B-730CBC0F119B">Utility classes</xref> </p> </li>
<li id="GUID-11AC842E-924E-55D2-B24F-AE4E1F65BBE0"><p><xref href="GUID-FA5782F2-3E30-5EB9-A9E2-843CB9614FD6.dita#GUID-FA5782F2-3E30-5EB9-A9E2-843CB9614FD6/GUID-C728078B-A9FC-5779-91F9-482666203A8C">Baseband sender</xref> </p> </li>
<li id="GUID-16B5676D-4351-5510-81BA-3CF51AF4CDC3"><p><xref href="GUID-FA5782F2-3E30-5EB9-A9E2-843CB9614FD6.dita#GUID-FA5782F2-3E30-5EB9-A9E2-843CB9614FD6/GUID-5E0A2911-7A6A-5BCF-8832-0F8FF8CB76F2">Baseband receiver</xref> </p> </li>
</ul> <title>Message
router</title> <p>The message router routes the telephony client requests
to the appropriate methods implemented by the licensees in the baseband. CTSY
provides the functionality through the <xref href="GUID-70ABA633-AA88-3042-8DB9-78B88BF96D8E.dita"><apiname>CMmMessageRouter</apiname></xref> class.
Licensees should implement this class to acknowledge the CTSY messages. The
message router creates and processes all the message handlers. Each CTSY request
is distinguished by a specific Inter Process Communication (IPC) value. The
IPC number is used to route the calls. When a message router receives a request
from the CTSY, it creates baseband sender and baseband receiver objects. </p> <title>Message handlers</title> <p>The main function of the message handlers is
to group the CTSY requests into logical units. There is no limit on the number
of message handlers. The number of message handlers depends on the logical
grouping of baseband messages, decided by the licensees. The message handlers
implement the <xref href="GUID-B7024C98-B4C4-3FB1-9339-6057CEEF2A3A.dita"><apiname>ExtFuncL()</apiname></xref> entry point. The message handlers
are responsible for handling the CTSY requests and their response from the
baseband. </p> <title>Utility
class</title> <p>The utility class must contain the information that can be
used by the LTSY to adapt baseband data to Symbian platform data format. The
information such as error code mapping is stored in the utility class. </p> <title>Baseband sender</title> <p>The purpose of the baseband sender is to send
messages to the baseband. The messages are created based upon the baseband
and should be able to get the information required to acknowledge the CTSY
requests. </p> <title>Baseband
receiver</title> <p>The main purpose of the baseband receiver is to receive
messages from the baseband and forward them to the CTSY. It is also responsible
for verifying the status of baseband and format of the data. The class must
format the data so that it can be processed by the CTSY. </p> </section>
<section id="GUID-7E1BEBC6-F234-4D09-86AD-12A9CB40B1CD"><title>Procedure</title> <ol id="GUID-27BC9B0E-CC64-5EDC-9F8A-91193E7841BF">
<li id="GUID-E75E6914-C4F2-5511-AD8D-C54C1EC7155C"><p>Phone engine starts
during the device startup </p> </li>
<li id="GUID-0C672679-1ED4-5259-B2BB-4211DC6A77F3"><p>Phone engine creates
the PhoneTSY.dll </p> </li>
<li id="GUID-D79F8569-287E-5D43-94A1-4C6B26403789"><p>PhoneTSY.dll loads the
CommonTSY.dll and the LicenseeTSY.dll </p> </li>
<li id="GUID-1E72A1CD-2D1D-5491-943F-6196ACB5979A"><p>LicenseeTSY.dll connects
with the baseband to verify that it is ready to receive requests from the
TSY </p> </li>
<li id="GUID-3794A4DD-3514-582D-8A56-5033C964BD71"><p>The baseband updates
the status to the LTSY </p> </li>
<li id="GUID-DAE40C5D-A6E8-5FEB-88DC-7044721F73CC"><p>Any change in the baseband
status is notified to the CTSY by the LTSY. </p> </li>
</ol> </section>
<example id="GUID-A0CD6CFD-8727-5A40-B061-0A1D72DA0585"><title>Voice call
example</title> <p>If a client application wants to make a call the following
sequence of events takes place after the TSY is initialised: </p> <ol id="GUID-C2C24A4B-CB22-5C2B-A596-521764D65525">
<li id="GUID-02138921-E7EC-523B-8958-A35A1A5EF321"><p>The client application
sends a request to the telephony server. </p> </li>
<li id="GUID-C6F961EE-76BE-557A-8205-5EA640A6DA46"><p>The server calls the
Dial function through the client side telephony object. </p> </li>
<li id="GUID-501BD4FC-F7E2-5D50-8B6D-85E84BC3BF1A"><p>The dial request is
processed by the CTSY and forwarded to the message manager. </p> </li>
<li id="GUID-0659E831-3F4E-58C7-9D2C-E6FBFC8DD020"><p>The message manager
forwards the request to the message router in LTSY. </p> </li>
<li id="GUID-795EBFE4-D57D-5DD5-96C1-15373985CC67"><p>After getting the information
from the message manager, the message router calls the ExtFunc, and forwards
the request to the baseband. </p> </li>
<li id="GUID-10B0AFF2-BC25-54C6-8F0D-BBA41F3095DE"><p>The baseband should
notify of the status changes and the call details to the LTSY. These details
should be forwarded to the CTSY using the Complete() method. </p> </li>
<li id="GUID-0FE6C4B2-70F0-5989-AC69-2099ED293CD2"><p>The complete method
should return the call details with: </p> <ul>
<li id="GUID-454C0149-12EB-58FF-80D4-FB6F926FA316"><p>a <xref href="GUID-6CA4F1ED-7947-3087-B618-D35858FAA3BC.dita"><apiname>KErrNone</apiname></xref>,
if the call is established successfully. </p> </li>
<li id="GUID-B197FB68-9D3A-589B-86E5-82520625A587"><p>one of the GSM error
code, as specified in the <xref href="GUID-87AB0DA8-E634-5D87-AD89-EFFB1090C9D0.dita#GUID-87AB0DA8-E634-5D87-AD89-EFFB1090C9D0/GUID-B1BDF73C-8C31-5351-936B-CB56239E8B17">reference</xref> section,
if the call establishment is unsuccessful. </p> </li>
</ul> </li>
</ol> </example>
<section id="GUID-7B656AFD-A81A-5A7A-90A2-1F47858FD20C"><p>The events can
be logged and debugged with the <codeph>CommsDebugUtility</codeph>. </p> <p>The
Common TSY uses the <codeph>CommsDebugUtility</codeph> to log the TSY events.
The <codeph>CommsDebugUtility</codeph> can be enabled by adding <b>LOG TSY
CTSY</b> in <i>commsdbg.ini</i> file located at <codeph>c:\logs</codeph>. </p> </section>
<section id="GUID-01C6CDF4-2FC4-4E22-A17C-5C65010EFD2A"><title>Intermediate library </title> <p>This topic describes how
to build and load the licensee TSY. </p> <p><b>System
state manager</b> </p> <p>The system state manager is an ECOM plug-in used
by the CTSY. An alternative to the system state plug-in is available as a
stubbed method in <codeph>ctsy/systemstateplugin</codeph>. </p> <p><b>Licensee TSY intermediate library</b> </p> <p> <filepath>Phonetsy.tsy</filepath> is
the DLL that loads the common TSY and the Licensee TSY. Each device has its
own LTSY. To load the TSYs dynamically: </p> <ul>
<li id="GUID-81F0E187-B1AF-53C8-B2A3-DA1CD58D43F3"><p>The LTSY to be used
in the device is known at ROM build time. </p> </li>
<li id="GUID-F2D37F7B-7715-5DEC-9701-30F797B4D237"><p>There is only one LTSY
per device. </p> </li>
<li id="GUID-D3A5AB0F-483D-5292-9613-69BD6AB326C7"><p>The CTSY must not load
or unload any other TSY at runtime. </p> </li>
</ul> <p>The common TSY does not use the ECOM plug-in, instead it is developed
as a <codeph>IMPLIB</codeph> target type. The <codeph>IMPLIB</codeph> target
will generates a <codeph>licenseetsy.lib</codeph>. The runtime library is
not available. The run time library must be developed and built by the licensees.
The licensees can name and configure the LTSY modules. </p> <p>Licensees should
implement the interface defined by <xref href="GUID-C96C7C6B-547A-3917-AA2A-2831096E8C1C.dita"><apiname>MLtsyFactoryV1</apiname></xref> class
in <codeph>ctsy/licenseetsy_lib/inc/mltsyfactory.h</codeph>. The UID3 value
used in the intermediate library must be the same UID3 used in the LTSY implementation. </p> </section>
</conbody></concept>