2 * Copyright (c) 2002-2006 Nokia Corporation and/or its subsidiary(-ies). 

     2 * Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies).

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

     5 * under the terms of "Eclipse Public License v1.0"

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

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

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

    14 * Description:

    22 //  INCLUDES

    23 #include <coemain.h>

    23 #include    <coemain.h>

    24 

    25 

    26 // CLASS DECLARATION

    27 

    28 /**

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

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

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

    32 *

    33 * Examples of valid phone numbers:

    34 * 1.	+358501234567

    35 * 2.	+358 (50) 123 4567

    36 *

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

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

    39 * parsing method of the API.

    40 *

    41 *

    42 * Usage:

    43 *   

    44 * @code

    45 *  #include <commonphoneparser.h> 

    46 *

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

    48 *

    49 *  // A number to be parsed. 

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

    51 * 

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

    53 *  TBool validNumber1 = 

    54 *  CommonPhoneParser::ParsePhoneNumber( number1,

    55 *                                       CommonPhoneParser::EPlainPhoneNumber );

    56 *

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

    58 *  // After parsing validNumber1 is ETrue and 

    59 *  // number1 is "+35840123132".

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

    61 * 

    62 *  // A number to be parsed. 

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

    64 * 

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

    66 *  TBool validNumber2 = 

    67 *  CommonPhoneParser::ParsePhoneNumber( number2,

    68 *                                       CommonPhoneParser::EPlainPhoneNumber );

    69 *

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

    71 *  // After parsing validNumber2 is EFalse and 

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

    73 * @endcode

    74 *

    75 * @lib commonengine.lib

    76 * @since S60 2.0

    77 */

    81     public:

    32 public:

    33 	enum TPhoneNumberType

    34 		{

    35 		EPlainPhoneNumber,

    36 		EContactCardNumber,

    37 		EPhoneClientNumber,

    38 		ESMSNumber

    39 		};

    83         /** 

    41     IMPORT_C static TBool ParsePhoneNumber( TDes& aNumber, TInt aType );

    84         * Enumeration for phone number types. 

    42     IMPORT_C static TBool IsValidPhoneNumber( const TDesC& aNumber, TInt aType );

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

    86         * CommonPhoneParser class.

    87         */

    88         enum TPhoneNumberType

    89             {

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

    91             */

    92             EPlainPhoneNumber,

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

    94             */

    95             EContactCardNumber,

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

    97             */

    98             EPhoneClientNumber,

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

   100             */

   101             ESMSNumber

   102             };

   103 

   104         /**

   105         * Parses the supplied phone number. This method removes irrelevant 

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

   107         * characters are determined by phone number type.

   108         *

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

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

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

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

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

   114         * supplied type and the parsing succeeds. Otherwise EFalse.

   115         */

   116         IMPORT_C static TBool ParsePhoneNumber( TDes& aNumber, 

   117                                                 TPhoneNumberType aType );

   118 

   119         /**

   120         * Checks if string is a valid phone number.

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

   122         * number of the supplied type.

   123         *

   124         * @param aNumber which validity will be checked.

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

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

   127         * supplied type. Otherwise EFalse.

   128         */

   129         IMPORT_C static TBool IsValidPhoneNumber( const TDesC& aNumber,

   130                                                   TPhoneNumberType aType );

   131         

   132         /**

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

   134         * Check if string is a valid phone number

   135         *

   136         * @param aNumber Number which will be checked

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

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

   139         *           UI specification for more info.

   140         *

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

   142         */

   143         static TBool IsValidPhoneNumber( const TDesC& aNumber,

   144                                          const TDesC& aValidChars);

   145         /**

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

   147         * Parses invalid characters from a string

   148         *

   149         * @param aNumber Number which will be parsed.

   150         * @param aInvalidChars Characters that are invalid.

   151         */

   152         static void ParseInvalidChars( TDes& aNumber,

   153                                        const TDesC& aInvalidChars);