1 /*

     2 * Copyright (c) 2002-2005 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:  Utility class for presence functions

    15 *

    16 */

    17 

    18 

    19 

    20 #ifndef CAPRESENCEUTILS_H

    21 #define CAPRESENCEUTILS_H

    22 

    23 //  INCLUDES

    24 #include "TStorageManagerGlobals.h"

    25 #include "CAPresenceDefinitions.h"

    26 #include "MCAContactLists.h"

    27 

    28 #include <e32def.h>

    29 #include <badesca.h>

    30 

    31 #include "impsbuilddefinitions.h"

    32 

    33 // FORWARD DECLARATIONS

    34 class MCAWatcherObserver;

    35 class MPEngPresenceAttrModel2;

    36 class MCAStoredContacts;

    37 class MPEngContactList2;

    38 class MPEngTransactionStatus2;

    39 class CCAPresenceErrors;

    40 class TPEngNotify;

    41 class MCAStoredContact;

    42 struct TDecodeAttrParams;

    43 class TResourceReader;

    44 class MCAPresenceUpdater;

    45 class MCAContactList;

    46 

    47 // helper classes for storing attributes

    48 class TCAAttribute

    49     {

    50     public: // data

    51 

    52         TUint32 iAttribute;

    53         TBool iQualifier;

    54         TInt iData;

    55         TInt iField;

    56         TInt iGroup;

    57     };

    58 

    59 class CCAState : public CBase

    60     {

    61     public:

    62         // constructor

    63         CCAState( TInt aStateId )

    64                 : iStateId( aStateId )

    65             {

    66             };

    67 

    68         // destructor

    69         virtual ~CCAState()

    70             {

    71             iAttributes.Close();

    72             };

    73 

    74     public: // data

    75 

    76         TInt iStateId;

    77         RArray<TCAAttribute> iAttributes;

    78 

    79     };

    80 

    81 

    82 // CLASS DECLARATION

    83 

    84 /**

    85 *  Utility class for presence functions

    86 *

    87 *  @lib CAPresence.dll

    88 *  @since 2.1

    89 */

    90 class CAPresenceUtils // CSI: 51 # This is not a C-class

    91             // although it begins with CA.

    92     {

    93     public: // New functions

    94 

    95         /**

    96         * Decodes given TPresenceAttrEntity (clientType) to storage TClientType

    97         * @since 2.1

    98         * @return Storage TClientType

    99         */

   100         static TStorageManagerGlobals::TClientType DecodeClientType(

   101             TCAAttribute aClientTypeAttr );

   102 

   103         /**

   104         * Decodes given TPresenceAttrEntities (Online, CommCAP/IM) to presence

   105         * TPresenceStatus

   106         * @since 2.1

   107         * @param aStates State-array

   108         * @param aOnlineAttr Online-attribute

   109         * @param aIMStatusAttr CommCAP/IM-attribute

   110         * @param aUserAvailAttr User availability attribute

   111         * @return Presence TPresenceStatus

   112         */

   113         static MCAPresence::TPresenceStatus DecodeOnlineState(

   114             const RPointerArray<CCAState>& aStates,

   115             const RPointerArray<MPEngPresenceAttrModel2>& aAttributes );

   116 

   117         /**

   118         * Fills given arrays with given data (aUserId,aPresenceStatus).

   119         * You can give only selected arrays that will be populated.

   120         * @since 2.1

   121         * @param aUserId WVId of user

   122         * @param aPresenceStatus Presence status of given user

   123         * @param aStateOnline Online-array

   124         * @param aStateOnline aStateOffline-array

   125         * @param aStateOnline aStateUnknown-array

   126         */

   127         static void FillArraysL( const TDesC& aUserId,

   128                                  TStorageManagerGlobals::TPresenceStatus aPresenceStatus,

   129                                  CDesCArray *aStateOnline,

   130                                  CDesCArray *aStateOffline,

   131                                  CDesCArray *aStateUnknown );

   132 

   133         /**

   134         * Populates some of given attributes with data found from given model

   135         * @since 3.0

   136         */

   137         static void PopulateAttributesL(

   138             const MPEngPresenceAttrModel2& aModel,

   139             RPointerArray<MPEngPresenceAttrModel2>& aArray,

   140             TStorageManagerGlobals::TClientType& aClientType,

   141             TPtrC& aAlias,

   142             TPtrC& aStatusText );

   143 

   144         /**

   145         * Generates array of friends.

   146         * Array ownership is transferred to caller!!!

   147         * @since 2.1

   148         * @param aContactStorage Handle to contact storage

   149         * appending to result array

   150         * @return Array of friends.

   151         */

   152         static CPtrCArray* GenerateFriendsArrayLC(

   153             MCAStoredContacts* aContactStorage );

   154 

   155         /**

   156         * Pushes given array to CleanupStack

   157         * @since 2.1

   158         * @param aArray Array to be pushed to CleanupStack

   159         * @param aOwnsItems Does array own it's objects

   160         */

   161         static void PushModelArrayL(

   162             RPointerArray<MPEngPresenceAttrModel2>& aArray,

   163             TBool aOwnsItems );

   164 

   165         /**

   166          * Internally used by IM Presence.

   167          * Decode the attribute models.

   168          * @param aParams The structure used when decoding the parameters

   169          * @return ETrue if all done?

   170          */

   171         static TBool DecodeAttrModelsL(

   172             struct TDecodeAttrParams& aParams

   173         );

   174 

   175         /**

   176         * Handles given error.

   177         * This method will leave with given error, except when error is:

   178         * KErrNone/KErrNotFound/KErrAlreadyExists. These errors can be ignored

   179         * with presence engine list-handling.

   180         * @since 2.1

   181         * @param aError Errorcode

   182         */

   183         static void HandleListErrorsL( TInt aError );

   184 

   185         /**

   186         * Compares two attribute models by presence ids.

   187         * @since 2.1

   188         * @param aFirst First model

   189         * @param aSecond Second model

   190         * @return Comparison value (@see TDesC::CompareF)

   191         */

   192         static TInt CompareAttrModelArray(

   193             const MPEngPresenceAttrModel2& aFirst,

   194             const MPEngPresenceAttrModel2& aSecond );

   195 

   196         /**

   197         * Calls close to given array.

   198         * @since 2.1

   199         * @param aObject Array (RPointerArray<MPEngPresenceAttrModel>)

   200         */

   201         static void CloseModelArray( TAny* aObject );

   202 

   203         /**

   204         * Calls ResetAndDestroy to given array

   205         * @since 2.1

   206         * @param aObject Array (RPointerArray<MPEngPresenceAttrModel2>)

   207         */

   208         static void DestroyCloseModelArray( TAny* aObject );

   209 

   210         /**

   211         * Creates detailed error description to error container based on

   212         * information retrieved from given MPEngTransactionStatus

   213         * @since 2.1

   214         * @param aStatus Transaction status

   215         * @param aErrorContainer Error container

   216         */

   217         static void HandleTransactionStatusL(

   218             MPEngTransactionStatus2& aStatus,

   219             CCAPresenceErrors& aErrorContainer );

   220 

   221         /**

   222         * Changes given error's base to Imps_ERROR_BASE if given error is

   223         * in PEC range (KPEngErrorBase-KPEngErrorWVServerResponseBase)

   224         * @since 2.1

   225         * @param aError Original errorcode

   226         * @return Mapped errorcode

   227         */

   228         static TInt MapErrorPECtoCSP( TInt aError );

   229 

   230         /**

   231          * Appends contacts in multiple rounds. Used by CIdle.

   232          * @param aContactList contact list which is added to local data

   233          * @param aWVIds if not null then contact wvids are added here

   234          * @param aNicknames if not null then nicnames are added here

   235          * @param aContactStorage if aWVIds or aNicknames are null, then

   236          *        contacts are added to this storage

   237          * @param aEntryIndex current index were from continue contact

   238          *                    list handling

   239          * @return ETrue if method should be called again to continue

   240          *         list handling

   241          */

   242         static TBool AppendContactsL( MPEngContactList2* aContactList,

   243                                       CDesCArray* aWVIds,

   244                                       CDesCArray* aNicknames,

   245                                       MCAStoredContacts* aContactStorage,

   246                                       TInt& aEntryIndex,

   247                                       MCAContactList& aCaContactList,

   248                                       MCAPresenceUpdater& aPresenceUpdater );

   249 

   250 

   251 

   252         /**

   253          * Reads one attribute from resource

   254          * @param aResourceId Resource Id

   255          * @return Attribute

   256          */

   257         static TCAAttribute ReadAttributeL( TResourceReader& aReader );

   258 

   259         /**

   260          * Map resource state id to presence state id

   261          */

   262         static TInt MapStateId( TInt aResourceStateId );

   263 

   264         /**

   265          * Map presence state id to storage state id

   266          */

   267         static TStorageManagerGlobals::TPresenceStatus MapPresenceStateId(

   268             MCAPresence::TPresenceStatus aPresenceStateId );

   269 

   270         /**

   271          * Reads presence states and attribute combinations from resource

   272          * @param aResourceId Resource Id

   273          * @param aStates Containes states on return

   274          */

   275         static void ReadStatesFromResourceL( TInt aResourceId,

   276                                              RPointerArray<CCAState>& aStates );

   277 

   278         /**

   279          * @return State matching to aState, or NULL if not found

   280          */

   281         static CCAState* FindStateL( TInt aState, const RPointerArray<CCAState>& aStates );

   282 

   283         /**

   284          * @return Attribute matching to aType, or NULL if not found

   285          */

   286         static const MPEngPresenceAttrModel2* FindAttr( TInt aType,

   287                                                         const RPointerArray<MPEngPresenceAttrModel2>& aArray );

   288 

   289         /**

   290          * @return ETrue if states match

   291          */

   292         static TBool EqualStates( const CCAState& aState1, const CCAState& aState2 );

   293 

   294     };

   295 

   296 #endif      // CAPRESENCEUTILS_H

   297 

   298 // End of File