FCL/sf/app/im: comparison inc/ImpsImCli.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:
+*     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