VirtualBox

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

Last change on this file since 96550 was 96407, checked in by vboxsync, 2 years ago

scm copyright and license note update

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 10.3 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-2022 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: Expression match, required to be present.
76 * The expression is represented as a string. */
77 USBFILTERMATCH_NUM_EXPRESSION,
78 /** Numeric Field: Expression match or not present.
79 * The expression is represented as a string. */
80 USBFILTERMATCH_NUM_EXPRESSION_NP,
81 /** Numeric Field: The last numeric field matching method (inclusive). */
82 USBFILTERMATCH_NUM_LAST = USBFILTERMATCH_NUM_EXPRESSION_NP,
83
84 /** String Field: The first string field matching method. */
85 USBFILTERMATCH_STR_FIRST,
86 /** String Field: Exact match, required to be present. */
87 USBFILTERMATCH_STR_EXACT = USBFILTERMATCH_STR_FIRST,
88 /** String Field: Exact match or not present. */
89 USBFILTERMATCH_STR_EXACT_NP,
90 /** String Field: Pattern match, required to be present.*/
91 USBFILTERMATCH_STR_PATTERN,
92 /** String Field: Pattern match or not present.*/
93 USBFILTERMATCH_STR_PATTERN_NP,
94 /** String Field: The last string field matching method (inclusive). */
95 USBFILTERMATCH_STR_LAST = USBFILTERMATCH_STR_PATTERN_NP,
96
97 /** The end of valid matching methods (exclusive). */
98 USBFILTERMATCH_END
99} USBFILTERMATCH;
100AssertCompile(USBFILTERMATCH_END == 11);
101
102
103/**
104 * A USB filter field.
105 *
106 * @remarks This is a binary interface (drivers).
107 */
108typedef struct USBFILTERFIELD
109{
110 /** The matching method. (USBFILTERMATCH) */
111 uint16_t enmMatch;
112 /** The field value or offset into the string table.
113 * The enmMatch field decides which it is. */
114 uint16_t u16Value;
115} USBFILTERFIELD;
116AssertCompileSize(USBFILTERFIELD, 4);
117/** Pointer to a USB filter field. */
118typedef USBFILTERFIELD *PUSBFILTERFIELD;
119/** Pointer to a const USBFILTERFIELD. */
120typedef const USBFILTERFIELD *PCUSBFILTERFIELD;
121
122
123/**
124 * USB filter field index.
125 *
126 * This is used as an index into the USBFILTER::aFields array.
127 *
128 * @remarks This is a binary interface (drivers).
129 */
130typedef enum USBFILTERIDX
131{
132 /** idVendor (= 0) */
133 USBFILTERIDX_VENDOR_ID = 0,
134 /** idProduct (= 1) */
135 USBFILTERIDX_PRODUCT_ID,
136 /** bcdDevice (= 2)*/
137 USBFILTERIDX_DEVICE_REV,
138 USBFILTERIDX_DEVICE = USBFILTERIDX_DEVICE_REV,
139 /** bDeviceClass (= 3) */
140 USBFILTERIDX_DEVICE_CLASS,
141 /** bDeviceSubClass (= 4) */
142 USBFILTERIDX_DEVICE_SUB_CLASS,
143 /** bDeviceProtocol (= 5) */
144 USBFILTERIDX_DEVICE_PROTOCOL,
145 /** bBus (= 6 )*/
146 USBFILTERIDX_BUS,
147 /** bPort (=7) */
148 USBFILTERIDX_PORT,
149 /** Manufacturer string. (=8) */
150 USBFILTERIDX_MANUFACTURER_STR,
151 /** Product string. (=9) */
152 USBFILTERIDX_PRODUCT_STR,
153 /** SerialNumber string. (=10) */
154 USBFILTERIDX_SERIAL_NUMBER_STR,
155 /** The end of the USB filter fields (exclusive). */
156 USBFILTERIDX_END
157} USBFILTERIDX;
158AssertCompile(USBFILTERIDX_END == 11);
159
160
161/**
162 * USB Filter types.
163 *
164 * The filters types are list in priority order, i.e. highest priority first.
165 *
166 * @remarks This is a binary interface (drivers).
167 */
168typedef enum USBFILTERTYPE
169{
170 /** The usual invalid first zero value. */
171 USBFILTERTYPE_INVALID = 0,
172 /** The first valid entry. */
173 USBFILTERTYPE_FIRST,
174 /** A one-shot ignore filter that's installed when releasing a device.
175 * This filter will be automatically removedwhen the device re-appears,
176 * or when ring-3 decides that time is up, or if ring-3 dies upon us. */
177 USBFILTERTYPE_ONESHOT_IGNORE = USBFILTERTYPE_FIRST,
178 /** A one-shot capture filter that's installed when hijacking a device that's already plugged.
179 * This filter will be automatically removed when the device re-appears,
180 * or when ring-3 decides that time is up, or if ring-3 dies upon us. */
181 USBFILTERTYPE_ONESHOT_CAPTURE,
182 /** Ignore filter.
183 * This picks out devices that shouldn't be captured. */
184 USBFILTERTYPE_IGNORE,
185 /** A normal capture filter.
186 * When a device matching the filter is attach, we'll take it. */
187 USBFILTERTYPE_CAPTURE,
188 /** The end of the valid filter types (exclusive). */
189 USBFILTERTYPE_END,
190 /** The usual 32-bit hack. */
191 USBFILTERTYPE_32BIT_HACK = 0x7fffffff
192} USBFILTERTYPE;
193AssertCompileSize(USBFILTERTYPE, 4);
194AssertCompile(USBFILTERTYPE_END == 5);
195
196
197/**
198 * USB Filter.
199 *
200 * Consider the an abstract data type, use the methods below to access it.
201 *
202 * @remarks This is a binary interface (drivers).
203 */
204typedef struct USBFILTER
205{
206 /** Magic number (USBFILTER_MAGIC). */
207 uint32_t u32Magic;
208 /** The filter type. */
209 USBFILTERTYPE enmType;
210 /** The filter fields.
211 * This array is indexed by USBFILTERIDX */
212 USBFILTERFIELD aFields[USBFILTERIDX_END];
213 /** Offset to the end of the string table (last terminator). (used to speed up things) */
214 uint32_t offCurEnd;
215 /** String table.
216 * This is used for string and numeric patterns. */
217 char achStrTab[256];
218} USBFILTER;
219AssertCompileSize(USBFILTER, 312);
220
221/** Pointer to a USBLib filter. */
222typedef USBFILTER *PUSBFILTER;
223/** Pointer to a const USBLib filter. */
224typedef const USBFILTER *PCUSBFILTER;
225
226/** USBFILTER::u32Magic (Yasuhiro Nightow). */
227#define USBFILTER_MAGIC UINT32_C(0x19670408)
228
229
230RT_C_DECLS_BEGIN
231
232USBLIB_DECL(void) USBFilterInit(PUSBFILTER pFilter, USBFILTERTYPE enmType);
233USBLIB_DECL(void) USBFilterClone(PUSBFILTER pFilter, PCUSBFILTER pToClone);
234USBLIB_DECL(void) USBFilterDelete(PUSBFILTER pFilter);
235USBLIB_DECL(int) USBFilterValidate(PCUSBFILTER pFilter);
236USBLIB_DECL(bool) USBFilterMatch(PCUSBFILTER pFilter, PCUSBFILTER pDevice);
237USBLIB_DECL(int) USBFilterMatchRated(PCUSBFILTER pFilter, PCUSBFILTER pDevice);
238USBLIB_DECL(bool) USBFilterMatchDevice(PCUSBFILTER pFilter, PCUSBDEVICE pDevice);
239USBLIB_DECL(bool) USBFilterIsIdentical(PCUSBFILTER pFilter, PCUSBFILTER pFilter2);
240
241USBLIB_DECL(int) USBFilterSetFilterType(PUSBFILTER pFilter, USBFILTERTYPE enmType);
242USBLIB_DECL(int) USBFilterSetIgnore(PUSBFILTER pFilter, USBFILTERIDX enmFieldIdx);
243USBLIB_DECL(int) USBFilterSetPresentOnly(PUSBFILTER pFilter, USBFILTERIDX enmFieldIdx);
244USBLIB_DECL(int) USBFilterSetNumExact(PUSBFILTER pFilter, USBFILTERIDX enmFieldIdx, uint16_t u16Value, bool fMustBePresent);
245USBLIB_DECL(int) USBFilterSetNumExpression(PUSBFILTER pFilter, USBFILTERIDX enmFieldIdx, const char *pszExpression, bool fMustBePresent);
246USBLIB_DECL(int) USBFilterSetStringExact(PUSBFILTER pFilter, USBFILTERIDX enmFieldIdx, const char *pszValue,
247 bool fMustBePresent, bool fPurge);
248USBLIB_DECL(int) USBFilterSetStringPattern(PUSBFILTER pFilter, USBFILTERIDX enmFieldIdx, const char *pszPattern, bool fMustBePresent);
249USBLIB_DECL(int) USBFilterSetMustBePresent(PUSBFILTER pFilter, USBFILTERIDX enmFieldIdx, bool fMustBePresent);
250
251USBLIB_DECL(USBFILTERTYPE) USBFilterGetFilterType(PCUSBFILTER pFilter);
252USBLIB_DECL(USBFILTERMATCH) USBFilterGetMatchingMethod(PCUSBFILTER pFilter, USBFILTERIDX enmFieldIdx);
253USBLIB_DECL(int) USBFilterQueryNum(PCUSBFILTER pFilter, USBFILTERIDX enmFieldIdx, uint16_t *pu16Value);
254USBLIB_DECL(int) USBFilterGetNum(PCUSBFILTER pFilter, USBFILTERIDX enmFieldIdx);
255USBLIB_DECL(int) USBFilterQueryString(PUSBFILTER pFilter, USBFILTERIDX enmFieldIdx, char *pszBuf, size_t cchBuf);
256USBLIB_DECL(const char *) USBFilterGetString(PCUSBFILTER pFilter, USBFILTERIDX enmFieldIdx);
257USBLIB_DECL(ssize_t) USBFilterGetStringLen(PCUSBFILTER pFilter, USBFILTERIDX enmFieldIdx);
258
259USBLIB_DECL(bool) USBFilterHasAnySubstatialCriteria(PCUSBFILTER pFilter);
260USBLIB_DECL(bool) USBFilterIsNumericField(USBFILTERIDX enmFieldIdx);
261USBLIB_DECL(bool) USBFilterIsStringField(USBFILTERIDX enmFieldIdx);
262USBLIB_DECL(bool) USBFilterIsMethodUsingNumericValue(USBFILTERMATCH enmMatchingMethod);
263USBLIB_DECL(bool) USBFilterIsMethodUsingStringValue(USBFILTERMATCH enmMatchingMethod);
264USBLIB_DECL(bool) USBFilterIsMethodNumeric(USBFILTERMATCH enmMatchingMethod);
265USBLIB_DECL(bool) USBFilterIsMethodString(USBFILTERMATCH enmMatchingMethod);
266
267RT_C_DECLS_END
268
269/** @} */
270
271#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