/*

 * Copyright (c) 2002-2006 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 "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members

 * which accompanies this distribution, and is available

 * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

 *

 * Initial Contributors:

 * Nokia Corporation - initial contribution.

 *

 * Contributors:

 *

 * Description:  Offers methods for parsing and validating phone numbers.

 *

 */

 #ifndef COMMONPHONEPARSER_H

 #define COMMONPHONEPARSER_H

 //  INCLUDES

 #include    <coemain.h>

 // CLASS DECLARATION

 /**

 * Class offers static methods for parsing and validating phone numbers. 

 * Phone Parser API provides methods which are used to parse and validate

 * phone numbers. The API consist of the CommonPhoneParser class.

 *

 * Examples of valid phone numbers:

 * 1.	+358501234567

 * 2.	+358 (50) 123 4567

 *

 * Even though both of the above examples are valid phone numbers, only 1) is 

 * accepted as a phone number by many systems. To convert 2) to 1), use the 

 * parsing method of the API.

 *

 *

 * Usage:

 *   

 * @code

 *  #include <commonphoneparser.h> 

 *

 *  // Example shows how to use the parsing method of the API.

 *

 *  // A number to be parsed. 

 *  TBuf<50> number1 = _L("+358 (40) 123 132");

 * 

 *  // Type of the phone number to be parsed is a regular phone number.

 *  TBool validNumber1 = 

 *  CommonPhoneParser::ParsePhoneNumber( number1,

 *                                       CommonPhoneParser::EPlainPhoneNumber );

 *

 *  // The phone number number1 is a valid regular phone number.

 *  // After parsing validNumber1 is ETrue and 

 *  // number1 is "+35840123132".

 *  // Do something like SendSMS( number1 ) etc.

 * 

 *  // A number to be parsed. 

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

 * 

 *  // Type of the phone number to be parsed is a regular phone number.

 *  TBool validNumber2 = 

 *  CommonPhoneParser::ParsePhoneNumber( number2,

 *                                       CommonPhoneParser::EPlainPhoneNumber );

 *

 *  // The phone number number2 is not a valid regular phone number.

 *  // After parsing validNumber2 is EFalse and 

 *  // number2 is "+358 (40) 123p132" (unchanged).

 * @endcode

 *

 * @lib commonengine.lib

 * @since S60 2.0

 */

 class CommonPhoneParser

     {

     public:

         /** 

         * Enumeration for phone number types. 

         * Used to specify the type of phone numbers in methods of 

         * CommonPhoneParser class.

         */

         enum TPhoneNumberType

             {

             /** The associated phone number is a regular phone number.

             */

             EPlainPhoneNumber,

             /** The associated phone number is a contact card number.

             */

             EContactCardNumber,

             /** The associated phone number is is a phone client number.

             */

             EPhoneClientNumber,

 			/** The associated phone number is an SMS number.

             */

             ESMSNumber

             };

         /**

         * Parses the supplied phone number. This method removes irrelevant 

         * characters and white spaces from the supplied phone number. Allowed

         * characters are determined by phone number type.

         *

         * @param aNumber will be checked and parsed. After returning contains

         * the parsed number if the supplied phone number was a valid phone 

         * number. If the number was not valid no parsing will be done.

         * @param aType is the type of the supplied phone number.

         * @return ETrue if the supplied phone number is a valid number of the

         * supplied type and the parsing succeeds. Otherwise EFalse.

         */

         IMPORT_C static TBool ParsePhoneNumber( TDes& aNumber, 

                                                 TPhoneNumberType aType );

         /**

         * Checks if string is a valid phone number.

         * This method checks if the supplied phone number is a valid phone

         * number of the supplied type.

         *

         * @param aNumber which validity will be checked.

         * @param aType  is the type of the supplied phone number.

         * @return ETrue if the supplied phone number is a valid number of the 

         * supplied type. Otherwise EFalse.

         */

         IMPORT_C static TBool IsValidPhoneNumber( const TDesC& aNumber,

                                                   TPhoneNumberType aType );

         /**

         * This method is meant for internal use of Phone Parser. 

         * Check if string is a valid phone number

         *

         * @param aNumber Number which will be checked

         * @param aValidChars Characters that are valid for the number.

         *           Note! Some chars have special rules. See Find Item

         *           UI specification for more info.

         *

         * @return ETrue if the number was valid, otherwise EFalse.

         */

         static TBool IsValidPhoneNumber( const TDesC& aNumber,

                                          const TDesC& aValidChars);

         /**

         * This method is meant for internal use of Phone Parser.

         * Parses invalid characters from a string

         *

         * @param aNumber Number which will be parsed.

         * @param aInvalidChars Characters that are invalid.

         */

         static void ParseInvalidChars( TDes& aNumber,

                                        const TDesC& aInvalidChars);

     };

 #endif      // COMMONPHONEPARSER_H

 // End of File