/*

* Copyright (c) 2004 Nokia Corporation and/or its subsidiary(-ies). 

* All rights reserved.

* This component and the accompanying materials are made available

* under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members

* which accompanies this distribution, and is available

* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description:  Interface for Instant Messaging services

*

*/

#ifndef OPENAPI_IM_CLIENT_H

#define OPENAPI_IM_CLIENT_H

// INCLUDES

#include <e32base.h>

#include <bamdesca.h>

#include <cntdef.h>

// CONSTANTS

// FORWARD DECLARATIONS

class MImObserver;

class MImClientDetailedError;

// CLASS DECLARATION

/**

*  Instant Messaging interface class

*  This interface class provides methods to send and receive instant messages.

*  Application to be able to receive IMs it must register its own observer

*  using this interface class.

*  This interface can be obtained using a factory method from the CImConnection

*  class.

*

*  @lib imclient.lib

*  @since S60 3.0

*/

class MImClient

    {

    public:

        virtual ~MImClient() {}

        /**

        * Method for registering the IM client to the WV Engine.

        * This method is synchronous.

        * @since S60 3.0

        * @param aObserver observer object used for notifying the user

        *        software

        * @leave KImApiErrAlreadyRegistered if it was registered already or other system wide error code

        */

        virtual void RegisterObserverL(

            MImObserver* aObserver ) = 0;

        /**

        * Method for unregistering the IM Sender from the WV Engine.

        * This method is synchronous method.

        * @since S60 3.0

        */

        virtual void UnregisterObserver( ) = 0;

        /**

        * Method for sending person-to-person text message (UNICODE) using

        * Contact Model IDs. This method is asynchronous and it’s completion

        * is signaled in HandleMessageSentL() method.

        * The method will leave on error. The API specific error codes are

        * in imerrors.h file

        * @since S60 3.0

        * @param aContactItem Contact Model ID of the recipient

        * @param aContent The content of the message in UNICODE

        * @return operation code

        * @leave KImApiErrNotRegistered observer was not registered

        * @leave KImApiErrInvalidContactId the contact ID does not have a corresponding User ID

        */

        virtual TInt SendPToPMessageL(

            const TContactItemId& aContactItem,

            const TDesC16& aContent ) = 0;

        /**

        * Method for sending person-to-person text message (UNICODE) using

        * Contact Model IDs. This method is asynchronous and its completion

        * is signaled in HandleMessageSentL() method.

        * The method will leave on error. The API specific error codes are

        * in imerrors.h file

        * Please note that one contact can have more than one assigned IM user

        * ID. Sending IM to those contacts will result in partial success.

        * @since S60 3.0

        * @param aContactIds Contact Model Ids of the recipient(s)

        * @param aContent The content of the message in UNICODE

        * @return operation code

        * @leave KImApiErrNotRegistered observer was not registered

        * @leave KImApiErrInvalidContactId the contact ID does not have a corresponding User ID

        */

        virtual TInt SendPToPMessageL(

            const CContactIdArray& aContactIds,

            const TDesC16& aContent ) = 0;

        /**

        * Method for sending person-to-person binary (or 8bit text) message

        * using Contact Model IDs. This method is asynchronous and its

        * completion is signaled in HandleMessageSentL() method.

        * The method will leave on error. The API specific error codes are

        * in imerrors.h file

        * Please note that one contact can have more than one assigned IM user

        * ID. Sending IM to those contacts will result in partial success.

        * @since S60 3.0

        * @param aContactIds Contact Model Ids of the recipient(s)

        * @param aContentType MIME type of the content

        * @param aContent The content of the message

        * @return operation code

        *

        * NOTE: Not yet supported!

        */

        virtual TInt SendPToPMessageL(

            const CContactIdArray& aContactIds,

            const TDesC& aContentType,

            const TDesC8& aContent ) = 0;

        /**

        * Method for sending person-to-person text message using

        * directly the User IDs.

        * This method is asynchronous and its completion is signaled

        * in HandleMessageSentL() method.

        * The method will leave on error. The API specific error codes are

        * in imerrors.h file

        * @since S60 3.0

        * @param aUserId the recipient of the message

        * @param aContent the message in UNICODE

        * @return operation code.

        * @leave KImApiErrNotRegistered observer was not registered

        * @leave KImApiErrInvalidUserId wrong User ID

        */

        virtual TInt SendPToPMessageL(

            const TDesC& aUserId,

            const TDesC16& aContent ) = 0;

        /**

        * Method for sending person-to-person text message using

        * directly the User IDs.

        * This method is asynchronous and its completion is signaled

        * in HandleMessageSentL() method.

        * The method will leave on error. The API specific error codes are

        * in imerrors.h file

        * @since S60 3.0

        * @param aUserIds recipient(s) of the message

        * @param aContent the message in UNICODE

        * @return operation code.

        * @leave KImApiErrNotRegistered observer was not registered

        * @leave KImApiErrInvalidUserId wrong User ID

        */

        virtual TInt SendPToPMessageL(

            const MDesCArray& aUserIds,

            const TDesC16& aContent ) = 0;

        /**

        * Method for sending person-to-person binary (or 8 bit text) message

        * using directly the User IDs.

        * This method is asynchronous and its completion is signaled

        * in HandleMessageSentL() method.

        * The method will leave on error. The API specific error codes are

        * in imerrors.h file

        * @since S60 3.0

        * @param aUserIds recipient(s) of the message

        * @param aContentType MIME type of the message

        * @param aContent the message

        * @return operation code.

        *

        * NOTE: Not yet supported!

        */

        virtual TInt SendPToPMessageL(

            const MDesCArray& aUserIds,

            const TDesC& aContentType,

            const TDesC8& aContent ) = 0;

    };

// CLASS DECLARATION

/**

*  Observer interface for Instant Messaging

*  The user shall implement this interface and register it through the MImClient

*  interface to the API to be able to receive IMs

*

*  @lib imclient.lib

*  @since S60 3.0

*/

class MImObserver

    {

    public:

        /**

        * This method is called when the SendPToPMessageL succeeded

        * @since S60 3.0

        * @param aOpCode operation code matching the called functions.

        * @param aErrorCode error codes.

        */

        virtual void HandleMessageSentL(

            const TInt aOpCode,

            const TInt aErrorCode ) = 0;

        /**

        * This method is called when the SendPToPMessageL failed for some reason.

        * If the IM was sent to more recipients the error can be a partial

        * success. In that case the detailed error codes for each user can

        * fetched separately. Please note that the aDetailedError is valid

        * during the function call. After that it gets destroyed in the API.

        * @since S60 3.0

        * @param aOpCode operation code matching the called functions.

        * @param aErrorCode error codes.

        * @param aDetailedError list of errors for each failed user ID.

        */

        virtual void HandleSendErrorL(

            const TInt aOpCode,

            const TInt aErrorCode,

            MImClientDetailedError* aDetailedError ) = 0;

        /**

        * This method is called when a new point-to-point text message

        * has arrived.

        * @since S60 3.0

        * @param aErrorCode error codes (to be defined)

        * @param aContactId Contact model ID of the sender

        * @param aUserId UserID of the message sender

        * @param aMessageType MIME type of the received message

        * @param aContent the message in UNICODE

        */

        virtual void HandleNewPToPMessageL(

            const TInt aErrorCode,

            const TContactItemId  aContactId,

            const TDesC& aUserId,

            const TDesC& aMessageType,

            const TDesC16& aContent ) = 0;

        /**

        * This method is called when a new point-to-point message (8bit)

        * has arrived. The message can be text or binary data.

        * @since S60 3.0

        * @param aErrorCode error codes (to be defined)

        * @param aContactId Contact model ID of the sender

        * @param aUserId UserID of the message sender

        * @param aMessageType MIME type of the received message

        * @param aContent the message

        *

        * NOTE: Not yet supported!

        */

        virtual void HandleNewPToPMessageL(

            const TInt aErrorCode,

            const TContactItemId  aContactId,

            const TDesC& aUserId,

            const TDesC& aMessageType,

            const TDesC8& aContent ) = 0;

    };

// CLASS DECLARATION

/**

*  Detailed errors accessor class

*  @lib imclient.lib

*  @since S60 3.0

*/

class MImClientDetailedError

    {

    public:

        /**

        * Gets the number of failed User IDs

        * @since S60 3.0

        * @return number of failed user IDs

        */

        virtual TInt Count() = 0;

        /**

        * Gets the failed User ID

        * @since S60 3.0

        * @param aIndex index of the user in the list

        * @return failed user ID

        */

        virtual const TDesC& UserId( TInt aIndex ) = 0;

        /**

        * Gets the reason of the failure. The API specific error codes are

        * defined in imerrors.h file.

        * @since S60 3.0

        * @param aIndex index of the user in the list

        * @return the fail reason

        */

        virtual TInt ErrorCode( TInt aIndex ) = 0;

    };

#endif

// End of File