|
1 /* |
|
2 * Copyright (c) 2005 Nokia Corporation and/or its subsidiary(-ies). |
|
3 * All rights reserved. |
|
4 * This component and the accompanying materials are made available |
|
5 * under the terms of "Eclipse Public License v1.0" |
|
6 * which accompanies this distribution, and is available |
|
7 * at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
8 * |
|
9 * Initial Contributors: |
|
10 * Nokia Corporation - initial contribution. |
|
11 * |
|
12 * Contributors: |
|
13 * |
|
14 * Description: IMPS Connection UI. |
|
15 * |
|
16 */ |
|
17 |
|
18 #ifndef __CIMPSPRESENCECONNECTIONUING_H__ |
|
19 #define __CIMPSPRESENCECONNECTIONUING_H__ |
|
20 |
|
21 // INCLUDES |
|
22 #include <E32base.h> |
|
23 #include <PEngPresenceEngineConsts2.h> |
|
24 #include <impspresenceconnectionuiconstsng.h> |
|
25 |
|
26 |
|
27 |
|
28 // FORWARD DECLARATION |
|
29 class MIMPSConnProcessObserver; |
|
30 class CIMPSSAPSettingsStore; |
|
31 class CIMPSPresenceConnectionUiImp; |
|
32 class CIMPSSAPSettings; |
|
33 class CPEngNWSessionSlotID2; |
|
34 |
|
35 // CLASS DECLARATION |
|
36 /** |
|
37 * CIMPSPresenceConnectionUi. |
|
38 * |
|
39 * CIMPSPresenceConnectionUi encapsulates remote Presence Server connection / |
|
40 * disconnection procedures. CIMPSPresenceConnectionUi allows applications |
|
41 * just execute the connection procedure, CIMPSPresenceConnectionUi shows |
|
42 * all required UI notes, asks login data from user when needed, etc. |
|
43 * |
|
44 * @lib IMPSConnectionUi |
|
45 * @since 3.0 |
|
46 */ |
|
47 class CIMPSPresenceConnectionUi : public CBase |
|
48 { |
|
49 public: // Two-phased constructors and destructor |
|
50 |
|
51 /** |
|
52 * Two-phased constructor. |
|
53 * |
|
54 * @param aClient The client using the Connection UI |
|
55 * @param aSapStore The SAP settings store to use. |
|
56 * Given SAP settings store object lifetime must be |
|
57 * longer than created CIMPSPresenceConnectionUi. |
|
58 * If no SAP settings store provided, creates own |
|
59 * SAP Settings store internally when needed. |
|
60 */ |
|
61 IMPORT_C static CIMPSPresenceConnectionUi* NewL( |
|
62 TIMPSConnectionClient aClient, |
|
63 CIMPSSAPSettingsStore* aSapStore = NULL ); |
|
64 |
|
65 /** |
|
66 * Two-phased constructor. |
|
67 * Leaves CIMPSPresenceConnectionUi object on the |
|
68 * CleanupStack. |
|
69 * |
|
70 * @param aClient The client using the Connection UI |
|
71 * @param aSapStore The SAP settings store to use. |
|
72 * Given SAP settings store object lifetime must be |
|
73 * longer than created CIMPSPresenceConnectionUi. |
|
74 * If no SAP settings store provided, creates own |
|
75 * SAP Settings store internally when needed. |
|
76 */ |
|
77 IMPORT_C static CIMPSPresenceConnectionUi* NewLC( |
|
78 TIMPSConnectionClient aClient, |
|
79 CIMPSSAPSettingsStore* aSapStore = NULL ); |
|
80 |
|
81 |
|
82 /** |
|
83 * Destructor. |
|
84 */ |
|
85 IMPORT_C virtual ~CIMPSPresenceConnectionUi(); |
|
86 |
|
87 |
|
88 public: // New connection handling methods |
|
89 |
|
90 |
|
91 /** |
|
92 * Connects to remote presence server. |
|
93 * |
|
94 * Handles error situations internally by showing |
|
95 * a proper error note. Asks login data and used server |
|
96 * from user when needed. Retries to open the connection if |
|
97 * needed. |
|
98 * |
|
99 * Connection status is returned as return value. |
|
100 * Internal Symbian OS errors (like running out of resources, |
|
101 * or other fatal errors coming from underlying Presence Engine) |
|
102 * are handled by leaving. |
|
103 * |
|
104 * The client must intialize an instance of CPEngNWSessionSlotID2 |
|
105 * and give it as a parameter. When the call returns the slot ID |
|
106 * contains the current active connection's network session slot ID. |
|
107 * |
|
108 * @since 3.0 |
|
109 * @param aClient The client using the Connection UI to login |
|
110 * to presence service. (This client is logged in.) |
|
111 * @param aLoginType Wanted Connection UI behaviour. |
|
112 * @param aNWSessionSlotID a network session slot ID, on return will contain |
|
113 * the active network session slot ID |
|
114 * @param aObserver The observer to notify from login process |
|
115 * events. |
|
116 * @return Login operation status, one of following: |
|
117 * - KErrNone ==> Login succeeded |
|
118 * - KErrNotFound ==> Missing the whole default SAP / or no SAP's at all |
|
119 * - KErrArgument ==> Default / selected SAP to login was |
|
120 * missing some required fields. (URL & AccessPoint) |
|
121 * - KErrCancel ==> User has cancelled the login at some point. |
|
122 * - KErrAlreadyExist ==> Current client is already logged in. |
|
123 * (Thus not a real error.) |
|
124 * - KErrGeneral ==> General failure during login (no connection |
|
125 * to network, network access denied, etc..) |
|
126 */ |
|
127 IMPORT_C TInt LoginL( TIMPSConnectionClient aClient, |
|
128 TIMPSLoginType aLoginType, |
|
129 CPEngNWSessionSlotID2& aNWSessionSlotID, |
|
130 MIMPSConnProcessObserver* aObserver = NULL, |
|
131 CIMPSSAPSettings* aSap = NULL, TBool aLastLoginSap = EFalse ); |
|
132 |
|
133 |
|
134 /** |
|
135 * Disconnects from remote presence server. |
|
136 * |
|
137 * Internal Symbian OS errors (like running out of resources, |
|
138 * or other fatal errors coming from underlying Presence Engine) |
|
139 * are handled by leaving. |
|
140 * |
|
141 * @since 3.0 |
|
142 * @param aNWSessionSlotID a network session slot ID to logout from. |
|
143 * @param aObserver The observer to notify from logout process |
|
144 * events. |
|
145 * @return Currently always KErrNone. |
|
146 */ |
|
147 IMPORT_C TInt LogoutL( const CPEngNWSessionSlotID2& aNWSessionSlotID, |
|
148 MIMPSConnProcessObserver* aObserver = NULL ); |
|
149 |
|
150 |
|
151 /** |
|
152 * Handles the application exit according the |
|
153 * IMPS Server Settings specification. |
|
154 * |
|
155 * Internal Symbian OS errors (like running out of resources, |
|
156 * or other fatal errors coming from underlying Presence Engine) |
|
157 * are handled by leaving. |
|
158 * |
|
159 * @since 3.0 |
|
160 * @param aClient Which client categorys exit to handle. |
|
161 * |
|
162 * @param TIMPSExitType Wished behaviour of handle exit. |
|
163 * EIMPSNormalExit: |
|
164 * If there exist open connection for the given application |
|
165 * category, and the connection type is is manual or application |
|
166 * launch, a confirmation query is opened wether to close |
|
167 * open connection or not. Connection is closed if desired so. |
|
168 * EIMPSForceExit: |
|
169 * No confirmation queries etc. isn't shown. |
|
170 * Existing open connection is silently closed. |
|
171 * |
|
172 * EIMPSLeaveSessionOpenExit: |
|
173 * The network session is left open by storing the network session |
|
174 * slot ownership to Presence engine. This ownership is restored |
|
175 * next time the application starts |
|
176 * |
|
177 * @param aNWSessionSlotID the current network session slot ID. |
|
178 * @param aObserver The observer to notify from logout process |
|
179 * events. |
|
180 * @return Currently always KErrNone. |
|
181 */ |
|
182 IMPORT_C TInt HandleApplicationExitL( TIMPSConnectionClient aClient, |
|
183 TIMPSExitType aExitType, |
|
184 const CPEngNWSessionSlotID2& aNWSessionSlotID, |
|
185 MIMPSConnProcessObserver* aObserver = NULL ); |
|
186 |
|
187 /** |
|
188 * Gets the remote presence server connection status. |
|
189 * |
|
190 * @since 3.0 |
|
191 * @param aClient The client which connection status |
|
192 * to check. |
|
193 * @return ETrue if client is logged in, else EFalse. |
|
194 */ |
|
195 IMPORT_C TBool LoggedInL( TIMPSConnectionClient aClient ); |
|
196 |
|
197 /** |
|
198 * Gets the currently active network session slot id. |
|
199 * If there is no active network session slot ID return |
|
200 * the default SAP's network session slot ID. |
|
201 * If there are no SAPs defined in the system leaves |
|
202 * with KErrNotFound. |
|
203 * Note that ownership is transferred to the caller. |
|
204 * |
|
205 * @since 3.0 |
|
206 * @param aClient The client which slots to get |
|
207 * @return the network session slot ID |
|
208 */ |
|
209 IMPORT_C CPEngNWSessionSlotID2* GetActiveNWSessionSlotIDL( TIMPSConnectionClient aClient ); |
|
210 |
|
211 |
|
212 /** |
|
213 * Gets the remote presence server settings. |
|
214 * |
|
215 * Gets the remote presence server settings for |
|
216 * current connection. There can be just one |
|
217 * real network presence connection active at time, |
|
218 * and this method retrieves details of that |
|
219 * connection. (Different client groups share |
|
220 * logically on real network connection.) |
|
221 * |
|
222 * If there isn't a active (logged in) connection |
|
223 * for any of known clients, returns KErrNotFound. |
|
224 * Else the given aSap is filled with connection |
|
225 * settings and KErrNone is returned. |
|
226 * |
|
227 * If sap get fails due out of resources or to some |
|
228 * other fatal error coming from underlying PEC engine, |
|
229 * leaves with system error codes. In this case |
|
230 * aSap parameter state is undetermined. |
|
231 * |
|
232 * @since 3.0 |
|
233 * @param aNWSessionSlotID the current active network session slot ID |
|
234 * @param aSap The SAP container to fill with current |
|
235 * connection settings. |
|
236 * @return KErrNone if there exist a connection for known |
|
237 * client. Else KErrNotFound. |
|
238 */ |
|
239 IMPORT_C TInt GetLoggedInSapL( const CPEngNWSessionSlotID2& aNWSessionSlotID, |
|
240 CIMPSSAPSettings& aSap ); |
|
241 |
|
242 |
|
243 |
|
244 /** |
|
245 * Gets the pure connection status from Presence Engine. |
|
246 * |
|
247 * @since 3.0 |
|
248 * @param aNWSessionSlotID a network session slot ID |
|
249 * @return Connection status from Presence Engine. |
|
250 */ |
|
251 IMPORT_C TPEngNWSessionSlotState PureServiceStatusL( |
|
252 const CPEngNWSessionSlotID2& aNWSessionSlotID ); |
|
253 |
|
254 |
|
255 /** |
|
256 * Gets the currently ongoing connection |
|
257 * state change operation. Returned operation |
|
258 * is client wide, so it doesn't care about which |
|
259 * client is doing the operation. |
|
260 * |
|
261 * @since 3.0 |
|
262 * @param aAddtionalDesc The descriptor describing / related |
|
263 * to current connection operation. Method allocates a |
|
264 * buffer for descriptive descriptor if needed and returns |
|
265 * its to caller trough the HBufC*& aDetailDesc. |
|
266 * Ownership of the created buffer is returned to |
|
267 * caller. (NOTE! Only EIMPSConnOppClientLogin returns |
|
268 * descriptive text, currently connected server name. |
|
269 * Other operations return NULL.) |
|
270 * @return The Current connection operation. |
|
271 */ |
|
272 IMPORT_C TIMPSConnectionOperation CurrentConnectionOperationL( HBufC*& aAddtionalDesc ); |
|
273 |
|
274 public: // Other new functions |
|
275 |
|
276 /** |
|
277 * Displays a list query for selecting a domain ("@domain.com" etc.) |
|
278 * @param aSelectedDomain Here is copied the domain user selected. |
|
279 * @param aSap Current SAP settings, previously selected domain is |
|
280 * stored per SAP. |
|
281 * @return If user cancelled the query return 0, |
|
282 * otherwise the dialog dismiss key code |
|
283 * @since 3.1u |
|
284 */ |
|
285 IMPORT_C TInt DisplayDomainSelectionQueryL( TDes& aSelectedDomain, |
|
286 CIMPSSAPSettings* aSap ); |
|
287 |
|
288 private: //Constructors. |
|
289 |
|
290 /** |
|
291 * C++ default constructor. |
|
292 */ |
|
293 CIMPSPresenceConnectionUi( TIMPSConnectionClient aClient ); |
|
294 |
|
295 |
|
296 /** |
|
297 * Symbian OS constructor. |
|
298 */ |
|
299 void ConstructL( CIMPSSAPSettingsStore* aSapStore ); |
|
300 |
|
301 |
|
302 private: //Data |
|
303 CIMPSPresenceConnectionUiImp* iImp; ///<Implementation, owned |
|
304 TIMPSConnectionClient iClient; ///<Client using the Connection UI |
|
305 TAny* iReserved1; ///<Reserved, owned |
|
306 }; |
|
307 |
|
308 |
|
309 |
|
310 #endif //__CIMPSPRESENCECONNECTIONUING_H__ |
|
311 |
|
312 // End of File |
|
313 |