/ 
Protocol-Sys-Virt-v10.3.7
River stage zero No dependents
/ Protocol::Sys::Virt::Remote

NAME

Protocol::Sys::Virt::Remote - Connect to remote libvirt daemon

VERSION

v10.3.7

Based on LibVirt tag v10.3.0

SYNOPSIS

use Protocol::Sys::Virt::Transport;
use Protocol::Sys::Virt::Remote;
use Protocol::Sys::Virt::Remote::XDR;
my $prot = 'Protocol::Sys::Virt::Remote::XDR';

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

my $remote = Protocol::Sys::Virt::Remote->new(
     role => 'client',
     on_reply => sub { say 'Reply handled!'; },
);
$remote->register( $transport );

$remote->start_auth( $prot->AUTH_NONE,
                     on_complete => sub { say "Authenticated!" });

my $serial = $remote->call( $prot->PROC_CONNECT_OPEN,
               { name => 'qemu:///system', flags => 0 } );

DESCRIPTION

This module contains a class to connect to a "remote" libvirt daemon. That is, a deamon connected to a stream, which may be a Unix socket, a TCP socket, a pipe, etc. The data sent and received is encoded and decoded before passing it on to the transport or back to the caller.

EVENTS

on_closed

Called when the remote side of the stream announces it will close the stream using the REMOTE_PROC_CONNECT_CLOSE message, or when it confirms such a message as initiated locally.

on_call

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

Called when receiving a VIR_NET_CALL or VIR_NET_CALL_WITH_FDS (abbreviated as CALL or CALL_WITH_FDS) message. This callback differs from the one in Protocol::Sys::Virt::Transport by the fact the data has been decoded from XDR to the Perl representation.

on_reply

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

Called when receiving a VIR_NET_REPLY or VIR_NET_REPLY_WITH_FDS (abbreviated as REPLY or REPLY_WITH_FDS) message. This callback differs from the one in Protocol::Sys::Virt::Transport by the fact the data has been decoded from XDR to the Perl representation.

on_message

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

Called when receiving a VIR_NET_MESSAGE (abbreviated as MESSAGE) message. This callback differs from the one in Protocol::Sys::Virt::Transport by the fact the data has been decoded from XDR to the Perl representation.

on_stream

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

Passthrough from the on_stream event in Protocol::Sys::Virt::Transport.

CONSTRUCTOR

new

my $remote = Protocol::Sys::Virt::Remote->new(
    role     => 'client',
    on_close => sub { ... },
    on_call  => sub { ... },
);

Creates an instance on the client side (role => 'client') or server side (role => 'server') of the connection. In addition to the required role parameter, the constructor may be provided with a coderef for each of the events.

METHODS

configure

$remote->configure( on_reply => $callback, ... );

Sets callback handlers for events.

register

$remote->register( $transport );

Sets the callbacks on $transport for $remote->PROGRAM, allowing this instance to handle any incoming transfers.

start_auth

$remote->start_auth( $wanted_auth_type,
                     sasl => $sasl,
                     on_complete => sub { ... } );

Starts a sequence of message exchanges to authenticate with the remote. The messages being exchanged are handled internally and not passed to the event handlers. When AUTH_SASL is wanted, the sasl key should be provided with an instance of Authen::SASL. The on_complete handler is defined as:

$on_complete->(status => $status);

Where $status can be success or fail.

call

$serial = $remote->call( $proc, $data );

Calls the remote procedure $proc with the arguments given in $data. $proc is one of the values in the enum procedure as defined in Protocol::Sys::Virt::Remote::XDR. Reply and stream messages in response to this call are identified by $serial.

Note: If the on_send callback of the associated transport is declared async (as in Future::AsyncAwait), a Future is returned which (eventually) resolves to the $serial.

reply

$remote->reply( $proc, $serial, $status, $data );

Sends a reply to a remote call $proc using $serial. If $status is ERROR, $data is expected to provide an error (remote_error) structure.

Note: If the on_send callback of the associated transport is declared async (as in Future::AsyncAwait), a Future is returned which resolves when the reply has been sent.

message

$remote->message( $proc, $data );

Sends a notification message $data to the remote procedure $proc.

Note: If the on_send callback of the associated transport is declared async (as in Future::AsyncAwait), a Future is returned which resolves when the message has been sent.

stream

# TODO

CONSTANTS

DRV_FEATURE_MIGRATION_V1
DRV_FEATURE_REMOTE
DRV_FEATURE_MIGRATION_V2
DRV_FEATURE_MIGRATION_P2P
DRV_FEATURE_MIGRATION_DIRECT
DRV_FEATURE_MIGRATION_V3
DRV_FEATURE_MIGRATE_CHANGE_PROTECTION
DRV_FEATURE_FD_PASSING
DRV_FEATURE_TYPED_PARAM_STRING
DRV_FEATURE_PROGRAM_KEEPALIVE
DRV_FEATURE_XML_MIGRATABLE
DRV_FEATURE_MIGRATION_OFFLINE
DRV_FEATURE_MIGRATION_PARAMS
DRV_FEATURE_REMOTE_EVENT_CALLBACK
DRV_FEATURE_REMOTE_CLOSE_CALLBACK
DRV_FEATURE_NETWORK_UPDATE_HAS_CORRECT_ORDER

LICENSE AND COPYRIGHT

See the LICENSE file in this distribution.