diff -r 6ca72c0fe49a -r a941bc465d9f IMPSengine/inc/ImpsGroupCli.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/IMPSengine/inc/ImpsGroupCli.h Wed Sep 01 12:31:13 2010 +0100 @@ -0,0 +1,482 @@ +/* +* 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 +#include +#include +#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 + +