VirtualBox

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

Last change on this file since 68689 was 62690, checked in by vboxsync, 8 years ago

HostDrivers: warnings

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