Provides access to USB Gadget (OTG) support, allowing to control the USB OTG behavior on the system. More...

#include <HemeraCore/USBGadgetManager>

Inheritance diagram for Hemera::USBGadgetManager:

Public Types

enum  Mode { Mode::None, Mode::EthernetTethering, Mode::EthernetP2P, Mode::MassStorage }
 The various modes in which a USB Gadget can be activated. More...
 
enum  USBCableStatus { USBCableStatus::Unknown, USBCableStatus::Unplugged, USBCableStatus::Plugged }
 Status of the USB Cable. More...
 

Signals

void activeModeChanged (Hemera::USBGadgetManager::Mode mode)
 Emitted whenever the active mode changes. More...
 
void systemWideLockChanged (bool active)
 Emitted whenever the system wide lock changes. More...
 
void usbCableStatusChanged (Hemera::USBGadgetManager::USBCableStatus status)
 Emitted whenever the USB Cable plug status changes. More...
 
- Signals inherited from Hemera::AsyncInitObject
void ready ()
 

Public Member Functions

 USBGadgetManager (QObject *parent)
 Default constructor. More...
 
virtual ~USBGadgetManager ()
 Default destructor. More...
 
Modes availableModes () const
 Returns available USB gadget modes on this system. More...
 
Mode activeMode () const
 
bool canDetectCableHotplugging () const
 Returns whether this system supports detection of USB cable hotplugging. More...
 
USBCableStatus usbCableStatus () const
 
bool isSystemWideLockActive () const
 
QString systemWideLockOwner () const
 
QString systemWideLockReason () const
 
OperationacquireSystemWideLock (const QString &reason=QString())
 Tries to acquire a system wide lock. More...
 
OperationreleaseSystemWideLock ()
 Releases a system wide lock. More...
 
Operationactivate (Mode mode, const QVariantMap &arguments=QVariantMap())
 Requests the activation of the USB Gadget. More...
 
Operationdeactivate ()
 Requests the deactivation of the USB Gadget. More...
 

Protected Member Functions

virtual void initImpl () Q_DECL_OVERRIDE Q_DECL_FINAL
 
- Protected Member Functions inherited from Hemera::AsyncInitObject
void setParts (uint parts)
 

Additional Inherited Members

- Public Slots inherited from Hemera::AsyncInitObject
Hemera::Operationinit ()
 
- Protected Slots inherited from Hemera::AsyncInitObject
void setReady ()
 
void setInitError (const QString &errorName, const QString &message=QString())
 
void setOnePartIsReady ()
 

Detailed Description

Provides access to USB Gadget (OTG) support, allowing to control the USB OTG behavior on the system.

USBGadgetManager enables an application to control USB Gadgets on the system, aka USB OTG buses. It allows to specify the mode under which the USB Gadget will operate, if any, and to bring up and down USB support. On selected devices, it also allows to detect hotplugging of the USB cable.

Usually, only one single USBGadgetManager object should be instantiated for each application for performance reasons.

System lock

If an application has the right to do so, it can request a system wide lock on the USBGadgetManager. This is useful, for example, for shells, where you want to manage USB gadgets globally, or when in Developer Mode, where Gravity takes hold of the global lock while no application is running besides the default shell.

When the System lock is active, no other application besides the application which holds the lock can activate or deactivate a USB Gadget Mode.

System-wide availability of SoftwareManager

USBGadgetManager is part of Gravity, and can be entirely disabled from the vendor. This class serves as a mere interface to Gravity, and its initialization will fail if the system USBGadgetManager is not installed or not available.

See also
Application

Member Enumeration Documentation

The various modes in which a USB Gadget can be activated.

Enumerator
None 

No mode.

EthernetTethering 

Emulates a Ethernet port, and shares any other connection (e.g.: WiFi) over it.

EthernetP2P 

Emulates a Ethernet port, and creates a zeroconf P2P bridge to the host.

MassStorage 

Emulates a mass storage.

Status of the USB Cable.

Enumerator
Unknown 

When device does not support detection of cable hotplugging, this value is returned.

Unplugged 

Cable is unplugged.

Plugged 

Cable is plugged.

Constructor & Destructor Documentation

Hemera::USBGadgetManager::USBGadgetManager ( QObject *  parent)
explicit

Default constructor.

Hemera::USBGadgetManager::~USBGadgetManager ( )
virtual

Default destructor.

Member Function Documentation

Modes Hemera::USBGadgetManager::availableModes ( ) const

Returns available USB gadget modes on this system.

Depending on the hardware and software features installed on the target, this method will return valid Modes you can use to activate USB Gadget.

Returns
a list of available modes for this system.
See also
activate
Mode Hemera::USBGadgetManager::activeMode ( ) const
Returns
the currently active mode on this system, if any.
bool Hemera::USBGadgetManager::canDetectCableHotplugging ( ) const

Returns whether this system supports detection of USB cable hotplugging.

Hemera is capable of doing a set of heuristics to detect if an USB cable is plugged or not to the OTG port. When the hardware itself is not capable of reporting that correctly (this is most of the times), Hemera tries to find out alternative methods to create a reliable heuristic. If this is possible, this method returns true.

Note
Most of the times, unless you are perfectly sure your hardware supports this feature or Hemera support told you so, this method might indeed be unreliable. It is advised to consult with your manufacturer or local Hemera support before heavily relying at runtime on this method.
Returns
whether this system supports detection of USB cable hotplugging
USBCableStatus Hemera::USBGadgetManager::usbCableStatus ( ) const
Returns
the current status of the USB cable
Note
If canDetectCableHotplugging returns false, this method will always return Unknown.
Even if canDetectCableHotplugging returns true, this method might return Unknown if heuristics fail for any reason or are not computable.
bool Hemera::USBGadgetManager::isSystemWideLockActive ( ) const
Returns
Whether a system wide lock is currently active
QString Hemera::USBGadgetManager::systemWideLockOwner ( ) const
Returns
the application ID of the current system wide lock owner, if any.
QString Hemera::USBGadgetManager::systemWideLockReason ( ) const
Returns
the reason for the current ongoing system wide lock, if any.
Operation * Hemera::USBGadgetManager::acquireSystemWideLock ( const QString &  reason = QString())

Tries to acquire a system wide lock.

The application will attempt to acquire a system wide lock on the USB Gadget Manager. This will work only if no other application is holding the lock and your application has the right to request a lock in the system.

reason The reason for the lock.

Returns
an Operation representing the ongoing request.
Operation * Hemera::USBGadgetManager::releaseSystemWideLock ( )

Releases a system wide lock.

If the application previously acquired a system wide lock, it will be released upon calling this method. The method will fail if the application does not hold the lock.

Note
This method cannot be used for forcing a different lock owner to release it.
Returns
an Operation representing the ongoing request.
Operation * Hemera::USBGadgetManager::activate ( USBGadgetManager::Mode  mode,
const QVariantMap &  arguments = QVariantMap() 
)

Requests the activation of the USB Gadget.

The application will attempt to activate the USB Gadget through USB Gadget Manager. This will work only if no other application is holding a lock (or if this application holds the lock) and your application has the right to manage USB Gadgets in the system.

Depending on the mode you have chosen, you might need to supply additional parameters. These are outlined in the documentation for each mode, and shall be provided in form of a QVariantMap.

mode The mode the USB Gadget should be activated in. arguments A map of parameters, dependent on the chosen mode.

Returns
an Operation representing the ongoing request.
Operation * Hemera::USBGadgetManager::deactivate ( )

Requests the deactivation of the USB Gadget.

The application will attempt to deactivate the USB Gadget through USB Gadget Manager. This will work only if no other application is holding a lock (or if this application holds the lock) and your application has the right to manage USB Gadgets in the system.

Note
When no lock is active, this method might as well deactivate USB Gadget when another application requested activation. If you do not wish for this to happen, you should acquire the lock first.

mode The mode the USB Gadget should be activated in. arguments A map of parameters, dependent on the chosen mode.

Returns
an Operation representing the ongoing request.
void Hemera::USBGadgetManager::activeModeChanged ( Hemera::USBGadgetManager::Mode  mode)
signal

Emitted whenever the active mode changes.

mode The new active mode.

void Hemera::USBGadgetManager::systemWideLockChanged ( bool  active)
signal

Emitted whenever the system wide lock changes.

active Whether the system wide lock is now active or not.

void Hemera::USBGadgetManager::usbCableStatusChanged ( Hemera::USBGadgetManager::USBCableStatus  status)
signal

Emitted whenever the USB Cable plug status changes.

status The new status of the USB cable.

void Hemera::USBGadgetManager::initImpl ( )
protectedvirtual

Implements the object intialization

When implementing an AsyncInitObject, this method should hold your initialization logic. It is called by AsyncInitObject when needed, and the developer should just reimplement it without invoking it.

Once the initialization procedure is completed, either setReady, setOnePartIsReady or setInitError must be called.

Implements Hemera::AsyncInitObject.