<?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-785701A4-615B-5590-91C6-FD29C56FB2E7"><title>Alternative Encoders Tutorial </title><shortdesc>This tutorial describes how to use the alternative character encoders. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody><section id="GUID-84759DE2-9116-5ABB-9795-6F9623AC9FCA"><title>Introduction</title> <p>Alternative Encoders support many Latin-based Eastern European characters. Default 7 bit encoders do not support Latin-based characters. The characters must be encoded using 16-bit Unicode. The use of Unicode limits the users to 70 characters in a single message. The Alternative Encoders supports the use a lossy conversion and can change the Eastern European characters to the nearest Global System for Mobile communication (GSM) character. The character converters are plug-ins to the SMS stack. The Alternative Encoders are optional and can be included in the ROM build time. </p> <p>When the user writes an SMS message data the SMS stack checks the characters and finds the encoders available. If installed, the SMS stack uses the Alternative Encoder. If the Alternative Encoders are not installed the default encoder available is used. The 7-bit default converter converts the unsupported characters to '?' and the alternative encoders changes them to closest GSM supported character. </p> <p>The client applications can call the <xref href="GUID-FA6D9B1B-3845-3B81-ACBB-34977D3C9631.dita#GUID-FA6D9B1B-3845-3B81-ACBB-34977D3C9631/GUID-E00A6DE9-38CA-37D7-B2F4-316A2489366F"><apiname>CSmsMessage::IsSupportedL()</apiname></xref> function to see if a particular character is supported by the device. The client applications can use the alternative encoders using the following APIs: </p> </section> <section><title>Character support</title> <p>The client applications can check if a character is supported by calling <xref href="GUID-BF70A971-E569-3871-9137-D760EB9F4EF0.dita#GUID-BF70A971-E569-3871-9137-D760EB9F4EF0/GUID-B0812202-D38F-3361-A020-11543EED240B"><apiname>CSmsAlphabetConverter::IsSupportedL(TChar aChar, TBool&amp;

          aIsDowngrade, TBool&amp; aRequiresAlternativeEncoding)</apiname></xref> and <xref href="GUID-286C83B6-A079-33FF-9FA7-A718A2F7C370.dita#GUID-286C83B6-A079-33FF-9FA7-A718A2F7C370/GUID-BD57A86A-CD20-3EE2-A94B-8C8152992011"><apiname>CSmsUserData::IsSupportedL(TChar aChar TBool&amp; aIsDowngrade,

          TBool&amp; aRequiresAlternativeEncoding)</apiname></xref>. These methods return the number of characters must be down-graded and if an alternative encoding is required to support the character. </p> </section> <section><title>Encoder information</title> <p>The clients uses the <xref href="GUID-FA6D9B1B-3845-3B81-ACBB-34977D3C9631.dita#GUID-FA6D9B1B-3845-3B81-ACBB-34977D3C9631/GUID-446EA6C8-A790-3F35-9AEB-2973D4714DA2"><apiname>CSmsMessage::GetEncodingInfoL()</apiname></xref> method to find the character support in the selected encoder. The function returns the following : </p> <ul><li id="GUID-CE4DCA9F-6D60-5214-8DB7-228CA1C5BC12"><p>the number of PDUs required </p> </li> <li id="GUID-B257739D-6192-59B1-9223-88A5B6322923"><p>the number of free characters in user data of previous PDUs </p> </li> <li id="GUID-6D8F8BFE-0FAF-598E-B73A-44280417D4F7"><p>the number of characters that are not changed </p> </li> </ul> <p>The clients can use these parameter values to determine the encoder to be used for the given message. </p> </section> <section><title>Procedure</title> <ol id="GUID-182B4F17-1701-5577-8777-EFC054623E22"><li id="GUID-30B4F957-737B-5000-AA01-1B9F9F89CB69"><p>Set alternative encoding </p> <p>The clients uses the <xref href="GUID-FA6D9B1B-3845-3B81-ACBB-34977D3C9631.dita#GUID-FA6D9B1B-3845-3B81-ACBB-34977D3C9631/GUID-DDC15164-4AD0-3681-BBD8-228CF3DC1A17"><apiname>CSmsMessage::SetAlternative7bitEncoding(TSmsEncoding

                aEncoding)</apiname></xref> method to request the SMS stack to use alternative encoding. The client uses the aEncoding parameter to specify the required encoding method. The encoding can be one of the following: </p> <ol id="GUID-81D86D89-88EB-5CD8-A53C-82DD372A5CD0"><li id="GUID-363DE0EB-4D1C-583E-B11A-8C47D06CD543"><p>single shift </p> </li> <li id="GUID-38C96EBE-6F9D-57BE-AD11-E3C51F306B28"><p>locking shift </p> </li> <li id="GUID-5E8E44B9-25AE-50C4-94D9-B77692BF2AF8"><p>locking and single shift </p> </li> </ol> <p>If more than one Alternative Encoder is selected by the client the SMS stack uses the encoder that converts most characters in the message. If the requested encoder is not available, the function returns <codeph>KErrNotSupported</codeph>. </p> </li> <li id="GUID-AF3AE441-3470-5ABE-805D-5A6EB979B2F2"><p>Get alternative encoder information </p> <p>The client uses the <xref href="GUID-FA6D9B1B-3845-3B81-ACBB-34977D3C9631.dita#GUID-FA6D9B1B-3845-3B81-ACBB-34977D3C9631/GUID-5A7F7417-B499-346E-84C8-E65AA4763DAB"><apiname>CSmsMessage::GetAlternative7bitEncoding()</apiname></xref> method to query the encoders supported by the SMS stack. </p> </li> <li id="GUID-4A3FEBC8-BE86-5E83-A430-2E1ED32075AD"><p>Turkish character support </p> <p>The clients uses the <xref href="GUID-FA6D9B1B-3845-3B81-ACBB-34977D3C9631.dita#GUID-FA6D9B1B-3845-3B81-ACBB-34977D3C9631/GUID-65D8DC9C-225A-39C5-8148-646D3810BA3F"><apiname>CSmsMessage::SetAlternative7bitEncoding()</apiname></xref> method to specify the required encoding method. </p> <p>Most of the Turkish characters require Alternative Encoders for the SMS stack to encode the message without the loss of information from the message. There are three types of encoders available to support the Turkish characters: </p> <ol id="GUID-E664F5B6-26CB-5427-90DA-EAD5B6756499"><li id="GUID-C356EA0D-D8D7-50B0-8FE3-1841DE9EAE23"><p>Single shift </p> </li> <li id="GUID-9ED83E82-97A0-5FC8-8B0A-A101BA2B5607"><p>Locking shift </p> </li> <li id="GUID-48C026D7-4483-5802-94F1-60A53C3C57E4"><p>Locking and Single shift </p> </li> </ol> </li> </ol> </section> <section><title>Supported encoders</title> <p>The table describes the supported encoders. These encoders are optional and can be excluded at ROM build time. The <xref href="GUID-FA6D9B1B-3845-3B81-ACBB-34977D3C9631.dita#GUID-FA6D9B1B-3845-3B81-ACBB-34977D3C9631/GUID-BD5E021B-9331-3D14-9E44-AD7B216AEE58"><apiname>CSmsMessage::IsSupported()</apiname></xref> method is used to determine if an encoder is available for the client applications. </p> <table id="GUID-ED01AF8F-9EF1-50A8-94A6-AF0BC1FAB0E4"><tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/><thead><row><entry>Enumeration for encoder</entry> <entry>Description</entry> </row> </thead> <tbody><row><entry><p> <xref href="GUID-4CBF851F-B589-336C-85A4-50D86EC98A4A.dita"><apiname>ESmsEncodingNone</apiname></xref>  </p> </entry> <entry><p>This is the default value which means Alternative Encoding is not used. The Eastern European characters being downgraded to the non-diacritic characters option is enabled automatically. The messages are encoded in 7-bit with acceptable representation to the receiving user. </p> </entry> </row> <row><entry><p> <xref href="GUID-EF940266-FC53-3EAD-BA16-88ABE4336DAD.dita"><apiname>ESmsEncodingTurkishSingleShift</apiname></xref>  </p> </entry> <entry><p>This allows the use of the Turkish Single Shift table instead of the default GSM shift table. If this is used during encoding there is a 3-octet cost in the user data. </p> </entry> </row> <row><entry><p> <xref href="GUID-2F959B05-FB40-3F5A-9864-123F9C9C8AFB.dita"><apiname>ESmsEncodingTurkishLockingShift</apiname></xref>  </p> </entry> <entry><p>This allows the use of the Turkish Locking Shift table instead of the default GSM alphabet table. If this is used during encoding there is a 3-octet cost in the user data. This encoding is used only if the relevant national regulatory body has requested its use. </p> </entry> </row> <row><entry><p> <xref href="GUID-D7821410-0585-31DA-BF2E-16FAE2AF996B.dita"><apiname>ESmsEncodingTurkishLockingAndSingleShift</apiname></xref>  </p> </entry> <entry><p>This allows the use of the Turkish Locking Shift and/or the Turkish Single Single Shift tables instead of the default GSM alphabet and shift tables. If this is used during encoding there is a 3- or 6-octet cost in the user data. This encoding is used only if the relevant national regulatory body has requested its use. </p> </entry> </row> <row><entry><p> <xref href="GUID-67910E48-971A-3E05-AF1F-5A6D1FDFBBFC.dita"><apiname>ESmsEncodingSpanishSingleShift</apiname></xref>  </p> </entry> <entry><p>This allows the use of the Spanish Single Shift table instead of the default GSM shift table. If this is used during encoding there is a 3-octet cost in the user data. </p> </entry> </row> <row><entry><p> <xref href="GUID-CBB8AA45-1ACD-3502-A430-CA6543EAE942.dita"><apiname>ESmsEncodingPortugueseSingleShift</apiname></xref>  </p> </entry> <entry><p>This allows the use of the Portuguese Single Shift table instead of the default GSM shift table. If this is used during encoding there is a 3-octet cost in the user data. </p> </entry> </row> <row><entry><p> <xref href="GUID-5EE9148F-F1A5-3EAD-9F91-C0B00E4B1502.dita"><apiname>ESmsEncodingPortugueseLockingShift</apiname></xref>  </p> </entry> <entry><p>This allows the use of the Portuguese Locking Shift table instead of the default GSM alphabet table. If this is used during encoding there is a 3-octet cost in the user data. This encoding is used only if the relevant Portuguese regulatory body has requested its use. </p> </entry> </row> <row><entry><p> <xref href="GUID-6746B0E3-B8AC-34D4-8D0B-43F2EA8D7734.dita"><apiname>ESmsEncodingPortugueseLockingAndSingleShift</apiname></xref>  </p> </entry> <entry><p>This allows the use of the Portuguese Locking Shift and/or the Portuguese Single Shift tables instead of the default GSM alphabet and shift tables. If this is used during encoding there is a 3- or 6- octet cost in the user data. This encoding is used only if the relevant Portuguese regulatory body has requested its use. </p> </entry> </row> </tbody> </tgroup> </table> </section> </conbody></concept>