/ 
Protocol-DBus-0.08-TRIAL1
River stage zero No dependents
/ Protocol::DBus::Peer

NAME

Protocol::DBus::Peer - base class for a D-Bus peer

SYNOPSIS

$dbus->send_call(
    interface => 'org.freedesktop.DBus.Properties',
    member => 'GetAll',
    signature => 's',
    path => '/org/freedesktop/DBus',
    destination => 'org.freedesktop.DBus',
    body => [ 'org.freedesktop.DBus' ],
    on_return => sub { my ($msg) = @_ },
);

my $msg = $dbus->get_message();

# Same pattern as the IO::Handle method.
$dbus->blocking(0);

my $fileno = $dbus->fileno();

$dbus->flush_write_queue() if $dbus->pending_send();

# I’m not sure why you’d want to do this, but …
$dbus->big_endian();

DESCRIPTION

This class contains D-Bus logic that is useful in both client and server contexts. (Currently this distribution does not include a server implementation.)

METHODS

$msg = OBJ->get_message()

This returns a single instace of Protocol::DBus::Message, or undef if no message is available. It will also fire the appropriate “on_return” method on METHOD_RETURN messages.

The backend I/O logic reads data in chunks; thus, if there is a message already available in the read buffer, no I/O is done. If you’re doing non-blocking I/O then it is thus vital that, every time the DBus socket is readable, you call this function until undef is returned.

OBJ->flush_write_queue()

Same as IO::Framed::Write’s method of the same name.

OBJ->send_call( %OPTS )

Send a METHOD_CALL message.

%OPTS are path, interface, member, destination, signature, body, and on_return. These do as you’d expect, with the following caveats:

  • body, if given, must be an array reference. See Protocol::DBus::Message for a discussion of how to map between D-Bus and Perl.

  • The on_return callback receives the server’s response message (NB: either METHOD_RETURN or ERROR) as argument.

OBJ->send_return( $ORIG_MSG, %OPTS )

Send a METHOD_RETURN message.

Arguments are similar to send_call() except for the header differences that the D-Bus specification describes. Also:

  • destination is taken from the $ORIG_MSG. (Behavior is undefined if this parameter is given directly.)

  • There is no on_return parameter.

OBJ->send_error( $ORIG_MSG, %OPTS )

Like send_return(), but sends an error instead. The error_name parameter is required.

OBJ->send_signal( %OPTS )

Like send_call() but sends a signal rather than a method call. There is no on_return parameter.

OBJ->big_endian()

Same interface as blocking(), but this sets/gets/toggles whether to send big-endian messages instead of little-endian.

By default this library uses the system’s native byte order, so you probably have little need for this function.

OBJ->preserve_variant_signatures()

Same interface as blocking(), but when this is enabled variants are given as two-member array references ([ signature => value ]), blessed as Protocol::DBus::Type::Variant instances.

For most Perl applications this is probably counterproductive.

OBJ->blocking()

Same interface as IO::Handle’s method of the same name.

OBJ->fileno()

Returns the connection socket’s file descriptor.

OBJ->pending_send()

Returns a boolean that indicates whether there is data queued up to send to the server.