VirtualBox Main API
Public Member Functions | Public Attributes | List of all members
IUSBController Interface Reference

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

attribute boolean enabled
 Flag whether the USB controller is present in the guest system.
attribute boolean enabledEHCI
 Flag whether the USB EHCI controller is present in the guest system.
readonly attribute boolean proxyAvailable
 Flag whether there is an USB proxy available.
readonly attribute unsigned short USBStandard
 USB standard version which the controller implements.
readonly attribute
IUSBDeviceFilter[] 
deviceFilters
 List of USB device filters associated with the machine.

Member Function Documentation

void IUSBController::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
nameFilter name. See IUSBDeviceFilter::name for more info.
filterCreated filter object.
  @par Expected result codes:
<table><tr>

VBOX_E_INVALID_VM_STATE

The virtual machine is not mutable.

See Also
deviceFilters
void IUSBController::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 <tt>0</tt>. 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
positionPosition to insert the filter to.
filterUSB device filter to insert.
  @par Expected result codes:
<table>

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 IUSBController::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 <tt>0</tt>. Specifying a
    position equal to or greater than the number of elements in
    the list will produce an error.
Parameters
positionPosition to remove the filter from.
filterRemoved USB device filter.
  @par Expected result codes:
<table>

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

attribute boolean IUSBController::enabled

Flag whether the USB controller is present in the guest system.

If disabled, the virtual guest hardware will not contain any USB controller. Can only be changed when the VM is powered off.

attribute boolean IUSBController::enabledEHCI

Flag whether the USB EHCI controller is present in the guest system.

If disabled, the virtual guest hardware will not contain a USB EHCI controller. Can only be changed when the VM is powered off.

readonly attribute boolean IUSBController::proxyAvailable

Flag whether there is an USB proxy available.

readonly attribute unsigned short IUSBController::USBStandard

USB standard version which the controller implements.

This is a BCD which means that the major version is in the high byte and minor version is in the low byte.

readonly attribute IUSBDeviceFilter [] IUSBController::deviceFilters

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
    (@link IHost::USBDeviceFilters IHost::USBDeviceFilters@endlink<b></b>).

    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
    @link ::USBDeviceState_Available USBDeviceState_Available@endlink<b></b>,
    @link ::USBDeviceState_Busy USBDeviceState_Busy@endlink<b></b>,
    @link ::USBDeviceState_Held USBDeviceState_Held@endlink<b></b>) 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