VirtualBox Main API

Public Attributes | List of all members
IUSBDeviceFilter Interface Reference

The IUSBDeviceFilter interface represents a USB device filter used to perform actions on one or more USB devices. More...

Inheritance diagram for IUSBDeviceFilter:

## Public Attributes
attribute wstring | name
| Visible name for this filter.
attribute boolean | active
| Whether this filter active or has been temporarily disabled.
attribute wstring | vendorId
| Vendor ID filter.
attribute wstring | productId
| Product ID filter.
attribute wstring | revision
| Product revision number filter.
attribute wstring | manufacturer
| Manufacturer filter.
attribute wstring | product
| Product filter.
attribute wstring | serialNumber
| Serial number filter.
attribute wstring | port
| Host USB port filter.
attribute wstring | remote
| Remote state filter.
attribute unsigned long | maskedInterfaces
| This is an advanced option for hiding one or more USB interfaces from the guest.

## Detailed Description

The IUSBDeviceFilter interface represents a USB device filter used to perform actions on one or more USB devices.

USB device filters are used by running virtual machines to automatically capture selected USB devices once they are physically attached to the host computer.

A USB device is matched to a specific device filter if and only if all attributes of the device filter match the corresponding attributes of the device (that is, attributes are joined together using a logical AND operation). On the other hand filter attributes in separate USB device filters are applied as a logical OR operation. So if one would like to create a match such as "this vendor id OR this product id", then one would need to create two filters and specify "any match" (see below) for the other unused attributes.

All filter attributes used for matching are strings. The following filtering expressions are currently supported:

- Interval filters. Used to specify valid intervals for integer device attributes (Vendor ID, Product ID, Revision and Port). The format of the string is:

  `int:((m)|([m]-[n]))(,(m)|([m]-[n]))*`

  where `m` and `n` are integer numbers, either in octal (starting with `0`), hexadecimal (starting with `0x`) or decimal (otherwise), so that `m < n`. If `m` is omitted before a dash (`-`), the minimum possible integer is assumed; if `n` is omitted after a dash, the maximum possible integer is assumed.

- Boolean filters. Used to specify acceptable values for boolean device attributes. The format of the string is:

  `true|false|yes|no|0|1`

- Exact match. Used to specify a single value for the given device attribute. Any string that doesn't start with `int:` represents an exact match. String device attributes are compared to this string in a case-sensitive manner. Integer attributes are first converted to a string (see individual filter attributes) and then compared in a case-insensitive manner.

- Any match. Any value of the corresponding device attribute will match the given filter. An empty or `null` string is used to construct this type of filtering expressions.

Note
  On Windows hosts, interval filters are not currently available. Also all string filter attributes (manufacturer, product, serialNumber) are ignored, so they behave as any match no matter what string expression is specified.

See also
  IUSBDeviceFilters::deviceFilters, IHostUSBDeviceFilter

Interface ID:
  `{45587218-4289-EF4E-8E6A-E5B07816B631}`

## Member Data Documentation

## ◆ name

attribute wstring IUSBDeviceFilter::name

Visible name for this filter.

This name is used to visually distinguish one filter from another, so it can neither be `null` nor an empty string.

## ◆ active

attribute boolean IUSBDeviceFilter::active

Whether this filter active or has been temporarily disabled.

## ◆ vendorId

attribute wstring IUSBDeviceFilter::vendorId

Vendor ID filter.

The string representation for the exact matching has the form `XXXX`, where `X` is the hex digit (including leading zeroes).

## ◆ productId

attribute wstring IUSBDeviceFilter::productId

Product ID filter.

The string representation for the exact matching has the form `XXXX`, where `X` is the hex digit (including leading zeroes).

## ◆ revision

attribute wstring IUSBDeviceFilter::revision

Product revision number filter.

The string representation for the exact matching has the form `IIFF`, where `I` is the decimal digit of the integer part of the revision, and `F` is the decimal digit of its fractional part (including leading and trailing zeros). Note that for interval filters, it's best to use the hexadecimal form, because the revision is stored as a 16 bit packed BCD value; so the expression `int:0x0100-0x0199` will match any revision from `1.0` to `1.99`.

## ◆ manufacturer

attribute wstring IUSBDeviceFilter::manufacturer

Manufacturer filter.

## ◆ product

attribute wstring IUSBDeviceFilter::product

Product filter.

## ◆ serialNumber

attribute wstring IUSBDeviceFilter::serialNumber

Serial number filter.

## ◆ port

attribute wstring IUSBDeviceFilter::port

Host USB port filter.

## ◆ remote

attribute wstring IUSBDeviceFilter::remote

Remote state filter.

Note
  This filter makes sense only for machine USB filters, i.e. it is ignored by IHostUSBDeviceFilter objects.

## ◆ maskedInterfaces

attribute unsigned long IUSBDeviceFilter::maskedInterfaces

This is an advanced option for hiding one or more USB interfaces from the guest.

The value is a bit mask where the bits that are set means the corresponding USB interface should be hidden, masked off if you like. This feature only works on Linux hosts.