1 /*
2 * Copyright (C) 2006 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17 #ifndef ANDROID_USB_FILE_OBJECT_H__
18 #define ANDROID_USB_FILE_OBJECT_H__
19 /** \file
20 This file consists of declaration of class AndroidUsbFileObject that
21 encapsulates a common extension for all KMDF file object types.
22 */
23
24 #include "android_usb_wdf_object.h"
25 #include "android_usb_device_object.h"
26
27 /** Enumerator AndroidUsbFileObjectType defines possible types for our file
28 object extension.
29 */
30 enum AndroidUsbFileObjectType {
31 /// File extends device FO
32 AndroidUsbFileObjectTypeDevice,
33
34 // File extends a pipe FO
35 AndroidUsbFileObjectTypePipe,
36
37 AndroidUsbFileObjectTypeMax,
38 };
39
40 /** AndroidUsbFileObject class encapsulates a common extension for all KMDF
41 file object types. Instances of this class must be allocated from
42 NonPagedPool.
43 */
44 class AndroidUsbFileObject : public AndroidUsbWdfObject {
45 public:
46 /** \brief Constructs the object.
47
48 This method must be called at low IRQL.
49 @param fo_type[in] Type of the file object that this object extends
50 @param dev_obj[in] Our device object for which this file has been created
51 @param wdf_fo[in] KMDF file object for this extension
52 */
53 AndroidUsbFileObject(AndroidUsbFileObjectType fo_type,
54 AndroidUsbDeviceObject* dev_obj,
55 WDFFILEOBJECT wdf_fo);
56
57 /** \brief Destructs the object.
58
59 This method can be called at any IRQL.
60 */
61 virtual ~AndroidUsbFileObject();
62
63 /** \brief Initializes the object
64
65 This method verifies that instance has been created and calls base class's
66 InitializeContext method to register itself with the wrapped FO. All
67 derived classes must call this method when initializing.
68 This method must be called at low IRQL.
69 @return STATUS_SUCCESS on success or an appropriate error code
70 */
71 virtual NTSTATUS Initialize();
72
73 /** \brief Read event handler
74
75 This method is called when a read request comes to the file object this
76 class extends.
77 This method can be called IRQL <= DISPATCH_LEVEL.
78 @param request[in] A handle to a framework request object.
79 @param length[in] The number of bytes to be read.
80 @return Successful status or an appropriate error code
81 */
82 virtual void OnEvtIoRead(WDFREQUEST request, size_t length);
83
84 /** \brief Write event handler
85
86 This method is called when a write request comes to the file object this
87 class extends.
88 This callback can be called IRQL <= DISPATCH_LEVEL.
89 @param request[in] A handle to a framework request object.
90 @param length[in] The number of bytes to be written.
91 @return Successful status or an appropriate error code
92 */
93 virtual void OnEvtIoWrite(WDFREQUEST request, size_t length);
94
95 /** \brief IOCTL event handler
96
97 This method is called when a device control request comes to the file
98 object this class extends.
99 This callback can be called IRQL <= DISPATCH_LEVEL.
100 @param request[in] A handle to a framework request object.
101 @param output_buf_len[in] The length, in bytes, of the request's output
102 buffer, if an output buffer is available.
103 @param input_buf_len[in] The length, in bytes, of the request's input
104 buffer, if an input buffer is available.
105 @param ioctl_code[in] The driver-defined or system-defined I/O control code
106 that is associated with the request.
107 @return Successful status or an appropriate error code
108 */
109 virtual void OnEvtIoDeviceControl(WDFREQUEST request,
110 size_t output_buf_len,
111 size_t input_buf_len,
112 ULONG ioctl_code);
113
114 public:
115 /// Gets KMDF file handle for this extension
wdf_file()116 __forceinline WDFFILEOBJECT wdf_file() const {
117 return reinterpret_cast<WDFFILEOBJECT>(wdf_object());
118 }
119
120 /// Gets device object that owns this file
device_object()121 __forceinline AndroidUsbDeviceObject* device_object() const {
122 return device_object_;
123 }
124
125 /// Gets type of the file object that this extension wraps
file_type()126 __forceinline AndroidUsbFileObjectType file_type() const {
127 return file_type_;
128 }
129
130 /// Gets WDF device handle for device that owns this file
wdf_device()131 __forceinline WDFDEVICE wdf_device() const {
132 ASSERT(NULL != device_object());
133 return (NULL != device_object()) ? device_object()->wdf_device() :
134 NULL;
135 }
136
137 /// Gets target (PDO) device handle for the device that owns this file
wdf_target_device()138 __forceinline WDFUSBDEVICE wdf_target_device() const {
139 ASSERT(NULL != device_object());
140 return (NULL != device_object()) ? device_object()->wdf_target_device() :
141 NULL;
142 }
143
144 protected:
145 /// Device object that owns this file
146 AndroidUsbDeviceObject* device_object_;
147
148 /// Type of the file object that this extension wraps
149 AndroidUsbFileObjectType file_type_;
150 };
151
152 /** \brief Gets file KMDF object extension for the given KMDF file object
153
154 This method can be called at any IRQL
155 @param wdf_fo[in] KMDF file handle describing file object
156 @return Instance of AndroidUsbFileObject associated with this object or NULL
157 if association is not found.
158 */
GetAndroidUsbFileObjectFromHandle(WDFFILEOBJECT wdf_fo)159 __forceinline AndroidUsbFileObject* GetAndroidUsbFileObjectFromHandle(
160 WDFFILEOBJECT wdf_fo) {
161 AndroidUsbWdfObject* wdf_object_ext =
162 GetAndroidUsbWdfObjectFromHandle(wdf_fo);
163 ASSERT(NULL != wdf_object_ext);
164 if (NULL != wdf_object_ext) {
165 ASSERT(wdf_object_ext->Is(AndroidUsbWdfObjectTypeFile));
166 if (wdf_object_ext->Is(AndroidUsbWdfObjectTypeFile))
167 return reinterpret_cast<AndroidUsbFileObject*>(wdf_object_ext);
168 }
169 return NULL;
170 }
171
172 /** \brief Gets file KMDF file object extension for the given request
173
174 This method can be called at any IRQL
175 @param request[in] KMDF request object
176 @return Instance of AndroidUsbFileObject associated with this request or NULL
177 if association is not found.
178 */
GetAndroidUsbFileObjectForRequest(WDFREQUEST request)179 __forceinline AndroidUsbFileObject* GetAndroidUsbFileObjectForRequest(
180 WDFREQUEST request) {
181 return GetAndroidUsbFileObjectFromHandle(WdfRequestGetFileObject(request));
182 }
183
184 #endif // ANDROID_USB_FILE_OBJECT_H__
185