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' ],
    )->then( sub { .. } );

    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 or ERROR 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.

$promise = OBJ->send_call( %OPTS )

Send a METHOD_CALL message.

%OPTS are path, interface, member, destination, signature, and body. These do as you’d expect, but note that body, if given, must be an array reference.

The return value is an instance of Promise::ES6 that will resolve when a METHOD_RETURN arrives in response, or reject when an ERROR arrives. The promise both resolves and rejects with a Protocol::DBus::Message instance that represents the response.

Note that exceptions can still happen (outside of the promise), e.g., if your input is invalid or if there’s a socket I/O error.

$flushed_yn = OBJ->send_return( $ORIG_MSG, %OPTS )

Send a METHOD_RETURN message.

The return is a boolean that indicates whether the message is sent (truthy) or remains queued (falsy).

Arguments are similar to send_call() except for the header differences that the D-Bus specification describes. Also, destination is not given directly but is instead inferred from the $ORIG_MSG. (Behavior is undefined if this parameter is given directly.)

$flushed_yn = OBJ->send_error( $ORIG_MSG, %OPTS )

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

$flushed_yn = OBJ->send_signal( %OPTS )

Like send_call() but sends a signal rather than a method call. This also returns a boolean like send_return().

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.

cpanm Protocol::DBus

perl -MCPAN -e shell
install Protocol::DBus