| 1 | package Protocol::DBus::Client; | ||||||||||||||||||||||||||||
| 2 | |||||||||||||||||||||||||||||
| 3 | 5 | ▶ | use strict; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 4 | 5 | ▶ | use warnings; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 5 | |||||||||||||||||||||||||||||
| 6 | =encoding utf-8 | ||||||||||||||||||||||||||||
| 7 | |||||||||||||||||||||||||||||
| 8 | =head1 NAME | ||||||||||||||||||||||||||||
| 9 | |||||||||||||||||||||||||||||
| 10 | Protocol::DBus::Client | ||||||||||||||||||||||||||||
| 11 | |||||||||||||||||||||||||||||
| 12 | =head1 SYNOPSIS | ||||||||||||||||||||||||||||
| 13 | |||||||||||||||||||||||||||||
| 14 | my $dbus = Protocol::DBus::Client::system(); | ||||||||||||||||||||||||||||
| 15 | |||||||||||||||||||||||||||||
| 16 | $dbus->initialize(); | ||||||||||||||||||||||||||||
| 17 | |||||||||||||||||||||||||||||
| 18 | =head1 DESCRIPTION | ||||||||||||||||||||||||||||
| 19 | |||||||||||||||||||||||||||||
| 20 | This is the end class for use in DBus client applications. It subclasses | ||||||||||||||||||||||||||||
| 21 | L<Protocol::DBus::Peer>. | ||||||||||||||||||||||||||||
| 22 | |||||||||||||||||||||||||||||
| 23 | B<NOTE:> This module will automatically send a “Hello” message after | ||||||||||||||||||||||||||||
| 24 | authentication completes. That message’s response will be processed | ||||||||||||||||||||||||||||
| 25 | automatically. Because this is part of the protocol’s handshake | ||||||||||||||||||||||||||||
| 26 | logic rather than something useful for callers, it is abstracted away from | ||||||||||||||||||||||||||||
| 27 | the caller. It is neither necessary nor productive for callers to send a | ||||||||||||||||||||||||||||
| 28 | “Hello” message. | ||||||||||||||||||||||||||||
| 29 | |||||||||||||||||||||||||||||
| 30 | =cut | ||||||||||||||||||||||||||||
| 31 | |||||||||||||||||||||||||||||
| 32 | 5 | ▶ | use parent 'Protocol::DBus::Peer'; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 33 | |||||||||||||||||||||||||||||
| 34 | 5 | ▶ | use Protocol::DBus::Authn; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 35 | 5 | ▶ | use Protocol::DBus::Connect; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 36 | 5 | ▶ | use Protocol::DBus::Path; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 37 | |||||||||||||||||||||||||||||
| 38 | =head1 STATIC FUNCTIONS | ||||||||||||||||||||||||||||
| 39 | |||||||||||||||||||||||||||||
| 40 | =head2 system() | ||||||||||||||||||||||||||||
| 41 | |||||||||||||||||||||||||||||
| 42 | Creates an instance of this class that includes a connection to the | ||||||||||||||||||||||||||||
| 43 | system’s message bus. | ||||||||||||||||||||||||||||
| 44 | |||||||||||||||||||||||||||||
| 45 | This does not do authentication; you’ll need to do that via the class’s | ||||||||||||||||||||||||||||
| 46 | methods. | ||||||||||||||||||||||||||||
| 47 | |||||||||||||||||||||||||||||
| 48 | =cut | ||||||||||||||||||||||||||||
| 49 | |||||||||||||||||||||||||||||
| 50 | sub system { | ||||||||||||||||||||||||||||
| 51 | 1 | ▶ | my @addrs = Protocol::DBus::Path::system_message_bus(); | ||||||||||||||||||||||||||
|
Subroutine
system: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||||||||||
| 52 | |||||||||||||||||||||||||||||
| 53 | 1 | return _create_local(@addrs); | |||||||||||||||||||||||||||
| 54 | } | ||||||||||||||||||||||||||||
| 55 | |||||||||||||||||||||||||||||
| 56 | =head2 login_session() | ||||||||||||||||||||||||||||
| 57 | |||||||||||||||||||||||||||||
| 58 | Like C<system()> but for the login session’s message bus. | ||||||||||||||||||||||||||||
| 59 | |||||||||||||||||||||||||||||
| 60 | =cut | ||||||||||||||||||||||||||||
| 61 | |||||||||||||||||||||||||||||
| 62 | sub login_session { | ||||||||||||||||||||||||||||
| 63 | 0 | ▶ | my @addrs = Protocol::DBus::Path::login_session_message_bus(); | ||||||||||||||||||||||||||
|
Subroutine
login_session: not called CC=2 SCAR=17.9
Pod
documented
| |||||||||||||||||||||||||||||
| 64 | |||||||||||||||||||||||||||||
| 65 | 0 | ▶ | if (!@addrs) { | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 66 | 0 | die "Failed to identify login system message bus!"; | |||||||||||||||||||||||||||
| 67 | } | ||||||||||||||||||||||||||||
| 68 | |||||||||||||||||||||||||||||
| 69 | 0 | return _create_local(@addrs); | |||||||||||||||||||||||||||
| 70 | } | ||||||||||||||||||||||||||||
| 71 | |||||||||||||||||||||||||||||
| 72 | sub _create_local { | ||||||||||||||||||||||||||||
| 73 | 1 | ▶ | my ($addr) = @_; | ||||||||||||||||||||||||||
|
Subroutine
_create_local: called CC=1 SCAR=0.4
| |||||||||||||||||||||||||||||
| 74 | 1 | my $socket = Protocol::DBus::Connect::create_socket($addr); | |||||||||||||||||||||||||||
| 75 | |||||||||||||||||||||||||||||
| 76 | 0 | return __PACKAGE__->new( | |||||||||||||||||||||||||||
| 77 | socket => $socket, | ||||||||||||||||||||||||||||
| 78 | authn_mechanism => 'EXTERNAL', | ||||||||||||||||||||||||||||
| 79 | ); | ||||||||||||||||||||||||||||
| 80 | } | ||||||||||||||||||||||||||||
| 81 | |||||||||||||||||||||||||||||
| 82 | #---------------------------------------------------------------------- | ||||||||||||||||||||||||||||
| 83 | |||||||||||||||||||||||||||||
| 84 | =head1 METHODS | ||||||||||||||||||||||||||||
| 85 | |||||||||||||||||||||||||||||
| 86 | =head2 $done_yn = I<OBJ>->initialize() | ||||||||||||||||||||||||||||
| 87 | |||||||||||||||||||||||||||||
| 88 | This returns truthy once the connection is ready to use and falsy until then. | ||||||||||||||||||||||||||||
| 89 | In blocking I/O contexts the call will block. | ||||||||||||||||||||||||||||
| 90 | |||||||||||||||||||||||||||||
| 91 | Note that this includes the initial C<Hello> message and its response. | ||||||||||||||||||||||||||||
| 92 | |||||||||||||||||||||||||||||
| 93 | Previously this function was called C<do_authn()> and did not wait for | ||||||||||||||||||||||||||||
| 94 | the C<Hello> message’s response. The older name is retained | ||||||||||||||||||||||||||||
| 95 | as an alias for backward compatibility. | ||||||||||||||||||||||||||||
| 96 | |||||||||||||||||||||||||||||
| 97 | =cut | ||||||||||||||||||||||||||||
| 98 | |||||||||||||||||||||||||||||
| 99 | sub initialize { | ||||||||||||||||||||||||||||
| 100 | 1 | ▶ | my ($self) = @_; | ||||||||||||||||||||||||||
|
Subroutine
initialize: called CC=6 SCAR=18.8
Pod
documented
| |||||||||||||||||||||||||||||
| 101 | |||||||||||||||||||||||||||||
| 102 | 1 | ▶ | if ($self->{'_authn'}->go()) { | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 103 | 1 | ▶ | $self->{'_sent_hello'} ||= do { | ||||||||||||||||||||||||||
|
Condition33%1/3
$self->{"_sent_hello"} ||= do {
$self->send_call("path", "/org/freedesktop/DBus", "interface", "org.freedesktop.DBus", "destination", "org.freedesktop.DBus", "member", "Hello", "on_return", sub {
$self->{"_connection_name"} = $_[0]->get_body->[0];
}
)
}
MC/DC0%0/2
$self->{"_sent_hello"} ||= do {
$self->send_call("path", "/org/freedesktop/DBus", "interface", "org.freedesktop.DBus", "destination", "org.freedesktop.DBus", "member", "Hello", "on_return", sub {
$self->{"_connection_name"} = $_[0]->get_body->[0];
}
)
}
$self->{"_sent_hello"}
do {
$self->send_call("path", "/org/freedesktop/DBus", "interface", "org.freedesktop.DBus", "destination", "org.freedesktop.DBus", "member", "Hello", "on_return", sub {
$self->{"_connection_name"} = $_[0]->get_body->[0];
}
)
}
Truth table33%1/3
A ||= B
A= $self->{"_sent_hello"}B= do {
$self->send_call("path", "/org/freedesktop/DBus", "interface", "org.freedesktop.DBus", "destination", "org.freedesktop.DBus", "member", "Hello", "on_return", sub {
$self->{"_connection_name"} = $_[0]->get_body->[0];
}
)
}
| |||||||||||||||||||||||||||||
| 104 | $self->send_call( | ||||||||||||||||||||||||||||
| 105 | path => '/org/freedesktop/DBus', | ||||||||||||||||||||||||||||
| 106 | interface => 'org.freedesktop.DBus', | ||||||||||||||||||||||||||||
| 107 | destination => 'org.freedesktop.DBus', | ||||||||||||||||||||||||||||
| 108 | member => 'Hello', | ||||||||||||||||||||||||||||
| 109 | on_return => sub { | ||||||||||||||||||||||||||||
| 110 | 1 | ▶ | $self->{'_connection_name'} = $_[0]->get_body()->[0]; | ||||||||||||||||||||||||||
|
Subroutine
__ANON__: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 111 | }, | ||||||||||||||||||||||||||||
| 112 | 1 | ); | |||||||||||||||||||||||||||
| 113 | }; | ||||||||||||||||||||||||||||
| 114 | |||||||||||||||||||||||||||||
| 115 | 1 | ▶ | if (!$self->{'_connection_name'}) { | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 116 | GET_MESSAGE: { | ||||||||||||||||||||||||||||
| 117 | 1 | ▶ | if (my $msg = $self->SUPER::get_message()) { | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 118 | 2 | ▶ | return 1 if $self->{'_connection_name'}; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 119 | |||||||||||||||||||||||||||||
| 120 | 1 | push @{ $self->{'_pending_received_messages'} }, $msg; | |||||||||||||||||||||||||||
| 121 | |||||||||||||||||||||||||||||
| 122 | 1 | redo GET_MESSAGE; | |||||||||||||||||||||||||||
| 123 | } | ||||||||||||||||||||||||||||
| 124 | } | ||||||||||||||||||||||||||||
| 125 | } | ||||||||||||||||||||||||||||
| 126 | } | ||||||||||||||||||||||||||||
| 127 | |||||||||||||||||||||||||||||
| 128 | 0 | return 0; | |||||||||||||||||||||||||||
| 129 | } | ||||||||||||||||||||||||||||
| 130 | |||||||||||||||||||||||||||||
| 131 | 5 | *do_authn = \*initialize; | |||||||||||||||||||||||||||
| 132 | |||||||||||||||||||||||||||||
| 133 | #---------------------------------------------------------------------- | ||||||||||||||||||||||||||||
| 134 | |||||||||||||||||||||||||||||
| 135 | =head2 $yn = I<OBJ>->init_pending_send() | ||||||||||||||||||||||||||||
| 136 | |||||||||||||||||||||||||||||
| 137 | This indicates whether there is data queued up to send for the initialization. | ||||||||||||||||||||||||||||
| 138 | Only useful with non-blocking I/O. | ||||||||||||||||||||||||||||
| 139 | |||||||||||||||||||||||||||||
| 140 | This function was previously called C<authn_pending_send()>; the former | ||||||||||||||||||||||||||||
| 141 | name is retained for backward compatibility. | ||||||||||||||||||||||||||||
| 142 | |||||||||||||||||||||||||||||
| 143 | =cut | ||||||||||||||||||||||||||||
| 144 | |||||||||||||||||||||||||||||
| 145 | sub init_pending_send { | ||||||||||||||||||||||||||||
| 146 | 0 | ▶ | my ($self) = @_; | ||||||||||||||||||||||||||
|
Subroutine
init_pending_send: not called CC=3 SCAR=24.8
Pod
documented
| |||||||||||||||||||||||||||||
| 147 | |||||||||||||||||||||||||||||
| 148 | 0 | ▶ | if ($self->{'_connection_name'}) { | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 149 | 0 | die "Don’t call this after initialize() is done!"; | |||||||||||||||||||||||||||
| 150 | } | ||||||||||||||||||||||||||||
| 151 | |||||||||||||||||||||||||||||
| 152 | 0 | ▶ | if ($self->{'_sent_hello'}) { | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 153 | 0 | return $self->pending_send(); | |||||||||||||||||||||||||||
| 154 | } | ||||||||||||||||||||||||||||
| 155 | |||||||||||||||||||||||||||||
| 156 | 0 | return $self->{'_authn'}->pending_send(); | |||||||||||||||||||||||||||
| 157 | } | ||||||||||||||||||||||||||||
| 158 | |||||||||||||||||||||||||||||
| 159 | 5 | *authn_pending_send = \*init_pending_send; | |||||||||||||||||||||||||||
| 160 | |||||||||||||||||||||||||||||
| 161 | #---------------------------------------------------------------------- | ||||||||||||||||||||||||||||
| 162 | |||||||||||||||||||||||||||||
| 163 | =head2 $yn = I<OBJ>->supports_unix_fd() | ||||||||||||||||||||||||||||
| 164 | |||||||||||||||||||||||||||||
| 165 | Boolean that indicates whether this client supports UNIX FD passing. | ||||||||||||||||||||||||||||
| 166 | |||||||||||||||||||||||||||||
| 167 | =cut | ||||||||||||||||||||||||||||
| 168 | |||||||||||||||||||||||||||||
| 169 | sub supports_unix_fd { | ||||||||||||||||||||||||||||
| 170 | 0 | ▶ | my ($self) = @_; | ||||||||||||||||||||||||||
|
Subroutine
supports_unix_fd: not called CC=1 SCAR=6.9
Pod
documented
| |||||||||||||||||||||||||||||
| 171 | |||||||||||||||||||||||||||||
| 172 | 0 | return $self->{'_authn'}->negotiated_unix_fd(); | |||||||||||||||||||||||||||
| 173 | } | ||||||||||||||||||||||||||||
| 174 | |||||||||||||||||||||||||||||
| 175 | #---------------------------------------------------------------------- | ||||||||||||||||||||||||||||
| 176 | |||||||||||||||||||||||||||||
| 177 | =head2 $msg = I<OBJ>->get_message() | ||||||||||||||||||||||||||||
| 178 | |||||||||||||||||||||||||||||
| 179 | Same as in the base class, but for clients the initial “Hello” message and | ||||||||||||||||||||||||||||
| 180 | its response are abstracted | ||||||||||||||||||||||||||||
| 181 | |||||||||||||||||||||||||||||
| 182 | =cut | ||||||||||||||||||||||||||||
| 183 | |||||||||||||||||||||||||||||
| 184 | sub get_message { | ||||||||||||||||||||||||||||
| 185 | 1 | ▶ | my ($self) = @_; | ||||||||||||||||||||||||||
|
Subroutine
get_message: called CC=4 SCAR=15.2
Pod
documented
| |||||||||||||||||||||||||||||
| 186 | |||||||||||||||||||||||||||||
| 187 | 1 | ▶ | die "initialize() is not finished!" if !$self->{'_connection_name'}; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 188 | |||||||||||||||||||||||||||||
| 189 | 1 | ▶ | if ($self->{'_pending_received_messages'} && @{ $self->{'_pending_received_messages'} }) { | ||||||||||||||||||||||||||
|
Branch: 1 branch
Condition33%1/3
$self->{"_pending_received_messages"} and @{$self->{"_pending_received_messages"};}
MC/DC0%0/2
$self->{"_pending_received_messages"} and @{$self->{"_pending_received_messages"};}
$self->{"_pending_received_messages"}
@{$self->{"_pending_received_messages"};}
Truth table33%1/3
A and B
A= $self->{"_pending_received_messages"}B= @{$self->{"_pending_received_messages"};}
| |||||||||||||||||||||||||||||
| 190 | 1 | return shift @{ $self->{'_pending_received_messages'} }; | |||||||||||||||||||||||||||
| 191 | } | ||||||||||||||||||||||||||||
| 192 | |||||||||||||||||||||||||||||
| 193 | 5 | ▶ | no warnings 'redefine'; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 194 | 0 | *get_message = Protocol::DBus::Peer->can('get_message'); | |||||||||||||||||||||||||||
| 195 | |||||||||||||||||||||||||||||
| 196 | 0 | return $_[0]->get_message(); | |||||||||||||||||||||||||||
| 197 | } | ||||||||||||||||||||||||||||
| 198 | |||||||||||||||||||||||||||||
| 199 | =head2 $name = I<OBJ>->get_connection_name() | ||||||||||||||||||||||||||||
| 200 | |||||||||||||||||||||||||||||
| 201 | Returns the name of the connection. | ||||||||||||||||||||||||||||
| 202 | |||||||||||||||||||||||||||||
| 203 | =cut | ||||||||||||||||||||||||||||
| 204 | |||||||||||||||||||||||||||||
| 205 | sub get_connection_name { | ||||||||||||||||||||||||||||
| 206 | 1 | ▶ | return $_[0]->{'_connection_name'} || die 'No connection name known yet!'; | ||||||||||||||||||||||||||
|
Subroutine
get_connection_name: called CC=2 SCAR=7.6
Pod
documented
Condition50%1/2
$_[0]{'_connection_name'} || die('No connection name known yet!')
MC/DC0%0/1
$_[0]{'_connection_name'} || die('No connection name known yet!')
$_[0]{'_connection_name'}
Truth table50%1/2
A
A= $_[0]{'_connection_name'}
| |||||||||||||||||||||||||||||
| 207 | } | ||||||||||||||||||||||||||||
| 208 | |||||||||||||||||||||||||||||
| 209 | # undocumented for now | ||||||||||||||||||||||||||||
| 210 | sub new { | ||||||||||||||||||||||||||||
| 211 | 1 | ▶ | my ($class, %opts) = @_; | ||||||||||||||||||||||||||
|
Subroutine
new: called CC=1 SCAR=0.0
Pod
undocumented
| |||||||||||||||||||||||||||||
| 212 | |||||||||||||||||||||||||||||
| 213 | my $authn = Protocol::DBus::Authn->new( | ||||||||||||||||||||||||||||
| 214 | socket => $opts{'socket'}, | ||||||||||||||||||||||||||||
| 215 | 1 | mechanism => $opts{'authn_mechanism'}, | |||||||||||||||||||||||||||
| 216 | ); | ||||||||||||||||||||||||||||
| 217 | |||||||||||||||||||||||||||||
| 218 | 1 | my $self = $class->SUPER::new( $opts{'socket'} ); | |||||||||||||||||||||||||||
| 219 | |||||||||||||||||||||||||||||
| 220 | 1 | $self->{'_authn'} = $authn; | |||||||||||||||||||||||||||
| 221 | |||||||||||||||||||||||||||||
| 222 | 1 | return $self; | |||||||||||||||||||||||||||
| 223 | } | ||||||||||||||||||||||||||||
| 224 | |||||||||||||||||||||||||||||
| 225 | 5 | 1; | |||||||||||||||||||||||||||