--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/inc/ImpsGroupCli.h Thu Dec 17 08:41:52 2009 +0200
@@ -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 <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
+
+