williamr@2: /* williamr@2: * Copyright (c) 2004 Nokia Corporation and/or its subsidiary(-ies). williamr@2: * All rights reserved. williamr@2: * This component and the accompanying materials are made available williamr@2: * 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 williamr@2: * which accompanies this distribution, and is available williamr@2: * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html". williamr@2: * williamr@2: * Initial Contributors: williamr@2: * Nokia Corporation - initial contribution. williamr@2: * williamr@2: * Contributors: williamr@2: * williamr@2: * Description: Interface for Instant Messaging services williamr@2: * williamr@2: */ williamr@2: williamr@2: williamr@2: #ifndef OPENAPI_IM_CLIENT_H williamr@2: #define OPENAPI_IM_CLIENT_H williamr@2: williamr@2: // INCLUDES williamr@2: #include williamr@2: #include williamr@2: #include williamr@2: williamr@2: // CONSTANTS williamr@2: williamr@2: // FORWARD DECLARATIONS williamr@2: class MImObserver; williamr@2: class MImClientDetailedError; williamr@2: williamr@2: // CLASS DECLARATION williamr@2: /** williamr@2: * Instant Messaging interface class williamr@2: * This interface class provides methods to send and receive instant messages. williamr@2: * Application to be able to receive IMs it must register its own observer williamr@2: * using this interface class. williamr@2: * This interface can be obtained using a factory method from the CImConnection williamr@2: * class. williamr@2: * williamr@2: * @lib imclient.lib williamr@2: * @since S60 3.0 williamr@2: */ williamr@2: class MImClient williamr@2: { williamr@2: williamr@2: public: williamr@2: williamr@2: virtual ~MImClient() {} williamr@2: williamr@2: /** williamr@2: * Method for registering the IM client to the WV Engine. williamr@2: * This method is synchronous. williamr@2: * @since S60 3.0 williamr@2: * @param aObserver observer object used for notifying the user williamr@2: * software williamr@2: * @leave KImApiErrAlreadyRegistered if it was registered already or other system wide error code williamr@2: */ williamr@2: virtual void RegisterObserverL( williamr@2: MImObserver* aObserver ) = 0; williamr@2: williamr@2: /** williamr@2: * Method for unregistering the IM Sender from the WV Engine. williamr@2: * This method is synchronous method. williamr@2: * @since S60 3.0 williamr@2: */ williamr@2: virtual void UnregisterObserver( ) = 0; williamr@2: williamr@2: /** williamr@2: * Method for sending person-to-person text message (UNICODE) using williamr@2: * Contact Model IDs. This method is asynchronous and it’s completion williamr@2: * is signaled in HandleMessageSentL() method. williamr@2: * The method will leave on error. The API specific error codes are williamr@2: * in imerrors.h file williamr@2: * @since S60 3.0 williamr@2: * @param aContactItem Contact Model ID of the recipient williamr@2: * @param aContent The content of the message in UNICODE williamr@2: * @return operation code williamr@2: * @leave KImApiErrNotRegistered observer was not registered williamr@2: * @leave KImApiErrInvalidContactId the contact ID does not have a corresponding User ID williamr@2: */ williamr@2: virtual TInt SendPToPMessageL( williamr@2: const TContactItemId& aContactItem, williamr@2: const TDesC16& aContent ) = 0; williamr@2: williamr@2: /** williamr@2: * Method for sending person-to-person text message (UNICODE) using williamr@2: * Contact Model IDs. This method is asynchronous and its completion williamr@2: * is signaled in HandleMessageSentL() method. williamr@2: * The method will leave on error. The API specific error codes are williamr@2: * in imerrors.h file williamr@2: * Please note that one contact can have more than one assigned IM user williamr@2: * ID. Sending IM to those contacts will result in partial success. williamr@2: * @since S60 3.0 williamr@2: * @param aContactIds Contact Model Ids of the recipient(s) williamr@2: * @param aContent The content of the message in UNICODE williamr@2: * @return operation code williamr@2: * @leave KImApiErrNotRegistered observer was not registered williamr@2: * @leave KImApiErrInvalidContactId the contact ID does not have a corresponding User ID williamr@2: */ williamr@2: virtual TInt SendPToPMessageL( williamr@2: const CContactIdArray& aContactIds, williamr@2: const TDesC16& aContent ) = 0; williamr@2: williamr@2: /** williamr@2: * Method for sending person-to-person binary (or 8bit text) message williamr@2: * using Contact Model IDs. This method is asynchronous and its williamr@2: * completion is signaled in HandleMessageSentL() method. williamr@2: * The method will leave on error. The API specific error codes are williamr@2: * in imerrors.h file williamr@2: * Please note that one contact can have more than one assigned IM user williamr@2: * ID. Sending IM to those contacts will result in partial success. williamr@2: * @since S60 3.0 williamr@2: * @param aContactIds Contact Model Ids of the recipient(s) williamr@2: * @param aContentType MIME type of the content williamr@2: * @param aContent The content of the message williamr@2: * @return operation code williamr@2: * williamr@2: * NOTE: Not yet supported! williamr@2: */ williamr@2: virtual TInt SendPToPMessageL( williamr@2: const CContactIdArray& aContactIds, williamr@2: const TDesC& aContentType, williamr@2: const TDesC8& aContent ) = 0; williamr@2: williamr@2: /** williamr@2: * Method for sending person-to-person text message using williamr@2: * directly the User IDs. williamr@2: * This method is asynchronous and its completion is signaled williamr@2: * in HandleMessageSentL() method. williamr@2: * The method will leave on error. The API specific error codes are williamr@2: * in imerrors.h file williamr@2: * @since S60 3.0 williamr@2: * @param aUserId the recipient of the message williamr@2: * @param aContent the message in UNICODE williamr@2: * @return operation code. williamr@2: * @leave KImApiErrNotRegistered observer was not registered williamr@2: * @leave KImApiErrInvalidUserId wrong User ID williamr@2: */ williamr@2: virtual TInt SendPToPMessageL( williamr@2: const TDesC& aUserId, williamr@2: const TDesC16& aContent ) = 0; williamr@2: williamr@2: /** williamr@2: * Method for sending person-to-person text message using williamr@2: * directly the User IDs. williamr@2: * This method is asynchronous and its completion is signaled williamr@2: * in HandleMessageSentL() method. williamr@2: * The method will leave on error. The API specific error codes are williamr@2: * in imerrors.h file williamr@2: * @since S60 3.0 williamr@2: * @param aUserIds recipient(s) of the message williamr@2: * @param aContent the message in UNICODE williamr@2: * @return operation code. williamr@2: * @leave KImApiErrNotRegistered observer was not registered williamr@2: * @leave KImApiErrInvalidUserId wrong User ID williamr@2: */ williamr@2: virtual TInt SendPToPMessageL( williamr@2: const MDesCArray& aUserIds, williamr@2: const TDesC16& aContent ) = 0; williamr@2: williamr@2: /** williamr@2: * Method for sending person-to-person binary (or 8 bit text) message williamr@2: * using directly the User IDs. williamr@2: * This method is asynchronous and its completion is signaled williamr@2: * in HandleMessageSentL() method. williamr@2: * The method will leave on error. The API specific error codes are williamr@2: * in imerrors.h file williamr@2: * @since S60 3.0 williamr@2: * @param aUserIds recipient(s) of the message williamr@2: * @param aContentType MIME type of the message williamr@2: * @param aContent the message williamr@2: * @return operation code. williamr@2: * williamr@2: * NOTE: Not yet supported! williamr@2: */ williamr@2: virtual TInt SendPToPMessageL( williamr@2: const MDesCArray& aUserIds, williamr@2: const TDesC& aContentType, williamr@2: const TDesC8& aContent ) = 0; williamr@2: williamr@2: }; williamr@2: williamr@2: williamr@2: // CLASS DECLARATION williamr@2: /** williamr@2: * Observer interface for Instant Messaging williamr@2: * The user shall implement this interface and register it through the MImClient williamr@2: * interface to the API to be able to receive IMs williamr@2: * williamr@2: * @lib imclient.lib williamr@2: * @since S60 3.0 williamr@2: */ williamr@2: class MImObserver williamr@2: { williamr@2: williamr@2: public: williamr@2: williamr@2: /** williamr@2: * This method is called when the SendPToPMessageL succeeded williamr@2: * @since S60 3.0 williamr@2: * @param aOpCode operation code matching the called functions. williamr@2: * @param aErrorCode error codes. williamr@2: */ williamr@2: virtual void HandleMessageSentL( williamr@2: const TInt aOpCode, williamr@2: const TInt aErrorCode ) = 0; williamr@2: williamr@2: /** williamr@2: * This method is called when the SendPToPMessageL failed for some reason. williamr@2: * If the IM was sent to more recipients the error can be a partial williamr@2: * success. In that case the detailed error codes for each user can williamr@2: * fetched separately. Please note that the aDetailedError is valid williamr@2: * during the function call. After that it gets destroyed in the API. williamr@2: * @since S60 3.0 williamr@2: * @param aOpCode operation code matching the called functions. williamr@2: * @param aErrorCode error codes. williamr@2: * @param aDetailedError list of errors for each failed user ID. williamr@2: */ williamr@2: virtual void HandleSendErrorL( williamr@2: const TInt aOpCode, williamr@2: const TInt aErrorCode, williamr@2: MImClientDetailedError* aDetailedError ) = 0; williamr@2: williamr@2: /** williamr@2: * This method is called when a new point-to-point text message williamr@2: * has arrived. williamr@2: * @since S60 3.0 williamr@2: * @param aErrorCode error codes (to be defined) williamr@2: * @param aContactId Contact model ID of the sender williamr@2: * @param aUserId UserID of the message sender williamr@2: * @param aMessageType MIME type of the received message williamr@2: * @param aContent the message in UNICODE williamr@2: */ williamr@2: virtual void HandleNewPToPMessageL( williamr@2: const TInt aErrorCode, williamr@2: const TContactItemId aContactId, williamr@2: const TDesC& aUserId, williamr@2: const TDesC& aMessageType, williamr@2: const TDesC16& aContent ) = 0; williamr@2: williamr@2: /** williamr@2: * This method is called when a new point-to-point message (8bit) williamr@2: * has arrived. The message can be text or binary data. williamr@2: * @since S60 3.0 williamr@2: * @param aErrorCode error codes (to be defined) williamr@2: * @param aContactId Contact model ID of the sender williamr@2: * @param aUserId UserID of the message sender williamr@2: * @param aMessageType MIME type of the received message williamr@2: * @param aContent the message williamr@2: * williamr@2: * NOTE: Not yet supported! williamr@2: */ williamr@2: virtual void HandleNewPToPMessageL( williamr@2: const TInt aErrorCode, williamr@2: const TContactItemId aContactId, williamr@2: const TDesC& aUserId, williamr@2: const TDesC& aMessageType, williamr@2: const TDesC8& aContent ) = 0; williamr@2: williamr@2: }; williamr@2: williamr@2: // CLASS DECLARATION williamr@2: /** williamr@2: * Detailed errors accessor class williamr@2: * @lib imclient.lib williamr@2: * @since S60 3.0 williamr@2: */ williamr@2: class MImClientDetailedError williamr@2: { williamr@2: williamr@2: public: williamr@2: /** williamr@2: * Gets the number of failed User IDs williamr@2: * @since S60 3.0 williamr@2: * @return number of failed user IDs williamr@2: */ williamr@2: virtual TInt Count() = 0; williamr@2: williamr@2: /** williamr@2: * Gets the failed User ID williamr@2: * @since S60 3.0 williamr@2: * @param aIndex index of the user in the list williamr@2: * @return failed user ID williamr@2: */ williamr@2: virtual const TDesC& UserId( TInt aIndex ) = 0; williamr@2: williamr@2: /** williamr@2: * Gets the reason of the failure. The API specific error codes are williamr@2: * defined in imerrors.h file. williamr@2: * @since S60 3.0 williamr@2: * @param aIndex index of the user in the list williamr@2: * @return the fail reason williamr@2: */ williamr@2: virtual TInt ErrorCode( TInt aIndex ) = 0; williamr@2: williamr@2: }; williamr@2: williamr@2: #endif williamr@2: // End of File