--- /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 <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
+