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

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

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

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

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

     6 <!-- Initial Contributors:

     7     Nokia Corporation - initial contribution.

     8 Contributors: 

     9 -->

    10 <!DOCTYPE concept

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

    12 <concept id="GUID-6501FAFF-6E21-5BC8-BA85-B1B4CE1AC6A7" xml:lang="en"><title>Phone

    13 number utility overview</title><prolog><metadata><keywords/></metadata></prolog><conbody>

    14 <section id="GUID-648FA965-ED6E-432E-BE02-0AD632DA2630"><title>Purpose</title> <p>The

    15 Phone Number Utility is part of the Symbian Text Utility Component (<codeph>etul.dll</codeph>)

    16 and it offers methods for parsing and validating phone numbers. </p> <p>Examples

    17 of valid phone numbers: </p> <ul>

    18 <li id="GUID-C6D1DCE8-CC29-5C1D-840F-E22390F3F878"><p>1. +358501234567 </p> </li>

    19 <li id="GUID-912697C8-0BFF-57BA-9B08-7D760F4E4F6F"><p>2. +358 (50) 123 4567 </p> </li>

    20 </ul> <p>Even though both of the above examples are valid phone numbers, only

    21 the first one is accepted as a phone number by many systems. To convert the

    22 second number to the first number, parsing methods of Phone Number Utility

    23 can be used. </p> </section>

    24 <section id="GUID-CB2CAEEF-131E-48F2-A53E-3716C386E7C8"><title>Architectural

    25 Relationships</title> <p>The <xref href="GUID-2ABFC65A-FA52-36AB-8910-99D3A10A2D66.dita"><apiname>TulPhoneNumberUtils</apiname></xref> class

    26 implements the static methods that make up the interface. </p> <p>Phone Number

    27 Utility can be accessed through the <xref href="GUID-2ABFC65A-FA52-36AB-8910-99D3A10A2D66.dita"><apiname>TulPhoneNumberUtils</apiname></xref> class

    28 that is defined in the header <codeph>tulphonenumberutils.h</codeph>. This

    29 utility is linked to the <codeph>etul.lib</codeph> library. </p> </section>

    30 <section id="GUID-0C7FB3A9-2B7A-4576-B4A0-CDF706769D2C"><title>Description</title> <p><b>Method

    31 Information</b> </p> <p>The enumerated type <xref href="GUID-2ABFC65A-FA52-36AB-8910-99D3A10A2D66.dita"><apiname>TPhoneNumberType</apiname></xref> is

    32 used to specify the type of phone number for some of the methods below. </p> <table id="GUID-FD36C6FF-407D-5705-AE6E-62B2EC9D0C4E">

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

    34 <thead>

    35 <row>

    36 <entry>Method name</entry>

    37 <entry>Details</entry>

    38 </row>

    39 </thead>

    40 <tbody>

    41 <row>

    42 <entry><p> <codeph>static TBool ParsePhoneNumber(TDes&amp; aNumber,      

    43                TPhoneNumberType aType)</codeph>  </p> </entry>

    44 <entry><p>Removes irrelevant characters and white space from the supplied

    45 phone number. Allowed characters are determined by phone number type, in other

    46 words, the <codeph>aType</codeph> parameter. For example, parsing the number <codeph>+358

    47 (40) 123 467</codeph> results in the number <codeph>+35840123467</codeph>. </p> </entry>

    48 </row>

    49 <row>

    50 <entry><p> <codeph>static TBool IsValidPhoneNumber(const TDesC&amp; aNumber,

    51                      TPhoneNumberType aType)</codeph>  </p> </entry>

    52 <entry><p>Checks if the supplied phone number is a valid phone number of the

    53 supplied type. </p> </entry>

    54 </row>

    55 <row>

    56 <entry><p> <codeph>TBool IsValidPhoneNumber(const TDesC&amp; aNumber, const

    57                      TDesC&amp; aValidChars)</codeph>  </p> </entry>

    58 <entry><p>Checks if the supplied phone number is a valid phone number. The

    59 phone number is valid if it contains only characters specified by the parameter <codeph>aValidChars.</codeph>  </p> </entry>

    60 </row>

    61 <row>

    62 <entry><p> <codeph>static void ParseInvalidChars(TDes&amp; aNumber, const

    63                      TDesC&amp; aInvalidChars)</codeph>  </p> </entry>

    64 <entry><p>Removes the specified invalid characters from the supplied phone

    65 number string. </p> </entry>

    66 </row>

    67 </tbody>

    68 </tgroup>

    69 </table> <p><b>Example</b> </p> <p>The following example shows how to use

    70 the <codeph>TulPhoneNumberUtils</codeph> class parsing methods: </p> <codeblock id="GUID-BE0A3654-7CDF-536E-9392-D884E557163D" xml:space="preserve">TBuf&lt;50&gt; number = _L("+358 (40) 123 132");

    71 TBool validNumber = TulPhoneNumberUtils::ParsePhoneNumber(number,

    72                         TulPhoneNumberUtils::EPlainPhoneNumber );

    73 // validNumber == ETrue;

    74 // number == "+35840123132"

    75 

    76 SendSMS(number) // etc..

    77 

    78 // OR

    79 

    80 TBuf<50> number = _L("+358 (40) 123p132"); // note 'p'

    81 TBool validNumber = TulPhoneNumberUtils::ParsePhoneNumber(number,

    82                         TulPhoneNumberUtils::EPlainPhoneNumber );

    83 

    84 // validNumber == EFalse;

    85 // number == "+358 (40) 123p132" // unchanged

    86 </codeblock> <p>For more information on individual methods, please see the

    87 reference API for <xref href="GUID-2ABFC65A-FA52-36AB-8910-99D3A10A2D66.dita"><apiname>TulPhoneNumberUtils</apiname></xref>  </p> </section>

    88 </conbody></concept>