MCL/sf/app/im: comparison im_pub/im

equal deleted inserted replaced

--1:000000000000
+:094583676ce7
+/*
+* 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