--- a/epoc32/include/commonphoneparser.h Tue Nov 24 13:55:44 2009 +0000
+++ b/epoc32/include/commonphoneparser.h Tue Mar 16 16:12:26 2010 +0000
@@ -1,1 +1,158 @@
-commonphoneparser.h
+/*
+* 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