/*

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

*

*/

#ifndef CAPRESENCEUTILS_H

#define CAPRESENCEUTILS_H

//  INCLUDES

#include "TStorageManagerGlobals.h"

#include "CAPresenceDefinitions.h"

#include "MCAContactLists.h"

#include <e32def.h>

#include <badesca.h>

#include "impsbuilddefinitions.h"

// FORWARD DECLARATIONS

class MCAWatcherObserver;

class MPEngPresenceAttrModel2;

class MCAStoredContacts;

class MPEngContactList2;

class MPEngTransactionStatus2;

class CCAPresenceErrors;

class TPEngNotify;

class MCAStoredContact;

struct TDecodeAttrParams;

class TResourceReader;

class MCAPresenceUpdater;

class MCAContactList;

// helper classes for storing attributes

class TCAAttribute

    {

    public: // data

        TUint32 iAttribute;

        TBool iQualifier;

        TInt iData;

        TInt iField;

        TInt iGroup;

    };

class CCAState : public CBase

    {

    public:

        // constructor

        CCAState( TInt aStateId )

                : iStateId( aStateId )

            {

            };

        // destructor

        virtual ~CCAState()

            {

            iAttributes.Close();

            };

    public: // data

        TInt iStateId;

        RArray<TCAAttribute> iAttributes;

    };

// CLASS DECLARATION

/**

*  Utility class for presence functions

*

*  @lib CAPresence.dll

*  @since 2.1

*/

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

            // although it begins with CA.

    {

    public: // New functions

        /**

        * Decodes given TPresenceAttrEntity (clientType) to storage TClientType

        * @since 2.1

        * @return Storage TClientType

        */

        static TStorageManagerGlobals::TClientType DecodeClientType(

            TCAAttribute aClientTypeAttr );

        /**

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

        * TPresenceStatus

        * @since 2.1

        * @param aStates State-array

        * @param aOnlineAttr Online-attribute

        * @param aIMStatusAttr CommCAP/IM-attribute

        * @param aUserAvailAttr User availability attribute

        * @return Presence TPresenceStatus

        */

        static MCAPresence::TPresenceStatus DecodeOnlineState(

            const RPointerArray<CCAState>& aStates,

            const RPointerArray<MPEngPresenceAttrModel2>& aAttributes );

        /**

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

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

        * @since 2.1

        * @param aUserId WVId of user

        * @param aPresenceStatus Presence status of given user

        * @param aStateOnline Online-array

        * @param aStateOnline aStateOffline-array

        * @param aStateOnline aStateUnknown-array

        */

        static void FillArraysL( const TDesC& aUserId,

                                 TStorageManagerGlobals::TPresenceStatus aPresenceStatus,

                                 CDesCArray *aStateOnline,

                                 CDesCArray *aStateOffline,

                                 CDesCArray *aStateUnknown );

        /**

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

        * @since 3.0

        */

        static void PopulateAttributesL(

            const MPEngPresenceAttrModel2& aModel,

            RPointerArray<MPEngPresenceAttrModel2>& aArray,

            TStorageManagerGlobals::TClientType& aClientType,

            TPtrC& aAlias,

            TPtrC& aStatusText );

        /**

        * Generates array of friends.

        * Array ownership is transferred to caller!!!

        * @since 2.1

        * @param aContactStorage Handle to contact storage

        * appending to result array

        * @return Array of friends.

        */

        static CPtrCArray* GenerateFriendsArrayLC(

            MCAStoredContacts* aContactStorage );

        /**

        * Pushes given array to CleanupStack

        * @since 2.1

        * @param aArray Array to be pushed to CleanupStack

        * @param aOwnsItems Does array own it's objects

        */

        static void PushModelArrayL(

            RPointerArray<MPEngPresenceAttrModel2>& aArray,

            TBool aOwnsItems );

        /**

         * Internally used by IM Presence.

         * Decode the attribute models.

         * @param aParams The structure used when decoding the parameters

         * @return ETrue if all done?

         */

        static TBool DecodeAttrModelsL(

            struct TDecodeAttrParams& aParams

        );

        /**

        * Handles given error.

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

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

        * with presence engine list-handling.

        * @since 2.1

        * @param aError Errorcode

        */

        static void HandleListErrorsL( TInt aError );

        /**

        * Compares two attribute models by presence ids.

        * @since 2.1

        * @param aFirst First model

        * @param aSecond Second model

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

        */

        static TInt CompareAttrModelArray(

            const MPEngPresenceAttrModel2& aFirst,

            const MPEngPresenceAttrModel2& aSecond );

        /**

        * Calls close to given array.

        * @since 2.1

        * @param aObject Array (RPointerArray<MPEngPresenceAttrModel>)

        */

        static void CloseModelArray( TAny* aObject );

        /**

        * Calls ResetAndDestroy to given array

        * @since 2.1

        * @param aObject Array (RPointerArray<MPEngPresenceAttrModel2>)

        */

        static void DestroyCloseModelArray( TAny* aObject );

        /**

        * Creates detailed error description to error container based on

        * information retrieved from given MPEngTransactionStatus

        * @since 2.1

        * @param aStatus Transaction status

        * @param aErrorContainer Error container

        */

        static void HandleTransactionStatusL(

            MPEngTransactionStatus2& aStatus,

            CCAPresenceErrors& aErrorContainer );

        /**

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

        * in PEC range (KPEngErrorBase-KPEngErrorWVServerResponseBase)

        * @since 2.1

        * @param aError Original errorcode

        * @return Mapped errorcode

        */

        static TInt MapErrorPECtoCSP( TInt aError );

        /**

         * Appends contacts in multiple rounds. Used by CIdle.

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

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

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

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

         *        contacts are added to this storage

         * @param aEntryIndex current index were from continue contact

         *                    list handling

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

         *         list handling

         */

        static TBool AppendContactsL( MPEngContactList2* aContactList,

                                      CDesCArray* aWVIds,

                                      CDesCArray* aNicknames,

                                      MCAStoredContacts* aContactStorage,

                                      TInt& aEntryIndex,

                                      MCAContactList& aCaContactList,

                                      MCAPresenceUpdater& aPresenceUpdater );

        /**

         * Reads one attribute from resource

         * @param aResourceId Resource Id

         * @return Attribute

         */

        static TCAAttribute ReadAttributeL( TResourceReader& aReader );

        /**

         * Map resource state id to presence state id

         */

        static TInt MapStateId( TInt aResourceStateId );

        /**

         * Map presence state id to storage state id

         */

        static TStorageManagerGlobals::TPresenceStatus MapPresenceStateId(

            MCAPresence::TPresenceStatus aPresenceStateId );

        /**

         * Reads presence states and attribute combinations from resource

         * @param aResourceId Resource Id

         * @param aStates Containes states on return

         */

        static void ReadStatesFromResourceL( TInt aResourceId,

                                             RPointerArray<CCAState>& aStates );

        /**

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

         */

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

        /**

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

         */

        static const MPEngPresenceAttrModel2* FindAttr( TInt aType,

                                                        const RPointerArray<MPEngPresenceAttrModel2>& aArray );

        /**

         * @return ETrue if states match

         */

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

    };

#endif      // CAPRESENCEUTILS_H

// End of File