| 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; |