Public Member Functions | Public Attributes

IUSBDeviceFilters Interface Reference

List of all members.

Public Member Functions

void createDeviceFilter (in wstring name,[retval] out IUSBDeviceFilter filter)
 Creates a new USB device filter.
void insertDeviceFilter (in unsigned long position, in IUSBDeviceFilter filter)
 Inserts the given USB device to the specified position in the list of filters.
void removeDeviceFilter (in unsigned long position,[retval] out IUSBDeviceFilter filter)
 Removes a USB device filter from the specified position in the list of filters.

Public Attributes

readonly attribute
IUSBDeviceFilter[] 
deviceFilters
 List of USB device filters associated with the machine.

Member Function Documentation

void IUSBDeviceFilters::createDeviceFilter ( in wstring  name,
[retval] out IUSBDeviceFilter  filter 
)

Creates a new USB device filter.

All attributes except the filter name are set to empty (any match), active is false (the filter is not active).

The created filter can then be added to the list of filters using insertDeviceFilter.

Parameters:
name Filter name. See IUSBDeviceFilter::name for more info.
filter Created filter object.
Expected result codes:
VBOX_E_INVALID_VM_STATE The virtual machine is not mutable.
See also:
deviceFilters
void IUSBDeviceFilters::insertDeviceFilter ( in unsigned long  position,
in IUSBDeviceFilter  filter 
)

Inserts the given USB device to the specified position in the list of filters.

Positions are numbered starting from 0. If the specified position is equal to or greater than the number of elements in the list, the filter is added to the end of the collection.

Parameters:
position Position to insert the filter to.
filter USB device filter to insert.
Expected result codes:
VBOX_E_INVALID_VM_STATE Virtual machine is not mutable.
E_INVALIDARG USB device filter not created within this VirtualBox instance.
VBOX_E_INVALID_OBJECT_STATE USB device filter already in list.
Note:
Duplicates are not allowed, so an attempt to insert a filter that is already in the collection, will return an error.
See also:
deviceFilters
void IUSBDeviceFilters::removeDeviceFilter ( in unsigned long  position,
[retval] out IUSBDeviceFilter  filter 
)

Removes a USB device filter from the specified position in the list of filters.

Positions are numbered starting from 0. Specifying a position equal to or greater than the number of elements in the list will produce an error.

Parameters:
position Position to remove the filter from.
filter Removed USB device filter.
Expected result codes:
VBOX_E_INVALID_VM_STATE Virtual machine is not mutable.
E_INVALIDARG USB device filter list empty or invalid position.
See also:
deviceFilters

Member Data Documentation

List of USB device filters associated with the machine.

If the machine is currently running, these filters are activated every time a new (supported) USB device is attached to the host computer that was not ignored by global filters (IHost::USBDeviceFilters).

These filters are also activated when the machine is powered up. They are run against a list of all currently available USB devices (in states USBDeviceState_Available, USBDeviceState_Busy, USBDeviceState_Held) that were not previously ignored by global filters.

If at least one filter matches the USB device in question, this device is automatically captured (attached to) the virtual USB controller of this machine.

See also:
IUSBDeviceFilter, IUSBController