/*
* 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:
* Interface for WV IM services.
*
*/
#ifndef IMPS_IM_CLIENT_H
#define IMPS_IM_CLIENT_H
// INCLUDES
#include <e32base.h>
#include <badesca.h>
#include <bamdesca.h>
#include "impsconst.h"
#include "impsclient.h"
// CONSTANTS
// FORWARD DECLARATIONS
class MImpsImHandler2;
class MImpsBlockingHandler2;
class CImpsImCommand2;
// CLASS DECLARATION
/**
* RImpsImClient2 API
*
* Applications use IM service via RImpsImClient2 class. First, they need to
* connect to the server by calling RegisterL() member function.
* Immediately after that an error handler must be registered by
* RegisterErrorObserverL.
*
* 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 RImpsImClients
* connected to the server, each has its own notify requests.
*
* In order to use notify services, you need to implement MImpsImHandler2
* 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.
*
*
* Addressing:
* -----------
* WV CSP specification defines characters that must be escaped if they
* occur within the User-ID, Resource or Domain portions of a Wireless Village
* address. WV engine does NOT escape those characters on behalf of user
* application. WV CSP also denies usage of certain characters in UserID
* totally.
*
*/
// CLASS DECLARATION
class RImpsImClient2 : public RImpsClient2
{
public: // Constructors and destructor
/**
* C++ default constructor.
*/
IMPORT_C RImpsImClient2();
public: // New functions
// INITILIZATION AND CONNECT
/**
* Registers the listener object for IM events and connects to
* the Symbian OS Server.
* Leaves with KImpsErrorAlreadyInUse if the client
* has already registered.
* @param aEngine WV Engine server instance
* @param aObserver new message observer. May be NULL.
* @param aBlockingHandler block feature observer. May be NULL.
* @param aClientId Client-Id. If non zero length then new messages
* having this Client-Id only are delivered
* when aReceiveNew is ETrue.
* @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. Refer to CActive priority.
*/
IMPORT_C void RegisterL( RImpsEng& aEngine,
MImpsImHandler2* aImpsObserver,
MImpsBlockingHandler2* aBlockingHandler,
const TDesC& aClientId,
TBool aReceiveNew = ETrue,
TInt aPriority = CActive::EPriorityStandard );
/**
* Unregisters listener objects and disconnects from the Symbian server.
*/
IMPORT_C void Unregister();
// MESSAGING
/**
* Send a text message.
* MImpsImHandler2 handles the server response.
* Leaves if out of memory before sending a message to the SOS server.
* If sender information is not given then WV engine inserts user's
* UserId as a sender.
* Recipient must be specified, i.e. at least aUserIds or aGroupId
* must be specified.
* Errors are handled by MImpsErrorHandler2.
* @param aSenderSn, sender's screen name. Optional.
* @param aUserIds recipients UserID, optional
* @param aGroupId, optional.
* 1) Group recipient as such or
* 2) GroupID for aScreenNames.
* GroupID is used as Recipient( Group ( GroupID ) ) only if
* aScreenNames is omitted.
* @param aScreenNames recipients' screen names in the group, optional
* Recipient(Group*(ScreenName( SName)))
* @param aContent UNICODE text/plain content
* @param aDeliveryReportWanted True, if the user wats to
* order delivery report. HandleDeliveryReportL from
* MImpsImHandler handles the arriving report.
* @return operation-id
*/
IMPORT_C TInt SendTextMessageL( const TDesC* aSenderSn,
const MDesCArray* aUserIds,
const TDesC* aGroupId,
const MDesCArray* aScreenNames,
const TDesC& aContent,
TBool aDeliveryReportWanted );
/**
* Send a message with binary content.
* MImpsImHandler2 handles the server response.
* Leaves if out of memory before sending a message to the SOS server.
* Leaves with KErrNotSupported if the content type is not supported.
* If sender information is not given then WV engine inserts user's
* UserId as a sender.
* Recipient must be specified, i.e. at least aUserIds or aGroupId
* must be specified.
* Errors are handled by MImpsErrorHandler2.
* @param aSenderSn, sender's screen name. Optional.
* @param aUserIds recipients UserID, optional
* @param aGroupId, optional.
* 1) Group recipient as such or
* 2) GroupID for aScreenNames.
* GroupID is used as Recipient( Group ( GroupID ) ) only if
* aScreenNames is omitted.
* @param aScreenNames recipients' screen names in the group, optional
* Recipient(Group*(ScreenName( SName)))
* @param aContentType MIME type of the content
* @param aContent The content of the message
* @param aDeliveryReportWanted True, if the user wats to
* order delivery report. HandleDeliveryReportL from
* MImpsImHandler2 handles the arriving report.
* @return operation-id
*/
IMPORT_C TInt SendContentMessageL( const TDesC* aSenderSn,
const MDesCArray* aUserIds,
const TDesC* aGroupId,
const MDesCArray* aScreenNames,
const TDesC& aContentType,
const TDesC8& aContent,
TBool aDeliveryReportWanted );
/**
* Block, UnBlock, Grant, UnGrant users based on UserID
* MImpsBlockHandler2 handles successful server response.
* Errors are handled by MImpsErrorHandler2
* @param aBlockEntity entities to be blocked
* @param aUnBlockEntity entities to be unblocked
* @param aBlockedListInUse is blocked list in use or not
* @param aGrantedEntityList entities to be granted
* @param aUnGrantEntity entities to be ungranted
* @param aGrantedListInUse is granted list in use or not
* @return operation-id
*/
IMPORT_C TInt BlockEntityRequestL( const MDesCArray* aBlockEntity,
const MDesCArray* aUnBlockEntity,
TBool aBlockedListInUse,
const MDesCArray* aGrantedEntityList,
const MDesCArray* aUnGrantEntity,
TBool aGrantedListInUse );
/**
* Get Blocked and granted users list from server
* Supports only UserIDs in response.
* MImpsBlockHandler2 handles successful server response.
* Errors are handled by MImpsErrorHandler2
* @return operation-id
*/
IMPORT_C TInt GetBlockedListRequestL();
/**
* Pointer to the observer handler
* @return handler
*/
MImpsImHandler2* Handler();
/**
* Pointer to the block observer handler
* @return handler
*/
MImpsBlockingHandler2* BlockHandler();
private: // New functions
/**
* Registers the listener object for Access 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
MImpsImHandler2* iImHandlerCallback;
MImpsBlockingHandler2* iBlockingHandlerCallback;
CImpsImCommand2* iCommand;
TPtrC8 iMessagePtr;
private: // friend classes
friend class CImpsImCommand;
};
// CLASS DECLARATION
/**
* MImpsImHandler2
*
* Abstract interface for handling the notify events from the server.
* User derives his class from this and implements the methods below.
*/
class MImpsImHandler2
{
public: // New functions
/**
* Observer method for incoming instant message
* @param aOpId operation id map response to the
* GetMessageFromServerL request.
* For new "pushed" messages this is 0.
* Operation code may be 0 if the event is no consequence of
* the request from this session. (e.g. GetMessage)
* @param aMessageId message-id
* @param aSender message sender, UserID or ScreenName if aGroupId
* @param aGroupId GroupID for ScreenName in aSender, may be zero length.
* If aRecipients and aScreenNames are empty then this specifies
* message recipient too.
* @param aRecipients recipients, UserIDs
* @param aScreenNames screen name recipients,
* Recipient(Group(ScreenName, SName ))
* The groups for screen names are in aSnGroups.
* @param aText message text in UNICODE format.
* @param aCspId CSP session identifier
*/
virtual void HandleNewTextMessageL( TInt aOpId,
const TDesC& aMessageId,
const TDesC& aSender,
const TDesC& aGroupId,
const MDesCArray& aRecipients,
const MDesCArray& aScreenNames,
const TDesC& aText,
TImpsCspIdentifier& aCspId ) = 0;
/**
* Observer method for incoming content message
* @param aOpId operation id map response to the
* GetMessageFromServerL request.
* For new "pushed" messages this is 0.
* Operation code may be 0 if the event is no consequence of
* the request from this session. (e.g. GetMessage)
* @param aMessageId message-id
* @param aSender message sender, UserID or ScreenName if aGroupId
* @param aGroupId GroupID for ScreenName in aSender, may be zero length.
* If aRecipients and aScreenNames are empty then this specifies
* message recipient too.
* @param aRecipients recipients, UserIDs
* @param aScreenNames screen name recipients,
* Recipient(Group(ScreenName, SName ))
* The groups for screen names are in aSnGroups.
* @param aContentType MIME type of the content
* @param aContent The content of the message
* @param aCspId CSP session identifier
*/
virtual void HandleNewContentMessageL( TInt aOpId,
const TDesC& aMessageId,
const TDesC& aSender,
const TDesC& aGroupId,
const MDesCArray& aRecipients,
const MDesCArray& aScreenNames,
const TDesC& aContentType,
const TDesC8& aContent,
TImpsCspIdentifier& aCspId ) = 0;
/**
* Observer for message send completion.
* This means that SAP has confirmed the send transaction.
* Common for all kind of messages.
* @param aOpId operation id to map responses to the requests.
* @param aDeliveryReportOrdered ETrue if delivery report wanted.
* @param aCspId CSP session identifier
*/
virtual void HandleSendCompleteL( TInt aOpId,
TBool aDeliveryReportOrdered,
TImpsCspIdentifier& aCspId ) = 0;
/**
* Observer for delivery report request.
* This means that SAP has delivered the message to all recipients.
* @param aMessageId MessageID from message that has been delivered.
* @param aResult result code
* @param aDescripton result description or NULL
* @param aCspId CSP session identifier
*/
virtual void HandleDeliveryReportL( const TDesC& aMessageId,
TInt aResult,
const TDesC* aDescription,
TImpsCspIdentifier& aCspId ) = 0;
};
//Handler
class MImpsBlockingHandler2
{
public:
/**
* Handler for GetBlockedListRequestL reponse
* @param aBlockedList list of blocked users identified by UserID
* @param aBlockedListInUse is blocked list use or not
* @param aGrantedList list of granted users identified by UserID
* @param aGranedListInUse is granted list use or not
* @param aCspId CSP session identifier
*/
virtual void GetBlockedListResponseL( const MDesCArray* aBlockedList,
TBool aBlockedListInUse,
const MDesCArray* aGrantedList,
TBool aGrantedListInUse,
TImpsCspIdentifier& aCspId ) = 0;
/**
* Handler for BlockEntityRequestL response
* @param aOpId operation id to map responses to the requests.
* @param aCspId CSP session identifier
*/
virtual void HandleCompleteL( TInt aOpId,
TImpsCspIdentifier& aCspId ) = 0;
};
#endif