VirtualBox

source: vbox/trunk/include/VBox/usbfilter.h@ 103224

Last change on this file since 103224 was 100772, checked in by vboxsync, 15 months ago

include/VBox/usbfilter.h,HostDrivers/VBoxUSB/USBFilter: IUSBDeviceFilter:
USB device interval filters don't work. bugref:10452

Main/Host,Main/USBDeviceFilter: Adding or removing global USB device
filters causes memory corruption wihch can lead to a deadlock or a SEGV
as the list of global USB device filters (llChildren) changes while
the list is being walked.

Frontends/VBoxManage: 'VBoxManage list usbfilters' doesn't display the
'Port' value of the device filter.

Frontends/VBoxManage: 'VBoxManage add usbfilter' and 'VBoxManage modify
usbfilter' both ignore the --product="Value" option.

Main/VirtualBox.xidl: Improve the IUSBDeviceFilter wording to make
things clearer in the 'VirtualBox Programming Guide and Reference Guide'
aka SDKRef.pdf.

HostDrivers/VBoxUSB/testcase/tstUSBFilter: Include a variety of USB
device filter entries which include the 'int:' prefix to fully exercise
the interval filter parsing code.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 10.2 KB
Line 
1/** @file
2 * USBFilter - USB Filter constructs shared by kernel and user mode.
3 * (DEV,HDrv,Main)
4 */
5
6/*
7 * Copyright (C) 2007-2023 Oracle and/or its affiliates.
8 *
9 * This file is part of VirtualBox base platform packages, as
10 * available from https://www.virtualbox.org.
11 *
12 * This program is free software; you can redistribute it and/or
13 * modify it under the terms of the GNU General Public License
14 * as published by the Free Software Foundation, in version 3 of the
15 * License.
16 *
17 * This program is distributed in the hope that it will be useful, but
18 * WITHOUT ANY WARRANTY; without even the implied warranty of
19 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
20 * General Public License for more details.
21 *
22 * You should have received a copy of the GNU General Public License
23 * along with this program; if not, see <https://www.gnu.org/licenses>.
24 *
25 * The contents of this file may alternatively be used under the terms
26 * of the Common Development and Distribution License Version 1.0
27 * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
28 * in the VirtualBox distribution, in which case the provisions of the
29 * CDDL are applicable instead of those of the GPL.
30 *
31 * You may elect to license modified versions of this file under the
32 * terms and conditions of either the GPL or the CDDL or both.
33 *
34 * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
35 */
36
37#ifndef VBOX_INCLUDED_usbfilter_h
38#define VBOX_INCLUDED_usbfilter_h
39#ifndef RT_WITHOUT_PRAGMA_ONCE
40# pragma once
41#endif
42
43#include <iprt/types.h>
44#include <iprt/assert.h>
45#include <VBox/cdefs.h>
46#include <VBox/usb.h>
47
48
49/** @defgroup grp_usbfilter USBFilter - USB Filter constructs shared by kernel and user mode
50 * @ingroup grp_usblib
51 * @{
52 */
53
54/**
55 * How to match a field.
56 *
57 * @remarks This is a binary interface (drivers).
58 */
59typedef enum USBFILTERMATCH
60{
61 /** The usual invalid first zero value. */
62 USBFILTERMATCH_INVALID = 0,
63 /** Ignore this field (always matching).
64 * Device Data: No value present. */
65 USBFILTERMATCH_IGNORE,
66 /** Only require this field to be present on the device. */
67 USBFILTERMATCH_PRESENT,
68
69 /** Numeric Field: The first numeric field matching method. */
70 USBFILTERMATCH_NUM_FIRST,
71 /** Numeric Field: Exact match, required to be present. */
72 USBFILTERMATCH_NUM_EXACT = USBFILTERMATCH_NUM_FIRST,
73 /** Numeric Field: Exact match or not present. */
74 USBFILTERMATCH_NUM_EXACT_NP,
75 /** Numeric Field: The last numeric field matching method (inclusive). */
76 USBFILTERMATCH_NUM_LAST = USBFILTERMATCH_NUM_EXACT_NP,
77
78 /** String Field: The first string field matching method. */
79 USBFILTERMATCH_STR_FIRST,
80 /** String Field: Exact match, required to be present. */
81 USBFILTERMATCH_STR_EXACT = USBFILTERMATCH_STR_FIRST,
82 /** String Field: Exact match or not present. */
83 USBFILTERMATCH_STR_EXACT_NP,
84 /** String Field: Pattern match, required to be present.*/
85 USBFILTERMATCH_STR_PATTERN,
86 /** String Field: Pattern match or not present.*/
87 USBFILTERMATCH_STR_PATTERN_NP,
88 /** String Field: Numerical expression match, required to be present. */
89 USBFILTERMATCH_NUM_EXPRESSION,
90 /** String Field: Numerical expression match or not present. */
91 USBFILTERMATCH_NUM_EXPRESSION_NP,
92 /** String Field: The last string field matching method (inclusive). */
93 USBFILTERMATCH_STR_LAST = USBFILTERMATCH_NUM_EXPRESSION_NP,
94
95 /** The end of valid matching methods (exclusive). */
96 USBFILTERMATCH_END
97} USBFILTERMATCH;
98AssertCompile(USBFILTERMATCH_END == 11);
99
100
101/**
102 * A USB filter field.
103 *
104 * @remarks This is a binary interface (drivers).
105 */
106typedef struct USBFILTERFIELD
107{
108 /** The matching method. (USBFILTERMATCH) */
109 uint16_t enmMatch;
110 /** The field value or offset into the string table.
111 * The enmMatch field decides which it is. */
112 uint16_t u16Value;
113} USBFILTERFIELD;
114AssertCompileSize(USBFILTERFIELD, 4);
115/** Pointer to a USB filter field. */
116typedef USBFILTERFIELD *PUSBFILTERFIELD;
117/** Pointer to a const USBFILTERFIELD. */
118typedef const USBFILTERFIELD *PCUSBFILTERFIELD;
119
120
121/**
122 * USB filter field index.
123 *
124 * This is used as an index into the USBFILTER::aFields array.
125 *
126 * @remarks This is a binary interface (drivers).
127 */
128typedef enum USBFILTERIDX
129{
130 /** idVendor (= 0) */
131 USBFILTERIDX_VENDOR_ID = 0,
132 /** idProduct (= 1) */
133 USBFILTERIDX_PRODUCT_ID,
134 /** bcdDevice (= 2)*/
135 USBFILTERIDX_DEVICE_REV,
136 USBFILTERIDX_DEVICE = USBFILTERIDX_DEVICE_REV,
137 /** bDeviceClass (= 3) */
138 USBFILTERIDX_DEVICE_CLASS,
139 /** bDeviceSubClass (= 4) */
140 USBFILTERIDX_DEVICE_SUB_CLASS,
141 /** bDeviceProtocol (= 5) */
142 USBFILTERIDX_DEVICE_PROTOCOL,
143 /** bBus (= 6 )*/
144 USBFILTERIDX_BUS,
145 /** bPort (=7) */
146 USBFILTERIDX_PORT,
147 /** Manufacturer string. (=8) */
148 USBFILTERIDX_MANUFACTURER_STR,
149 /** Product string. (=9) */
150 USBFILTERIDX_PRODUCT_STR,
151 /** SerialNumber string. (=10) */
152 USBFILTERIDX_SERIAL_NUMBER_STR,
153 /** The end of the USB filter fields (exclusive). */
154 USBFILTERIDX_END
155} USBFILTERIDX;
156AssertCompile(USBFILTERIDX_END == 11);
157
158
159/**
160 * USB Filter types.
161 *
162 * The filters types are list in priority order, i.e. highest priority first.
163 *
164 * @remarks This is a binary interface (drivers).
165 */
166typedef enum USBFILTERTYPE
167{
168 /** The usual invalid first zero value. */
169 USBFILTERTYPE_INVALID = 0,
170 /** The first valid entry. */
171 USBFILTERTYPE_FIRST,
172 /** A one-shot ignore filter that's installed when releasing a device.
173 * This filter will be automatically removedwhen the device re-appears,
174 * or when ring-3 decides that time is up, or if ring-3 dies upon us. */
175 USBFILTERTYPE_ONESHOT_IGNORE = USBFILTERTYPE_FIRST,
176 /** A one-shot capture filter that's installed when hijacking a device that's already plugged.
177 * This filter will be automatically removed when the device re-appears,
178 * or when ring-3 decides that time is up, or if ring-3 dies upon us. */
179 USBFILTERTYPE_ONESHOT_CAPTURE,
180 /** Ignore filter.
181 * This picks out devices that shouldn't be captured. */
182 USBFILTERTYPE_IGNORE,
183 /** A normal capture filter.
184 * When a device matching the filter is attach, we'll take it. */
185 USBFILTERTYPE_CAPTURE,
186 /** The end of the valid filter types (exclusive). */
187 USBFILTERTYPE_END,
188 /** The usual 32-bit hack. */
189 USBFILTERTYPE_32BIT_HACK = 0x7fffffff
190} USBFILTERTYPE;
191AssertCompileSize(USBFILTERTYPE, 4);
192AssertCompile(USBFILTERTYPE_END == 5);
193
194
195/**
196 * USB Filter.
197 *
198 * Consider the an abstract data type, use the methods below to access it.
199 *
200 * @remarks This is a binary interface (drivers).
201 */
202typedef struct USBFILTER
203{
204 /** Magic number (USBFILTER_MAGIC). */
205 uint32_t u32Magic;
206 /** The filter type. */
207 USBFILTERTYPE enmType;
208 /** The filter fields.
209 * This array is indexed by USBFILTERIDX */
210 USBFILTERFIELD aFields[USBFILTERIDX_END];
211 /** Offset to the end of the string table (last terminator). (used to speed up things) */
212 uint32_t offCurEnd;
213 /** String table.
214 * This is used for string and numeric patterns. */
215 char achStrTab[256];
216} USBFILTER;
217AssertCompileSize(USBFILTER, 312);
218
219/** Pointer to a USBLib filter. */
220typedef USBFILTER *PUSBFILTER;
221/** Pointer to a const USBLib filter. */
222typedef const USBFILTER *PCUSBFILTER;
223
224/** USBFILTER::u32Magic (Yasuhiro Nightow). */
225#define USBFILTER_MAGIC UINT32_C(0x19670408)
226
227
228RT_C_DECLS_BEGIN
229
230USBLIB_DECL(void) USBFilterInit(PUSBFILTER pFilter, USBFILTERTYPE enmType);
231USBLIB_DECL(void) USBFilterClone(PUSBFILTER pFilter, PCUSBFILTER pToClone);
232USBLIB_DECL(void) USBFilterDelete(PUSBFILTER pFilter);
233USBLIB_DECL(int) USBFilterValidate(PCUSBFILTER pFilter);
234USBLIB_DECL(bool) USBFilterMatch(PCUSBFILTER pFilter, PCUSBFILTER pDevice);
235USBLIB_DECL(int) USBFilterMatchRated(PCUSBFILTER pFilter, PCUSBFILTER pDevice);
236USBLIB_DECL(bool) USBFilterMatchDevice(PCUSBFILTER pFilter, PCUSBDEVICE pDevice);
237USBLIB_DECL(bool) USBFilterIsIdentical(PCUSBFILTER pFilter, PCUSBFILTER pFilter2);
238
239USBLIB_DECL(int) USBFilterSetFilterType(PUSBFILTER pFilter, USBFILTERTYPE enmType);
240USBLIB_DECL(int) USBFilterSetIgnore(PUSBFILTER pFilter, USBFILTERIDX enmFieldIdx);
241USBLIB_DECL(int) USBFilterSetPresentOnly(PUSBFILTER pFilter, USBFILTERIDX enmFieldIdx);
242USBLIB_DECL(int) USBFilterSetNumExact(PUSBFILTER pFilter, USBFILTERIDX enmFieldIdx, uint16_t u16Value, bool fMustBePresent);
243USBLIB_DECL(int) USBFilterSetNumExpression(PUSBFILTER pFilter, USBFILTERIDX enmFieldIdx, const char *pszExpression, bool fMustBePresent);
244USBLIB_DECL(int) USBFilterSetStringExact(PUSBFILTER pFilter, USBFILTERIDX enmFieldIdx, const char *pszValue,
245 bool fMustBePresent, bool fPurge);
246USBLIB_DECL(int) USBFilterSetStringPattern(PUSBFILTER pFilter, USBFILTERIDX enmFieldIdx, const char *pszPattern, bool fMustBePresent);
247USBLIB_DECL(int) USBFilterSetMustBePresent(PUSBFILTER pFilter, USBFILTERIDX enmFieldIdx, bool fMustBePresent);
248
249USBLIB_DECL(USBFILTERTYPE) USBFilterGetFilterType(PCUSBFILTER pFilter);
250USBLIB_DECL(USBFILTERMATCH) USBFilterGetMatchingMethod(PCUSBFILTER pFilter, USBFILTERIDX enmFieldIdx);
251USBLIB_DECL(int) USBFilterQueryNum(PCUSBFILTER pFilter, USBFILTERIDX enmFieldIdx, uint16_t *pu16Value);
252USBLIB_DECL(int) USBFilterGetNum(PCUSBFILTER pFilter, USBFILTERIDX enmFieldIdx);
253USBLIB_DECL(int) USBFilterQueryString(PUSBFILTER pFilter, USBFILTERIDX enmFieldIdx, char *pszBuf, size_t cchBuf);
254USBLIB_DECL(const char *) USBFilterGetString(PCUSBFILTER pFilter, USBFILTERIDX enmFieldIdx);
255USBLIB_DECL(ssize_t) USBFilterGetStringLen(PCUSBFILTER pFilter, USBFILTERIDX enmFieldIdx);
256
257USBLIB_DECL(bool) USBFilterHasAnySubstatialCriteria(PCUSBFILTER pFilter);
258USBLIB_DECL(bool) USBFilterIsNumericField(USBFILTERIDX enmFieldIdx);
259USBLIB_DECL(bool) USBFilterIsStringField(USBFILTERIDX enmFieldIdx);
260USBLIB_DECL(bool) USBFilterIsMethodUsingNumericValue(USBFILTERMATCH enmMatchingMethod);
261USBLIB_DECL(bool) USBFilterIsMethodUsingStringValue(USBFILTERMATCH enmMatchingMethod);
262USBLIB_DECL(bool) USBFilterIsMethodNumeric(USBFILTERMATCH enmMatchingMethod);
263USBLIB_DECL(bool) USBFilterIsMethodString(USBFILTERMATCH enmMatchingMethod);
264
265RT_C_DECLS_END
266
267/** @} */
268
269#endif /* !VBOX_INCLUDED_usbfilter_h */
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette