1 // Copyright (c) 2004-2009 Nokia Corporation and/or its subsidiary(-ies). |
|
2 // All rights reserved. |
|
3 // This component and the accompanying materials are made available |
|
4 // 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 |
|
5 // which accompanies this distribution, and is available |
|
6 // at the URL "http://www.symbianfoundation.org/legal/licencesv10.html". |
|
7 // |
|
8 // Initial Contributors: |
|
9 // Nokia Corporation - initial contribution. |
|
10 // |
|
11 // Contributors: |
|
12 // |
|
13 // Description: |
|
14 // Remote Control client side. |
|
15 // |
|
16 // |
|
17 |
|
18 |
|
19 |
|
20 /** |
|
21 @file |
|
22 @internalComponent |
|
23 */ |
|
24 |
|
25 #ifndef REMCONCLIENT_H |
|
26 #define REMCONCLIENT_H |
|
27 |
|
28 #include <remcon/clienttype.h> |
|
29 #include <remcon/messagetype.h> |
|
30 #include <remcon/operationinformation.h> |
|
31 |
|
32 class TRemConAddress; |
|
33 |
|
34 /** |
|
35 The abstract base class for RemCon session handles. |
|
36 */ |
|
37 class RRemCon : public RSessionBase |
|
38 { |
|
39 public: |
|
40 /** |
|
41 Connect the handle to the server. |
|
42 Must be called before all other methods (except Version and Close). |
|
43 @return Error. |
|
44 */ |
|
45 IMPORT_C TInt Connect(); |
|
46 |
|
47 /** |
|
48 Getter for the version of the server. |
|
49 @return Version of the server. |
|
50 */ |
|
51 IMPORT_C TVersion Version() const; |
|
52 |
|
53 /** |
|
54 Sends a message (command or response) to the remote device. |
|
55 @param aStatus TRequestStatus for asynchronous completion. |
|
56 @param aInterfaceUid The UID of the interface to which the message |
|
57 belongs. |
|
58 @param aOperationId The ID of the message. RemCon needs to know this, |
|
59 separately from the arbitrary data, so it can (a) match up any incoming |
|
60 response to this client (if the message is a command), and (b) match this |
|
61 message up to the target (if this message is a response). |
|
62 @param aNumRemotes On success only, the number of remotes the message was |
|
63 successfully sent to (at the bearer level). If the message is a command |
|
64 from a connection-oriented controller, then on success aNumRemotes will be |
|
65 1. [For consistency, this pattern holds if the message is a response, even |
|
66 though the information is redundant.] If the message is a command from a |
|
67 connectionless controller, then aNumRemotes will be zero or more, |
|
68 depending on what the TSP said should be done with the message and how |
|
69 many of the TSP-nominated bearers successfully sent the message. |
|
70 @param aData Data associated with the message. |
|
71 */ |
|
72 IMPORT_C void Send(TRequestStatus& aStatus, |
|
73 TUid aInterfaceUid, |
|
74 TUint aOperationId, |
|
75 TUint& aNumRemotes, |
|
76 TRemConMessageSubType aSubType, |
|
77 const TDesC8& aData = KNullDesC8()); |
|
78 |
|
79 IMPORT_C TInt SendUnreliable( TUid aInterfaceUid, |
|
80 TUint aOperationId, |
|
81 TRemConMessageSubType aSubType, |
|
82 const TDesC8& aData = KNullDesC8()); |
|
83 |
|
84 /** |
|
85 Cancels interest in the completion of an outstanding Send operation. |
|
86 @return KErrNone. |
|
87 */ |
|
88 IMPORT_C TInt SendCancel(); |
|
89 |
|
90 /** |
|
91 Receive a message (command or response) from the remote device. Note that |
|
92 RemCon server queues both commands and responses so that none are ever |
|
93 thrown away just because the client didn't have a Receive outstanding when |
|
94 they arrived. |
|
95 @param aStatus TRequestStatus for asynchronous completion. |
|
96 @param aInterfaceUid The UID of the interface to which the message |
|
97 belongs. |
|
98 @param aOperationId The ID of the message. |
|
99 @param aData Data associated with the message. |
|
100 */ |
|
101 IMPORT_C void Receive(TRequestStatus& aStatus, |
|
102 TUid& aInterfaceUid, |
|
103 TUint& aOperationId, |
|
104 TRemConMessageSubType& aSubType, |
|
105 TDes8& aData); |
|
106 |
|
107 /** |
|
108 Cancels interest in the completion of an outstanding Receive operation. |
|
109 @return KErrNone. |
|
110 */ |
|
111 IMPORT_C TInt ReceiveCancel(); |
|
112 |
|
113 /** |
|
114 Getter for the current set of connections in the system (not just those |
|
115 associated with this session). The client is responsible for cleaning up |
|
116 the collection- the addresses are on the client's heap. |
|
117 @param aConnections A collection of remote addresses, representing all the |
|
118 currently extant connections. Must be empty when this function is called. |
|
119 @return Error. |
|
120 */ |
|
121 IMPORT_C TInt GetConnections(TSglQue<TRemConAddress>& aConnections); |
|
122 |
|
123 /** |
|
124 Notification for changes in the set of connections. |
|
125 This completes whenever the set of connections changes in some way. |
|
126 If they wish to know what specifically changed, the client must call |
|
127 GetConnections and do their own analysis of the results from that. |
|
128 Changes to the connection history of the system are logged internally so |
|
129 that the client will not 'miss' any changes by not reposting the |
|
130 notification quickly enough. However, if more than one bearer-level |
|
131 connection change occurs in the server before the notification is reposted |
|
132 by the client, then the following notification completion may 'cover' more |
|
133 than one actual state change. |
|
134 @param aStatus TRequestStatus for asynchronous completion. |
|
135 */ |
|
136 IMPORT_C void NotifyConnectionsChange(TRequestStatus& aStatus); |
|
137 |
|
138 /** |
|
139 Cancels interest in the completion of an outstanding |
|
140 NotifyConnectionsChange operation. |
|
141 @return KErrNone. |
|
142 */ |
|
143 IMPORT_C TInt NotifyConnectionsChangeCancel(); |
|
144 |
|
145 /** |
|
146 Marks the start of heap cell checking in the server's heap. In release |
|
147 builds, just returns KErrNone. |
|
148 @return Error. |
|
149 */ |
|
150 IMPORT_C TInt __DbgMarkHeap(); |
|
151 |
|
152 /** |
|
153 Checks that the number of allocated cells on the server's heap is correct. |
|
154 The server is panicked if not. In release builds, just returns KErrNone. |
|
155 @param aCount The expected number of allocated heap cells. |
|
156 @return Error. |
|
157 */ |
|
158 IMPORT_C TInt __DbgCheckHeap(TInt aCount); |
|
159 |
|
160 /** |
|
161 Marks the end of heap cell checking. Checks that the number of heap cells |
|
162 allocated since the last __DbgMarkHeap() is aCount; the most common value |
|
163 to pass here is zero. In release builds, just returns KErrNone. |
|
164 @param aCount The expected number of allocated heap cells. |
|
165 @return Error. |
|
166 */ |
|
167 IMPORT_C TInt __DbgMarkEnd(TInt aCount); |
|
168 |
|
169 /** |
|
170 Simulates memory allocation failure in the server. In release builds, just |
|
171 returns KErrNone. |
|
172 @param aCount The number of allocations after which memory allocation |
|
173 should fail. |
|
174 @return Error. |
|
175 */ |
|
176 IMPORT_C TInt __DbgFailNext(TInt aCount); |
|
177 |
|
178 protected: |
|
179 /** |
|
180 Constructor. |
|
181 @param aType The type of the session. |
|
182 */ |
|
183 RRemCon(TRemConClientType aType); |
|
184 |
|
185 /** Destructor. */ |
|
186 ~RRemCon(); |
|
187 |
|
188 private: // utility |
|
189 TInt DoConnect(); |
|
190 TInt SetClientType(); |
|
191 |
|
192 private: // owned |
|
193 const TRemConClientType iClientType; |
|
194 |
|
195 /** |
|
196 Used by Send. |
|
197 */ |
|
198 TPckg<TUint> iNumRemotesPckg; |
|
199 TPckgBuf<TOperationInformation> iOpInfoPckg; |
|
200 |
|
201 /** |
|
202 Used by Receive. |
|
203 */ |
|
204 TPckg<TUint> iUidPckg; |
|
205 TPckg<TUint> iOpIdPckg; |
|
206 TPckg<TRemConMessageSubType> iMsgSubTypePckg; |
|
207 }; |
|
208 |
|
209 /** |
|
210 The concrete session class for RemCon controllers. |
|
211 Controller sessions are connectionless when opened. This means that addressing |
|
212 of commands is done by the Target Selector Plugin (TSP). A controller may |
|
213 alternatively be connection-oriented, which means that addressing of commands |
|
214 is done using a member of the server-side session which specifies a connection |
|
215 to a remote device. [NB Just because a session 'points to' a connection in |
|
216 this way does not means that the connection necessarily exists at the bearer |
|
217 level or at any other level.] |
|
218 To make a controller session connection-oriented, call GoConnectionOriented. |
|
219 On success, the session's remote address member will have been set to the |
|
220 requested remote address. |
|
221 To make a session connectionless again, use GoConnectionless. On success, the |
|
222 remote address member will be null, indicating that the TSP will be used to |
|
223 address our commands. |
|
224 To control bearer-level connections, use ConnectBearer and DisconnectBearer. |
|
225 Note that real connections may, depending on the bearer, be torn down by the |
|
226 remote end outside of our control. Use GetConnections (and the associated |
|
227 notification) to get information about the current state of the real |
|
228 connections. Note however that the client is not _required_ to be interested |
|
229 in this level of control as RemCon is responsible for making sure the required |
|
230 connection exists at the bearer level before sending the message. The level of |
|
231 control mentioned is provided to the client so that it can, for instance, |
|
232 ensure adequate responsiveness of the first command sent. |
|
233 ConnectBearerCancel and DisconnectBearerCancel merely cancel interest in the |
|
234 corresponding request. They do not change the state of the system, bearers, |
|
235 connections, or member data in any other way. They operate as pure Symbian OS |
|
236 asynchronous cancel methods. |
|
237 */ |
|
238 class RRemConController : public RRemCon |
|
239 { |
|
240 public: |
|
241 /** Constructor */ |
|
242 IMPORT_C RRemConController(); |
|
243 |
|
244 /** Destructor */ |
|
245 IMPORT_C ~RRemConController(); |
|
246 |
|
247 /** |
|
248 Makes the session connection-oriented. On success, the given connection |
|
249 data will be used for sending commands. |
|
250 @param aBearerUid The UID of the bearer to use. |
|
251 @param aData Optional bearer-specific connection data. |
|
252 @return Error. |
|
253 */ |
|
254 IMPORT_C TInt GoConnectionOriented(const TRemConAddress& aConnection); |
|
255 |
|
256 /** |
|
257 Makes the session connectionless. On success, the TSP will be used for |
|
258 sending commands. |
|
259 @return Error. |
|
260 */ |
|
261 IMPORT_C TInt GoConnectionless(); |
|
262 |
|
263 /** |
|
264 Establish a bearer-level connection using the information supplied in |
|
265 GoConnectionOriented. |
|
266 @param aStatus Used by the server to indicate completion of the request. |
|
267 */ |
|
268 IMPORT_C void ConnectBearer(TRequestStatus& aStatus); |
|
269 |
|
270 /** |
|
271 Cancels interest in the completion of an outstanding ConnectBearer |
|
272 request. Does not affect the state of the bearer-level connection. |
|
273 @return KErrNone. |
|
274 */ |
|
275 IMPORT_C TInt ConnectBearerCancel(); |
|
276 |
|
277 /** |
|
278 Triggers bearer-level disconnection of the connection specified in |
|
279 GoConnectionOriented. |
|
280 @param aStatus Used by the server to indicate completion of the request. |
|
281 */ |
|
282 IMPORT_C void DisconnectBearer(TRequestStatus& aStatus); |
|
283 |
|
284 /** |
|
285 Cancels interest in the completion of an outstanding DisconnectBearer |
|
286 request. Does not affect the state of the bearer-level connection. |
|
287 @return KErrNone. |
|
288 */ |
|
289 IMPORT_C TInt DisconnectBearerCancel(); |
|
290 }; |
|
291 |
|
292 /** |
|
293 The concrete session class for RemCon targets. |
|
294 */ |
|
295 class RRemConTarget : public RRemCon |
|
296 { |
|
297 public: |
|
298 /** Constructor */ |
|
299 IMPORT_C RRemConTarget(); |
|
300 |
|
301 /** Destructor */ |
|
302 IMPORT_C ~RRemConTarget(); |
|
303 |
|
304 /** |
|
305 Tells the server in which APIs the client is interested. The server |
|
306 will only deliver incoming commands of these APIs to the client. |
|
307 @param aNumAPIs The number of APIs to be registered |
|
308 @param aAPIs The concatenation of all the API UIDs. |
|
309 @return The error code returned from the server. |
|
310 */ |
|
311 IMPORT_C TInt RegisterInterestedAPIs(TInt aNumAPIs, const TDesC8& aAPIs); |
|
312 }; |
|
313 |
|
314 #endif // REMCONCLIENT_H |
|