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