/*
* 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 "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 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