NAME

Protocol::Sys::Virt::Transport - Low level Libvirt connection protocol

SYNOPSIS

use Protocol::Sys::Virt::Transport;
use Protocol::Sys::Virt::Remote;

open my $fh, 'rw', '/run/libvirt/libvirt.sock';
my $transport = Protocol::Sys::Virt::Transport->new(
     role => 'client',
     on_send => sub { syswrite( $fh, $_ ) for @_ }
);

my $remote = Protocol::Sys::Virt::Remote->new;
$remote->register( $transport );

DESCRIPTION

This module implements an abstract transport with the low level mechanics to talk to (remote) LibVirt deamons like libvirtd, libvirt-qemud, libvirt-lockd or libvirtd-admin. Instances do not directly communicate over a connection stream; instead, they expect the caller to handle incoming data and call the receive method for handling by the protocol. Similarly, the on_send event is invoked with data to be transmitted.

EVENTS

on_send

$on_send->( $chunk [, ..., $chunkN ] );

Invoked with any number of argumens, each a chunk of data to be transmitted over the connection stream.

CONSTRUCTOR

new

my $transport = Protocol::Sys::Virt::Transport->new(
   role => 'client',
   on_send => sub { ... }
);

Creates an instance on the client side (role => 'client') or server (role => 'server') side of the connection.

The on_send event is triggered with data to be transmitted. It may be called with multiple arguments:

sub _transmitter {
   syswrite( $fh, $_ ) for (@_);
}

METHODS

receive

$transport->receive( $data, [ type => 'fd' ] );

Feed data received on the connection stream to the protocol transport instance. When $data is a file descriptor, the type => 'fd'

The function returns a list of 2 elements:

• The number of items expected on the next call to receive

• The type of item to receive on the next call; this can be data or fd

  When the value fd is returned, the protocol expects a file descriptor as the next $data argument. File descriptors can only be passed over Unix domain sockets; over any other connection, this should result in a fatal error at the caller.

register

 my $sender = $transport->register($remote->PROG, $remote->PROTOCOL_VERSION, {
    on_call    => ...,
    on_reply   => ...,
    on_message => ...,
    on_stream  => ...
 });

my $serial = $sender->($proc, $type, data => $data,
              [status => $status], [fds => $fds], [serial => $serial]);

Registers callbacks for a 'program' (remote, keep alive, admin, ...) with a version of the protocol and a series of callbacks to be invoked when the specific type of input is received.

In case where $type is CALL or CALL_WITH_FDS, the $serial returned by the sender function must be used to link messages passed to on_reply or on_stream to the call that triggered the replies.

The callbacks are called as follows:

• on_call

  $on_call->(header => $hdr, data => $data, [fds => $fds]);

  Called for messages of type CALL and CALL_WITH_FDS. The difference between the two is that the latter is passed an array of file descriptors in the fds key. The header key contains the deserialized header.

  The data key contains the undecoded data of the *_args structure associated with $hdr-{proc}>.

• on_reply

  $on_reply->(header => $hdr, data  => $data, [fds => $fds]);
  $on_reply->(header => $hdr, error => $err);

  Called for messages of type REPLY or REPLY_WITH_FDS. The difference between the two is that the latter is passed an array of file descriptors in the fds key. The header key contains the deserialized header.

  The data key contains the undecoded data of the *_ret structure associated with $hdr-{proc}>.

  In case the server sends an error, the error key contains the deserialized error structure and neither data nor fds keys are supplied.

• on_message

  $on_message->(header => $hdr, data  => $data);

  Called for messages of type MESSAGE. The data key contains the undecoded data of the *_msg structure associated with $hdr-{proc}>.

• on_stream

  $on_stream->(header => $hdr, data => $data);
  $on_stream->(header => $hdr, hole => $hole);
  $on_stream->(header => $hdr, error => $err);

  Called for messages of type STREAM or STREAM_HOLE. $data is the raw stream data to be written to the stream. $hole is the deserialized stream hole structure. $err is the deserialized error structure.

LICENSE AND COPYRIGHT

See the LICENSE file in this distribution.