|
1 /* |
|
2 * Copyright (c) 2007-2009 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: |
|
15 * |
|
16 */ |
|
17 |
|
18 /** |
|
19 @file |
|
20 @publishedPartner |
|
21 @released |
|
22 */ |
|
23 |
|
24 #ifndef FDCINTERFACE_H |
|
25 #define FDCINTERFACE_H |
|
26 |
|
27 #include <e32base.h> |
|
28 |
|
29 class TUsbDeviceDescriptor; |
|
30 class TUsbConfigurationDescriptor; |
|
31 |
|
32 /** |
|
33 The UID of this FDC interface. |
|
34 If the FDC API ever has to change, a new UID and associated M class will be |
|
35 created. New FDC implementations may implement the new API. Old (non-updated) |
|
36 FDCs will still work because the FDF examines at run-time which interfaces are |
|
37 supported by any particular FDC. |
|
38 */ |
|
39 const TInt KFdcInterfaceV1 = 0x10282B4C; |
|
40 |
|
41 /** |
|
42 Mixin for the FDC API. |
|
43 */ |
|
44 class MFdcInterfaceV1 |
|
45 { |
|
46 public: |
|
47 /** |
|
48 Called when a device is attached. |
|
49 |
|
50 The Function Driver Framework has determined that this Function Driver is |
|
51 the most suitable to drive at least one of the interfaces in the device's |
|
52 selected configuration. |
|
53 |
|
54 Each call to this method represents an attempt by the Function Driver |
|
55 Framework to get the Function Driver Controller to take ownership of |
|
56 interfaces (exactly one Function) on the device. |
|
57 |
|
58 Not all the interfaces contained may be relevant to this Function Driver. |
|
59 Some interfaces may be relevant to this Function Driver, but should *not* |
|
60 be claimed in this call, as described below. |
|
61 |
|
62 The device's entire device descriptor and configuration descriptor are |
|
63 given. |
|
64 |
|
65 The Function Driver Framework provides a collection (aInterfaces) of |
|
66 interfaces which it is offering to the Function Driver Controller. The |
|
67 Function Driver Controller MUST take ownership of the first of these by |
|
68 calling MFdcPluginObserver::TokenForInterface (the Function Driver |
|
69 Controller was selected by the Function Driver Framework on the basis of |
|
70 its default_data field matching this particular interface). The Function |
|
71 Driver Controller MUST also take ownership of as many following interfaces |
|
72 as make up a single Function as defined by the relevant USB Class, again |
|
73 by calling MFdcPluginObserver::TokenForInterface for them. |
|
74 |
|
75 The Function Driver Controller may examine interface descriptors for the |
|
76 interfaces it is being offered using the bInterfaceNumber items in |
|
77 aInterfaces, and the TUsbConfigurationDescriptor given |
|
78 (aConfigurationDescriptor). |
|
79 |
|
80 Once exactly one Function has been claimed, the Function Driver Controller |
|
81 may return from this method. |
|
82 The Function Driver Framework does not make further attempts to load |
|
83 Function Drivers for the interfaces that have been claimed, whether an |
|
84 error is returned or not. |
|
85 If an error is returned, then (a) the FDF will send a driver loading error |
|
86 to USBMAN, and (b) the FDC must not have opened ANY RUsbInterfaces as a |
|
87 result of this call to Mfi1NewFunction. |
|
88 It is important for the Function Driver Controller to claim all the |
|
89 interfaces it should, even if it finds out early on that it won't be able |
|
90 to handle the Function for environmental or other reasons. |
|
91 The FDC may also return an error indicating that the Class-specific |
|
92 descriptors are incorrectly formatted. |
|
93 |
|
94 The FD is not required to open RUsbInterface handles during |
|
95 Mfi1NewFunction. If it does, then it can pass any failure back as a return |
|
96 value to Mfi1NewFunction and this will be relayed to USBMAN as a driver |
|
97 loading error. If it does not, then the FD must itself take responsibility |
|
98 for relaying relevant failures to the user. (This is in aid of the 'no |
|
99 silent failures' requirement.) |
|
100 |
|
101 This method may be called zero or more times for each device attached, |
|
102 depending on the interfaces present in the device's active configuration |
|
103 and on the other FDs present on the phone. If this function is called (and |
|
104 returns KErrNone) one or more times on a particular FDC, then |
|
105 Mfi1DeviceDetached will be called exactly once when the device is detached. |
|
106 If on device attachment this function is called one or more times for a |
|
107 particular FDC, and each time the FDC returns an error, then no device |
|
108 detachment notification will be given to that FDC. Hence any RUsbInterface |
|
109 handles successfully opened in a call to this function should be cleaned |
|
110 up immediately if the function returns error. |
|
111 |
|
112 @see MFdcPluginObserver::TokenForInterface. |
|
113 |
|
114 @param aDeviceId This is the ID of the new device. This identifier is |
|
115 private between the Function Driver Framework and the Function Driver. Its |
|
116 significance is to identify a device when it is removed (see |
|
117 Mfi1DeviceDetached). It is not equivalent to the device address or to |
|
118 anything else. |
|
119 |
|
120 @param aInterfaces A collection of interface numbers (bInterfaceNumber) |
|
121 which are being offered to the Function Driver Controller. The Function |
|
122 Driver Controller uses items in this array in calls to |
|
123 MFdcPluginObserver::TokenForInterface. Ownership of the array is retained |
|
124 by the FDF. |
|
125 |
|
126 @param aDeviceDescriptor The device descriptor of the device. Ownership is |
|
127 retained by the FDF. |
|
128 |
|
129 @param aConfigurationDescriptor The selected configuration descriptor of |
|
130 the device. Ownership is retained by the FDF. |
|
131 |
|
132 @return Error. On return (ANY error code), the interfaces claimed in calls |
|
133 to MFdcPluginObserver::TokenForInterface are claimed by this FDC. If an |
|
134 error is returned, the FDC must cause no interface handles to be opened as |
|
135 a result of this call. The FDF will indicate a failure to load drivers to |
|
136 USBMAN. |
|
137 */ |
|
138 virtual TInt Mfi1NewFunction(TUint aDeviceId, |
|
139 const TArray<TUint>& aInterfaces, |
|
140 const TUsbDeviceDescriptor& aDeviceDescriptor, |
|
141 const TUsbConfigurationDescriptor& aConfigurationDescriptor) = 0; |
|
142 |
|
143 /** |
|
144 Called when a device is detached. |
|
145 The device is one of those which have previously been notified to the |
|
146 Function Driver in a Mfi1NewFunction call. |
|
147 Any RUsbInterface handles which were opened as a result of the |
|
148 corresponding earlier Mfi1NewFunction call should be closed as they |
|
149 will be useless. |
|
150 |
|
151 @param aDeviceId This serves to identify the device which has disappeared. |
|
152 This will be the device ID given in a previously completed |
|
153 Mfi1NewFunction call. |
|
154 */ |
|
155 virtual void Mfi1DeviceDetached(TUint aDeviceId) = 0; |
|
156 }; |
|
157 |
|
158 #endif // FDCINTERFACE_H |