1 /*

     2 * Copyright (c) 2002 - 2009 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:  

    15 *       Utility methods for UI and engine modules. Provides help for address

    16 *       string parsing, and contact database access.

    17 *       General address format is either 

    18 *           alias<real-address> 

    19 *       or

    20 *           <real-address>

    21 *       as used in the Client MTM API.   

    22 *

    23 */

    24 

    25 

    26 

    27 #ifndef TMMSGENUTILS_H

    28 #define TMMSGENUTILS_H

    29 

    30 //  INCLUDES

    31 #include <badesca.h>             // CDesCArray

    32 #include "mmsconst.h"

    33 

    34 // CONSTANTS

    35 _LIT( KSepaOpen, "<" );

    36 _LIT( KSepaClose, ">" );

    37 

    38 // This defines the number of digits that will used for matching phone numbers to contacts

    39 // in contact database. The number is counted from the right.

    40 const TInt KMmsNumberOfDigitsToMatch = 7;

    41 

    42 // MACROS

    43 

    44 // DATA TYPES

    45 

    46 // FUNCTION PROTOTYPES

    47 

    48 // FORWARD DECLARATIONS

    49 

    50 // CLASS DECLARATION

    51 

    52 class CContactMatcher;

    53 class CVPbkContactStoreUriArray;

    54 class MVPbkContactLink;

    55 class CVPbkContactLinkArray;

    56 

    57 /**

    58 *  TMmsGenUtils

    59 */

    60 class TMmsGenUtils 

    61     {

    62     public:  // Constructors and destructor   

    63         

    64         /**

    65         * Constructor.

    66         */

    67         IMPORT_C TMmsGenUtils();

    68         

    69         /**

    70         * Destructor.

    71         */

    72         IMPORT_C ~TMmsGenUtils();

    73       

    74 

    75     public: // New functions 

    76 

    77         /**

    78         * Resolve address type and the real address part excluding alias definition.

    79         * NOTE: Ipv4 and IPv6 not yet supported.

    80         * @param aAddress address to be resolved. May include alias part.

    81         * @param aType address type (OUT)

    82         * @param aRealAddress real address part (OUT)

    83         * @param aMaxLength maximum length of the address.

    84         * @return KErrNone if successful.

    85         */

    86         IMPORT_C static TInt AddressTypeAndRealAddress(

    87             const TDesC& aAddress,

    88             TMmsAddressType& aType, 

    89             TDes& aRealAddress,

    90             TInt aMaxLength,

    91             const TDesC& aOpen = KSepaOpen,

    92             const TDesC& aClose = KSepaClose );

    93 

    94         /**

    95         * Validate the address.

    96         * The address must be EMail address or MMS global phone number address.

    97         * @param aAddress address to be resolved.  

    98         * @param aReal is true if address is real address excluding alias definition. 

    99         * @return ETrue if real address without alias part

   100         * @param aOpen real address part start separator. Optional. Open bracket is default.

   101         * @param aClose real address part end separator. Optional. Close bracket is default.

   102         */

   103         IMPORT_C static TBool IsValidAddress( 

   104             const TDesC& aAddress,

   105             TBool aReal = ETrue,

   106             const TDesC& aOpen = KSepaOpen,

   107             const TDesC& aClose = KSepaClose ); 

   108 

   109         /**

   110         * Validate that the address contains valid EMail address.

   111         * @param aAddress address to be resolved.

   112         * @param aReal is true if address is real address excluding alias definition. 

   113         * @return ETrue if real address without alias part

   114         * @param aOpen real address part start separator. Optional. Open bracket is default.

   115         * @param aClose real address part end separator. Optional. Close bracket is default.

   116         */        

   117         IMPORT_C static TBool IsValidEmailAddress( 

   118             const TDesC& aAddress,

   119             TBool aReal = ETrue,

   120             const TDesC& aOpen = KSepaOpen,

   121             const TDesC& aClose = KSepaClose );

   122 

   123         /**

   124         * Validate that the address contains valid MMS global phone number address.

   125         * You do not need to strip off the alias before this method.

   126         * @param aAddress address to be resolved.

   127         * @param aReal is true if address is real address without alias definition.

   128         * @param aOpen real address part start separator. Optional. Open bracket is default.

   129         * @param aClose real address part end separator. Optional. Close bracket is default.

   130         * @return ETrue if valid address

   131         */

   132         IMPORT_C static TBool IsValidMMSPhoneAddress( 

   133             const TDesC& aAddress,

   134             TBool aReal = ETrue,

   135             const TDesC& aOpen = KSepaOpen,

   136             const TDesC& aClose = KSepaClose );  

   137 

   138         /**

   139         * Alias part from the address.

   140         * @param aAddress address to be resolved.

   141         * @param aOpen real address part start separator. Optional. Open bracket is default.

   142         * @param aClose real address part end separator. Optional. Close bracket is default.

   143         * @return address alias. Zero length if not defined.

   144         */

   145         IMPORT_C static TPtrC Alias( 

   146             const TDesC& aAddress,

   147             const TDesC& aOpen = KSepaOpen,

   148             const TDesC& aClose = KSepaClose );

   149 

   150         /**

   151         * Real address excluding alias part.

   152         * @param aAddress address to be resolved.

   153         * @param aOpen real address part start separator. Optional. Open bracket is default.

   154         * @param aClose real address part end separator. Optional. Close bracket is default.

   155         * @return real address.

   156         */

   157         IMPORT_C static TPtrC PureAddress( 

   158             const TDesC& aAddress,

   159             const TDesC& aOpen = KSepaOpen,

   160             const TDesC& aClose = KSepaClose );

   161 

   162         /**

   163         * Generate address from given address and alias

   164         * @param aRealAddress real address

   165         * @param aAlias alias part 

   166         * @param aOpen real address part start separator. 

   167         *        Optional. Open bracket is default.

   168         * @param aClose real address part end separator.

   169         *        Optional. Close bracket is default.

   170         * @return combined address in format: <br>

   171         *    alias separator1 real_address separator2

   172         */

   173         IMPORT_C static HBufC* GenerateAddressL(

   174             const TDesC& aRealAddress, 

   175             const TDesC& aAlias,

   176             const TDesC& aOpen = KSepaOpen,

   177             const TDesC& aClose = KSepaClose ); 

   178 

   179         /**

   180         * Get message's description.

   181         * @param aPath full path of the attachment binary file

   182         * @param aFileSize attachment size

   183         * @param aMimeType attachment's MIME type.

   184         * @param aCharSet attachment character set MIBEnum value.

   185         * @param aDescription message entry's description (OUT).

   186         *        Truncated as necessary to fit into return value.

   187         */

   188         IMPORT_C static void GetDescriptionL(

   189             RFs& aFs,

   190             const TDesC& aPath,

   191             TInt aFileSize,

   192             TPtrC8 aMimetype,

   193             TInt aCharSet,

   194             TDes& aDescription );

   195 

   196         /**

   197         * Replaces CRs + LFs with spaces and trims all white spaces.

   198         * @param aDes string where to replace CRs + LFs (IN/OUT)

   199         */

   200         IMPORT_C static void ReplaceCRLFAndTrim( TDes16& aDes );

   201 

   202         /**

   203         * Replaces CRs + LFs with spaces and trims all white spaces.

   204         * @param aDes string where to replace CRs + LFs (IN/OUT)

   205         */

   206         IMPORT_C static void ReplaceCRLFAndTrim( TDes8& aDes );

   207 

   208 

   209         /**

   210         * Write message to MMS client log

   211         * @param aFmt like sprintf params in C++.

   212         */

   213         IMPORT_C static void Log( 

   214             TRefByValue<const TDesC> aFmt,...);

   215         

   216 // The following function is for future use

   217         /**

   218         * Removes all escapes from standard URIs, and replaces them with chars.

   219         *  The user is reponsible for allocating the aOutput object prior to

   220         *  calling the method.

   221         *  (e.g. <space> character coding is changed from "%20" to " ".)

   222         * @param aInput URI received from network (IN).

   223         * @param aOutput descriptor containing the resulting string (OUT).

   224         * @return errorvalue.

   225         */

   226         /*static TInt ConvertEscapesFromUri(

   227             const TDesC8& aInput,

   228             TDes8& aOutput

   229             );*/

   230                 

   231         /**

   232         * Decodes base64 or quoted-printable descriptor into plain unicode.

   233         * The user is responsible for allocating memory for output parameter.

   234         * @param[in] aInput 'base64' or 'quoted-printable' encoded string (IN).

   235         * @param[out] aOutput 16 bit unicode descriptor containing the resulting 

   236         *   string.

   237         * @param[in] aFs open file system handle

   238         * @return errorvalue.

   239         */

   240         IMPORT_C static void DecodeAndConvertMessageHeaderL(

   241             const TDesC8& aInput,

   242             TDes16& aOutput,

   243             RFs& aFs

   244             );

   245             

   246         /**

   247         * Generic method to check if free drive storage

   248         * space is or will fall below Critical Level (CL).

   249         * The CL per drive is defined by this module.

   250         * @param aFs File server session.

   251         *        Must be given if available in the caller.

   252         *        If NULL this method will create a temporary session for

   253         *        a check, but then the check is more expensive.

   254         * @param aBytesToWrite number of bytes the caller is about to add

   255         *        FFS.The value 0 checks if the current

   256         *        space is already below the CL. 

   257         * @param aDrive number of the drive to be checked.

   258         *        (see TDriveNumber of f32file.h)

   259         * @return ETrue if storage space would go below CL after adding

   260         *         aBytesToWrite more data, EFalse otherwise.

   261         *         Leaves on error with one of system-wide error code.

   262         *         e.g. KErrNotReady if drive contais no media.

   263         */

   264         IMPORT_C static TBool DiskSpaceBelowCriticalLevelL(

   265             RFs* aFs, TInt aBytesToWrite, TInt aDrive);

   266             

   267         /** 

   268         * Check if network operations are allowed

   269         * @return ETrue if network operations are allowed

   270         *         EFalse if network operations are forbidden

   271         */

   272         IMPORT_C static TBool NetworkOperationsAllowed();

   273         

   274         /** 

   275         * Add attribute to an attribute array. No duplicates allowed

   276         * If attribute exists, its value is changed

   277         * @param aName Name of the attribute (case sensitive)

   278         * @param aValue Value of the attribute

   279         * @param aAttributeList Array of attributes

   280         * Leaves if memory runs out

   281         */

   282         IMPORT_C static void AddAttributeL(

   283             const TDesC& aName,

   284             const TDesC& aValue,

   285             CDesCArray& aAttributeList );

   286             

   287         /**

   288         * Get value for an attribute.

   289         * @param aName Name of the attribute (case sensitive)

   290         * @param aAttributeList Array of attributes

   291         * @return Pointer to the value of the attribute

   292         * Leaves with KErrNotFound if attribute not found

   293         */

   294         IMPORT_C static TPtrC GetAttributeL(

   295             const TDesC& aName,

   296             const CDesCArray& aAttributeList );

   297             

   298         /**

   299         * Check if attribute is present

   300         * @param aName Name of the attribute (case sensitive)

   301         * @param aAttributeList Array of attributes

   302         * @return ETrue if the attribute is found, EFalse otherwise

   303         */

   304         IMPORT_C static TBool FindAttribute(

   305             const TDesC& aName,

   306             const CDesCArray& aAttributeList );

   307             

   308         /**

   309         * Delete named attribute from list

   310         * @param aName Name of the attribute (case sensitive)

   311         * @param aAttributeList Array of attributes

   312         */

   313         IMPORT_C static void DeleteAttribute(

   314             const TDesC& aName,

   315             CDesCArray& aAttributeList );

   316             

   317         /**

   318         * Generate message details (alias) from ContactDb based on given address.

   319         * Only default separators <> are allowed (compatibility with email)

   320         *

   321         * @since 3.1

   322         * @param aAddress address. May include alias part, which will be the result.

   323         * @param aAlias generated alias name (OUT). If no match in contact db then 

   324         *     this is a real address part of aAddress.

   325         * @param aMaxLength maximum length of the alias

   326         * @param aFs file system

   327         * @return KErrNone if no fatal error, Otherwise general error code.

   328         */

   329         IMPORT_C static TInt GenerateDetails( 

   330             const TDesC& aAddress,

   331             TDes& aAlias,

   332             TInt aMaxLength,

   333             RFs& aFs ); 

   334 

   335         /**

   336         * Get alias from ContactDb based on given address.

   337         *        

   338         * @since 3.1

   339         * @param aAddress address (pure real address). 

   340         * @param aAlias generated alias name (OUT). 

   341         * @param aMaxLength maximum length of the alias

   342         * @param aFs file system

   343         * @return KErrNone if no fatal error, Otherwise general error code.

   344         */

   345         IMPORT_C static TInt GetAlias( 

   346             const TDesC& aAddress,

   347             TDes& aAlias,

   348             TInt aMaxLength,

   349             RFs& aFs );

   350             

   351         /**

   352         * Get alias from ContactDb based on given address.

   353         *        

   354         * @since 3.1

   355         * @param aAddress Array of addresses (pure real address). 

   356         * @param aAlias Array of generated alias names (OUT). 

   357         * @param aMaxLength maximum length of the alias

   358         * @param aFs file system

   359         * Leaves in case of error

   360         */

   361         IMPORT_C static void GetAliasForAllL(

   362             const CDesCArray& aAddress,

   363             CDesCArray& aAlias,

   364             TInt aMaxLength,

   365             RFs& aFs );  

   366             

   367         /**

   368         * Read decode logging and dump settings from central repository

   369         * @since 3.2

   370         *

   371         * @param aDecodeLoggingOn tells if detailed logging is needed

   372         * @param aDumpOn tells if binary dump of message is needed

   373         */

   374         IMPORT_C static void GetLoggingSettings( TBool& aDecodeLoggingOn, TBool& aDumpOn );

   375             

   376 

   377     protected:  // New functions

   378         

   379 

   380     private:

   381 

   382         // By default, prohibit copy constructor

   383         TMmsGenUtils( const TMmsGenUtils& );

   384 

   385         // Prohibit assignment operator

   386         TMmsGenUtils& operator= ( const TMmsGenUtils& );

   387 

   388         /**

   389         * Generate alias from ContactDb based on given address.

   390         * @param aFs file system

   391         * @param aAddress real address

   392         * @param aAlias generated alias name (OUT)

   393         * @param aMaxLength maximum length of the alias

   394         * @param aId contacd db id of the matched contact

   395         */

   396         static void DoGetAliasL(

   397             RFs& aFs,

   398             const TDesC& aAddress, 

   399             TDes& aAlias, 

   400             TInt aMaxLength );

   401         

   402 

   403         /**

   404         * Generate aliases from ContactDb based on given address.

   405         * This is optimized version of the previous DoGetAliasL

   406         * because the contact db is opened before calling this function.

   407         * Opening the db is quite an time consuming operation.

   408         * @param aAddress real address

   409         * @param aAlias generated alias name (OUT)

   410         * @param aMaxLength maximum length of the alias

   411         * @param aContactMatcher pointer to contact matcher

   412         * @param aId contacd db id of the matched contact

   413         * @param aDigitsToMatch number of digits to match

   414         */

   415         static void  DoGetAliasL(

   416             const TDesC& aAddress, 

   417             TDes&  aAlias, 

   418             TInt aMaxLength,

   419             CContactMatcher& aContactMatcher,

   420             TInt aDigitsToMatch  );

   421 

   422         /**

   423         * Find position of attribute

   424         * @param aName Name of the attribute (case sensitive)

   425         * @param aAttributeList Array of attributes

   426         * @return index of attribute, KerrNot found if not found

   427         */

   428         static TInt FindAttributePosition(

   429             const TDesC& aName,

   430             const CDesCArray& aAttributeList );

   431             

   432         /**

   433         * Get number of digits to be used when matching phone numbers

   434         * @return number of digits to match from central repository

   435         * If reading central repository fails, returns hard coded default

   436         */   

   437         static TInt DigitsToMatch();

   438          

   439         /**

   440         * Create contact match wrapper and open all stores

   441         * Caller must close stores and delete contact matcher when no longer needed

   442         * @param aFs file system

   443         * @return pointer to contact matcher for further operations

   444         * Leaves in case of error

   445         */

   446         static CContactMatcher* OpenAllStoresL( RFs& aFs );

   447         

   448 

   449         /**

   450         * extracts contact name out of the contact link passed

   451         * Caller must delete the name buffer returned

   452         * @param aContactLink - contact link

   453         * @param aContactMatcher - contact matcher

   454         * @return pointer to contact name for further operation

   455         * Leaves in case of error

   456         */

   457         static HBufC* GetContactNameL(

   458                 const MVPbkContactLink& aContactLink,

   459                 CContactMatcher &aContactMatcher);

   460 

   461 

   462         /**

   463         * extracts contact name and converts to lower case chars.

   464         * Caller must delete the name buffer returned

   465         * @param aContactLink - contact link

   466         * @param aContactMatcher - contact matcher

   467         * @return pointer to contact name for further operation

   468         * Leaves in case of error

   469         */

   470         static HBufC* GetContactNameInLowerCaseL(

   471                 const MVPbkContactLink& aContactLink,

   472                 CContactMatcher &aContactMatcher);

   473 

   474         /**

   475         * checks if contact names in the linkArray are identical. Can be used t

   476         * Caller must delete the name buffer returned

   477         * @param aLinkArray- contact link array

   478         * @param aContactMatcher - contact matcher

   479         * @param aNameIndex - index of the name to be finally shown(output param)

   480         * @return true/false, to decide if name has to be shown or not. 

   481         * Leaves in case of error

   482         */

   483         static TBool ShowContactNameL(

   484                 CVPbkContactLinkArray* aLinkArray,

   485                 TInt &aNameIndex,

   486                 CContactMatcher &aContactMatcher);

   487                 

   488 

   489         /**

   490         * Gets the index of contact match in current store. 

   491         * If multiple matches are found in current store, then the link Array

   492         * is modified to include only current store contact matches for further name mapping.

   493         * else, link array can be used as is for further name mapping

   494         * @param aLinkArray- contact link array containing all the matches

   495         * @return Valid name index, if single match in current store is found

   496         *         else returns KErrMultipleMatchFound, if multiple mathes are found

   497         *         and also modifies aLinkArray as explained above.

   498         * Leaves in case of error

   499         */

   500         static TInt GetCurrentStoreIndexL( CVPbkContactLinkArray& aLinkArray );

   501 

   502     private:    // Data

   503 

   504     };

   505 

   506 #endif      // TMMSGENUTILS_H   

   507             

   508 // End of File