/*

* Copyright (c) 2006 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:  Array of voip matches.

*

*/

#ifndef TPHCNTVOIPMATCHARRAY_H

#define TPHCNTVOIPMATCHARRAY_H

#include <e32std.h>

class CPhCntContact;

class TPhCntSipURI;

/**

 *  Array of voip matches

 *

 *  Offers way to figure out correct match from many matches.

 *

 *  @lib PhoneCntFinder

 *  @since S60 v3.1

 */

class TPhCntVoipMatchArray 

    {

public:

    TPhCntVoipMatchArray();

    ~TPhCntVoipMatchArray();

    /**

     * Adds contact, takes ownership if the contact.

     *

     * @since S60 v3.1

     * @param aVoipMatch Voip match.

     */

    void AppendL( CPhCntContact* aVoipMatch );

    /**

     * Finds first matched contact, which number

     * is matches aSipNumber. If no such match is found, null is

     * returned. Note that the found match is not in this

     * array after this call. Ownership of match is given

     * to client.

     *

     * @since S60 v3.1

     * @return Contact, which voip number is aSipURI

     */

    CPhCntContact* FindFullMatch( const TPhCntSipURI& aSipURI );

    /**

     * Finds full or just username match from contacts added to this array.

     * If no full matches are found then possible username match is given.

     * Note that the found match is not in this array after this call. 

     * Ownership of match is given to client.

     * 

     * @since S60 v3.1

     * @param aSipUri Sip URI that the match is compared against.

     * @return Found match. Null is returned if no match is found.

     */

    CPhCntContact* FindFullOrUsernameMatch( 

        const TPhCntSipURI& aSipUri,

        const TInt aCharsForMatch = 0 );

    /**

     * Releases the matches. Needs to be called before this class goes 

     * out of scope.

     * @since S60 

     */

    void ReleaseMatches();

private:

    /**

     * Removes contact from array of iMatches. If aMatch does not

     * exist in iMatches then nothing is done.

     * 

     * @since S60 v3.1

     * @param aContact Contact to be removed from iMatches.

     */

    void RemoveMatchFromArray( const CPhCntContact* const aContact );    

    /**

     * Match type.

     */

    enum TMatchType 

        {

        ENone,

        EFullMatch,

        EUserNameMatch,

        };

    /**

     * Determines if contact has aSipURI voip number.

     *

     * @since S60 v3.2

     * @param aContact Contact, which is checked.

     * @param aSipURI SIP URI

     * @return ENone Contact does not have aSipURI voip number.

     *         EFullMatch Contact has aSipUri voip number.

     *         EUserNameMatch Contact has voip number which user name part

     *         equals to aSupURI's user name part.

     */

    TMatchType HasVoipNumber( 

        CPhCntContact& aContact,

        const TPhCntSipURI& aSipURI,

        const TInt aCharsForMatch = 0 ) const;

    /**

     * Finds contact, which voip number is aSipUri or username part

     * are same.

     * 

     * @since S60 v3.2

     * @param aSipURI Voip number of wanted contact.

     * @param aContact Contact found or null.

     * @return ENone - No contact found.

     *         EFullMatch Contact found with full match.

     *         EUserNameMatch contact found that has same user name part

     *         than aSipURI.

     */

    TMatchType FindFullOrUsernameMatch( 

        const TPhCntSipURI& aSipUri,

        CPhCntContact*& aFoundContact,

        const TInt aCharsForMatch = 0 );

private: // data

    /**

     * Array of contact matches.

     * Own.

     */

    RPointerArray<CPhCntContact> iMatches;

    };

#endif // TPHCNTVOIPMATCHARRAY_H