2 * Copyright (c) 2004 Nokia Corporation and/or its subsidiary(-ies).
4 * This component and the accompanying materials are made available
5 * 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
6 * which accompanies this distribution, and is available
7 * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
9 * Initial Contributors:
10 * Nokia Corporation - initial contribution.
14 * Description: IM Connection interface
19 #ifndef IMCONNECTION_H
20 #define IMCONNECTION_H
24 #include <ecom/ecom.h>
27 enum TImConnectionStatus
33 // FORWARD DECLARATIONS
35 class MImConnectionObserver;
40 * Instant Messaging API class
41 * By creating this class the user automatically connects to the Symbian server
42 * but to do something reasonable the IM interface has to be created using
43 * this class. The following order of calling the methods is one possibility to
45 * 1. NewL() - instantiate the object
46 * 2. RegisterObserverL() - register the observer methods
47 * 3. LoginL() - connect to the protocol stack and login to remote IM server
48 * 4. CreateImClientL() - get the IM interface
50 * All the error codes are returned using the leave mechanism.
55 class CImConnection : public CBase
60 * Factory method for creating the class instance.
62 * @param aApplicationId the ApplicationId of the application
63 * @return CImConnection
65 static CImConnection* NewL(
66 const TDesC& aApplicationId );
69 virtual ~CImConnection( );
72 public: // New functions
75 * Creates the IM interface to sending and receiving IMs
79 virtual MImClient* CreateImClientL( ) = 0;
82 * Method for registering the IM Connection observer to the API.
83 * This method is synchronous.
85 * @param aObserver observer object which receives the notification
86 * @leave KImApiErrAlreadyRegistered if it was registered already or other system wide error code
88 virtual void RegisterObserverL(
89 MImConnectionObserver* aObserver ) = 0;
92 * Method for unregistering the IM Connection observer.
93 * This method is synchronous.
96 virtual void UnregisterObserver( ) = 0;
99 * Method for getting the connection status.
100 * This method is synchronous.
102 * @return connection status enum
104 virtual TImConnectionStatus ImConnectionStatus( ) = 0;
107 * Connects the application to the protocol stack and logs in to the
108 * remote SAP server using the given login info.
109 * This method is asynchronous and the completion is signaled by
110 * HandleLoginL() observer method.
112 * @return connection status enum
113 * @leave KImApiErrLoginInProgress already logging in
114 * @leave KImApiErrLogoutInProgress logout is ongoing
115 * @leave KImApiErrCancelLoginInProgress cancel login is ongoing
116 * @leave KImApiErrAlreadyLoggedIn already logged in
119 const TDesC& aServer,
120 const TDesC& aUserID,
121 const TDesC& aPassword,
122 const TUint32 aAP ) = 0;
125 * Cancels the ongoing login operation.
126 * This method is asynchronous and the completion is signaled by
127 * HandleCancelLoginL() observer method.
129 * @leave KImApiErrNotLogged not logged in
130 * @leave KImApiErrLogoutInProgress logout is ongoing
131 * @leave KImApiErrCancelLoginInProgress cancel login is ongoing
132 * @leave KImApiErrAlreadyLoggedIn already logged in
134 virtual void CancelLoginL( ) = 0;
137 * Logs out from current session.
138 * This method is asynchronous and the completion is signaled by
139 * HandleLogoutL() observer method.
140 * Possible leave reasons:
142 * @leave KImApiErrNotLogged not logged in
143 * @leave KImApiErrLogoutInProgress logout is ongoing
144 * @leave KImApiErrCancelLoginInProgress cancel login is ongoing
146 virtual void LogoutL( ) = 0;
150 inline CImConnection( );
153 // Unique instance identifier key (needed for ECom)
159 * Connection Observer interface
164 class MImConnectionObserver
169 * Method is called when the LoginL() is completed.
171 * @param aErrorCode status code
173 virtual void HandleLoginL(
174 const TInt aErrorCode ) = 0;
177 * Method is called when the CancelLoginL() is completed.
179 * @param aErrorCode status code
181 virtual void HandleCancelLoginL(
182 const TInt aErrorCode ) = 0;
185 * Method is called when the LogoutL() is completed.
186 * Also called in situations when the Logout was initiated by the server
187 * or another client which was using the same connection
189 * @param aErrorCode status code
191 virtual void HandleLogoutL(
192 const TInt aErrorCode ) = 0;
196 #include "imconnection.inl"