Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/fgasper/p5-protocol-dbus
CPAN’s Protocol::DBus
https://github.com/fgasper/p5-protocol-dbus
Last synced: 2 months ago
JSON representation
CPAN’s Protocol::DBus
- Host: GitHub
- URL: https://github.com/fgasper/p5-protocol-dbus
- Owner: FGasper
- License: other
- Created: 2018-09-15T17:35:46.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2022-07-06T17:53:47.000Z (over 2 years ago)
- Last Synced: 2024-10-09T10:06:14.904Z (3 months ago)
- Language: Perl
- Size: 331 KB
- Stars: 6
- Watchers: 3
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: Changes
- License: LICENSE
Awesome Lists containing this project
README
# NAME
Protocol::DBus - D-Bus in pure Perl
# SYNOPSIS
(NB: Examples below assume use of
[subroutine signatures](https://metacpan.org/pod/perlsub#Signatures).)
For blocking I/O:
my $dbus = Protcol::DBus::Client::system();
# Authentication and “Hello” call/response:
$dbus->initialize();
$dbus->send_call(
path => '/org/freedesktop/DBus',
interface => 'org.freedesktop.DBus.Properties',
member => 'GetAll',
destination => 'org.freedesktop.DBus',
signature => 's',
body => [ 'org.freedesktop.DBus' ],
)->then( sub ($resp_msg) { .. } );
my $msg = $dbus->get_message();
For non-blocking I/O, it is recommended to use an event loop.
This distribution includes some connectors to simplify that work:
- [Protocol::DBus::Client::IOAsync](https://metacpan.org/pod/Protocol%3A%3ADBus%3A%3AClient%3A%3AIOAsync) (for [IO::Async](https://metacpan.org/pod/IO%3A%3AAsync))
- [Protocol::DBus::Client::Mojo](https://metacpan.org/pod/Protocol%3A%3ADBus%3A%3AClient%3A%3AMojo) (for [Mojolicious](https://metacpan.org/pod/Mojolicious))
- [Protocol::DBus::Client::AnyEvent](https://metacpan.org/pod/Protocol%3A%3ADBus%3A%3AClient%3A%3AAnyEvent) (for [AnyEvent](https://metacpan.org/pod/AnyEvent))
Example:
my $loop = IO::Async::Loop->new();
my $dbus = Protcol::DBus::Client::IOAsync::login_session($loop);
$dbus->initialize()->then(
sub ($dbus) {
return $dbus->send_call( … ); # same arguments as above
},
)->finally( sub { $loop->stop() } );
$loop->run();
You can also interface with a manually-written event loop.
See [the example](#example-using-manually-written-event-loop) below.
# DESCRIPTION
This is an original, pure-Perl implementation of client messaging logic for
[the D-Bus protocol](https://dbus.freedesktop.org/doc/dbus-specification.html).
It’s not much more than an implementation of the wire protocol; it doesn’t
know about objects, services, or anything else besides the actual messages.
This is fine, of course, if all you want to do is, e.g., replace
an invocation of `gdbus` or `dbus-send` with pure Perl.
If you want an interface that mimics D-Bus’s actual object system,
you’ll need to implement it yourself or use something like [Net::DBus](https://metacpan.org/pod/Net%3A%3ADBus).
(See ["DIFFERENCES FROM Net::DBus"](#differences-from-net-dbus) below.)
# STATUS
This project is in BETA status. While the API should be pretty stable now,
breaking changes can still happen. If you use this module
in your project, you **MUST** check the changelog before deploying a new
version. Please file bug reports as appropriate.
# EXAMPLES
See [Protocol::DBus::Client](https://metacpan.org/pod/Protocol%3A%3ADBus%3A%3AClient) and the above samples for a starting point.
Also see the distribution’s `examples/` directory.
# DIFFERENCES FROM Net::DBus
[Net::DBus](https://metacpan.org/pod/Net%3A%3ADBus) is an XS binding to
[libdbus](https://www.freedesktop.org/wiki/Software/dbus/),
the reference D-Bus implementation. It is CPAN’s most mature D-Bus
implementation.
There are several reasons why you might prefer this module instead,
though, such as:
- Net::DBus discerns how to send a method call via D-Bus introspection.
While handy, this costs extra network overhead and requires an XML parser.
With Protocol::DBus you give a signature directly to send a method call.
- Protocol::DBus can work smoothly with any event system you like,
including custom-written ones. (The distribution ships with connectors for
three popular ones.) Net::DBus, on the other hand, expects you to use its
own event loop, [Net::DBus::Reactor](https://metacpan.org/pod/Net%3A%3ADBus%3A%3AReactor).
- Protocol::DBus has a considerably lighter memory footprint.
- Protocol::DBus is pure Perl, so on most OSes you can fat-pack it
for easy distribution.
- Protocol::DBus exposes a simpler API.
Of course, there are tradeoffs: most notably, Protocol::DBus’s API is
simpler because it doesn’t attempt to implement D-Bus’s object system.
(You never **need** the object system, but it can be a useful abstraction.)
An XS-powered D-Bus library is also likely to outperform a
pure-Perl one, introspection overhead notwithstanding. YMMV. BYOB.
# NOTES
- UNIX FD support requires that [Socket::MsgHdr](https://metacpan.org/pod/Socket%3A%3AMsgHdr) be loaded at
authentication time.
- Certain OSes may require [Socket::MsgHdr](https://metacpan.org/pod/Socket%3A%3AMsgHdr) in order to authenticate
via a UNIX socket. (Linux, notably, does not.) It depends if your OS can
send local socket credentials without using [sendmsg(2)](http://man.he.net/man2/sendmsg).
- EXTERNAL and DBUS\_COOKIE\_SHA1 authentications are supported.
# EXAMPLE USING MANUALLY-WRITTEN EVENT LOOP
my $dbus = Protcol::DBus::Client::system();
$dbus->blocking(0);
my $fileno = $dbus->fileno();
# You can use whatever polling method you prefer;
# the following is just for demonstration:
vec( my $mask, $fileno, 1 ) = 1;
while (!$dbus->initialize()) {
if ($dbus->init_pending_send()) {
select( undef, my $wout = $mask, undef, undef );
}
else {
select( my $rout = $mask, undef, undef, undef );
}
}
$dbus->send_call( .. ); # same parameters as above
while (1) {
my $wout = $dbus->pending_send() || q<>;
$wout &&= $mask;
select( my $rout = $mask, $wout, undef, undef );
if ($wout =~ tr<\0><>c) {
$dbus->flush_write_queue();
}
if ($rout =~ tr<\0><>c) {
# It’s critical to get_message() until undef is returned.
1 while $dbus->get_message();
}
}
Life is easier if you use someone else’s event loop. :)