1 /*

     2 * Copyright (c) 2004 Nokia Corporation and/or its subsidiary(-ies). 

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  Tools for matching & handling presence addresses & user id's.

    15 *

    16 */

    17 

    18 #ifndef PENGADDRESSUTILS_H__

    19 #define PENGADDRESSUTILS_H__

    20 

    21 

    22 //  INCLUDES

    23 #include <e32base.h>

    24 #include <BamDescA.h>

    25 

    26 

    27 // CLASS DECLARATION

    28 

    29 /**

    30  * Tools for matching & handling presence addresses & user id's.

    31  *

    32  * Generic WV address syntax is defined as follows (in WV CSP 1.1):

    33  *

    34  * Address = "wv:" [User-ID] ["/" Resource] ["@" Domain]

    35  * Resource = Group-ID | Contact-List-ID | Content-ID

    36  * Domain = sub-domain *("." sub-domain)

    37  *

    38  * @since 3.0

    39  */

    40 NONSHARABLE_CLASS( PEngAddressUtils )

    41     {

    42 public: //Fragment extractors

    43 

    44     /**

    45      * Match mode for for locating / matching WV addresses.

    46      *

    47      * ENormal: Normal matching with match domain.

    48      * EMatchToUniqueId: With this mode, extended uniqued

    49      * id matching is performed if normal find fails.

    50      *

    51      * @since 3.0

    52      */

    53     enum TPEngAddressMatchdMode { ENormal, EMatchToUniqueId };

    54 

    55 

    56 

    57 

    58 public: //Fragment extractors

    59 

    60     /**

    61      * Extracts user id part from possibly complete WV address.

    62      * E.g. gets "john.doe" from "wv:john.doe/friends@imps.com"

    63      *

    64      * Possible user ID address structures are:

    65      *  - "wv:john/colleagues@imps.com"

    66      *  - "wv:john/friends"

    67      *  - "wv:john

    68      *

    69      * @since 3.0

    70      * @param aWVAddress WV address.

    71      * @return Plain user ID part without starting schema prefix

    72      * or without trailing resource and domain definition.

    73      * If no user id present in given address, returns empty descriptor.

    74      */

    75     static TPtrC WVUserId( const TDesC& aWVAddress );

    76 

    77 

    78 

    79     /**

    80      * Extracts resource id part from possibly complete WV address.

    81      * E.g. gets "friends" from "wv:john.doe/friends@imps.com"

    82      *

    83      * Possible resource ID address structures are:

    84      *  - "wv:john/colleagues@imps.com"

    85      *  - "wv:/managers"

    86      *  - "wv:john/friends"

    87      *  - "wv:/managers@imps.com"

    88      *

    89      * @since 3.0

    90      * @param aWVAddress WV address.

    91      * @return Resource id part without starting user / schema prefix

    92      * or without trailing domain definition.

    93      * If no resource part present in given address, returns empty descriptor.

    94      */

    95     static TPtrC WVResourceId( const TDesC& aWVAddress );

    96 

    97 

    98 

    99     /**

   100      * Extracts domain part from possibly complete WV address.

   101      * E.g. gets "imps.com" from "wv:john.doe/friends@imps.com"

   102      *

   103      * Possible domain address structures are:

   104      *  - "wv:john/colleagues@imps.com"

   105      *  - "wv:john@imps.com"

   106      *  - "wv:/managers@imps.com"

   107      *

   108      * @since 3.0

   109      * @param aWVAddress WV address.

   110      * @return Domain part without starting user / resource parts.

   111      * If no resource part present in given address, returns empty descriptor.

   112      */

   113     static TPtrC WVDomain( const TDesC& aWVAddress );

   114 

   115 

   116 

   117     /**

   118      * Strips possible wv-schema part away from complete

   119      * WV address and returns the rest.

   120      *

   121      * @since 3.0

   122      * @param aWVAddress Full WV address to reduce.

   123      * @return Plain presence address without wv-schema prefix.

   124      */

   125     static TPtrC ReducedWVAddress( const TDesC& aWVAddress );

   126 

   127 

   128 

   129 public: //Address generator

   130 

   131 

   132     /**

   133      * Composes canonic WV address from

   134      * given WV addres parts.

   135      *

   136      * If some given part is zero length,

   137      * then corresponding part is not present

   138      * in generated full WV address.

   139      *

   140      * Either user id part or resource id part must be defined.

   141      * In other cases a leave with KErrArgument is raised.

   142      *

   143      * @since 3.0

   144      * @param aUserId User id

   145      * @param aResourceId

   146      * @param aDomain

   147      * @return Canonic WV address.

   148      */

   149     static HBufC* CanonicWVAddressLC( const TDesC& aUserId,

   150                                       const TDesC& aResourceId,

   151                                       const TDesC& aDomain );

   152 

   153 

   154 

   155 public: //Match & find

   156 

   157     /**

   158      * Checks does two WV address match.

   159      * (Do they refer same WV user / resource.)

   160      *

   161      * Matching is case insensitive and possible "wv:" schema

   162      * prefixes are ignored in matching.

   163      *

   164      * Example 1: No match domain information available

   165      *  - "wv:User" == "wv:User" (Direct match.)

   166      *  - "wv:User" == "User"    (Direct match, schema prefix ignored.)

   167      *  - "wv:User@Server.com" == "wv:User@Server.com"  (Direct match.)

   168      *

   169      *

   170      * Example 2: Match domain "Server.com"

   171      *  - "wv:User" == "wv:User" (Direct match.)

   172      *  - "wv:User" == "User"    (Direct match, schema prefix ignored.)

   173      *  - "wv:User@Server.com" == "wv:User@Server.com"  (Direct match.)

   174      *

   175      *  - "wv:User" == "wv:User@Server.com"         (Domain extended match.)

   176      *  - "wv:User@Server.com" == "wv:User"         (Domain extended match.)

   177      *

   178      * @since 3.0

   179      * @param aWVAddress1 First WV address.

   180      * @param aWVAddress2 Second WV address.

   181      * @param aMatchDomain Match domain. If no match domain available

   182      * pass empty descriptor.

   183      * @return ETrue if passed addresses refer same WV user / resource.

   184      * Else EFalse.

   185      */

   186     static TBool MatchWVAddressesF( const TDesC& aWVAddress1,

   187                                     const TDesC& aWVAddress2,

   188                                     const TDesC& aMatchDomain );

   189 

   190 

   191 

   192     /**

   193      * Finds matching WV address from array of WV

   194      * addresses. (Finds a WV address which refers

   195      * to same user / resource than given address.)

   196      *

   197      * Gets the index for matching address from

   198      * passed descriptor array. Matching is case

   199      * insensitive and possible "wv:" schema prefixes are

   200      * ignored in matching.

   201      *

   202      * If non empty match domain is provided, local addresses

   203      * (addresses without domain part) are matched to users or

   204      * resources with matching aMatchDomain domain.

   205      *

   206      * If no matching presence id is found, returns KErrNotFound

   207      * If there is matching entry, returns index of it.

   208      * (In case there is several matches, returns the index of

   209      * first found.)

   210      *

   211      * If match mode EMatchToUniqueId is used, standard matching is

   212      * extended  with unique id matching if normal find fails.

   213      * Extended unique id matching is performed only if:

   214      * - empty match domain is provided

   215      * - also the searched address is local one (missing the domain part)

   216      *

   217      * Extended unique id matching succeeds if the given searched

   218      * user ID/resource ID matches only one WV address's user ID/resource ID

   219      * part. If there is several possible user ID / resource ID matches ion

   220      * the array, then KErrNotFound is returned, because the match is not

   221      * anymore confident.

   222      *

   223      * @since 3.0

   224      * @param aWVAddress The WV address to locate.

   225      * @param aWVAddresses The array of WV addresses to search.

   226      * @param aMatchDomain The match domain to use.

   227      * @param aMode The mode for matching.

   228      * @return Returns find operation result.

   229      * KErrNotFound if no matching address was found.

   230      * Else the index of matching entry.

   231      */

   232     static TInt FindWVAddressF( const TDesC& aWVAddress,

   233                                 const MDesCArray& aWVAddresses,

   234                                 const TDesC& aMatchDomain,

   235                                 TPEngAddressMatchdMode aMode = ENormal );

   236 

   237 private: //Prohibited constructor and destructor

   238 

   239     PEngAddressUtils();

   240     ~PEngAddressUtils();

   241     };

   242 

   243 #endif      //  PENGADDRESSUTILS_H__

   244 

   245 //  End of File

   246