/*

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

* All rights reserved.

* This component and the accompanying materials are made available

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

* which accompanies this distribution, and is available

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

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description: 

*

*    This class gives feature variant - independent access to Series 60 number grouping 

*    and provides digit type conversion.

*

*

*/

#ifndef AKNPHONENUMBERGROUPING_H

#define AKNPHONENUMBERGROUPING_H

// INCLUDES

#include <e32std.h>

#include <gdi.h>

// CONSTANTS

// CLASS DECLARATION

class CPNGNumberGrouping; 

/**

* This class acts as a wrapper for the Number Grouping engine (NumberGrouping.dll). 

* It exposes non-static API to the engine so that it can be used without the client code dealing with the

* issues of

* - build switches for calling numbergrouping API

* - build switches for linking to NumberGrouping.lib

* - checks on Feature Manager.

*

* It deals with these internally.  In the case of __SERIES60_PHONE_NUMBER_GROUPING being #undef-ed, this 

* object acts as if there is a "null" phone number grouping.

* 

* Static methods are included for those who are doing a small number of individual groupings of phone numbers, 

* say, when a view or popup is constructed, or a title pane is refreshed. These construct the object 

* internally within the static call.

* 

* The class also deals with the conversion of numbers to potentially locale or setting-

* specific number symbols, using the Series 60 platform policy.

* 

* For repeated, frequent operations, the non-static API is recommended.  Only a limited number of methods 

* from NumberGrouping.h are exposed, but these suffice in the main use cases.  

*

*  @lib Avkon.dll

*  @since 2.6

*/

NONSHARABLE_CLASS(CAknPhoneNumberGrouping) : public CBase

    {

    public:

        // 2 stage constructors

        IMPORT_C static CAknPhoneNumberGrouping* NewLC(TInt aUnformattedLength);

        IMPORT_C static CAknPhoneNumberGrouping* NewL(TInt aUnformattedLength);

        // Destructor

        ~CAknPhoneNumberGrouping();

    public: // non-static methods for using phone number grouping engine in the simplest cases

        /**

        * Load an ungrouped number into the phone number grouping engine

        * This calls the CPNGNumberGrouping::Set within the engine

        *

        * @since 2.6

        * @param    aUngroupedNumber    input ungrouped phone number

        * @return                       KErrNone if there was no error                   

        */

        IMPORT_C TInt Set( const TDesC& aUngroupedNumber );

        /**

        * Returns a reference to the formatted number stored within the number grouping engine

        *

        * NOTE: This api does not convert to current digit type. This requires a method that takes

        * a modifiable descriptor, so use CopyFormattedNumber( TDes& ) const

        *

        * This method is particularly useful for obtaining the size of the required buffer to copy 

        * the grouped phone number to by calling FormattedNumber.Length()

        *

        * @since 2.6

        * @return   reference to internally held formatted (grouped) phone number

        */

	    IMPORT_C const TDesC& FormattedNumber() const;

        /**

        * Copies the grouped phone number stored in the object to the supplied output buffer, 

        * performing any current digit type conversion required.

        *

        * The length required for the supplied output descriptor must be greater or equal to the text waiting

        * to be copied out of the instance.  This can be determined before the call with no loss of 

        * performance with FormattedNumber().Length();

        *       

        * The application will be Panicked (USER 11) if the output descriptor is too short.

        *

        * @since 2.6

        * @param    aGroupedNumber      Output (grouped) descriptor to be written to.  To avoid a panic, this

        *                               must be at least as big as the formatted number currently stored.

        */

	    IMPORT_C void CopyFormattedNumber( TDes& aGroupedNumber ) const;

    public: // Static utility methods for doing the one-off grouping of phone numbers

        /**

        * Static utility method for doing one-off grouping of a phone number according to the current

        * configuration.

        * 

        * The method Leaves if the number grouping engine could not be allocated, or the output heap memory

        * could not be allocated.

        *

        * @since 2.6

        * @param    aUngroupedNumber    Input descriptor to be grouped

        * @return                       Pointer to heap descriptor containing the grouped number

        *                               Ownership is transferred to the caller

        */

        IMPORT_C static HBufC* CreateGroupedPhoneNumberL( const TDesC& aUngroupedNumber );

        /**

        * Static utility method for doing one-off grouping of a phone number according to the current

        * configuration.

        *

        * The operations are internally trapped so as not to leave. The grouped number must fit into output

        * descriptor, or else no grouping will take place and the input will just be copied to the output.

        * A negative return value will indicate that the output did not fit, and by how much.

        * 

        * The application will be Panicked (USER 11) if the output descriptor is too short even for an exact

        * copy of the input.

        *

        * @since 2.6

        * @param    aUngroupedNumber    Input descriptor to be grouped

        * @param    aGroupedNumber      Output (grouped) descriptor to be written to

        * @return                       If the entire grouped number could be copied to the output, then the

        *                               returned number is zero or positive. This number represents the number

        *                               of further characters in the grouped number that could have been accomodated.

        *                               A negative return value indicates that the grouped number could not be

        *                               copied, and that the ungrouped number had to be copied. The magnitude

        *                               of the return value in this case is how many more characters would have

        *                               been needed.

        */

        IMPORT_C static TInt GroupPhoneNumber( const TDesC& aUngroupedNumber, TDes& aGroupedNumber );

        /**

        * Static utility method for doing one-off grouping of a phone number according to the current

        * configuration.

        * 

        * The operations are internally trapped so as not to leave. The grouped number must fit into the one, 

        * input/output descriptor, or else no grouping will take place. A negative return value indicates that the

        * grouped number did not fit. 

        *

        * @since 2.6

        * @param    aUngroupedNumber    Input descriptor to be grouped

        * @return                       If the entire grouped number could be copied to the output, then the

        *                               returned number is zero or positive. This number represents the number

        *                               of further characters in the grouped number that could have been accomodated.

        *                               A negative return value indicates that the grouped number could not be

        *                               copied, and that the ungrouped number had to be copied. The magnitude

        *                               of the return value in this case is how many more characters would have

        *                               been needed.

        */

        IMPORT_C static TInt GroupPhoneNumber( TDes& aPhoneNumber );

    private:

        /**

        * C++ constructor.

        */

        CAknPhoneNumberGrouping();

        /**

        * 2nd phase constructor is private.

        */

        void ConstructL( TInt aUnformattedLength );

        /**

        * Internal method for creating a phone number grouping engine and copying out the result to an 

        * output buffer. 

        *

        * The creation of the engine may leave, in which case nothing else happens. But if it does not

        * leave, an attempt will be made to copy the grouped phone number to aGroupedPhoneNumber.  

        * If there is enough space, it is copied and the amount of space in characters left over in 

        * the target buffer is returned.  If it does not fit, then there is no copy made and the 

        * aExtraSpace contains a negative value, the additional length required.

        * 

        * @param    aUngroupedNumber    Input descriptor containing a phone number        

        * @param    aGroupedNumber      Output descriptor for the grouped phone number

        * @param    aExtraSpace         How much extra space there was in the output descriptor

        * @return   EFalse iff the grouped phone number was not copied.

        */

        static TBool DoFormatPhoneNumberL( 

            const TDesC& aUngroupedNumber,

            TDes& aGroupedNumber,

            TInt& aExtraSpace);

    private:

        // Owned number grouping engine

        CPNGNumberGrouping* iNumberGroupingEngine;

        };

#endif

// End of File