MCL/sf/app/im: comparison inc/ImpsGroupCli.h

equal deleted inserted replaced

--1:000000000000
+:094583676ce7
+/*
+* 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