VirtualBox Main API
Public Attributes | List of all members
IUSBDeviceFilter Interface Reference

The IUSBDeviceFilter interface represents an USB device filter used to perform actions on a group of USB devices. More...

Inheritance diagram for IUSBDeviceFilter:
IHostUSBDeviceFilter

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 an USB device filter used to perform actions on a group of USB devices.

  This type of filters is 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 the given device filter if and only if all
  attributes of the device match the corresponding attributes of the
  filter (that is, attributes are joined together using the logical AND
  operation). On the other hand, all together, filters in the list of
  filters carry the semantics of the logical OR operation. So if it is
  desirable to create a match like "this vendor id OR this product id",
  one needs to create two filters and specify "any match" (see below)
  for unused attributes.

  All filter attributes used for matching are strings. Each string
  is an expression representing a set of values of the corresponding
  device attribute, that will match the given filter. Currently, the
  following filtering expressions are supported:

  <ul>

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

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

where m and n are integer numbers, either in octal (starting from 0), hexadecimal (starting from 0x) or decimal (otherwise) form, 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 the exact match. String device attributes are compared to this string including case of symbols. Integer attributes are first converted to a string (see individual filter attributes) and then compared ignoring case.

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 the Windows host platform, 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
IUSBController::deviceFilters, IHostUSBDeviceFilter
Interface ID:
{D6831FB4-1A94-4C2C-96EF-8D0D6192066D}

Member Data Documentation

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.

attribute boolean IUSBDeviceFilter::active

Whether this filter active or has been temporarily disabled.

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).

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).

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.

attribute wstring IUSBDeviceFilter::manufacturer

Manufacturer filter.

attribute wstring IUSBDeviceFilter::product

Product filter.

attribute wstring IUSBDeviceFilter::serialNumber

Serial number filter.

attribute wstring IUSBDeviceFilter::port

Host USB port filter.

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.
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.