qmp

Documentation

Overview

Package qmp implments part of the QEMU Machine Protocol Specification. It provides serializable types and functions for communicating with a running QEMU instance.

Index

• Variables
• type Capabilities
• type Capability
• type Client
  • func NewClient(id uint64) *Client
  • func (c *Client) Close() error
  • func (c *Client) Connect(conn net.Conn, timeout time.Duration) error
  • func (c *Client) Execute(ctx context.Context, cmd Command) error
  • func (c *Client) Listen() *Listener
  • func (c *Client) ServerInfo() (VersionInfo, Capabilities)
• type Command
• type Greeting
  • func (g *Greeting) UnmarshalQMP(msg []byte) error
• type GreetingPayload
• type Listener
  • func (listener *Listener) Close() error
  • func (listener *Listener) Receive(ctx context.Context) (qmpmsg.Event, error)
• type MessageHandler
  • func (m *MessageHandler) UnmarshalJSON(b []byte) error
• type VersionInfo
  • func (v VersionInfo) String() string
• type VersionTriple
  • func (v VersionTriple) String() string

Variables

var (
	ErrClientClosed           = errors.New("the qmp client does not have an open connection")
	ErrClientAlreadyConnected = errors.New("the qmp client is already connected")
)

Possible client errors.

Types

type Capabilities

type Capabilities []string

Capabilities is a set of supported QMP capabilities.

type Capability

type Capability string

Capability identifies a capability supported by the server.

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client establishes and maintains a QMP communications channel with a QEMU instance.

func NewClient

func NewClient(id uint64) *Client

NewClient returns a new QMP client that will communicate with a QEMU instance.

The id should be a randomly generated number. It is used to ensure the QMP request identifiers generated by the client are unique.

func (*Client) Close

func (c *Client) Close() error

Close releases any resources consumed by the client

func (*Client) Connect

func (c *Client) Connect(conn net.Conn, timeout time.Duration) error

Connect attempts to esablish the client's connection to a QMP service provided over conn.

Only one client can be connected to a unix socket at a time. The Connect call will block when connecting to a unix socket that is already occupied, until the given timeout expires. See this email thread for background: https://lists.gnu.org/archive/html/qemu-devel/2016-10/msg02208.html

func (*Client) Execute

func (c *Client) Execute(ctx context.Context, cmd Command) error

Execute runs the given QMP command.

func (*Client) Listen

func (c *Client) Listen() *Listener

Listen returns a QMP asynchronous event listener.

func (*Client) ServerInfo

func (c *Client) ServerInfo() (VersionInfo, Capabilities)

ServerInfo returns information about the QMP server that the client is connected to.

type Command

type Command interface {
	// Command returns the name of the command to be issued.
	Command() string

	// CommandArgs returns the arguments of the command, marshaeled as JSON.
	// If no arguments are provided, a nil byte slice will be returned.
	CommandArgs() ([]byte, error)

	// CommandResponse unmarshals the response to the command, if present.
	CommandResponse([]byte) error
}

Command is a QMP command that can be sent by a client.

type Greeting

type Greeting struct {
	QMP GreetingPayload `json:"QMP"`
}

Greeting is sent by the server when a connection is first established.

func (*Greeting) UnmarshalQMP

func (g *Greeting) UnmarshalQMP(msg []byte) error

UnmarshalQMP unmarshals the given QMP greeting, encoded in JSON.

type GreetingPayload

type GreetingPayload struct {
	Version      VersionInfo  `json:"version"`
	Capabilities Capabilities `json:"capabilities"`
}

GreetingPayload is the payload of a greeting message.

type Listener

type Listener struct {
	// contains filtered or unexported fields
}

Listener receives QMP messages from a client.

func (*Listener) Close

func (listener *Listener) Close() error

Close causes the listener to stop receiving QMP messages.

func (*Listener) Receive

func (listener *Listener) Receive(ctx context.Context) (qmpmsg.Event, error)

Receive waits for the next event to arrive and returns it when it does. It returns an error if the context is cancelled, the listener has been closed, or the client to which it listens has encountered an error or been closed.

type MessageHandler

type MessageHandler struct {
	Handler func(msg []byte) error
}

Message holds a QMP message.

func (*MessageHandler) UnmarshalJSON

func (m *MessageHandler) UnmarshalJSON(b []byte) error

UnmarshalJSON copies the given JSON data to the respones.

type VersionInfo

type VersionInfo struct {
	Qemu    VersionTriple `json:"qemu"`
	Package string        `json:"package"`
}

VersionInfo identifies the version of the server that's running.

func (VersionInfo) String

func (v VersionInfo) String() string

String returns a string representation of the version.

type VersionTriple

type VersionTriple struct {
	Major int `json:"major"`
	Minor int `json:"minor"`
	Micro int `json:"micro"`
}

VersionTriple specifies the major, minor and macro parts of a version identifier.

func (VersionTriple) String

func (v VersionTriple) String() string

String returns a string representation of the version triple.