/*

* 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