The Qmpi class is an interface through which to communicate with a QEMU instance via the QEMU Machine Protocol. More...

#include <qi-qmp/qmpi.h>

Collaboration diagram for Qmpi:

Public Types
enum	CommunicationError { WriteFailed , ReadFailed , TransactionTimeout , UnexpectedReceive , UnexpectedResponse }

enum	State { Disconnected , Connecting , AwaitingWelcome , Negotiating , Idle , Closing , SendingCommand , AwaitingMessage , ReadingMessage }

Signals
void	commandQueueExhausted ()

void	communicationErrorOccurred (Qmpi::CommunicationError error)

void	connected (QJsonObject version, QJsonArray capabilities)

void	connectionErrorOccurred (QAbstractSocket::SocketError error)

void	disconnected ()

void	errorResponseReceived (QString errorClass, QString description, std::any context)

void	eventReceived (QString name, QJsonObject data, QDateTime timestamp)

void	finished ()

void	readyForCommands ()

void	responseReceived (QJsonValue value, std::any context)

void	stateChanged (Qmpi::State state)

Public Member Functions
	Qmpi (const QHostAddress &address, quint16 port, QObject *parent=nullptr)

	Qmpi (const QString &hostname, quint16 port, QObject *parent=nullptr)

	Qmpi (QObject *parent=nullptr)

	~Qmpi ()

void	abort ()

QHostAddress	address () const

void	connectToHost ()

void	disconnectFromHost ()

void	execute (QString command, QJsonObject args=QJsonObject(), std::any context=std::any())

QString	hostname () const

bool	isConnected () const

bool	isConnectionActive () const

quint16	port () const

void	setAddress (const QHostAddress address)

void	setHostname (const QString hostname)

void	setPort (quint16 port)

void	setTransactionTimeout (int timeout=30000)

State	state () const

int	transactionTimeout () const

Public Member Functions inherited from QObject
	QObject (QObject *parent)

bool	blockSignals (bool block)

const QObjectList &	children () const const

QMetaObject::Connection	connect (const QObject sender, const char signal, const char *method, Qt::ConnectionType type) const const

void	deleteLater ()

void	destroyed (QObject *obj)

bool	disconnect (const char signal, const QObject receiver, const char *method) const const

bool	disconnect (const QObject receiver, const char method) const const

void	dumpObjectInfo () const const

void	dumpObjectTree () const const

QList< QByteArray >	dynamicPropertyNames () const const

virtual bool	event (QEvent *e)

virtual bool	eventFilter (QObject watched, QEvent event)

T	findChild (const QString &name, Qt::FindChildOptions options) const const

QList< T >	findChildren (const QRegularExpression &re, Qt::FindChildOptions options) const const

QList< T >	findChildren (const QString &name, Qt::FindChildOptions options) const const

QList< T >	findChildren (Qt::FindChildOptions options) const const

bool	inherits (const char *className) const const

void	installEventFilter (QObject *filterObj)

bool	isQuickItemType () const const

bool	isWidgetType () const const

bool	isWindowType () const const

void	killTimer (int id)

virtual const QMetaObject *	metaObject () const const

void	moveToThread (QThread *targetThread)

QString	objectName () const const

void	objectNameChanged (const QString &objectName)

QObject *	parent () const const

QVariant	property (const char *name) const const

	Q_CLASSINFO (Name, Value)

	Q_DISABLE_COPY (Class)

	Q_DISABLE_COPY_MOVE (Class)

	Q_EMIT Q_EMIT

	Q_ENUM (...)

	Q_ENUM_NS (...)

	Q_ENUMS (...)

	Q_FLAG (...)

	Q_FLAG_NS (...)

	Q_FLAGS (...)

	Q_GADGET Q_GADGET

	Q_GADGET_EXPORT (EXPORT_MACRO)

	Q_INTERFACES (...)

	Q_INVOKABLE Q_INVOKABLE

	Q_MOC_INCLUDE Q_MOC_INCLUDE

	Q_NAMESPACE Q_NAMESPACE

	Q_NAMESPACE_EXPORT (EXPORT_MACRO)

	Q_OBJECT Q_OBJECT

	Q_PROPERTY (...)

	Q_REVISION Q_REVISION

	Q_SET_OBJECT_NAME (Object)

	Q_SIGNAL Q_SIGNAL

	Q_SIGNALS Q_SIGNALS

	Q_SLOT Q_SLOT

	Q_SLOTS Q_SLOTS

T	qobject_cast (const QObject *object)

T	qobject_cast (QObject *object)

	QT_NO_NARROWING_CONVERSIONS_IN_CONNECT QT_NO_NARROWING_CONVERSIONS_IN_CONNECT

void	removeEventFilter (QObject *obj)

void	setObjectName (const QString &name)

void	setObjectName (QAnyStringView name)

void	setParent (QObject *parent)

bool	setProperty (const char *name, const QVariant &value)

bool	signalsBlocked () const const

int	startTimer (int interval, Qt::TimerType timerType)

int	startTimer (std::chrono::milliseconds time, Qt::TimerType timerType)

QThread *	thread () const const

Additional Inherited Members
Static Public Member Functions inherited from QObject
QMetaObject::Connection	connect (const QObject sender, const char signal, const QObject receiver, const char method, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject sender, const QMetaMethod &signal, const QObject receiver, const QMetaMethod &method, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject sender, PointerToMemberFunction signal, const QObject context, Functor functor, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject sender, PointerToMemberFunction signal, const QObject receiver, PointerToMemberFunction method, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject *sender, PointerToMemberFunction signal, Functor functor)

bool	disconnect (const QMetaObject::Connection &connection)

bool	disconnect (const QObject sender, const char signal, const QObject receiver, const char method)

bool	disconnect (const QObject sender, const QMetaMethod &signal, const QObject receiver, const QMetaMethod &method)

bool	disconnect (const QObject sender, PointerToMemberFunction signal, const QObject receiver, PointerToMemberFunction method)

QString	tr (const char sourceText, const char disambiguation, int n)

Public Attributes inherited from QObject
typedef	QObjectList

Protected Member Functions inherited from QObject
virtual void	childEvent (QChildEvent *event)

virtual void	connectNotify (const QMetaMethod &signal)

virtual void	customEvent (QEvent *event)

virtual void	disconnectNotify (const QMetaMethod &signal)

bool	isSignalConnected (const QMetaMethod &signal) const const

int	receivers (const char *signal) const const

QObject *	sender () const const

int	senderSignalIndex () const const

virtual void	timerEvent (QTimerEvent *event)

Properties inherited from QObject
	objectName

Detailed Description

The interface works asynchronously, providing updates via signals and requires an event loop to function.

All commands issued through the interface may optionally contain a context parameter in the form of std::any, which will be provided along with that command's corresponding response when responseReceived() or error errorResponseReceived() is emitted.

Note: Currently only connecting to servers listening for TCP connections is supported (i.e. no local/UNIX socket connections).

See also: QTcpSocket.

Member Enumeration Documentation

◆ CommunicationError

enum Qmpi::CommunicationError

This enum describes the various communication errors that can occur.

Enumerator
WriteFailed	Writing data to the server failed.
ReadFailed	Reading data from the server failed.
TransactionTimeout	The server ran out of time to respond.
UnexpectedReceive	The interface received a response when it was not expecting one.
UnexpectedResponse	The interface received a response that does not follow the known protocol.

◆ State

enum Qmpi::State

This enum describes the different states in which the interface can be.

Enumerator
Disconnected	The interface is not connected to any server and is inactive.
Connecting	The interface is attempting to connect to its assigned server.
AwaitingWelcome	The interface is waiting to receive the server's greeting.
Negotiating	The interface is automatically handling capabilities negotiation.
Idle	The interface is connected to a server and is not sending any commands nor expecting any responses.
Closing	The interface is handling disconnection from the server.
SendingCommand	The interface is encoding/ending a command to the server.
AwaitingMessage	The interface is waiting for a response from the server.
ReadingMessage	The interface is parsing a response from the server.

Constructor & Destructor Documentation

◆ Qmpi() [1/3]

Qmpi::Qmpi ( QObject * parent = nullptr )

explicit

Constructs a QMP interface with parent parent.

The connection address is set to QHostAddress::LocalHost and the port is set to 4444.

See also: setAddress() and setPort().

◆ Qmpi() [2/3]

Qmpi::Qmpi	(	const QHostAddress &	address,
		quint16	port,
		QObject *	parent = `nullptr`
	)

explicit

Constructs a QMP interface configured to connect to a QEMU instance at address address on port port. port is specified in native byte order.

The parent of the object is set to parent.

◆ Qmpi() [3/3]

Qmpi::Qmpi	(	const QString &	hostname,
		quint16	port,
		QObject *	parent = `nullptr`
	)

explicit

Constructs a QMP interface configured to connect to a QEMU instance at hostname hostname on port port. hostname may be an IP address in string form (e.g., "192.168.1.1", or "7e72:692b:9797:8310:8e68:3a98:3a21:473c"), or it may be a host name (e.g., "example.com"). The interface will do a lookup only if required. port is specified in native byte order.

The parent of the object is set to parent.

◆ ~Qmpi()

Qmpi::~Qmpi ( )

Destroys the interface, closing the underlying connection immediately if necessary.

Member Function Documentation

◆ abort()

void Qmpi::abort ( )

Immediately closes the interface's connection, discarding any pending data.

◆ address()

QHostAddress Qmpi::address ( ) const

Returns the IP address the interface is configured to connect to if it was set as a QHostAddress; otherwise, returns QHostAddress::Null.

See also: setAddress() and port().

◆ commandQueueExhausted

void Qmpi::commandQueueExhausted ( )

signal

This signal is emitted when the interface's command queue becomes empty and the response to the last command in the queue has been received, just before it enters State::Idle.

See also: stateChanged(), and execute().

◆ communicationErrorOccurred

void Qmpi::communicationErrorOccurred ( Qmpi::CommunicationError error )

signal

This signal is emitted when IO with the server fails, the known QMP protocol is violated during communication, or the server otherwise behaves unexpectedly. error contains the type of communication error.

Note: When such and error occurs the connection is immediately aborted, all pending reads/writes are discarded, and the interface enters the Disconnected state.

◆ connected

void Qmpi::connected	(	QJsonObject	version,
		QJsonArray	capabilities
	)

signal

This signal is emitted once the interface has finished connecting to the QEMU instance and performing capabilities negotiation.

version contains the server's version information, while capabilities describes the server's QMP capabilities.

See also: disconnected(), readyForCommands().

◆ connectionErrorOccurred

void Qmpi::connectionErrorOccurred ( QAbstractSocket::SocketError error )

signal

This signal is emitted when the underlying socket experiences a connection error, with error containing the type of error.

Note: When such and error occurs the connection is immediately aborted, all pending reads/writes are discarded, and the interface enters the Disconnected state.

◆ connectToHost()

void Qmpi::connectToHost ( )

Attempts to make a connection to the QEMU instance via the interfaces configured address and port.

The interface's state immediately changes to Connecting, followed by AwaitingWelcome if the underlying socket successfully establishes a connection. Once the interface has received the server's welcome message, connected() is emitted and Qmpi enters the Negotiating state. At this point capabilities negotiation is handled automatically since only the base protocol capabilities are currently supported, upon which readyForCommands() is emitted and the interface enters the Idle state.

At any point, the interface can emit connectionErrorOccurred() or communicationErrorOccurred() to signal an error occurred.

See also: state(), and disconnectFromHost().

◆ disconnected

void Qmpi::disconnected ( )

signal

This signal is emitted when the interface has fully disconnected from the QEMU instance.

Note: This signal will only be emitted if the interface managed to fully connect to the server.

Warning: If you need to delete the sender() of this signal in a slot connected to it, use the deleteLater() function.

See also: connected(), finished(), isConnectionActive().

◆ disconnectFromHost()

void Qmpi::disconnectFromHost ( )

Initiates closure of the interface's connection and enters the Closing state. If there is pending data waiting to be written, Qmpi waits until all data has been written before the connection is closed. Eventually, it will enter the Disconnected state and emit the disconnected() signal.

See also: connectToHost(), and abort().

◆ errorResponseReceived

void Qmpi::errorResponseReceived	(	QString	errorClass,
		QString	description,
		std::any	context
	)

signal

This signal is emitted when the an error response is received from the server after executing a command.

errorClass contains the type of error and description contains a human readable summary of the error, while context contains the context object provided when the command was executed, if set.

See also: responseReceived().

◆ eventReceived

void Qmpi::eventReceived	(	QString	name,
		QJsonObject	data,
		QDateTime	timestamp
	)

signal

This signal is emitted when an asynchronous event is posted by the server.

The signal parameters provide the name of the event, the event's data and its timestamp.

Note: QEMU instances record the time of events with microsecond precision, while QDateTime is only capable of millisecond precision; therefore, the timestamp of all events are rounded to the nearest millisecond.

See also: responseReceived().

◆ execute()

void Qmpi::execute	(	QString	command,
		QJsonObject	args = `QJsonObject()`,
		std::any	context = `std::any()`
	)

Executes the provided command on the connected QEMU instance.

Parameters

command	The name of the command to execute.
args	The command's arguments, if any.
context	An optional object that will be provided with server's response to the command.

The command is placed into an internal queue to be sent when it reaches the front. Only one command is sent at a time, with the interface waiting for a response before sending the next.

The server responds to commands in the same order they are received.

The context parameter is useful for identifying which command a response is directed towards or associating the response to a command with specific data or actions (i.e. a callback function).

Note: readyForCommands() must have been emitted before commands can be sent.

◆ finished

void Qmpi::finished ( )

signal

This signal is emitted when the interface returns to the Disconnected state for any reason, regardless of whether or not a complete connection to the server was ever achieved.

Warning: If you need to delete the sender() of this signal in a slot connected to it, use the deleteLater() function.

See also: disconnected(), stateChanged().

◆ hostname()

QString Qmpi::hostname ( ) const

Returns the hostname the interface is configured to connect to if it was set as a hostname; otherwise, returns a null string.

See also: setHostname() and port().

◆ isConnected()

bool Qmpi::isConnected ( ) const

Returns true if the interface has fully connected to the QEMU instance, meaning the underlying socket successfully established a connection and the server's greeting was received.

See also: isConnectionActive().

◆ isConnectionActive()

bool Qmpi::isConnectionActive ( ) const

Returns true if the interface's connection is active is any way. That is, the interface is in any state other than Disconnected; otherwise, returns false.

See also: isConnected().

◆ port()

quint16 Qmpi::port ( ) const

Returns the port the interface is configured to connect through.

See also: setPort() and address().

◆ readyForCommands

void Qmpi::readyForCommands ( )

signal

This signal is emitted once capabilities negotiation has been completed and the server is ready to receive commands.

See also: connected().

◆ responseReceived

void Qmpi::responseReceived	(	QJsonValue	value,
		std::any	context
	)

signal

This signal is emitted when a success (i.e. return) response is received from the server after executing a command.

value contains the return value of the command, which will be an empty QJsonObject if the command does not return data, while context contains the context object provided when the command was executed, if set.

See also: errorResponseReceived().

◆ setAddress()

void Qmpi::setAddress ( const QHostAddress address )

Sets the address of the interface to address.

This function does nothing if the connection is currently active

See also: address() and setHostname().

◆ setHostname()

void Qmpi::setHostname ( const QString hostname )

Sets the hostname of the interface to hostname.

This function does nothing if the connection is currently active

See also: hostname() and setAddress().

◆ setPort()

void Qmpi::setPort ( quint16 port )

Sets the port, specified in native byte order, of the interface to port.

This function does nothing if the connection is currently active

See also: port() and setAddress().

◆ setTransactionTimeout()

void Qmpi::setTransactionTimeout ( int timeout = 30000 )

Sets the transaction timeout of the interface to timeout.

The transaction timeout is how long the connected QEMU instance has to reply with a complete message after sending a command before the connection is automatically closed.

The received message does not have to be a response to that particular command; any received message will reset the timeout, while sending additional commands will not.

If a transaction timeout occurs communicationErrorOccurred() will be emitted with the value TransactionTimeout. If all sent commands have been processed and the interface is not currently expecting any responses the timeout will not be in effect.

Setting this value to -1 will disable the timeout.

See also: transactionTimeout().

◆ state()

Qmpi::State Qmpi::state ( ) const

Returns the state of the interface.

◆ stateChanged

void Qmpi::stateChanged ( Qmpi::State state )

signal

This signal is emitted when the interface's state changes, with state containing the new state.

See also: connected(), disconnected(), readyForCommands() and finished().

◆ transactionTimeout()

int Qmpi::transactionTimeout ( ) const

Returns the transaction timeout of the interface.

The default is 30,000 milliseconds.

See also: setTransactionTimeout().

The documentation for this class was generated from the following files:

qmpi.h
qmpi.cpp

Public Types

Signals

Public Member Functions

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ CommunicationError

◆ State

Constructor & Destructor Documentation

◆ Qmpi() [1/3]

◆ Qmpi() [2/3]

◆ Qmpi() [3/3]

◆ ~Qmpi()

Member Function Documentation

◆ abort()

◆ address()

◆ commandQueueExhausted

◆ communicationErrorOccurred

◆ connected

◆ connectionErrorOccurred

◆ connectToHost()

◆ disconnected

◆ disconnectFromHost()

◆ errorResponseReceived

◆ eventReceived

◆ execute()

◆ finished

◆ hostname()

◆ isConnected()

◆ isConnectionActive()

◆ port()

◆ readyForCommands

◆ responseReceived

◆ setAddress()

◆ setHostname()

◆ setPort()

◆ setTransactionTimeout()

◆ state()

◆ stateChanged

◆ transactionTimeout()