diff -r 000000000000 -r 094583676ce7 PECengine/AttributeLibrary2/SrcTransactions/PEngAddressUtils.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/PECengine/AttributeLibrary2/SrcTransactions/PEngAddressUtils.h Thu Dec 17 08:41:52 2009 +0200 @@ -0,0 +1,246 @@ +/* +* 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 +#include + + +// 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 +