/*
* 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