/*

 * 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