<?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-A957A1DF-AF81-5A9D-BB44-1B34B2EB809E" xml:lang="en"><title>GSM

Utilities</title><shortdesc>This section describes the GSM utility classes and the functionality

they provide in the SMS stack. . </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>The GSM utility (GSMU) class provides the functionality specified in the

3GPP standards <xref href="&#34;http://www.3gpp.org/ftp/Specs/html-info/23038.htm&#34;.dita">23.038</xref> and<xref href="&#34;http://www.3gpp.org/ftp/Specs/html-info/23040.htm&#34;.dita">23.040</xref>. </p>

<section><title>Specialised SMS classes</title> <p>The GSMU provides a specialised

SMS class called <xref href="GUID-CCF026F3-BB2F-383B-B15D-C73EC7DD81B3.dita"><apiname>TGsmuLex8</apiname></xref>. <xref href="GUID-757CA2F5-4FEF-3E7E-BD2F-3D3F87204A3C.dita"><apiname>TGsmulex8</apiname></xref> provides

methods to decode the PDU data. </p> </section>

<section><title>PDU element classes</title> <p>The following classes provide

utility methods to encode and decode different elements of a PDU. </p> <table id="GUID-EE9BC649-3752-5BBD-88B8-D6E3C4B40CDC">

<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>

<thead>

<row>

<entry>GSMU Class</entry>

<entry>Functionality </entry>

</row>

</thead>

<tbody>

<row>

<entry><p> <xref href="GUID-BBF068E3-8DFA-3FD4-B24C-E71E781E0F33.dita"><apiname>TSmsOctet</apiname></xref>  </p> </entry>

<entry><p>Provides methods to encode and decode the octets of a PDU </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-BF70A971-E569-3871-9137-D760EB9F4EF0.dita"><apiname>CSmsAlphabetConverter</apiname></xref>  </p> </entry>

<entry><p>Provides methods for character conversion between native type and

user defined type. This class provides the functionality to compliment <xref href="GUID-F77B4E1E-66E6-327F-BCE2-3AEDC51BB430.dita"><apiname>CSmsBufferSegmenter</apiname></xref>, <xref href="GUID-A168BD0C-03AC-3342-B1FE-05969E05DEA8.dita"><apiname>TSmsBufferReassembler</apiname></xref> and <xref href="GUID-A6141B70-D1C0-3DFE-AE2A-BE096F81FC67.dita"><apiname>TSmsAlphabetPacker</apiname></xref>. </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-B21EB26E-6CE5-3020-9A68-8BB4F18B4704.dita"><apiname>CSmsmAddress</apiname></xref>  </p> </entry>

<entry><p>Provides methods to represent the recipient device or the service

centre address. </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-53D31C79-A867-3D52-897B-AC8AD0934F8C.dita"><apiname>TGsmSmsTypeOfAddress</apiname></xref>  </p> </entry>

<entry><p>Provides methods to specify the type of address used. The type of

address includes the details of the numbering plan indicator and the type

of numbering used. </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-2C2DD096-D132-3B40-86CE-FDE1FE268313.dita"><apiname>TGsmSmsTelNumber</apiname></xref>  </p> </entry>

<entry><p>Provides methods to encapsulate basic address information like source

device address, destination address and the service centre address in a SMS

message. </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-7E31BDC4-24DF-3D35-9FB2-77AAC1AE40E8.dita"><apiname>TSmsServiceCenterTimeStamp</apiname></xref>  </p> </entry>

<entry><p>Provides methods to get and set the service centre time stamp in

a SMS message. </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-BCC14F20-C78D-3A16-8890-FAD22F261450.dita"><apiname>TSmsValidityPeriod</apiname></xref>  </p> </entry>

<entry><p>Provides methods to get and set the validity period in a PDU. </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-B0511E77-85EC-3646-9081-834ACC42B7B7.dita"><apiname>TSmsStatus</apiname></xref>  </p> </entry>

<entry><p>Provides methods to get and set the SMS status in the <codeph>STATUS

REPORT</codeph> PDU. </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-41AEFEFA-1F94-3AC9-91C1-9BA4FD2D9FFB.dita"><apiname>TSmsParameterIndicator</apiname></xref>  </p> </entry>

<entry><p>Provides methods to get and set flags in the reports and <codeph>COMMAND</codeph> PDUs.

The flags represent extension, user data, data coding scheme and protocol

identifier. </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-E9006834-1964-3F62-BB79-551888274C1E.dita"><apiname>TSmsProtocolIdentifier</apiname></xref>  </p> </entry>

<entry><p>Provides methods to get and set the protocol identifier. </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-3503C5E1-1940-31EF-A401-4397D04544F3.dita"><apiname>TSmsCommandType</apiname></xref>  </p> </entry>

<entry><p>Provides methods to get and set the type of commands in a <codeph>COMMAND</codeph> PDU. </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-C12D3DFA-773F-3A08-B477-FE9420DB6DE7.dita"><apiname>CSmsuserData</apiname></xref>  </p> </entry>

<entry><p>Provides methods to get and set user data elements from a PDU. </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-1719BD77-DFB0-3E64-A2F1-8B5B4E0B8C2A.dita"><apiname>CSmsCommandData</apiname></xref>  </p> </entry>

<entry><p>Provides methods to get and set various information elements from

a SMS command message. </p> </entry>

</row>

</tbody>

</tgroup>

</table> </section>

<section><title>PDU classes</title> <p>The following classes provide methods

to create and process the six types of messages <codeph>DELIVER, SUBMIT, DELIVER

REPORT, SUBMIT REPORT, STATUS           REPORT</codeph> and <codeph>COMMAND</codeph>. </p> <table id="GUID-9AFF41C0-C11D-5F4B-8E7F-637004AE983C">

<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>

<thead>

<row>

<entry>class</entry>

<entry>Functionality</entry>

</row>

</thead>

<tbody>

<row>

<entry><p> <xref href="GUID-7E49F0BC-75C7-3D65-9628-55572FD7005C.dita"><apiname>CSmsPDU</apiname></xref>  </p> </entry>

<entry><p>Provides generic interface to encode and decode all six types of

PDUs. <xref href="GUID-7E49F0BC-75C7-3D65-9628-55572FD7005C.dita"><apiname>CSmsPDU</apiname></xref> provides the common functionalities to encode

and decode different types of PDUs. For more information about the methods

provided by this class see the reference documentation. </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-A2DFAA2C-990B-3220-91AC-62963BD3759A.dita"><apiname>CSmsDeliver</apiname></xref>  </p> </entry>

<entry><p>Provides the methods to create a <codeph>DELIVER</codeph> PDU. </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-7C2F135A-9204-38F2-85C0-BBA1708096EA.dita"><apiname>CSmsSubmit</apiname></xref>  </p> </entry>

<entry><p>Provides methods to create a <codeph>SUBMIT</codeph> PDU. </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-45AC53BB-8671-3FAE-B217-8E4085DC8598.dita"><apiname>CSmsDeliverReport</apiname></xref>  </p> </entry>

<entry><p>Provides methods to create a <codeph>DELIVER REPORT</codeph> PDU.

A DELIVER REPORT message is created to acknowledge a received SMS. </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-05BDF012-354E-3513-8BB0-88D044B78901.dita"><apiname>CSmsSubmitReport</apiname></xref>  </p> </entry>

<entry><p>Provides methods to process a SUBMIT REPORT message sent by the

network in response to a submit message. The SUBMIT REPORT contains the result

of the SUBMIT message like if the message was submitted successfully, if not

the reason for the failure. </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-60DCC747-1ACE-305E-A4BA-F07C33A6B6CF.dita"><apiname>CSmsStatusReport</apiname></xref>  </p> </entry>

<entry><p>Provides the methods to process the STATUS REPORT message sent by

the network. The message contains the details of the status of a previously

sent SUBMIT message. </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-AC19C0ED-1D6C-3A8D-995B-AC6965EF8A4B.dita"><apiname>CSmsCommand</apiname></xref>  </p> </entry>

<entry><p>Provides methods to create a COMMAND message. This message is mobile

originated and sent to the network requesting some action like status of sent

message. </p> </entry>

</row>

</tbody>

</tgroup>

</table> </section>

<section><title>Buffer classes</title> <p>The GSMU provides the utility classes

to store the SMS messages before segmentation and concatenation. <xref href="GUID-E6CDD68C-EBCF-3EEF-A17C-EF475B9868B7.dita"><apiname>CSmsBufferBase</apiname></xref> is

the base class to create the buffer space in the memory. <xref href="GUID-6798011A-29D7-35AC-938E-B6E7E32CE539.dita"><apiname>CSmsBuffer</apiname></xref> is

used to store an array of <xref href="GUID-317497AE-D70D-3FD5-9865-6446FF4AD035.dita"><apiname>TText</apiname></xref> in the memory. <xref href="GUID-0251B613-62C9-3C81-9E98-60C9ED3606AD.dita"><apiname>CSmsEditorBuffer</apiname></xref> class

is used by the messaging server to store the text in <xref href="GUID-39945DA4-B362-3DF6-BF9E-DD079EEA7934.dita"><apiname>CRichText</apiname></xref> type. </p> </section>

<section><title>User data settings</title> <p> <xref href="GUID-C1615364-719B-3BE2-93D2-562631EDCDAE.dita"><apiname>TSmsUserDataSettings</apiname></xref> class

is used to encapsulate the settings such as character concatenation. The stored

settings affect the encoding and decoding of the messages. </p> </section>

<section><title>CSmsMessage</title> <p> <xref href="GUID-FA6D9B1B-3845-3B81-ACBB-34977D3C9631.dita"><apiname>CSmsMessage</apiname></xref> class

is used to represent a complete message inside the SMS stack before segmentation

and a complete message after reassembly. If the message type is class 0, incomplete

messages are also stored by the <xref href="GUID-D7F28F6D-6D94-315D-A16C-25D54F80839F.dita"><apiname>CSmsMesasge</apiname></xref>. The complete

message is stored in the <xref href="GUID-6798011A-29D7-35AC-938E-B6E7E32CE539.dita"><apiname>CSmsBuffer</apiname></xref>. The main function

of the <xref href="GUID-FA6D9B1B-3845-3B81-ACBB-34977D3C9631.dita"><apiname>CSmsMessage</apiname></xref> is to store the information in a SMS

and to encode and decode the message into different PDUs. The text in a message

is accessed using <xref href="GUID-75FADA5A-569F-3654-902D-6E19BC906B50.dita"><apiname>Buffer()</apiname></xref> method. The <xref href="GUID-FA6D9B1B-3845-3B81-ACBB-34977D3C9631.dita"><apiname>CSmsMessage</apiname></xref> also

supports decoding of partial complete Class 0 SMS. </p> <p>The CSmsMesasge

class supports the following functionality: </p> <ul>

<li id="GUID-077254B3-67CD-56BC-923C-3E81F97273A4"><p>To add hyperlink in

a SMS message using <xref href="GUID-C57FBD33-73BA-3745-A7A3-BE806E0EFB64.dita"><apiname>CSmsHyperlinkOperations</apiname></xref>  </p> </li>

<li id="GUID-FD2DB455-1F53-5946-8C10-21BF4C18ED56"><p>To get and set the reply

address path using <xref href="GUID-09486F51-9ABE-3E8B-8A88-101ECE33FB3E.dita"><apiname>CSmsReplyAddressOperations</apiname></xref>  </p> </li>

<li id="GUID-E23CB9C2-D3C2-55BA-8751-DAB1DF48B2E3"><p>To get, set and remove

special message indicators using <xref href="GUID-7DCE58D9-C3E5-35A5-88BC-235869F36B39.dita"><apiname>CSmsSpecialMessageOperations</apiname></xref>  </p> </li>

<li id="GUID-95DC2E4B-58B8-55AB-824C-D97F2CEE0C6E"><p>To support the voice

mail notifications. </p> </li>

<li id="GUID-2E9C2992-CEEC-56BB-B249-BBE9EDF86370"><p> <xref href="GUID-54179AA6-3B34-3965-8CBC-3BA07E9A1C55.dita"><apiname>CSmsSMSCCtrlParameterOperations</apiname></xref> class

provide the clients with methods to manipulate Short Message Service Centre

(SMSC) control information elements. class </p> </li>

<li id="GUID-F9086B00-F6D9-539E-BB8D-9F84B0991E4D"><p>To support segmentation

and reassembly in the SMS stack. </p> </li>

<li id="GUID-BBDA5B06-9EC4-5A8C-B03D-5359B9799E9A"><p>To pack and unpack data

from the SMS messages. </p> </li>

</ul> <p>The GSMU also provides the segmentation and reassembly

store described in <xref href="GUID-B5BA3CB6-F2B8-524B-BF99-545AAE81549A.dita">SMS

Stack Message Stores</xref>. </p> </section>