lib/WL/Connection.pm untested

filter: Statementstmt 0.0% 0 / 74 Branchbran 0.0% 0 / 12 Conditioncond 0.0% 0 / 24 MC/DCmcdc 0.0% 0 / 12 Subroutinesub 0.0% 0 / 15 Podpod 0.0% 0 / 9 totaltotal 0.0% 0 / 146 CC 7 SCAR 17.3
CC
7
Cov
0%
recv
12.0
process_event
12.0
send
6.0
CRAP 5.6
1 package WL::Connection;
2  
3 =head1 NAME
4  
5 WL::Connection - Estabilitsh connection for Wayland protocol
6  
7 =head1 SYNOPSIS
8  
9 use WL::Connection;
10  
11 # Connect to Wayland server (compositor)
12 my $conn = new WL::Connection;
13  
14 # Obtain the display object singleton
15 my $display = $conn->get_display ();
16  
17 ...
18  
19 $conn->loop ();
20  
21 =head1 DESCRIPTION
22  
23 B<WL::Connection> takes care of estabilishing and tearing down a Wayland
24 protocol connection, marshalling and demarshalling the messages and event
25 processing. Moreover it bootstraps the B<WL::wl_display> singleton that is
26 essential for further communication via Wayland protocol.
27  
28 Please consider this an alpha quality code, whose API can change at any time,
29 until we reach version 1.0.
30  
31 =cut
32  
33 use strict;
34 use warnings;
35  
36 use IO::Socket::UNIX;
37 use Socket::MsgHdr;
38 use WL::Base;
39 use WL;
40  
41 =head1 METHODS
42  
43 =over 4
44  
45 =item B<new>
46  
47 Estabilish the connection. The display socket address is determined using
48 C<XDG_RUNTIME_DIR> and C<WAYLAND_DISPLAY> environment variables, falling back
49 to C<wayland-0> display.
50  
51 =cut
52  
53 sub new
54 {
55 my $class = shift;
56 my $self = {};
57  
58 my $xdg_home = $ENV{XDG_RUNTIME_DIR} || "/run/user/$<";
59 my $wayland_display = $ENV{WAYLAND_DISPLAY} || 'wayland-0';
60 my $addr = "$xdg_home/$wayland_display";
61 $self->{conn} = new IO::Socket::UNIX ($addr) or die "$addr: $!";
62 $self->{objs} = [undef];
63  
64 return bless $self, $class;
65 }
66  
67 =item B<send> DATA [FILE]
68  
69 Send a request. The data is aready marshalled message from a L<WL::Base>
70 subclass and the optional second argument is a file handle to be sent as
71 anciliary data alongside the message.
72  
73 This should only be used by C<send_request> called from L<WL::Base> subclasses,
74 not directly.
75  
76 =cut
77  
78 sub send
79 {
80 my $self = shift;
81 my $data = shift;
82 my $file = shift;
83  
84 my $shdr = new Socket::MsgHdr (buf => $data);
85 $shdr->cmsghdr (SOL_SOCKET, SCM_RIGHTS, pack ('i', fileno $file))
86 if $file;
87 sendmsg ($self->{conn}, $shdr);
88 }
89  
90 =item B<recv> LENGTH
91  
92 Read an event, returning the data and optionally a file handle, if a file
93 descriptor is obtained from anciliary data.
94  
95 This should only be used from C<process_event>, not directly.
96  
97 =cut
98  
99 sub recv
100 {
101 my $self = shift;
102 my $len = shift;
103 my $file;
104  
105 return 0 unless $self->{conn};
106  
107 # 12 bytes the cmsg header, 4 bytes the 32-bit file descriptor payload
108 my $chdr = new Socket::MsgHdr (buflen => $len, controllen => 12+4);
109  
110 recvmsg ($self->{conn}, $chdr) or return undef;
111 my ($level, $type, $data) = $chdr->cmsghdr;
112  
113 # File descriptor received. Create a handle for it.
114 if ($level and $type and $level == SOL_SOCKET and $type = SCM_RIGHTS) {
115 open ($file, "+<&=", unpack ('i', $data)) or die $!;
116 }
117  
118 return ($chdr->buf, $file || ());
119 }
120  
121 =item B<send_request> ID OPCODE PAYLOAD [FILE]
122  
123 Add message heading with id, opcode and length to already marshalled payload
124 and send it, optionally with an open file handle as anciliary data.
125  
126 =cut
127  
128 sub send_request
129 {
130 my $self = shift;
131 my $id = shift;
132 my $opcode = shift;
133 my $payload = shift;
134 my $file = shift,
135  
136 my $length = 8 + length $payload;
137 $self->send (pack ('L L a*', $id,
138 (($length << 16) | $opcode), $payload), $file);
139 }
140  
141 =item B<process_event>
142  
143 Read a message, decode the header and call a C<callback> method (inherited from
144 L<WL::Base>) of its recipient with raw message body and optional file handle.
145  
146 =cut
147  
148 sub process_event
149 {
150 my $self = shift;
151  
152 # First two words, identifying the recipient and length of the body
153 my ($buf, $file) = $self->recv (8);
154 die $! unless defined $buf;
155 return 0 unless $buf;
156  
157 my ($id, $word2) = unpack 'LL', $buf;
158 my $opcode = $word2 & 0x0000ffff;
159 my $length = $word2 >> 16;
160  
161 # Read the body, we aready have first two words, the header
162 ($buf) = $self->recv ($length - 8) or die $!;
163 $self->{objs}[$id]->callback ($opcode, $buf, $file);
164  
165 return 1;
166 }
167  
168 =item B<get_display>
169  
170 Create and return a L<WL::wl_display> singleton object.
171  
172 =cut
173  
174 sub get_display
175 {
176 my $self = shift;
177 return new WL::wl_display ($self);
178 }
179  
180 =item B<round_trip> DISPLAY
181  
182 Issue a C<sync> call for the display object and wait for C<done> event receipt.
183  
184 As Wayland ensures the calls are processed in order, this creates a barrier in
185 message stream.
186  
187 =cut
188  
189 sub round_trip
190 {
191 my $self = shift;
192 my $display = shift;
193  
194 my $finished = 0;
195 my $done = $display->sync ();
196 $done->{'WL::wl_callback::done'} = sub {
197 $finished = 1;
198 };
199  
200 while (not $finished) {
201 last unless $self->process_event ();
202 }
203 }
204  
205 =item B<loop>
206  
207 Process the events until the connection tears down.
208  
209 =cut
210  
211 sub loop
212 {
213 my $self = shift;
214 while ($self->process_event ()) {};
215 }
216  
217 =item B<disconnect>
218  
219 Tear down the connection.
220  
221 =cut
222  
223 sub disconnect
224 {
225 my $self = shift;
226 close delete $self->{conn};
227 }
228  
229 =back
230  
231 =head1 SEE ALSO
232  
233 =over
234  
235 =item *
236  
237 L<http://wayland.freedesktop.org/> -- Wayland project web site
238  
239 =item *
240  
241 L<WL::Base> -- Base class for Wayland objects
242  
243 =back
244  
245 =head1 COPYRIGHT
246  
247 Copyright 2013 Lubomir Rintel
248  
249 This program is free software; you can redistribute it and/or modify it
250 under the same terms as Perl itself.
251  
252 =head1 AUTHORS
253  
254 Lubomir Rintel C<lkundrak@v3.sk>
255  
256 =cut
257  
258 1;