|
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 "Eclipse Public License v1.0" |
|
5 // which accompanies this distribution, and is available |
|
6 // at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
7 // |
|
8 // Initial Contributors: |
|
9 // Nokia Corporation - initial contribution. |
|
10 // |
|
11 // Contributors: |
|
12 // |
|
13 // Description: |
|
14 // |
|
15 |
|
16 /** |
|
17 @file |
|
18 @publishedPartner |
|
19 @released |
|
20 */ |
|
21 |
|
22 #ifndef REMCONBEAREROBSERVER_H |
|
23 #define REMCONBEAREROBSERVER_H |
|
24 |
|
25 #include <e32base.h> |
|
26 #include <remcon/messagetype.h> |
|
27 #include <remcon/clientid.h> |
|
28 |
|
29 class CRemConConverterPlugin; |
|
30 class TRemConAddress; |
|
31 |
|
32 /** |
|
33 Interface presented by RemCon down to bearers. |
|
34 The public methods are non-virtual and exported, so that they can be added to |
|
35 without breaking BC for existing (non-rebuilt) bearers. |
|
36 */ |
|
37 class MRemConBearerObserver |
|
38 { |
|
39 public: |
|
40 /** |
|
41 Called when an incoming response from a remote is ready to be picked up by |
|
42 RemCon. |
|
43 @param aAddr The address the response came from. |
|
44 @return Error. If KErrNone, RemCon is committing to collecting the message |
|
45 using GetResponse. If non-KErrNone, the message will be dropped by the |
|
46 bearer. |
|
47 */ |
|
48 IMPORT_C TInt NewResponse(const TRemConAddress& aAddr); |
|
49 |
|
50 /** |
|
51 Called when an incoming notify response from a remote is ready to be picked up by |
|
52 RemCon. |
|
53 @param aAddr The address the response came from. |
|
54 @return Error. If KErrNone, RemCon is committing to collecting the message |
|
55 using GetNotifyResponse. If non-KErrNone, the message will be dropped by the |
|
56 bearer. |
|
57 */ |
|
58 IMPORT_C TInt NewNotifyResponse(const TRemConAddress& aAddr); |
|
59 |
|
60 /** |
|
61 Called when an incoming command from a remote is ready to be picked up by |
|
62 RemCon. |
|
63 @param aAddr The address the command came from. |
|
64 @return Error. If KErrNone, RemCon is committing to collecting the message |
|
65 using GetResponse. If non-KErrNone, the message will be dropped by the |
|
66 bearer. |
|
67 */ |
|
68 IMPORT_C TInt NewCommand(const TRemConAddress& aAddr); |
|
69 |
|
70 /** |
|
71 Called when an incoming notify command from a remote is ready to be picked up by |
|
72 RemCon. A Notify command is different to a normal command in that it doesn't |
|
73 follow the standard request / response sequence. Instead a notify is registered |
|
74 to retrieve the current state value in an interim response, then when the state |
|
75 has changed relative the interim response a second response is sent containing the |
|
76 new, changed, state. |
|
77 |
|
78 Depending on the semantics of the bearer protocol it may be able to map its |
|
79 state observation commands to plain RemCon commands, however for a reliable |
|
80 mechanism without polling this NotifyCommand is provided. |
|
81 |
|
82 @param aAddr The address the command came from. |
|
83 @return Error. If KErrNone, RemCon is committing to collecting the message |
|
84 using GetResponse. If non-KErrNone, the message will be dropped by the |
|
85 bearer. |
|
86 */ |
|
87 IMPORT_C TInt NewNotifyCommand(const TRemConAddress& aAddr); |
|
88 |
|
89 /** |
|
90 Called by a bearer when an incoming connection has been established. |
|
91 @param aAddr The address of the connection. |
|
92 @return Error. If RemCon cannot add the connection to its internal data, |
|
93 then the bearer must logically drop the connection. |
|
94 */ |
|
95 IMPORT_C TInt ConnectIndicate(const TRemConAddress& aAddr); |
|
96 |
|
97 /** |
|
98 Called by a bearer when a connection has been disconnected from the remote |
|
99 end. |
|
100 The bearer should only call this function if either (a) ConnectIndicate |
|
101 has already been called for the connection aAddr (and KErrNone returned by |
|
102 RemCon), or (b) ConnectConfirm has been called with KErrNone for the |
|
103 connection aAddr (and KErrNone has been returned by RemCon). |
|
104 @param aAddr The RemCon address of the connection. |
|
105 */ |
|
106 IMPORT_C void DisconnectIndicate(const TRemConAddress& aAddr); |
|
107 |
|
108 /** |
|
109 Called by a bearer to indicate completion of an outgoing connection |
|
110 request (CRemConBearerPlugin::ConnectRequest). |
|
111 @param aAddr The address of the connection in question. |
|
112 @param aError The success status of the connection establishment. If |
|
113 KErrNone, the connection was established. If non-KErrNone, the connection |
|
114 was not established. |
|
115 @return Error. If RemCon cannot add the connection to its internal data, |
|
116 then the bearer must logically drop the connection. If aError is not |
|
117 KErrNone, then this return value is irrelevant. |
|
118 */ |
|
119 IMPORT_C TInt ConnectConfirm(const TRemConAddress& aAddr, TInt aError); |
|
120 |
|
121 /** |
|
122 Called by a bearer to indicate completion of a disconnection request |
|
123 (CRemConBearerPlugin::Disconnect). |
|
124 @param aAddr The address of the connection in question. |
|
125 @param aError The success status of the disconnection. If KErrNone, the |
|
126 disconnection occurred. If non-KErrNone, the connection still exists. |
|
127 */ |
|
128 IMPORT_C void DisconnectConfirm(const TRemConAddress& aAddr, TInt aError); |
|
129 |
|
130 /** |
|
131 Called by a bearer to convert a message from an outer-layer API format to |
|
132 the bearer's format. The bearer observer finds a converter to perform |
|
133 this. |
|
134 @param aBearerUid The UID of the bearer. |
|
135 @param aInterfaceUid The UID of the outer layer API to which the message |
|
136 belongs. |
|
137 @param aOperationId The operation ID of the message. |
|
138 @param aData The operation-specific data of the message. |
|
139 @param aMsgType The type of the message. |
|
140 @param aBearerData On success, the message encoded in the bearer's format. |
|
141 @return Error. If a converter could not be found, KErrNotSupported, |
|
142 indicating that the message/bearer combination is not supported by the |
|
143 system. |
|
144 */ |
|
145 IMPORT_C TInt InterfaceToBearer(TUid aBearerUid, |
|
146 TUid aInterfaceUid, |
|
147 TUint aOperationId, |
|
148 const TDesC8& aData, |
|
149 TRemConMessageType aMsgType, |
|
150 TDes8& aBearerData) const; |
|
151 |
|
152 /** |
|
153 Called by a bearer to convert a message from the bearer's format to that |
|
154 of an outer-layer API. The bearer observer finds a converter to perform |
|
155 this. |
|
156 @param aBearerUid The UID of the bearer. |
|
157 @param aInterfaceData Data identifying the interface in bearer-specific |
|
158 format. |
|
159 @param aBearerData The message encoded in the bearer's format. |
|
160 @param aInterfaceUid On success, the UID of the outer layer API to which |
|
161 the message belongs. |
|
162 @param aOperationId On success, the operation ID of the message. |
|
163 @param aData On success, the operation-specific data of the message. |
|
164 @param aMsgType On success, the type of the message. |
|
165 @return Error. If a converter could not be found, KErrNotSupported, |
|
166 indicating that the message/bearer combination is not supported by the |
|
167 system. |
|
168 */ |
|
169 IMPORT_C TInt BearerToInterface(TUid aBearerUid, |
|
170 const TDesC8& aInterfaceData, |
|
171 const TDesC8& aBearerData, |
|
172 TUid& aInterfaceUid, |
|
173 TUint& aOperationId, |
|
174 TRemConMessageType& aMsgType, |
|
175 TDes8& aData) const; |
|
176 |
|
177 /** |
|
178 Called by a bearer when a new command has come in. RemCon returns a cookie |
|
179 (a transaction id), guaranteed to be unique, which the bearer may use for |
|
180 its own identification purposes. |
|
181 @return A new transaction ID. |
|
182 */ |
|
183 IMPORT_C TUint NewTransactionId(); |
|
184 |
|
185 /** |
|
186 Called by a bearer when a command is no longer valid and should be removed |
|
187 from RemCon's queues |
|
188 @param aTransactionId The transaction ID of the expired command |
|
189 */ |
|
190 IMPORT_C void CommandExpired(TUint aTransactionId); |
|
191 |
|
192 /** |
|
193 Called when an incoming command from a remote is ready to be picked up by |
|
194 RemCon. |
|
195 |
|
196 This overload is provided for the case where the bearer supports command |
|
197 addressing. |
|
198 |
|
199 @param aAddr The address the command came from. |
|
200 @param aTarget The application to which the command is targeted |
|
201 @return Error. If KErrNone, RemCon is committing to collecting the message |
|
202 using GetResponse. If non-KErrNone, the message will be dropped by the |
|
203 bearer. |
|
204 */ |
|
205 IMPORT_C TInt NewCommand(const TRemConAddress& aAddr, const TRemConClientId& aClient); |
|
206 |
|
207 /** |
|
208 Called when an incoming notify command from a remote is ready to be picked up by |
|
209 RemCon. A Notify command is different to a normal command in that it doesn't |
|
210 follow the standard request / response sequence. Instead a notify is registered |
|
211 to retrieve the current state value in an interim response, then when the state |
|
212 has changed relative the interim response a second response is sent containing the |
|
213 new, changed, state. |
|
214 |
|
215 Depending on the semantics of the bearer protocol it may be able to map its |
|
216 state observation commands to plain RemCon commands, however for a reliable |
|
217 mechanism without polling this NotifyCommand is provided. |
|
218 |
|
219 This overload is provided for the case where the bearer supports command |
|
220 addressing. |
|
221 |
|
222 @param aAddr The address the command came from. |
|
223 @param aTarget The application to which the command is targeted |
|
224 @return Error. If KErrNone, RemCon is committing to collecting the message |
|
225 using GetResponse. If non-KErrNone, the message will be dropped by the |
|
226 bearer. |
|
227 */ |
|
228 IMPORT_C TInt NewNotifyCommand(const TRemConAddress& aAddr, const TRemConClientId& aClient); |
|
229 |
|
230 /** |
|
231 Called by the bearer when it want to retrieve which interfaces are supported by a |
|
232 specific client. |
|
233 @param aId A unique identifier for this client |
|
234 @param aUids An RArray to be populated with the supported UIDs. On return with |
|
235 KErrNone this array is populated with the UIDs of the interfaces which |
|
236 this client supports. Ownership of the RArray remains with the caller. |
|
237 Any existing entries in the array will be removed. |
|
238 @return KErrNone on successful retrieval of supported interfaces. System wide |
|
239 error code otherwise. |
|
240 */ |
|
241 IMPORT_C TInt SupportedInterfaces(const TRemConClientId& aId, RArray<TUid>& aUids) ; |
|
242 |
|
243 /** |
|
244 Called by the bearer when it wants to retrieve which operations within the interface |
|
245 are supported by this client. Note that this information is not available for all |
|
246 interface and client combinations. |
|
247 |
|
248 @param aId A unique identifier for this client |
|
249 @param aInterfaceUid The interface to return the supported operations for |
|
250 @param aOperations An RArray to be populated with the supported operations. |
|
251 On return with KErrNone this array is populated with the operation |
|
252 ids of each supported operations within the requested interface. |
|
253 Ownership of the RArray remains with the caller. Any existing |
|
254 entries in the array will be removed. |
|
255 @return KErrNone if the supported operations could be successfully retrieved. |
|
256 KErrNotSupported if the operations could not be retrieved for this |
|
257 particular client/interface combination. System wide error code |
|
258 otherwise. |
|
259 */ |
|
260 IMPORT_C TInt SupportedOperations(const TRemConClientId& aId, TUid aInterfaceUid, RArray<TUint>& aOperations); |
|
261 |
|
262 /** |
|
263 Called by the bearer to inform RemCon that remote user action means that |
|
264 this bearer will now route addressed commands to the specified client. |
|
265 This is valid until either the bearer calls SetRemoteAddressedPlayer again |
|
266 or RemCon calls SetLocalAddressedPlayer. |
|
267 |
|
268 @param aBearerUid The Uid of this bearer |
|
269 @param aId The client to which this bearer will route addressed commands. |
|
270 */ |
|
271 IMPORT_C void SetRemoteAddressedClient(const TUid& aBearerUid, const TRemConClientId& aId); |
|
272 |
|
273 private: |
|
274 /** |
|
275 @see NewResponse. |
|
276 */ |
|
277 virtual TInt MrcboDoNewResponse(const TRemConAddress& aAddr) = 0; |
|
278 |
|
279 /** |
|
280 @see NewNotifyResponse. |
|
281 */ |
|
282 virtual TInt MrcboDoNewNotifyResponse(const TRemConAddress& aAddr) = 0; |
|
283 |
|
284 /** |
|
285 @see NewCommand. |
|
286 */ |
|
287 virtual TInt MrcboDoNewCommand(const TRemConAddress& aAddr) = 0; |
|
288 |
|
289 /** |
|
290 @see NewNotifyCommand. |
|
291 */ |
|
292 virtual TInt MrcboDoNewNotifyCommand(const TRemConAddress& aAddr) = 0; |
|
293 |
|
294 /** |
|
295 @see ConnectIndicate. |
|
296 */ |
|
297 virtual TInt MrcboDoConnectIndicate(const TRemConAddress& aAddr) = 0; |
|
298 |
|
299 /** |
|
300 @see DisconnectIndicate. |
|
301 */ |
|
302 virtual void MrcboDoDisconnectIndicate(const TRemConAddress& aAddr) = 0; |
|
303 |
|
304 /** |
|
305 @see ConnectConfirm. |
|
306 */ |
|
307 virtual TInt MrcboDoConnectConfirm(const TRemConAddress& aAddr, TInt aError) = 0; |
|
308 |
|
309 /** |
|
310 @see DisconnectConfirm. |
|
311 */ |
|
312 virtual void MrcboDoDisconnectConfirm(const TRemConAddress& aAddr, TInt aError) = 0; |
|
313 |
|
314 /** |
|
315 @see InterfaceToBearer. |
|
316 */ |
|
317 virtual TInt MrcboDoInterfaceToBearer(TUid aBearerUid, |
|
318 TUid aInterfaceUid, |
|
319 TUint aOperationId, |
|
320 const TDesC8& aData, |
|
321 TRemConMessageType aMsgType, |
|
322 TDes8& aBearerData) const = 0; |
|
323 |
|
324 /** |
|
325 @see BearerToInterface. |
|
326 */ |
|
327 virtual TInt MrcboDoBearerToInterface(TUid aBearerUid, |
|
328 const TDesC8& aInterfaceData, |
|
329 const TDesC8& aBearerData, |
|
330 TUid& aInterfaceUid, |
|
331 TUint& aOperationId, |
|
332 TRemConMessageType& aMsgType, |
|
333 TDes8& aData) const = 0; |
|
334 |
|
335 /** |
|
336 @see TransactionId. |
|
337 */ |
|
338 virtual TUint MrcboDoNewTransactionId() = 0; |
|
339 |
|
340 /** |
|
341 @see CommandExpired. |
|
342 */ |
|
343 virtual void MrcboDoCommandExpired(TUint aTransactionId) = 0; |
|
344 |
|
345 /** |
|
346 @see NewCommand |
|
347 */ |
|
348 virtual TInt MrcboDoNewCommand(const TRemConAddress& aAddr, const TRemConClientId& aClient) = 0; |
|
349 |
|
350 /** |
|
351 @see NewNotifyCommand |
|
352 */ |
|
353 virtual TInt MrcboDoNewNotifyCommand(const TRemConAddress& aAddr, const TRemConClientId& aClient) = 0; |
|
354 |
|
355 /** |
|
356 @see SupportedInterfaces |
|
357 */ |
|
358 virtual TInt MrcboDoSupportedInterfaces(const TRemConClientId& aId, RArray<TUid>& aUids) = 0; |
|
359 |
|
360 /** |
|
361 @see SupportedOperations |
|
362 */ |
|
363 virtual TInt MrcboDoSupportedOperations(const TRemConClientId& aId, TUid aInterfaceUid, RArray<TUint>& aOperations) = 0; |
|
364 |
|
365 /** |
|
366 @see SetRemoteAddressedClient |
|
367 */ |
|
368 virtual void MrcboDoSetRemoteAddressedClient(const TUid& aBearerUid, const TRemConClientId& aId) = 0; |
|
369 }; |
|
370 |
|
371 #endif // REMCONBEAREROBSERVER_H |