--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/inc/ImpsImCli.h Wed Sep 01 12:31:13 2010 +0100
@@ -0,0 +1,392 @@
+/*
+* 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