|
1 // Copyright (c) 2005-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 #ifndef AVCTPSERVICES_H |
|
18 #define AVCTPSERVICES_H |
|
19 |
|
20 #include <bluetoothav.h> |
|
21 #include <bluetooth/avctptypes.h> |
|
22 |
|
23 /** Protocol version number for use in SDP records. |
|
24 */ |
|
25 const TUint16 KAvctpProtocolVersion = 0x0103; |
|
26 |
|
27 /** |
|
28 Mixin for receiving AVCTP events from RAvctp |
|
29 |
|
30 Note RAvctp doesn't expect the MAvctpEventNotify class to synchronously call Close() |
|
31 on it within any of these callbacks with the exception of MaenErrorNotify. You may |
|
32 call CloseGracefully since its asynchronous by nature. |
|
33 |
|
34 @internalTechnology |
|
35 @see RAvctp |
|
36 */ |
|
37 class MAvctpEventNotify |
|
38 { |
|
39 public: |
|
40 /** |
|
41 AVCTP Connection Confirm |
|
42 This is a response to RAvctp::ConnectRequest() and passes on the result of the Connection attempt. |
|
43 NB we don't return the configuration status as in Appendix A - AVCTP Upper Interface of [R2]. |
|
44 If the aConnectResult is KErrNone then RAvctp is now connected. |
|
45 @param aBTDevice the address of the device connected to |
|
46 @param aConnectResult KErrNone if the connection attempt was successful or one of the system-wide error codes |
|
47 */ |
|
48 virtual void MaenAttachConfirm(const TBTDevAddr& aBTDevice, TInt aMaxMessageSize, TInt aConnectResult) = 0; |
|
49 |
|
50 /** |
|
51 AVCTP Connection Indicate |
|
52 This is a is called when a remote device has connected to us. |
|
53 NB we don't return the configuration status as in Appendix A - AVCTP Upper Interface of [R2]. |
|
54 @param aBTDevice the address of the device connected to |
|
55 @param aAccept this parameter is provided so that the client of RAvctp can indicate whether |
|
56 they want to accept the connection. If aAccept is not changed the connection |
|
57 will be refused however this may not result in the actual disconnection of the |
|
58 device if another RAvctp client did accept the connection. The meaning of a |
|
59 refusal is that you don't care whether or not the connection is there or not. |
|
60 */ |
|
61 virtual void MaenAttachIndicate(const TBTDevAddr& aBTDevice, TInt aMaxMessageSize, TBool& aAccept) = 0; |
|
62 |
|
63 /** |
|
64 AVCTP Disconnection Indication that a remote device has disconnected from us. |
|
65 It is only called if the device had been explicitly Connected to. |
|
66 @param aBTDevice the address of the disconnecting device |
|
67 */ |
|
68 virtual void MaenDetachIndicate(const TBTDevAddr& aBTDevice) = 0; |
|
69 |
|
70 /** |
|
71 AVCTP Disconnection Confirm - disconnection from a device complete |
|
72 This is the response to RAvctp::DisconnectRequest. |
|
73 @param aBTDevice the address of the disconnected device |
|
74 @param aDisconnectResult will be one of the system-wide error codes. If KErrTimedOut is returned then the RAvctp will be disconnected. |
|
75 */ |
|
76 virtual void MaenDetachConfirm(const TBTDevAddr& aBTDevice, TInt aDisconnectResult) = 0; |
|
77 |
|
78 /** |
|
79 AVCTP Message received indication |
|
80 This method is called when a message has been received from the given device on the RAvctp's PID. |
|
81 |
|
82 Note that because AVCTP is a connectionless protocol, it is perfectly possible to get a |
|
83 MaenMessageReceivedIndicate event from a device that you have not either explicitly connected to. |
|
84 For instance even if you don't accept a MaenConnectIndicate you may still receive messages from that |
|
85 remote device. |
|
86 |
|
87 @param aBTDevice address of the device sending us an AVCTP message |
|
88 @param aTransactionLabel message transaction label |
|
89 @param aType type of message |
|
90 @param aIpidBitSet this will be set to true only if a message has been received indicating |
|
91 that the profile corresponding to the originally sent message is not valid. |
|
92 If RAvctp was used to send the message then this response will have come from |
|
93 the remote device aBTDevice. |
|
94 @param aMessageInformation contains only the AVCTP Command / Response Message Information and not the whole packet. |
|
95 Ownership transferred to client. |
|
96 */ |
|
97 virtual void MaenMessageReceivedIndicate(const TBTDevAddr& aBTDevice, |
|
98 SymbianAvctp::TTransactionLabel aTransactionLabel, |
|
99 SymbianAvctp::TMessageType aType, |
|
100 TBool aIpidBitSet, |
|
101 const TDesC8& aMessageInformation) = 0; |
|
102 |
|
103 /** |
|
104 AVCTP Message send complete. |
|
105 This method is called when a RAvctp has attempted to send the message defined by aTransactionLabel and aBTDevice. |
|
106 @param aTransactionLabel The transaction label of the message that has been sent |
|
107 @param aBTDevice the device to which the send has completed |
|
108 @param aSendResult KErrNone if the send was successful or one of the system-wide error codes |
|
109 |
|
110 */ |
|
111 virtual void MaenMessageSendComplete(const TBTDevAddr& aBTDevice, |
|
112 SymbianAvctp::TTransactionLabel aTransactionLabel, |
|
113 TInt aSendResult) = 0; |
|
114 /** |
|
115 AVCTP Close Complete |
|
116 This is the response to the CloseGracefully() that has been called on a RAvctp object. It is the |
|
117 last event that will be called until the RAvctp object is Open()'d again. |
|
118 */ |
|
119 virtual void MaenCloseComplete() = 0; |
|
120 |
|
121 /** |
|
122 AVCTP error notification |
|
123 Note an errored device does not indicate that the device has been disconnected. If it has then a |
|
124 MaenDisconnectIndicate event will be used to indicate this. |
|
125 @param aBTDevice the remote device associated with the error or TBTDevAddr(0) for a general error |
|
126 @param aError system wide error |
|
127 */ |
|
128 virtual void MaenErrorNotify(const TBTDevAddr& aBTDevice, TInt aError) = 0; |
|
129 |
|
130 /** |
|
131 Returns a null aObject if the extension is not implemented, or a pointer to another interface if it is. |
|
132 @param aInterface UID of the interface to return |
|
133 @param aObject the container for another interface as specified by aInterface |
|
134 */ |
|
135 virtual void MaenExtensionInterfaceL(TUid aInterface, void*& aObject) = 0; |
|
136 }; |
|
137 |
|
138 |
|
139 class MAvctpChannel |
|
140 { |
|
141 public: |
|
142 /** |
|
143 Starts an explicit connection attempt using the default AVCTP security settings |
|
144 This function should be used if you wish to ensure a connection is available before calling |
|
145 SendMessage to ensure that the message is sent with minimal delay. |
|
146 Following this function, MaenConnectConfirm will be called on aNotify with results of the connection |
|
147 attempt provided this function returned KErrNone. |
|
148 @param aBTDevice the remote device address to connect to |
|
149 @return a system-wide error code |
|
150 @panic if the RAvctp object isn't open or Close / CloseGracefully has been called on the RAvctp object |
|
151 */ |
|
152 virtual TInt MacAttachRequest(const TBTDevAddr& aBTDevice) = 0; |
|
153 |
|
154 /** |
|
155 Can be used to determine with this client has explicitly connected to the given device. |
|
156 @param aBTDevice the remote device in question |
|
157 @return ETrue if the client has previously requested a connection to this device, otherwise EFalse |
|
158 @panic if the RAvctp object isn't open or Close / CloseGracefully has been called on the RAvctp object |
|
159 */ |
|
160 virtual TBool MacIsAttached(const TBTDevAddr& aBTDevice) = 0; |
|
161 |
|
162 /** |
|
163 Cancels an outstanding connect operation so that MaenConnectConfirm is NOT called on aNotify |
|
164 Can be called at any time. |
|
165 |
|
166 @param aBTDevice the remote device of the Connect to cancel |
|
167 @panic if the RAvctp object isn't open or Close / CloseGracefully has been called on the RAvctp object |
|
168 */ |
|
169 virtual void MacCancelAttach(const TBTDevAddr& aBTDevice) = 0; |
|
170 /** |
|
171 Begins the disconnection process if the RAvctp object is explicitly connected to aBTDevice. |
|
172 When the remote device has been disconnected MaenDisconnectConfirm will be called on aNotify, |
|
173 provided this function returned KErrNone. |
|
174 |
|
175 Note that this function can not be used to prevent an ongoing connection attempt. If this is |
|
176 what you wish to do, use CancelConnect(...) instead. |
|
177 |
|
178 @param aBTDevice the remote device to disconnect from |
|
179 @return a system-wide error code |
|
180 @panic if the RAvctp object isn't open or Close / CloseGracefully has been called on the RAvctp object |
|
181 */ |
|
182 virtual TInt MacDetachRequest(const TBTDevAddr& aBTDevice) = 0; |
|
183 |
|
184 /** |
|
185 Send an AVCTP message |
|
186 This is a helper function so that the user doesn't have to know how to format an AVCTP packet. |
|
187 When the message has been sent, MaenMessageSendComplete will be called on aNotify, provided this function |
|
188 returned KErrNone. |
|
189 |
|
190 It is not necessary to call Connect(aBTDevice) before calling this function since a connection will be |
|
191 implicitly started to carry this message if one doesn't already exist. However, this has two potential |
|
192 drawbacks: |
|
193 i) If there isn't already a connection to the remote device then the packet may take some time to reach |
|
194 its destination |
|
195 ii) If there isn't already a connection to the remote device then and this connection attempt fails, you |
|
196 will not be informed of this fact. Effectively the packet will have been dropped. |
|
197 NB both the above problems will not occur if you explicitly connect the remote device and wait for the |
|
198 resulting ConnectCfm event. |
|
199 |
|
200 @param aBTDevice the remote device to connect to |
|
201 @param aTransactionLabel will be the transaction ID for the message as specified in the AVCTP 1.0 |
|
202 spec. It is the responsibility of the RAvctp user to provide a transaction ID that "uniquely |
|
203 identifies the transaction with a limited scope in the command / response flow". |
|
204 @param aType the packet type |
|
205 @param aMessageInformation should contain only the AVCTP Command / Response Message |
|
206 Information |
|
207 @return KErrInUse if the RAvctp is already sending a message (if this happens you need to wait until |
|
208 you get an MaenMessageSendComplete event before sending again) or another system wide error code |
|
209 @panic if the most significant four bits of aTransactionLabel are not zero |
|
210 @panic if the RAvctp object isn't open or Close / CloseGracefully has been called on the RAvctp object |
|
211 */ |
|
212 virtual TInt MacSendMessage(const TBTDevAddr& aBTDevice, |
|
213 SymbianAvctp::TTransactionLabel aTransactionLabel, |
|
214 SymbianAvctp::TMessageType aType, |
|
215 const TDesC8& aMessageInformation) = 0; |
|
216 |
|
217 /** |
|
218 Cancels an outstanding send operation so that MaenMessageSendComplete is NOT called on aNotify |
|
219 Can be called at any time. |
|
220 |
|
221 @panic if the RAvctp object isn't open or Close / CloseGracefully has been called on the RAvctp object |
|
222 */ |
|
223 virtual void MacCancelSend() = 0; |
|
224 }; |
|
225 |
|
226 |
|
227 |
|
228 |
|
229 // Forward declaration |
|
230 class CAvctpBody; |
|
231 |
|
232 |
|
233 |
|
234 /** |
|
235 AVCTP service provider |
|
236 |
|
237 Note that because AVCTP is a connectionless protocol, this class doesn't provide an API |
|
238 to directly control all aspects of whether or not a connection exists to a remote device. |
|
239 It provides an API to force a connection to exist (RAvctp::ConnectRequest()) until either a |
|
240 MaenDisconnectIndicate or MaenDisconnectConfirm event is notified via the MAvctpEventNotify |
|
241 class that clients should derive from. |
|
242 |
|
243 When using RAvctp clients need to make the distinction between an explicit connection and |
|
244 an actual connection. All this class provides is an API to bring up and in keeping a connection |
|
245 up by allowing explicit connections to be made. However if no explicit connection to a remote |
|
246 device has been made, that does NOT mandate that no such connection to this remote will exist. |
|
247 Instead it means the client doesn't care if there is a connection or not to this remote. |
|
248 Hence a client can receive messages from or send messages to a device they've not explicitly |
|
249 connected to. |
|
250 |
|
251 @internalTechnology |
|
252 */ |
|
253 NONSHARABLE_CLASS(RAvctp) |
|
254 { |
|
255 public: |
|
256 /** |
|
257 @see RAvctp::Close() |
|
258 */ |
|
259 enum TCloseType |
|
260 { |
|
261 ENormal, |
|
262 EImmediate, |
|
263 }; |
|
264 |
|
265 public: |
|
266 |
|
267 /** |
|
268 Default constructor |
|
269 */ |
|
270 IMPORT_C RAvctp(); |
|
271 |
|
272 /** |
|
273 Opens a channel to the AVCTP protocol. |
|
274 Only one RAvctp can be registered to receive events on each PID. |
|
275 @param aNotify the MAvctpEventNotify object to notify with all this RAvctp's AVCTP events. |
|
276 @param aPid the PID on which RAvctp will be used |
|
277 @return KErrInUse if aPid is already being used somewhere in the system |
|
278 KErrPermissionDenied if aNotify has the incorrect SID for aPid |
|
279 a system-wide error code |
|
280 @panic if Open() is not called before any other RAvctp method |
|
281 @capability the SID of the process holding the RAvctp is checked if it is allowed to access aPid. |
|
282 @panic if the RAvctp object is already open |
|
283 */ |
|
284 IMPORT_C TInt Open(MAvctpEventNotify& aNotify, SymbianAvctp::TPid aPid, MAvctpChannel*& aPrimaryChannel); |
|
285 |
|
286 /** |
|
287 Closes the RAvctp session by immediately disconnecting all remote devices it is explicitly connected to, |
|
288 cancelling all outstanding requests and freeing all resources associated with it. This method deregisters |
|
289 aNotify from receiving any more AVCTP event notifications. The client will have to Open() this object |
|
290 before it can be used again. |
|
291 |
|
292 This function is safe to call at almost any time. The only case when this is not appropriate is |
|
293 if a secondary channel is installed in a different thread AND that thread has it's own heap. For |
|
294 this case the UninstallSecondaryChannel function must be called in the thread running the secondary |
|
295 channel BEFORE this function is called. |
|
296 |
|
297 @see RAvctp::UninstallSecondaryChannel |
|
298 |
|
299 @param aImmediacy if the default, ENormal, is used then this function will shutdown gracefully. |
|
300 if EImmediate is given then RAvctp will close as quickly as possible which may result |
|
301 in some data not actually being sent that the client had received a successful SendComplete. |
|
302 */ |
|
303 IMPORT_C void Close(TCloseType aImmediacy = ENormal); |
|
304 |
|
305 /** |
|
306 This function is not currently supported. Use of it will result in MaenErrorNotify being called |
|
307 with an error of KErrNotSupported. |
|
308 */ |
|
309 IMPORT_C void CloseGracefully(); |
|
310 |
|
311 /** |
|
312 Installs the second AVCTP channel. |
|
313 */ |
|
314 IMPORT_C TInt InstallSecondaryChannel(MAvctpEventNotify& aSecondChannelObserver, MAvctpChannel*& aSecondaryChannel); |
|
315 |
|
316 /** |
|
317 Uninstalls the second AVCTP channel. |
|
318 This can be used for when the AVCTP second channel is run in a different thread to the primary channel. |
|
319 |
|
320 @param aImmediacy if the default, ENormal, is used then this function will shutdown gracefully. |
|
321 if EImmediate is given then the second channel will close as quickly as possible which may result |
|
322 in some data not actually being sent that the client had received a successful SendComplete. |
|
323 **/ |
|
324 IMPORT_C void UninstallSecondaryChannel(TCloseType aImmediacy = ENormal); |
|
325 private: |
|
326 /** |
|
327 The copy constructor is made private to help ensure there is only ever one RAvctp object |
|
328 per PID |
|
329 */ |
|
330 RAvctp(const RAvctp& aObjectToCopy); |
|
331 |
|
332 private: |
|
333 CAvctpBody* iBody; |
|
334 }; |
|
335 |
|
336 #endif // AVCTPSERVICES_H |