|
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: Connection manager |
|
15 * |
|
16 */ |
|
17 |
|
18 |
|
19 |
|
20 #ifndef __MSGCONNMANAGERAPI__ |
|
21 #define __MSGCONNMANAGERAPI__ |
|
22 |
|
23 #include "msgbearerobscallback.h" |
|
24 |
|
25 //Define the CommDb parameters which the Conn Manager must support |
|
26 enum TSupportedCommDbRecords |
|
27 { |
|
28 EMsgProxyAddress = 0, |
|
29 EMsgProxyPort |
|
30 }; |
|
31 |
|
32 //FORWARD DECLARATIONS |
|
33 class TInetAddr; |
|
34 class RConnection; |
|
35 class RSocketServ; |
|
36 class MMsgBearerObsCallback; |
|
37 |
|
38 class MMsgConnManager |
|
39 { |
|
40 public: // New functions |
|
41 |
|
42 /** |
|
43 * Start a connection. This asynchronous request completes |
|
44 * as soon as a connection has been successfully opened or |
|
45 * an error condition has been detected. |
|
46 * |
|
47 * Completes with: |
|
48 * |
|
49 * - KErrNone if a connection has been succesfully opened |
|
50 * - KErrNotReady if client has called StopConnection() |
|
51 * and attempts to start a new connection before the previous |
|
52 * one has been disconnected. |
|
53 * - KErrAlreadyExists if a client attempts to open a connection |
|
54 * while one is already being opened |
|
55 * - KErrTimedOut if the specified timeout value expires |
|
56 * |
|
57 * @param aStatus Request status of the client. |
|
58 */ |
|
59 virtual void StartConnection( TRequestStatus& aStatus ) = 0; |
|
60 |
|
61 /** |
|
62 * Stop a connection, synchronous version |
|
63 */ |
|
64 virtual void StopConnection() = 0; |
|
65 |
|
66 /** |
|
67 * Stop a connection. This asynchronous request completes |
|
68 * as soon as a connection has been closed. Note that it |
|
69 * takes a few seconds for the connection to really wear out. |
|
70 * Thus, when a client calls this function, it should really |
|
71 * mean what it is saying, because a new connection CANNOT BE |
|
72 * OPENED before a previous one has been deactivated. |
|
73 * |
|
74 * The request may complete with |
|
75 * - KErrNone if connection closing is successful |
|
76 * - KErrAbort if call takes place while connection initiation |
|
77 * is ongoing or if there is no active connection that would |
|
78 * require closing. If a connection initiation is ongoing |
|
79 * client should use CancelStartL() method instead. |
|
80 * |
|
81 * @param aStatus Request status of the client |
|
82 */ |
|
83 virtual void StopConnection( TRequestStatus& aStatus ) = 0; |
|
84 |
|
85 /** |
|
86 * Cancel StartConnection(). The method may leave with |
|
87 * - KErrAbort if the TRequestStatus object the client |
|
88 * supplied is not active, hence, there is no pending |
|
89 * request that would require cancelling. |
|
90 * In normal cases - when RConnection::Start() or its |
|
91 * progress notifications are pending - ConnMan completes |
|
92 * the client's request with the "error" KErrCancel. |
|
93 * |
|
94 * @return void |
|
95 */ |
|
96 virtual void CancelStartL() = 0; |
|
97 |
|
98 /** |
|
99 * Set the ID of the Access Point to connect to. Note that this |
|
100 * function is effective only when there is no active connection |
|
101 * the start of which has been initiated by the client. In other |
|
102 * words, the ID of the desired Access Point can be changed only |
|
103 * BEFORE calling StartConnection(). |
|
104 * |
|
105 * May leave with |
|
106 * - KErrNotFound if the Access Point ID does not exist |
|
107 * |
|
108 * @param TInt aAccessPointID ID of the Accee Point to use |
|
109 */ |
|
110 virtual void SetAccessPointIDL( const TInt aAccessPointID ) = 0; |
|
111 |
|
112 /** |
|
113 * Returns a reference to the active socket server. |
|
114 * |
|
115 * @return RSocketServ& An opened socket server |
|
116 */ |
|
117 virtual RSocketServ& SocketSession() = 0; |
|
118 |
|
119 /** |
|
120 * Returns a reference to the currently open connection |
|
121 * |
|
122 * @return RConnection& An opened connection |
|
123 */ |
|
124 virtual RConnection& Connection() = 0; |
|
125 |
|
126 /** |
|
127 * Returns the number of active connections currently open |
|
128 * |
|
129 * @return TInt Number of active connections on the device |
|
130 */ |
|
131 virtual TInt NumberOfActiveConns() = 0; |
|
132 |
|
133 /** |
|
134 * Read data from the Comms Database |
|
135 * |
|
136 * @param TMsgSupportedCommDbRecords aParameter The type of the CommDb record |
|
137 * @return HBufC* Value of the requested record |
|
138 */ |
|
139 virtual HBufC* ReadFromCommsDbLC( const TSupportedCommDbRecords aParameter ) = 0; |
|
140 |
|
141 /** |
|
142 * Add an object to the queue of listeners. The object to be added |
|
143 * must inplement the interface MMsgBearerObsCallback in order |
|
144 * to receive events from the system agent. It is important to note |
|
145 * that the call to the notification handler (HandleBearerEventL()) |
|
146 * takes place inside the RunL() method of this Connection Manager, |
|
147 * so the listening object MUST return the control to the Manager |
|
148 * AS SOON AS POSSIBLE in order not to clog the scheduler. |
|
149 * |
|
150 * @param MMsgBearerObserverCallback* aClient A subscribing client |
|
151 * @return void |
|
152 */ |
|
153 virtual void AddEventSubscriberL( MMsgBearerObsCallback* aClient ) = 0; |
|
154 |
|
155 /** |
|
156 * Remove an object from the queue of listeners. It is not necessary |
|
157 * to call this method at deletion time, as the destructor destroys |
|
158 * the subscriber queue altogether. If, however, a listener object is |
|
159 * destroyed (or is likely to be) before an instance of Connection Manager, |
|
160 * it is mandatory to remove the listener from the queue prior to deleting |
|
161 * the listener. |
|
162 * |
|
163 * @param MMsgBearerObsCallback* aClient The client to be removed |
|
164 * @return void |
|
165 */ |
|
166 virtual void RemoveEventSubscriber( MMsgBearerObsCallback* aClient ) = 0; |
|
167 |
|
168 /** |
|
169 * Returns the state of this connection manager: |
|
170 * |
|
171 * - ETrue, if a connection is available |
|
172 * - EFalse otherwise; bearer suspended, StartConnection() failed etc. |
|
173 * |
|
174 * A component that wishes to send/receive data is encouraged |
|
175 * to call this function before opening a socket, or reading |
|
176 * from or writing to one. This way it can be assured that |
|
177 * no component prompts up that annoying IAP dialog. |
|
178 * |
|
179 * @return TBool Is the connection OK |
|
180 */ |
|
181 virtual TBool Status() const = 0; |
|
182 |
|
183 /** |
|
184 * Destructor. Must be called when the services of the |
|
185 * manager are no longer needed. This is merely a |
|
186 * wrapper to the C++ destructor. |
|
187 * |
|
188 * It is highly advisable that a client of this API |
|
189 * ALWAYS Destroy()s the instance it owns only after |
|
190 * it has disposed of all other connection-related |
|
191 * components at its command. This is because the other |
|
192 * components may still be dependent on the RConnection |
|
193 * and RSocketServ instances provided by this object. |
|
194 * |
|
195 * @return void |
|
196 */ |
|
197 virtual void Destroy() = 0; |
|
198 }; |
|
199 |
|
200 /** |
|
201 * Creates a new Connection Manager |
|
202 * @param aDefaultAccessPoint ID of the default Access Point |
|
203 */ |
|
204 IMPORT_C MMsgConnManager* NewMsgConnManagerL( const TInt aDefaultAccessPoint ); |
|
205 |
|
206 #endif |
|
207 |
|
208 |
|
209 // End of File |