/** @file
* USBFilter - USB Filter constructs shared by kernel and user mode.
* (DEV,HDrv,Main)
*/
/*
* Copyright (C) 2007-2010 Oracle Corporation
*
* This file is part of VirtualBox Open Source Edition (OSE), as
* available from http://www.virtualbox.org. This file is free software;
* General Public License (GPL) as published by the Free Software
* Foundation, in version 2 as it comes in the "COPYING" file of the
* VirtualBox OSE distribution. VirtualBox OSE is distributed in the
* hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
*
* The contents of this file may alternatively be used under the terms
* of the Common Development and Distribution License Version 1.0
* (CDDL) only, as it comes in the "COPYING.CDDL" file of the
* VirtualBox OSE distribution, in which case the provisions of the
* CDDL are applicable instead of those of the GPL.
*
* You may elect to license modified versions of this file under the
* terms and conditions of either the GPL or the CDDL or both.
*/
#ifndef ___VBox_usbfilter_h
#define ___VBox_usbfilter_h
/** @defgroup grp_USBFilter USBFilter - USB Filter constructs shared by kernel and user mode
* @ingroup grp_USBLib
* @{
*/
/**
* How to match a field.
*
* @remarks This is a binary interface (drivers).
*/
typedef enum USBFILTERMATCH
{
/** The usual invalid first zero value. */
/** Ignore this field (always matching).
* Device Data: No value present. */
/** Only require this field to be present on the device. */
/** Numeric Field: The first numeric field matching method. */
/** Numeric Field: Exact match, required to be present. */
/** Numeric Field: Exact match or not present. */
/** Numeric Field: Expression match, required to be present.
* The expression is represented as a string. */
/** Numeric Field: Expression match or not present.
* The expression is represented as a string. */
/** Numeric Field: The last numeric field matching method (inclusive). */
/** String Field: The first string field matching method. */
/** String Field: Exact match, required to be present. */
/** String Field: Exact match or not present. */
/** String Field: Pattern match, required to be present.*/
/** String Field: Pattern match or not present.*/
/** String Field: The last string field matching method (inclusive). */
/** The end of valid matching methods (exclusive). */
/**
* A USB filter field.
*
* @remarks This is a binary interface (drivers).
*/
typedef struct USBFILTERFIELD
{
/** The matching method. (USBFILTERMATCH) */
/** The field value or offset into the string table.
* The enmMatch field decides which it is. */
/** Pointer to a USB filter field. */
/** Pointer to a const USBFILTERFIELD. */
/**
* USB filter field index.
*
* This is used as an index into the USBFILTER::aFields array.
*
* @remarks This is a binary interface (drivers).
*/
typedef enum USBFILTERIDX
{
/** idVendor (= 0) */
/** idProduct (= 1) */
/** bcdDevice (= 2)*/
/** bDeviceClass (= 3) */
/** bDeviceSubClass (= 4) */
/** bDeviceProtocol (= 5) */
/** bBus (= 6 )*/
/** bPort (=7) */
/** Manufacturer string. (=8) */
/** Product string. (=9) */
/** SerialNumber string. (=10) */
/** The end of the USB filter fields (exclusive). */
} USBFILTERIDX;
/**
* USB Filter types.
*
* The filters types are list in priority order, i.e. highest priority first.
*
* @remarks This is a binary interface (drivers).
*/
typedef enum USBFILTERTYPE
{
/** The usual invalid first zero value. */
/** The first valid entry. */
/** A one-shot ignore filter that's installed when releasing a device.
* This filter will be automatically removedwhen the device re-appears,
* or when ring-3 decides that time is up, or if ring-3 dies upon us. */
/** A one-shot capture filter that's installed when hijacking a device that's already plugged.
* This filter will be automatically removed when the device re-appears,
* or when ring-3 decides that time is up, or if ring-3 dies upon us. */
/** Ignore filter.
* This picks out devices that shouldn't be captured. */
/** A normal capture filter.
* When a device matching the filter is attach, we'll take it. */
/** The end of the valid filter types (exclusive). */
/** The usual 32-bit hack. */
/**
* USB Filter.
*
* Consider the an abstract data type, use the methods below to access it.
*
* @remarks This is a binary interface (drivers).
*/
typedef struct USBFILTER
{
/** Magic number (USBFILTER_MAGIC). */
/** The filter type. */
/** The filter fields.
* This array is indexed by USBFILTERIDX */
/** Offset to the end of the string table (last terminator). (used to speed up things) */
/** String table.
* This is used for string and numeric patterns. */
} USBFILTER;
/** Pointer to a USBLib filter. */
/** Pointer to a const USBLib filter. */
/** USBFILTER::u32Magic (Yasuhiro Nightow). */
USBLIB_DECL(int) USBFilterSetNumExact(PUSBFILTER pFilter, USBFILTERIDX enmFieldIdx, uint16_t u16Value, bool fMustBePresent);
USBLIB_DECL(int) USBFilterSetNumExpression(PUSBFILTER pFilter, USBFILTERIDX enmFieldIdx, const char *pszExpression, bool fMustBePresent);
USBLIB_DECL(int) USBFilterSetStringExact(PUSBFILTER pFilter, USBFILTERIDX enmFieldIdx, const char *pszValue, bool fMustBePresent);
USBLIB_DECL(int) USBFilterSetStringPattern(PUSBFILTER pFilter, USBFILTERIDX enmFieldIdx, const char *pszPattern, bool fMustBePresent);
USBLIB_DECL(int) USBFilterSetMustBePresent(PUSBFILTER pFilter, USBFILTERIDX enmFieldIdx, bool fMustBePresent);
USBLIB_DECL(USBFILTERMATCH) USBFilterGetMatchingMethod(PCUSBFILTER pFilter, USBFILTERIDX enmFieldIdx);
USBLIB_DECL(int) USBFilterQueryNum(PCUSBFILTER pFilter, USBFILTERIDX enmFieldIdx, uint16_t *pu16Value);
USBLIB_DECL(int) USBFilterQueryString(PUSBFILTER pFilter, USBFILTERIDX enmFieldIdx, char *pszBuf, size_t cchBuf);
/** @} */
#endif