/*

* 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