VirtualBox

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

Last change on this file since 78220 was 76585, checked in by vboxsync, 6 years ago

*: scm --fix-header-guard-endif

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