730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync * VirtualBox IHostUSBDevice COM interface implementation.
8c1c3e6cfb2f0d0c4656d1d03ada68a8318ca11fvboxsync * Copyright (C) 2006-2013 Oracle Corporation
b52c24239bed9dc9f284d829b6059073afcb1894vboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
b52c24239bed9dc9f284d829b6059073afcb1894vboxsync * available from http://www.virtualbox.org. This file is free software;
b52c24239bed9dc9f284d829b6059073afcb1894vboxsync * you can redistribute it and/or modify it under the terms of the GNU
b52c24239bed9dc9f284d829b6059073afcb1894vboxsync * General Public License (GPL) as published by the Free Software
b52c24239bed9dc9f284d829b6059073afcb1894vboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
b52c24239bed9dc9f284d829b6059073afcb1894vboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
b52c24239bed9dc9f284d829b6059073afcb1894vboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync/* #include "USBProxyService.h" circular on Host/HostUSBDevice, the includer
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync * must include this. */
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync * The unified state machine of HostUSBDevice.
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync * This is a super set of USBDEVICESTATE / USBDeviceState_T that
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync * includes additional states for tracking state transitions.
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync * The CapturingForVM and CapturingForProxy states have been merged
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync * into Capturing with a destination state (AttachingToVM or HeldByProxy).
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync * The DetachingFromVM state is a merge of DetachingFromVMToProxy and
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync * DetachingFromVMToHost and uses the destination state (HeldByProxy
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync * or ReleasingToHost) like Capturing.
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync * The *AwaitingDetach and *AwaitingReattach substates (optionally used
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync * in Capturing, AttachingToVM, DetachingFromVM and ReleasingToHost) are
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync * implemented via a substate kHostUSBDeviceSubState.
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsynctypedef enum
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync /** The device is unsupported (HUB).
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync * Next Host: PhysDetached.
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync * Next VBox: No change permitted.
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync kHostUSBDeviceState_Unsupported = USBDEVICESTATE_UNSUPPORTED,
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync /** The device is used exclusivly by the host or is inaccessible for some other reason.
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync * Next Host: Capturable, Unused, PhysDetached.
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync * Run filters.
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync * Next VBox: No change permitted.
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync kHostUSBDeviceState_UsedByHost = USBDEVICESTATE_USED_BY_HOST,
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync /** The device is used by the host but can be captured.
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync * Next Host: Unsupported, UsedByHost, Unused, PhysDetached.
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync * Run filters if Unused (for wildcard filters).
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync * Next VBox: CapturingForVM, CapturingForProxy.
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync kHostUSBDeviceState_Capturable = USBDEVICESTATE_USED_BY_HOST_CAPTURABLE,
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync /** The device is not used by the host and can be captured.
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync * Next Host: UsedByHost, Capturable, PhysDetached
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync * Don't run any filters (done on state entry).
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync * Next VBox: CapturingForVM, CapturingForProxy.
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync kHostUSBDeviceState_Unused = USBDEVICESTATE_UNUSED,
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync /** The device is held captive by the proxy.
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync * Next Host: PhysDetached
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync * Next VBox: ReleasingHeld, AttachingToVM
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync kHostUSBDeviceState_HeldByProxy = USBDEVICESTATE_HELD_BY_PROXY,
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync /** The device is in use by a VM.
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync * Next Host: PhysDetachingFromVM
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync * Next VBox: DetachingFromVM
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync kHostUSBDeviceState_UsedByVM = USBDEVICESTATE_USED_BY_GUEST,
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync /** The device has been detach from both the host and VMs.
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync * This is the final state. */
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync /** The start of the transitional states. */
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync /** The device is being seized from the host, either for HeldByProxy or for AttachToVM.
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync * On some hosts we will need to re-enumerate the in which case the sub-state
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync * is employed to track this progress. On others, this is synchronous or faked, and
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync * will will then leave the device in this state and poke the service thread to do
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync * the completion state change.
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync * Next Host: PhysDetached.
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync * Next VBox: HeldByProxy or AttachingToVM on success,
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync * previous state (Unused or Capturable) or UsedByHost on failure.
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync kHostUSBDeviceState_Capturing = kHostUSBDeviceState_FirstTransitional,
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync /** The device is being released back to the host, following VM or Proxy usage.
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync * Most hosts needs to re-enumerate the device and will therefore employ the
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync * sub-state as during capturing. On the others we'll just leave it to the usb
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync * service thread to advance the device state.
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync * Next Host: Unused, UsedByHost, Capturable.
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync * No filters.
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync * Next VBox: PhysDetached (timeout), HeldByProxy (failure).
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync /** The device is being attached to a VM.
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync * This requires IPC to the VM and we will not advance the state until
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync * that completes.
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync * Next Host: PhysDetachingFromVM.
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync * Next VBox: UsedByGuest, HeldByProxy (failure).
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync /** The device is being detached from a VM and will be returned to the proxy or host.
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync * This involves IPC and may or may not also require re-enumeration of the
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync * device. Which means that it might transition directly into the ReleasingToHost state
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync * because the client (VM) will do the actual re-enumeration.
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync * Next Host: PhysDetachingFromVM (?) or just PhysDetached.
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync * Next VBox: ReleasingToHost, HeldByProxy.
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync /** The device has been physically removed while a VM used it.
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync * This is the device state while VBoxSVC is doing IPC to the client (VM) telling it
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync * to detach it.
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync * Next Host: None.
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync * Next VBox: PhysDetached
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync /** Just an invalid state value for use as default for some methods. */
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync * Sub-state for dealing with device re-enumeration.
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsynctypedef enum
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync /** Not in any sub-state. */
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync /** Awaiting a logical device detach following a device re-enumeration. */
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync /** Awaiting a logical device re-attach following a device re-enumeration. */
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync * Object class used to hold Host USB Device properties.
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync // public initializer/uninitializer for internal purposes only
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync HRESULT init(PUSBDEVICE aUsb, USBProxyService *aUSBProxyService);
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync // public methods only for internal purposes
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync /** @note Must be called from under the object read lock. */
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync /** @note Must be called from under the object read lock. */
8c1c3e6cfb2f0d0c4656d1d03ada68a8318ca11fvboxsync HostUSBDeviceState i_getUnistate() const { return mUniState; }
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync /** @note Must be called from under the object read lock. */
8c1c3e6cfb2f0d0c4656d1d03ada68a8318ca11fvboxsync const char *i_getStateName() { return i_stateName (mUniState, mPendingUniState, mUniSubState); }
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync /** @note Must be called from under the object read lock. */
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync /** @note Must be called from under the object read lock. */
8c1c3e6cfb2f0d0c4656d1d03ada68a8318ca11fvboxsync ComObjPtr<SessionMachine> &i_getMachine() { return mMachine; }
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync /** @note Must be called from under the object read lock. */
dcc837f3a6f10996beb8aa7965f67f7f6c273fb4vboxsync HRESULT i_requestCaptureForVM(SessionMachine *aMachine, bool aSetError,
dcc837f3a6f10996beb8aa7965f67f7f6c273fb4vboxsync const com::Utf8Str &aCaptureFilename, ULONG aMaskedIfs = 0);
8c1c3e6cfb2f0d0c4656d1d03ada68a8318ca11fvboxsync HRESULT i_onDetachFromVM(SessionMachine *aMachine, bool aDone, bool *aRunFilters, bool aAbnormal = false);
8c1c3e6cfb2f0d0c4656d1d03ada68a8318ca11fvboxsync bool i_isMatch(const USBDeviceFilter::Data &aData);
8c1c3e6cfb2f0d0c4656d1d03ada68a8318ca11fvboxsync static int i_compare(PCUSBDEVICE aDev1, PCUSBDEVICE aDev2, bool aIsAwaitingReAttach = false);
8c1c3e6cfb2f0d0c4656d1d03ada68a8318ca11fvboxsync bool i_updateState(PCUSBDEVICE aDev, bool *aRunFilters, SessionMachine **aIgnoreMachine);
8c1c3e6cfb2f0d0c4656d1d03ada68a8318ca11fvboxsync bool i_updateStateFake(PCUSBDEVICE aDev, bool *aRunFilters, SessionMachine **aIgnoreMachine);
8c1c3e6cfb2f0d0c4656d1d03ada68a8318ca11fvboxsync static const char *i_stateName(HostUSBDeviceState aState,
8c1c3e6cfb2f0d0c4656d1d03ada68a8318ca11fvboxsync HostUSBDeviceState aPendingState = kHostUSBDeviceState_Invalid,
8c1c3e6cfb2f0d0c4656d1d03ada68a8318ca11fvboxsync HostUSBDeviceSubState aSubState = kHostUSBDeviceSubState_Default);
dcc837f3a6f10996beb8aa7965f67f7f6c273fb4vboxsync HRESULT i_attachToVM(SessionMachine *aMachine, const com::Utf8Str &aCaptureFilename, ULONG aMaskedIfs = 0);
8c1c3e6cfb2f0d0c4656d1d03ada68a8318ca11fvboxsync void i_detachFromVM(HostUSBDeviceState aFinalState);
8c1c3e6cfb2f0d0c4656d1d03ada68a8318ca11fvboxsync bool i_setState (HostUSBDeviceState aNewState, HostUSBDeviceState aNewPendingState = kHostUSBDeviceState_Invalid,
8c1c3e6cfb2f0d0c4656d1d03ada68a8318ca11fvboxsync HostUSBDeviceSubState aNewSubState = kHostUSBDeviceSubState_Default);
8c1c3e6cfb2f0d0c4656d1d03ada68a8318ca11fvboxsync bool i_startTransition (HostUSBDeviceState aNewState, HostUSBDeviceState aFinalState,
8c1c3e6cfb2f0d0c4656d1d03ada68a8318ca11fvboxsync HostUSBDeviceSubState aNewSubState = kHostUSBDeviceSubState_Default);
8c1c3e6cfb2f0d0c4656d1d03ada68a8318ca11fvboxsync bool i_advanceTransition(bool aSkipReAttach = false);
8c1c3e6cfb2f0d0c4656d1d03ada68a8318ca11fvboxsync // wrapped IUSBDevice properties
8c1c3e6cfb2f0d0c4656d1d03ada68a8318ca11fvboxsync HRESULT getManufacturer(com::Utf8Str &aManufacturer);
8c1c3e6cfb2f0d0c4656d1d03ada68a8318ca11fvboxsync HRESULT getSerialNumber(com::Utf8Str &aSerialNumber);
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync /** @name The state machine variables
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync * Only setState(), init() and uninit() will modify these members!
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync /** The RTTimeNanoTS() corresponding to the last state change.
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync * Old state machine: RTTimeNanoTS() of when mIsStatePending was set or mDetaching changed
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync * from kNotDetaching. For operations that cannot be canceled it's 0. */
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync /** Current state. */
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync /** Sub-state for tracking re-enumeration. */
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync /** The final state of an pending transition.
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync * This is mainly a measure to reduce the number of HostUSBDeviceState values. */
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync /** Previous state.
ad27e1d5e48ca41245120c331cc88b50464813cevboxsync * This is used for bailing out when a transition like capture fails. */
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync /** Indicator set by onDetachedPhys and check when advancing a transitional state. */
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync /** The machine the usb device is (being) attached to. */
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync /** Pointer to the USB Proxy Service instance. */
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync /** Pointer to the USB Device structure owned by this device.
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync * Only used for host devices. */
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync /** The interface mask to be used in the pending capture.
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync * This is a filter property. */
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync /** The name of this device. */
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync /** The name of this device (for logging purposes).
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync * This points to the string in mNameObj. */
dcc837f3a6f10996beb8aa7965f67f7f6c273fb4vboxsync /** The filename to capture the USB traffic to. */
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync /** One-shot filter id only for new code */
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync /** One-shot filter id. */
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync#endif // ____H_HOSTUSBDEVICEIMPL
730b109e93240f48a2fc4ca97c05e5f347f71ec9vboxsync/* vi: set tabstop=4 shiftwidth=4 expandtab: */