/*

* 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: 

*     WV engine group feature interface.

*

*/

#ifndef RImpsGroupCli_H

#define RImpsGroupCli_H

// INCLUDES

#include <e32base.h>

#include <badesca.h>

#include <bamdesca.h>

#include "impsconst.h"

#include "impsgroupprops.h"

#include "impsclient.h"

// FORWARD DECLARATIONS

class CImpsGroupHandler2;

class MImpsGroupHandler2;

class CImpsGroupCommand2;

// CLASS DECLARATION

/**

*  RImpsGroupClient2 API

*

*  Applications use the subsystem via RImpsGroupClient2 class. First, they 

*  need to connect to the server by calling RegisterL() member function. 

*  

*  When everything is done, call Unregister() to end

*  the session.

*

*  A user of this API must be aware that raising/releasing

*  the PDP context may affect the response times of called functions.

*

*  Observer methods:

*  -----------------------

*  Client can be notified when a certain type of message is received 

*  from the remote server.

*  Client has to be connected in the server in order to get notify events.

*  If the client is disconnected by server by calling Unregister(), all notify

*  requests and possible incoming events are canceled. 

*

*  Notify events are session-specific, 

*  ie. if you have several RImpsGroupClients

*  connected to the server, each has its own notify requests. 

*

*  In order to use notify services, you need to implement MImpsGroupHandler2 

*  and give a pointer to your class in RegisterL.

*  Observer method doesn't need to do anything else than your 

*  application needs it to do.

*

*

*/

class RImpsGroupClient2 : public RImpsClient2

    {

    public: // Constructors and destructor

        /**

        * C++ default constructor.

        */      

        IMPORT_C RImpsGroupClient2();

    public: // New functions        

        // INITILIZATION AND CONNECT

        /**

        * Registers the listener object for Group events and connects to

        * the Symbian Server.

        * Leaves with KImpsErrorAlreadyInUse if the client 

        * has already registered.

        * @param aEngine WV Engine server instance

        * @param aObserver The observer instance.

        * @param aClientId Client-Id for requests if non zero length.

        * @param aReceiveNew determines if new pushed messages are received.

        *        If EFalse then new messages are filtered out and 

        *        responses to own requests are deliverd only.

        * @param aPriority Observer priority. Refers to CActive priority.

        */

        IMPORT_C void RegisterL( RImpsEng& aEngine, 

                                 MImpsGroupHandler2* aObserver,

                                 const TDesC& aClientId,

                                 TBool aReceiveNew = ETrue,

                                 TInt aPriority = CActive::EPriorityStandard );

        /**

        * Unregisters the listener object and disconnects from 

        * the Symbian OS server.

        */

        IMPORT_C void Unregister();

        // WV PROTOCOL REQUESTS

        /**

        * Create a group.

        * MImpsGroupHandler2::HandleCompleteL handles the server response.

        * Leaves if out of memory before sending a message 

        * to the Symbian OS server.

        * @param aGroupId group id

        * @param aProperties initial group properties

        * @param aScreenName, ScreenName of the user

        * @param aJoingGroup indicates that the newly created group is  

        *        joined (or not) at creation time.

        * WV CSP static conformance has the statement CREAG-5.

        * CREAG-5:

        *       If the JoinGroup transaction was not agreed during

        *       service negotiation from either server or client side,

        *       the Join-Group flag in the CreateGroupRequest

        *       primitive indicates ‘F’ (false).

        * @param aSubscribeNotification indicates if we subscribe notification.

        * @return operation-id (positive)

        */

        IMPORT_C TInt CreateGroupL( const TDesC& aGroupId,

                                    const CImpsCommonGroupProps* aProperties,

                                    const TDesC& aScreenName,

                                    TBool aJoinGroup,

                                    TBool aSubscribeNotification = EFalse );

        /**

        * Delete a group.

        * MImpsGroupHandler2::HandleCompleteL handles the server response.

        * Leaves if out of memory before sending a 

        * message to the Symbian OS server.

        * @param aGroupId group id

        * @return operation-id (positive)

        */

        IMPORT_C TInt DeleteGroupL( const TDesC& aGroupId );

        /**

        * Join a group.

        * MImpsGroupHandler2::HandleJoinL handles the server response.

        * Leaves if out of memory before sending a message 

        * to the Symbian OS server.

        * @param aGroupId group id

        * @param aScreenName screen name for the user, 

        *  optional (may be zero length)

        * @param aUsers ETrue if a user wants to get list of joined 

        *  users in a reponse,

        * @param aSubscribeNotification indicates if we subscribe notification.

        * @return operation-id (positive)

        */

        IMPORT_C TInt JoinGroupL( const TDesC& aGroupId,

                                  const TDesC& aScreenName,

                                  TBool aUsers,

                                  TBool aSubscribeNotification = EFalse );

        /**

        * Leave a group.

        * MImpsGroupHandler2::HandleLeaveL handles the server response.

        * Leaves if out of memory before sending a message 

        * to the Symbian OS server.

        * @param aGroupId group id

        * @return operation-id (positive)

        */

        IMPORT_C TInt LeaveGroupL( const TDesC& aGroupId );

        /**

        * Get group members.

        * MImpsGroupHandler2::HandleGroupMembersL handles the server response.

        * Leaves if out of memory before sending a message 

        * to the Symbian OS server.

        * @param aGroupId group id

        * @return operation-id (positive)

        */

        IMPORT_C TInt GroupMembersL( const TDesC& aGroupId );

        /**

        * Add group members.

        * The new users' type is ordinary initially. 

        * MImpsGroupHandler2::HandleCompleteL handles the server response.

        * Leaves if out of memory before sending a 

        * message to the Symbian OS server. Leaves with 

        * KErrArgument if both aUserList and aScreenNameList are empty

        * @param aGroupId target group id

        * @param aUserList list of users to be added (user-ids)

        * @param aScreenNameList Screennames of the users

        * @return operation-id (positive)

        */

        IMPORT_C TInt AddMembersL( const TDesC& aGroupId,

                                   const MDesCArray& aUserList,

                                   const MDesCArray& aScreenNameList );

        /**

        * Remove group members.

        * MImpsGroupHandler2::HandleCompleteL handles the server response.

        * Leaves if out of memory before sending a 

        * message to the Symbian OS server.

        * Leaves with KErrArgument if aUserList is empty

        * @param aGroupId target group id

        * @param aUserList list of users to be removed

        * @return operation-id (positive)

        */

        IMPORT_C TInt RemoveMembersL( const TDesC& aGroupId,

                                      const MDesCArray& aUserList );

        /**

        * Modify members' access rights.

        * MImpsGroupHandler2::HandleCompleteL handles the server response.

        * Leaves if out of memory before sending a 

        * message to the Symbian OS server.

        * @param aGroupId target group id

        * @param aAdminList list of new administrators user-ids

        * @param aModerList list of new moderators user-ids

        * @param aOrdinaryList list of new ordinary users user-ids

        * @return operation-id (positive)

        */

        IMPORT_C TInt ModifyMembersAccessL( const TDesC& aGroupId,

                                            const MDesCArray* aAdminList,

                                            const MDesCArray* aModerList,

                                            const MDesCArray* aOrdinaryList );

        /**

        * Get group properties.

        * MImpsGroupHandler2::HandleGroupPropertiesL 

        * handles the server response.

        * Leaves if out of memory before sending a 

        * message to the Symbian OS server.

        * @param aGroupId target group id

        * @return operation-id (positive)

        */

        IMPORT_C TInt GroupPropertiesL( const TDesC& aGroupId );

        /**

        * Set group properties.

        * MImpsGroupHandler2::HandleCompleteL handles the server response.

        * Leaves if out of memory before sending a message 

        * to the Symbian OS server.

        * @param aGroupId target group id

        * @param aGroupProps common properties

        * @param aOwnProps user's own properties

        * @return operation-id (positive)

        */

        IMPORT_C TInt SetGroupPropertiesL( const TDesC& aGroupId,

                                           const CImpsCommonGroupProps* aGroupProps,

                                           const CImpsPrivateGroupProps* aOwnProps );

        /**

        * Update or get list of rejected users.

        * MImpsGroupHandler2::HandleRejectListL handles the server response.

        * If you want to get the current reject list only, then

        * give aGroupId parameter only.

        * Leaves if out of memory before sending a message 

        * to the Symbian OS server.

        * @param aGroupId target group id

        * @param aRejectedList users to be added to the reject list (user-ids)

        *        May be NULL.

        * @param aEnabledList users to be removed from 

        *        the reject list (user-ids). May be NULL.

        * @return operation-id (positive)

        */

        IMPORT_C TInt SetRejectListL( const TDesC& aGroupId,

                                      const MDesCArray* aRejectedList,

                                      const MDesCArray* aEnabledList );

        /**

        * Subscribe group change notice.

        * MImpsGroupHandler2::HandleCompleteL handles the server response.

        * After successfull subscription HandleGroupPropertiesL,

        * HandleNewUsersL and HandleLeftUsersL methods are called

        * whenever remote service sends notifications. 

        * Leaves if out of memory before sending a message 

        * to the Symbian OS server.

        * @param aGroupId group id

        * @return operation-id (positive)

        */

        IMPORT_C TInt SubscribeL( const TDesC& aGroupId );

        /**

        * Unsubscribe group change notice.

        * MImpsGroupHandler2::HandleCompleteL handles the server response.

        * Leaves if out of memory before sending a message 

        * to the Symbian OS server.

        * @param aGroupId group id

        * @return operation-id (positive)

        */

        IMPORT_C TInt UnsubscribeL( const TDesC& aGroupId );

        /**

        * Check the group change subscription status.

        * MImpsGroupHandler2::HandleSubscriptionL handles the server response.

        * Leaves if out of memory before sending a message 

        * to the Symbian OS server.

        * @param aGroupId group id

        * @return operation-id (positive)

        */

        IMPORT_C TInt CheckSubscriptionL( const TDesC& aGroupId );

        /**

        * Pointer to the observer handler

        * @return handler

        */

        MImpsGroupHandler2* Handler();

    private: // New functions

        /**

        * Registers the listener object for Fund events and connects to

        * the Symbian OS Server.

        * @param aEngine WV Engine server instance

        * @param aHandler the observer

        * @return general error code

        */

        TInt DoRegister( RImpsEng& aEngine,

                         CImpsHandler2* aHandler );

    private: // data

        MImpsGroupHandler2*      iHandlerCallBack;

        CImpsGroupCommand2*      iCommand;

    private: // friend classes

        friend class CImpsGroupCommand2;

    };

// CLASS DECLARATION

/**

* MImpsGroupHandler2

*

* Abstract interface for handling the notify events from the server.

* User derives his class from this and implements the observer methods below.

*/

class MImpsGroupHandler2

    {

    public:

    /**

    * Handles a response of CreateGroupL, DeleteGroupL, AddMembersL, 

    * RemoveMembersL, ModifyMembersAccessL, SubscribeL, UnsubscribeL.

    * @param aOpId  operation id to map responses to the requests.

    * @param aCspId CSP session identifier

    */

    virtual void HandleCompleteL( TInt aOpId,

                                  TImpsCspIdentifier& aCspId )  = 0;

    /**

    * Handles JoinGroupL response.

    * Leaves with KErrEof if no more data.

    * @param aOpId  operation id to map responses to the requests.

    * @param aUserList list of joined users if requested.

    * @param aScreenNames list of screen names if requested

    * @param aWelcomeText welcome text from remote service. 

    * @param aCspId CSP session identifier

    */

    virtual void HandleJoinL( TInt aOpId,

                              const MDesCArray& aUserList,

                              const MDesCArray& aScreenNames,        

                              const TDesC& aWelcomeText,

                              TImpsCspIdentifier& aCspId )  = 0;

    /**

    * Handles GroupMembersL response.

    * Leaves with KErrEof if no more data.

    * @param aOpId  operation id to map responses to the requests.

    * @param aUserList list of users of ordinary users

    * @param aScreenNames list of screen names of ordinary users

    * @param aModers list of moderators (user-ids)

    * @param aAdmins list of administrators

    * @param aCspId CSP session identifier

    */

    virtual void HandleGroupMembersL( TInt aOpId,

                                      const MDesCArray& aUserList,

                                      const MDesCArray& aScreenNames,

                                      const MDesCArray& aModers,

                                      const MDesCArray& aAdmins,

                                      TImpsCspIdentifier& aCspId )  = 0;

    /**

    * Handles GroupPropertiesL response and subscribed notification.

    * @param aOpId  operation id to map responses to the requests.

    *        This is 0 if event is initiated by remote service based on the

    *        group change notification subscription.

    * @param aGroupId group id, presnet only if aOpId is 0.

    * @param aGroupProps common properties

    * @param aOwnProps user's own properties

    * @param aCspId CSP session identifier

    */

    virtual void HandleGroupPropertiesL( TInt aOpId,

                                         const TDesC& aGroupId,

                                         const CImpsCommonGroupProps& aGroupProps,

                                         const CImpsPrivateGroupProps& aOwnProps, 

                                         TImpsCspIdentifier& aCspId )  = 0;

    /**

    * Handles SetRejectListL response.

    * Leaves with KErrEof if no more data.

    * @param aOpId  operation id to map responses to the requests.

    * @param aUserList list of rejected users in reject list

    * @param aCspId CSP session identifier

    */

    virtual void HandleRejectListL( TInt aOpId,

                                    const MDesCArray& aUserList,

                                    TImpsCspIdentifier& aCspId )  = 0;

    /**

    * Handles CheckSubscriptionL response.

    * @param aOpId  operation id to map responses to the requests.

    * @param aIsSubscribed ETrue if group is subscribed.

    * @param aCspId CSP session identifier

    */

    virtual void HandleSubscriptionL( TInt aOpId,

                                      TBool aIsSubscribed,

                                      TImpsCspIdentifier& aCspId )  = 0;

    /**

    * Handles group change notification about new users.

    *  Error indicates internal error.

    * @param aGroupId group id

    * @param aUserList list of joined users

    * @param aScreenNames list of screen names

    * @param aCspId CSP session identifier

    */

    virtual void HandleNewUsersL(

        const TDesC& aGroupId,

        const MDesCArray& aUserList,

        const MDesCArray& aScreenNames,

        TImpsCspIdentifier& aCspId )  = 0;

    /**

    * Handles group change notification about users left.

    * Error indicates internal error.

    * @param aGroupId group id

    * @param aUserList list of users left

    * @param aScreenNames list of screen names

    * @param aCspId CSP session identifier

    */

    virtual void HandleLeftUsersL(

        const TDesC& aGroupId,

        const MDesCArray& aUserList,

        const MDesCArray& aScreenNames,

        TImpsCspIdentifier& aCspId )  = 0;

    /**

    * Handles both LeaveGroupL response and a service 

    * initiated group leave situation.

    * Leaves with KErrEof if no more data.

    * @param aOpId  operation id to map responses to the requests. 

    *        This is 0 if operation is initiated by a remote service.

    * @param aGroupId group id

    * @param aDescription textual description of the leave

        * @param aCspId CSP session identifier

    */

    virtual void HandleLeaveL(

        TInt aOpId,

        const TDesC& aGroupId,

        const TDesC& aDescription,

        TImpsCspIdentifier& aCspId )  = 0;

    };

#endif 

// End of File