/*
* Copyright (c) 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:  Tools for matching & handling presence addresses & user id's.
*
*/

#ifndef PENGADDRESSUTILS_H__
#define PENGADDRESSUTILS_H__


//  INCLUDES
#include <e32base.h>
#include <BamDescA.h>


// CLASS DECLARATION

/**
 * Tools for matching & handling presence addresses & user id's.
 *
 * Generic WV address syntax is defined as follows (in WV CSP 1.1):
 *
 * Address = "wv:" [User-ID] ["/" Resource] ["@" Domain]
 * Resource = Group-ID | Contact-List-ID | Content-ID
 * Domain = sub-domain *("." sub-domain)
 *
 * @since 3.0
 */
NONSHARABLE_CLASS( PEngAddressUtils )
    {
public: //Fragment extractors

    /**
     * Match mode for for locating / matching WV addresses.
     *
     * ENormal: Normal matching with match domain.
     * EMatchToUniqueId: With this mode, extended uniqued
     * id matching is performed if normal find fails.
     *
     * @since 3.0
     */
    enum TPEngAddressMatchdMode { ENormal, EMatchToUniqueId };




public: //Fragment extractors

    /**
     * Extracts user id part from possibly complete WV address.
     * E.g. gets "john.doe" from "wv:john.doe/friends@imps.com"
     *
     * Possible user ID address structures are:
     *  - "wv:john/colleagues@imps.com"
     *  - "wv:john/friends"
     *  - "wv:john
     *
     * @since 3.0
     * @param aWVAddress WV address.
     * @return Plain user ID part without starting schema prefix
     * or without trailing resource and domain definition.
     * If no user id present in given address, returns empty descriptor.
     */
    static TPtrC WVUserId( const TDesC& aWVAddress );



    /**
     * Extracts resource id part from possibly complete WV address.
     * E.g. gets "friends" from "wv:john.doe/friends@imps.com"
     *
     * Possible resource ID address structures are:
     *  - "wv:john/colleagues@imps.com"
     *  - "wv:/managers"
     *  - "wv:john/friends"
     *  - "wv:/managers@imps.com"
     *
     * @since 3.0
     * @param aWVAddress WV address.
     * @return Resource id part without starting user / schema prefix
     * or without trailing domain definition.
     * If no resource part present in given address, returns empty descriptor.
     */
    static TPtrC WVResourceId( const TDesC& aWVAddress );



    /**
     * Extracts domain part from possibly complete WV address.
     * E.g. gets "imps.com" from "wv:john.doe/friends@imps.com"
     *
     * Possible domain address structures are:
     *  - "wv:john/colleagues@imps.com"
     *  - "wv:john@imps.com"
     *  - "wv:/managers@imps.com"
     *
     * @since 3.0
     * @param aWVAddress WV address.
     * @return Domain part without starting user / resource parts.
     * If no resource part present in given address, returns empty descriptor.
     */
    static TPtrC WVDomain( const TDesC& aWVAddress );



    /**
     * Strips possible wv-schema part away from complete
     * WV address and returns the rest.
     *
     * @since 3.0
     * @param aWVAddress Full WV address to reduce.
     * @return Plain presence address without wv-schema prefix.
     */
    static TPtrC ReducedWVAddress( const TDesC& aWVAddress );



public: //Address generator


    /**
     * Composes canonic WV address from
     * given WV addres parts.
     *
     * If some given part is zero length,
     * then corresponding part is not present
     * in generated full WV address.
     *
     * Either user id part or resource id part must be defined.
     * In other cases a leave with KErrArgument is raised.
     *
     * @since 3.0
     * @param aUserId User id
     * @param aResourceId
     * @param aDomain
     * @return Canonic WV address.
     */
    static HBufC* CanonicWVAddressLC( const TDesC& aUserId,
                                      const TDesC& aResourceId,
                                      const TDesC& aDomain );



public: //Match & find

    /**
     * Checks does two WV address match.
     * (Do they refer same WV user / resource.)
     *
     * Matching is case insensitive and possible "wv:" schema
     * prefixes are ignored in matching.
     *
     * Example 1: No match domain information available
     *  - "wv:User" == "wv:User" (Direct match.)
     *  - "wv:User" == "User"    (Direct match, schema prefix ignored.)
     *  - "wv:User@Server.com" == "wv:User@Server.com"  (Direct match.)
     *
     *
     * Example 2: Match domain "Server.com"
     *  - "wv:User" == "wv:User" (Direct match.)
     *  - "wv:User" == "User"    (Direct match, schema prefix ignored.)
     *  - "wv:User@Server.com" == "wv:User@Server.com"  (Direct match.)
     *
     *  - "wv:User" == "wv:User@Server.com"         (Domain extended match.)
     *  - "wv:User@Server.com" == "wv:User"         (Domain extended match.)
     *
     * @since 3.0
     * @param aWVAddress1 First WV address.
     * @param aWVAddress2 Second WV address.
     * @param aMatchDomain Match domain. If no match domain available
     * pass empty descriptor.
     * @return ETrue if passed addresses refer same WV user / resource.
     * Else EFalse.
     */
    static TBool MatchWVAddressesF( const TDesC& aWVAddress1,
                                    const TDesC& aWVAddress2,
                                    const TDesC& aMatchDomain );



    /**
     * Finds matching WV address from array of WV
     * addresses. (Finds a WV address which refers
     * to same user / resource than given address.)
     *
     * Gets the index for matching address from
     * passed descriptor array. Matching is case
     * insensitive and possible "wv:" schema prefixes are
     * ignored in matching.
     *
     * If non empty match domain is provided, local addresses
     * (addresses without domain part) are matched to users or
     * resources with matching aMatchDomain domain.
     *
     * If no matching presence id is found, returns KErrNotFound
     * If there is matching entry, returns index of it.
     * (In case there is several matches, returns the index of
     * first found.)
     *
     * If match mode EMatchToUniqueId is used, standard matching is
     * extended  with unique id matching if normal find fails.
     * Extended unique id matching is performed only if:
     * - empty match domain is provided
     * - also the searched address is local one (missing the domain part)
     *
     * Extended unique id matching succeeds if the given searched
     * user ID/resource ID matches only one WV address's user ID/resource ID
     * part. If there is several possible user ID / resource ID matches ion
     * the array, then KErrNotFound is returned, because the match is not
     * anymore confident.
     *
     * @since 3.0
     * @param aWVAddress The WV address to locate.
     * @param aWVAddresses The array of WV addresses to search.
     * @param aMatchDomain The match domain to use.
     * @param aMode The mode for matching.
     * @return Returns find operation result.
     * KErrNotFound if no matching address was found.
     * Else the index of matching entry.
     */
    static TInt FindWVAddressF( const TDesC& aWVAddress,
                                const MDesCArray& aWVAddresses,
                                const TDesC& aMatchDomain,
                                TPEngAddressMatchdMode aMode = ENormal );

private: //Prohibited constructor and destructor

    PEngAddressUtils();
    ~PEngAddressUtils();
    };

#endif      //  PENGADDRESSUTILS_H__

//  End of File