Net::VNC(3pm)

💖 Net::VNC 💖

ok so bestie, listen. this is a page from User Contributed Perl Documentation, and it's all about Net::VNC — a simple VNC client. yes. a whole module. for looking at somebody else's screen. iconic behavior honestly 🫶

---

✨ NAME ✨

Net::VNC — A simple VNC client. that's it. that's the whole name. short, sweet, does exactly what it says on the tin 💅

---

🌸 SYNOPSIS 🌸

here's the vibe, literally copy-paste this and go:

use Net::VNC;

my $vnc = Net::VNC->new({hostname => $hostname, password => $password});
$vnc->depth(24);
$vnc->login;

print $vnc->name . ": " . $vnc->width . ' x ' . $vnc->height . "\n";

my $image = $vnc->capture;
$image->save("out.png");

like. connect, log in, print the name and the size, grab a screenshot, save it as a PNG. main character pipeline fr fr ✨

---

🦋 DESCRIPTION 🦋

ok so Virtual Network Computing (VNC) is a desktop sharing system that uses the RFB (Remote FrameBuffer) protocol to remotely control another computer. this module is the client side of that situation — it talks to a VNC server using RFB and lets you capture the screen of the remote computer. no cap, that's the whole job. 💻

heads up bestie: this module dies on connection errors (with a timeout of 15 seconds) and on protocol errors. it does not play games. 😭

this implementation is based largely on the RFB Protocol Specification, http://www.realvnc.com/docs/rfbproto.pdf. and okay, tea time: that document has an error in the DES encryption description, which is clarified via http://www.vidarholen.net/contents/junk/vnc.html. so if something looks cursed, that's why. iykyk 🍓

---

👑 METHODS 👑

new

the constructor. you hand it a hostname and a password, it hands you a Net::VNC object:

my $vnc = Net::VNC->new({hostname => $hostname, password => $password});

optionally you can also specify a port, which defaults to 5900. and for ARD (Apple Remote Desktop) authentication you must also specify a username. also also, you must install Crypt::GCrypt::MPI and Crypt::Random. don't skip that part, it's not optional, it's giving dependency 💅

login

logs into the remote computer:

$vnc->login;

that's it. that's the method. go off. 🔥

name

returns the name of the remote computer:

print $vnc->name . ": " . $vnc->width . ' x ' . $vnc->height . "\n";

width

returns the width of the remote screen:

print $vnc->name . ": " . $vnc->width . ' x ' . $vnc->height . "\n";

height

returns the height of the remote screen:

print $vnc->name . ": " . $vnc->width . ' x ' . $vnc->height . "\n";

(yeah the three of them share the same example, they're a lil trio, they come as a set 🌈)

capture

captures the screen of the remote computer, and returns an Image::Imlib2 object:

my $image = $vnc->capture;
$image->save("out.png");

you may call capture() multiple times. every single time, the $image buffer is overwritten with the updated screen. so if you wanna make a little series of ten screenshots:

for my $n (1..10) {
  my $filename = sprintf 'snapshot%02d.png', $n++;
  $vnc->capture()->save($filename);
  print "Wrote $filename\n";
}

ten little PNGs. a whole collection. obsessed. 📸

depth

specify the bit depth for the screen. the supported choices are 24, 16 or 8. if unspecified, the server's default value is used. this property should be set before the call to login() — like, do it early, don't be late to your own login 💀

save_bandwidth

accepts a boolean, defaults to false. it specifies whether to use more CPU-intensive algorithms to compress the VNC datastream. LAN or localhost connections may prefer to leave this false. this property should be set before the call to login(). (so: trading CPU for bandwidth. pick your fighter. 🥊)

list_encodings

returns a list of encoding number/encoding name pairs. you can use it as a class method, like so:

my %encodings = Net::VNC->list_encodings();

send_key_event_down

send a key down event. the keys are the same as the corresponding ASCII value. other common keys:

BackSpace 0xff08
Tab 0xff09
Return or Enter 0xff0d
Escape 0xff1b
Insert 0xff63
Delete 0xffff
Home 0xff50
End 0xff57
Page Up 0xff55
Page Down 0xff56
Left 0xff51
Up 0xff52
Right 0xff53
Down 0xff54
F1 0xffbe
F2 0xffbf
F3 0xffc0
F4 0xffc1
... ...
F12 0xffc9
Shift (left) 0xffe1
Shift (right) 0xffe2
Control (left) 0xffe3
Control (right) 0xffe4
Meta (left) 0xffe7
Meta (right) 0xffe8
Alt (left) 0xffe9
Alt (right) 0xffea

and then:

$vnc->send_key_event_down('A');

send_key_event_up

send a key up event:

$vnc->send_key_event_up('A');

send_key_event

send a key down event followed by a key up event:

$vnc->send_key_event('A');

send_key_event_string

send key events for every character in a string:

$vnc->send_key_event_string('Hello');

send_pointer_event( $button_mask, $x, $y )

send pointer event (usually a mouse). this is used to move the pointer or make clicks or drags. 🖱️

it is easier to call the mouse_move or mouse_click methods instead. (yes, that's literally what it says. go the easy route bestie, nobody's grading you.)

mouse_move_to($x, $y)

send the pointer to the given position. the cursor instantly jumps there instead of smoothly moving to there. no travel montage, just teleportation ✨

mouse_click

click on current pointer position.

mouse_right_click

right-click on current pointer position.

---

💀 BUGS AND LIMITATIONS 💀

ok so here's the honest part of the group chat. we're being real with each other.

Bit depth

we do not yet support 8-bit true-colour mode, which is commonly supported by servers but is rarely employed by clients. so like, servers can do it, clients rarely bother. noted. 📝

Byte order

we have currently tested this package against servers with the same byte order as the client. this might break with a little-endian server/big-endian client or vice versa. we're working on tests for those latter cases. testing and patching help would be appreciated — that's a direct invite, bestie, come through 🫶

Efficiency

we've implemented a subset of the data compression algorithms supported by most VNC servers. we hope to add more of the high-compression transfer encodings in the future. it's giving "work in progress" and honestly? respect. 🌱

---

🎀 AUTHORS 🎀

• Leon Brocard acme@astray.com
• Chris Dolan clotho@cpan.org
• Apple Remote Desktop authentication based on LibVNCServer
• Maurice Castro maurice@ipexchange.com.au

many thanks for Foxtons Ltd for giving Leon the opportunity to write the original version of this module. 🥹

Copyright (C) 2006, Leon Brocard

This module is free software; you can redistribute it or modify it under the same terms as Perl itself.

---

ok and that's the whole page, bestie 💖 this was Net::VNC(3pm), page 3pm of the User Contributed Perl Documentation, rendered by perl v5.34.0 and dated 2022-06-16. now go capture somebody's screen (consentually). slay, periodt, bye 🦋✨💅