| 1 | package Protocol::DBus; | ||
| 2 | |||
| 3 | use strict; | ||
| 4 | use warnings; | ||
| 5 | |||
| 6 | our $VERSION = '0.08-TRIAL1'; | ||
| 7 | |||
| 8 | =encoding utf8 | ||
| 9 | |||
| 10 | =head1 NAME | ||
| 11 | |||
| 12 | Protocol::DBus - D-Bus in pure Perl | ||
| 13 | |||
| 14 | =head1 SYNOPSIS | ||
| 15 | |||
| 16 | my $dbus = Protcol::DBus::Client::system(); | ||
| 17 | |||
| 18 | For blocking I/O: | ||
| 19 | |||
| 20 | # Authentication and “Hello” call/response: | ||
| 21 | $dbus->initialize(); | ||
| 22 | |||
| 23 | $dbus->send_call( | ||
| 24 | path => '/org/freedesktop/DBus', | ||
| 25 | interface => 'org.freedesktop.DBus.Properties', | ||
| 26 | member => 'GetAll', | ||
| 27 | destination => 'org.freedesktop.DBus', | ||
| 28 | signature => 's', | ||
| 29 | body => [ 'org.freedesktop.DBus' ], | ||
| 30 | on_return => sub { my ($msg) = @_ }, | ||
| 31 | ); | ||
| 32 | |||
| 33 | my $msg = $dbus->get_message(); | ||
| 34 | |||
| 35 | For non-blocking I/O: | ||
| 36 | |||
| 37 | $dbus->blocking(0); | ||
| 38 | |||
| 39 | my $fileno = $dbus->fileno(); | ||
| 40 | |||
| 41 | # You can use whatever polling method you prefer; | ||
| 42 | # the following is just for demonstration: | ||
| 43 | vec( my $mask, $fileno, 1 ) = 1; | ||
| 44 | |||
| 45 | while (!$dbus->initialize()) { | ||
| 46 | if ($dbus->init_pending_send()) { | ||
| 47 | select( undef, my $wout = $mask, undef, undef ); | ||
| 48 | } | ||
| 49 | else { | ||
| 50 | select( my $rout = $mask, undef, undef, undef ); | ||
| 51 | } | ||
| 52 | } | ||
| 53 | |||
| 54 | $dbus->send_call( .. ); # same parameters as above | ||
| 55 | |||
| 56 | while (1) { | ||
| 57 | my $wout = $dbus->pending_send() || q<>; | ||
| 58 | $wout &&= $mask; | ||
| 59 | |||
| 60 | select( my $rout = $mask, $wout, undef, undef ); | ||
| 61 | |||
| 62 | if ($wout =~ tr<\0><>c) { | ||
| 63 | $dbus->flush_write_queue(); | ||
| 64 | } | ||
| 65 | |||
| 66 | if ($rout =~ tr<\0><>c) { | ||
| 67 | |||
| 68 | # It’s critical to get_message() until undef is returned. | ||
| 69 | 1 while $dbus->get_message(); | ||
| 70 | } | ||
| 71 | } | ||
| 72 | |||
| 73 | =head1 DESCRIPTION | ||
| 74 | |||
| 75 | This is an original, pure-Perl implementation of client logic for | ||
| 76 | L<the D-Bus protocol|https://dbus.freedesktop.org/doc/dbus-specification.html>. | ||
| 77 | |||
| 78 | It’s not much more than an implementation of the wire protocol; it doesn’t | ||
| 79 | know about objects, services, or anything else besides the actual messages. | ||
| 80 | That said, what’s here already should allow implementation of anything you | ||
| 81 | can do with D-Bus; moreover, it would not be difficult to implement | ||
| 82 | convenience logic—e.g., to mimic interfaces like L<Net::DBus>—on top of | ||
| 83 | what is here now. | ||
| 84 | |||
| 85 | Right now this distribution is an experimental effort. If you use it in your | ||
| 86 | project, be sure to check the changelog before deploying a new version. Please | ||
| 87 | file bug reports as appropriate. | ||
| 88 | |||
| 89 | See L<Protocol::DBus::Client> and the above sample for a starting point. | ||
| 90 | |||
| 91 | =head1 EXAMPLES | ||
| 92 | |||
| 93 | See the distribution’s F<examples/> directory. | ||
| 94 | |||
| 95 | =head1 NOTES | ||
| 96 | |||
| 97 | =over | ||
| 98 | |||
| 99 | =item * UNIX FD support requires that L<Socket::MsgHdr> be loaded at | ||
| 100 | authentication time. | ||
| 101 | |||
| 102 | =item * EXTERNAL and DBUS_COOKIE_SHA1 authentication is supported. | ||
| 103 | |||
| 104 | =back | ||
| 105 | |||
| 106 | =head1 TODO | ||
| 107 | |||
| 108 | =over | ||
| 109 | |||
| 110 | =item * Add conveniences like match rule logic. | ||
| 111 | |||
| 112 | =item * Improve parsing of bus paths in environment variables. | ||
| 113 | |||
| 114 | =item * Add more tests. | ||
| 115 | |||
| 116 | =back | ||
| 117 | |||
| 118 | =head1 SEE ALSO | ||
| 119 | |||
| 120 | L<Net::DBus> uses libdbus (via XS) as its backend. It’s more mature and | ||
| 121 | more idiomatic as to how a D-Bus application is normally written, but | ||
| 122 | it’s also heavier, and it doesn’t appear to support passing filehandles. | ||
| 123 | |||
| 124 | =cut |