Net::H...Client(3pm)

💖 Net::H...Client(3pm) 💖

okay bestie, welcome to the Net::H...Client(3pm) page from User Contributed Perl Documentation. Yes, the title gets abbreviated, but the module itself is Net::Hotline::Client. Buckle up, because this manual is long and we're doing every single crumb. 💅

---

✨ NAME ✨

Net::Hotline::Client — a Perl library for the Hotline internet client. That's the one-liner. Slay.

🌸 SYNOPSIS 🌸

use Net::Hotline::Client;

$hlc = new Net::Hotline::Client;
$hlc->connect("127.0.0.1")

$hlc->chat_handler(\&Chat_Handler);
$hlc->msg_handler(\&Msg_Handler);

$hlc->login(Login    => "Steve",
            Password => "xyzzy",
            Nickname => "Jobs",
            Icon     => 128);

$hlc->run();
...

🦋 DESCRIPTION 🦋

okay so Net::Hotline::Client is a class that implements a Hotline internet client in Perl. It was specifically developed to aid in the creation of Hotline "bots," although it's suitable for most other tasks as well. Hotline is an internet client/server system that's sort of a cross between IRC and a BBS. See http://www.hotlinesw.com/ for more information.

This document assumes you have some knowledge of the Hotline client. If not, I suggest downloading it from the URL above. (It's shareware. Mac and PC versions are available.)

🩷 CAVEATS 🩷

The Hotline protocol is not public. (An RFC? I wish!) This module got its start with the aid of the C source code from the Unix "hx" Hotline client written by Ryan Nielsen, the beginnings of a Java Hotline bot written by Gary Wong, and many hours spent staring at hexdumps of network data. Some features are still not implemented, the most notable being user administration capabilities. Finally, I'm sure all hell will break loose with the next major revision of Hotline. Such is life.

🌈 GETTING STARTED 🌈

Before we get into the nitty-gritty, it's important to understand the philosophy behind design of this module. If you do not read this section first, you will probably be confused by the rest of the documentation. Take the time now and save yourself headaches later. Fr fr.

Hotline is an event-driven protocol. A Hotline client receives packets each time something interesting occurs on the server--a new user joins, someone says something in chat, someone goes idle, etc. The client receives these packets whether it's ready for them or not. This type of interaction lends itself to an event-loop/callback-routine design, which is how this module was originally implemented. Handler routines are set for the events you're interested in, and then the event loop is started.

In this model, client actions are also treated as events. To retrieve the news, for example, the client calls a function that sends a news request to the server and returns a task ID number. The client then returns to the event loop and watches the incoming packet stream for a packet with the same task ID (it will be either a packet containing the news or a task error packet). In the time between when the news request was sent and the response is received from the server, many other unrelated events can (and probably will) occur.

This system works great for things like bots that want to deal with events in a non-linear fashion, but what about when you want to do things in a more deterministic manner? For example, imagine trying to implement a command line FTP-like Hotline client using the event loop model. Sure, it's possible, but it's not pretty! I found this out the hard way. What's needed are what I'm going to call "blocking tasks." That is, function calls that don't return until their work is done. In this new model, the news request function would not merely return a task ID number, it would return the news itself (or an error, of course).

To accomplish this, the "blocking task" version of the news retrieval function has to do everything that you'd do in the event loop model: send a request for the news and watch the incoming packet stream for the task results. There's no magic here. Of course, the question of what to do with those "unrelated" packets presents itself. They can't just be ignored because they may be telling the client something important like "you've just been disconnected." On the other hand, allowing them to invoke handler routines might spin us off into another section of the code indefinitely.

The solution I came up with is to let the user decide. All unrelated events that occur during blocking tasks are subject to the bare minimum processing needed to keep the internal state of the client object consistent (tracking joining and leaving users, disconnect messages, etc.). Going further, handler routines can indeed be called. The behavior is controlled by the client object's attributes.

These two modes of operation are called "event loop mode" and "blocking task mode" in the rest of the documentation. It's important to decide which model suits your particular needs before starting your Hotline client code. Blindly mixing and matching these techniques will get you nowhere fast. Now, on to the good stuff... 🫶

💅 METHODS 💅

🔌 CONNECTING 🔌

connect ADDRESS

Opens a network connection to ADDRESS, which can be an IP address or hostname optionally followed by a space or a colon and a port number. If no port is given, it defaults to 5500 (Hotline standard port).

Examples:

$hlc->connect("127.0.0.1:1234");
$hlc->connect("hostname.com 5678");

Returns 1 if successful, undef otherwise.

disconnect

Closes the network connection. Returns 1 if a connection was closed, undef if the connection wasn't open to begin with.

login PARAMETERS

Logs into a Hotline server opened via connect(), and requests the news and the userlist (unless overridden by the NoNews and NoUserList parameters). Arguments are in a "named parameter" format, and are case-sensitive. The parameters are:

• Nickname — Your nickname (default: guest)
• Login — Your account name (default: guest)
• Password — Your account password (default: <none>)
• Icon — Your icon number (default: 410, the big red "H")
• NoNews — If true, do not request the news.
• NoUserList — If true, do not request the userlist.

Example of use:

$hlc->login(Login    => "Steve",
            Password => "xyzzy",
            Nickname => "Jobs",
            Icon     => 128,
            NoNews   => 1);

If omitted, all parameters except Password will default to some sane (if not necessarily "sensible") value. The news and userlist will be requested unless NoNews and/or NoUserList are explicitly set by the user. Keep in mind that client functions like the tracking of connected users will not work properly without the userlist.

In blocking task mode, login() returns 1 on success, undef if an error occurred, and "zero but true" ("0E-0") if the login was successful, but the news and/or userlist retrieval failed.

In event loop mode, login() returns the task number if the login request was sent successfully, undef otherwise.

run

Starts the event loop. Returns when the connection to the server has been closed.

⚙️ SETTINGS ⚙️

blocking EXPR

Turns blocking network i/o on or off depending on how EXPR evaluates (true turns blocking i/o on). Returns the current setting. Blocking i/o is on by default. In this mode, the event loop will cycle each time data of any kind comes from the server. This means that your hotline client may spend a lot of its time blocked (and therefore unable to do anything interesting) waiting for something to happen on the server. Using non-blocking i/o will cycle through the event loop more frequently (see event_timing() below) regardless of server activity.

blocking_tasks EXPR

With no arguments, returns the blocking task status. With one argument, blocking tasks will be turned on or off depending on how EXPR evaluates (true means blocking task mode is active). Blocking tasks are off by default.

clear_error

Clears the error message text available via last_error(). last_error() is not cleared by the client object, so you may need to explicitly clear it before running a blocking task to prevent it from containing an old, unrelated error message if the blocking task somehow failed without setting last_error(). (This should not happen, but you never know...)

connect_timeout SECS

Sets the connection timeout to SECS seconds (if present). Returns the current connection timeout.

data_fork_extension TEXT

Sets the data fork filename extension for downloads to TEXT (if present). Returns the current data fork filename extension. The default setting is ".data".

downloads_dir PATH

Sets the directory where downloaded files are placed to PATH (if present). Returns the current setting.

event_timing SECS

Sets the event loop timing to SECS seconds (if present). Fractional seconds are allowed. The default setting is 1 second. This option only has an effect when non-blocking i/o is active (see blocking()). Returns the current event timing setting.

handlers_during_blocking_tasks EXPR

Allows handlers to run during blocking tasks if EXPR is present and evaluates to true. Returns the current setting. The default setting is off.

path_separator CHARACTER

Sets the path separator to CHARACTER (if present). The default setting is the Mac OS path separator ":". Returns the current value of the path separator. Note that this is the path separator used when sending commands to the server and has no bearing on what the path separator is on the local system. You should not need to change this, since all current Hotline servers use ":" regardless of the platform they're running on.

rsrc_fork_extension TEXT

Sets the resource fork filename extension for downloads to TEXT (if present). Returns the current resource fork filename extension. The default setting is ".rsrc".

tracker ADDR

Sets the tracker address to ADDR (if present), where ADDR is an IP address or hostname, optionally followed by a colon and a port number. Returns the current tracker address.

xfer_bufsize BYTES

Sets the file transfer buffer size to BYTES. Returns the current buffer size. The default is 4096 bytes.

🛠️ COMMANDS 🛠️

Unless otherwise specified, the methods in this section are treated as "tasks" by Hotline. Their status (start time, finish time, error state, etc.) is tracked internally by task number. In event mode, they return a task number if the request was sent successfully, and undef or an empty list if an error occurred. In blocking task mode, the return values vary.

lowkey important first, bestie: some commands (like chat() and pchat(), iykyk) are not treated as "tasks" by Hotline. They just hand you a 1 on success instead of a task number. So how do you even know they finished?? 💀 You gotta peek at the actual data coming back from the server. Like if you chat("hello"), go look for that chat line in your chat handler. (ngl this is rarely needed, because if one of these fails you've got way bigger problems. like, catastrophic vibe shift problems.)

---

ban USER

ban SOCKET

Bans the user you point at — either a Net::Hotline::User object or a raw user socket number. begone bestie 🚫✨

In blocking task mode: returns 1 on success, or undef if something went wrong. In event loop mode: returns a task number if the request made it out the door, or undef if an error happened.

chat LIST

Sends the text you get by concatenating LIST to the server as a "chat." Perl newlines ("\n") get translated into Net::Hotline::Constants::HTLC_NEWLINE, which is Hotline's native newline character. slay 🌸

Not treated as a task: returns 1 on success, undef or an empty list on failure.

chat_action LIST

Sends the concatenation of LIST to the server as a "chat action." Same deal — Perl newlines ("\n") become Net::Hotline::Constants::HTLC_NEWLINE, Hotline's native newline character. it's giving dramatic entrance 💅

Not treated as a task: returns 1 on success, undef or an empty list on failure.

comment PATH, TEXT

Sets the comments for the file or folder sitting at PATH to TEXT. If TEXT is undef or an empty string, the comments get yeeted — removed entirely. 🧹

In blocking task mode: returns 1 on success, or undef if an error occurred. In event loop mode: returns a task number if the request was sent successfully, or undef if an error occurred.

delete_file PATH

Deletes the file or folder located at located at PATH. (yes, the original says "located at located at" twice. I'm keeping it. character development. 😭)

In blocking task mode: returns 1 on success, or undef if an error occurred. In event loop mode: returns a task number if the request was sent successfully, or undef if an error occurred.

get_file PATH

Downloads the file on the server at PATH into the local directory you set with downloads_dir(). On Mac OS, file names longer than 31 characters get truncated, but it preserves the filename extension (like .jpg) if it possibly can. ✂️

In blocking task mode, returns either an array (in array context) or a reference to an array (in scalar context) containing a Net::Hotline::Task object, a download reference number, and the size of the download on success — or undef / an empty list if an error occurred. Those return values are meant to be fed straight into recv_file() like this (error handling omitted, because we're keeping it cute):

($task, $ref, $size) = $hlc->get_file("Folder1:file.sit");

$hlc->recv_file($task, $ref, $size);

In event loop mode, returns a task number if the request was sent successfully, and undef or an empty list if an error occurred.

get_file_resume PATH

Resumes downloading the file on the server at PATH into the local directory set via downloads_dir(). The partially downloaded file(s) must already exist in the local download directory, and (on non-Mac OS systems) must have filename extensions matching the current settings of data_fork_extension() and rsrc_fork_extensions(). no half-finished downloads, no skipping steps 💖

In blocking task mode, returns either an array (in array context) or a reference to an array (in scalar context) containing a Net::Hotline::Task object, a download reference number, and the size of the download on success, and undef or an empty list if an error occurred. Those return values are meant to be fed into recv_file() like this (error handling omitted):

($task, $ref, $size) = $hlc->get_file_resume("Folder1:file.sit");

$hlc->recv_file($task, $ref, $size);

In event loop mode, returns a task number if the request was sent successfully, and undef or an empty list if an error occurred.

get_fileinfo PATH

Returns a Net::Hotline::FileInfoItem object corresponding to the file specified by PATH, or undef if an error occurred. Should only be used in blocking task mode. fr fr 🫶

get_filelist PATH

Returns an array (in array context) or a reference to an array (in scalar context) of Net::Hotline::FileListItem objects corresponding to the contents of the server directory PATH, and the scalar value 0 if an error occurred. Why the 0, you ask? So you can tell the difference between an empty directory and an error — an empty directory returns an empty list in array context and undef in scalar context. Should only be used in blocking task mode.

get_news

Gets the news from the server. 📰

Returns an array containing the new posts (in array context) or the news as a string (in scalar context) on success, and undef if an error occurred. Heads up: successfully retrieving an empty news file returns an empty string ("") or an empty list. Should only be used in blocking task mode.

get_userinfo SOCKET

Returns info about the user specified by SOCKET as a string, or undef if there was an error. Will not work unless the userlist has already been retrieved from the server. Should only be used in blocking task mode.

get_userlist

Returns a reference to a hash keyed by socket number, containing Net::Hotline::User objects for every user currently logged on. Should only be used in blocking task mode. the whole roster, bestie 👑

icon ICON

Sets your icon in the userlist to ICON, where ICON is an icon ID number. glow-up time ✨

kick USER

kick SOCKET

Disconnects the user specified by a Net::Hotline::User object or a user socket number. bye bestie 👋💀

In blocking task mode: returns 1 on success, or undef if an error occurred. In event loop mode: returns a task number if the request was sent successfully, or undef if an error occurred.

macbinary MACBIN_FILE, DATA_FILE, DATA_LEN, RSRC_FILE, RSRC_LEN

BUF_SIZE, TYPE, CREATOR, COMMENTS, CREATED, MODIFIED, FINDER_FLAGS

Creates a MacBinary II file at the path designated by MACBIN_FILE, based on the file paths and other info you hand over as arguments (see the recv_file() method for a description of the other arguments).

If MACBIN_FILE is undefined, it defaults to DATA_FILE with .bin tacked onto the end.

It returns 1 on success, and undef if:

• MACBIN_FILE already exists or can't be created,
• DATA_LEN is greater than zero and DATA_FILE can't be opened, or
• RSRC_LEN is greater than zero and RSRC_FILE can't be opened.

The error condition is available via both last_error() and $! — because macbinary() can be called as a method or as a function. pick your fighter 😤

Example:

# As a method
unless($hlc->macbinary(@args))
{
  die "macbinary: ", $hlc->last_error();
}

# As a function
unless(macbinary(@args))
{
  die "macbinary: $!";
}

move SRC, DEST

Moves the file or folder at the path SRC to the directory at the path DEST. SRC should be the full path to the file or folder you wanna move, and DEST should be the full path to the directory you wanna move SRC into.

The file or folder name should only ever appear in the SRC path, never in the DEST path. As a consequence, renaming files or folders has to go through rename() and cannot be rolled into a move() call. no multitasking here, bestie 🙈

Here's an example of a valid call to move():

$hlc->move("Folder1:file1", "Folder2:");

This moves the "file1" from "Folder1" to "Folder2".

In blocking task mode: returns 1 on success, or undef if an error occurred. In event loop mode: returns a task number if the request was sent successfully, or undef if an error occurred.

msg USER, LIST

msg SOCKET, LIST

Sends the text formed by concatenating LIST as a private message to the user specified by a Net::Hotline::User object or a user socket number. sliding into DMs, Unix edition 💌

In blocking task mode: returns 1 on success, or undef if an error occurred. In event loop mode: returns a task number if the request was sent successfully, or undef if an error occurred.

new_folder PATH

Creates a new folder located at PATH. fresh folder, fresh start 🎀

In blocking task mode: returns 1 on success, or undef if an error occurred. In event loop mode: returns a task number if the request was sent successfully, or undef if an error occurred.

nick TEXT

Sets your nickname in the userlist to TEXT. main character naming ceremony 💅⭐

pchat REF, LIST

Sends the text formed by concatenating LIST to the private chat window specified by REF. Perl newlines ("\n") get translated to Net::Hotline::Constants::HTLC_NEWLINE, Hotline's native newline character.

Not treated as a task: returns 1 on success, undef or an empty list on failure.

pchat_action REF, LIST

Sends the text formed by concatenating LIST to the private chat window specified by REF as a "chat action". Perl newlines ("\n") get translated to Net::Hotline::Constants::HTLC_NEWLINE, which is Hotline's native newline character.

Not treated as a task: returns 1 on success, undef or an empty list on failure.

pchat_accept REF

Accepts an invitaton to the private chat specified by REF. (yes, "invitaton." typo preserved. iconic behavior. 😌)

In blocking task mode, returns 1 on success. In event loop mode, returns a task number if the request was sent successfully. In both modes, it returns undef or an empty list if an error occurred.

pchat_decline REF

Declines an invitaton to the private chat specified by REF. politely. with grace. 🚫🎀

Not treated as a task: returns 1 on success, undef or an empty list on failure.

pchat_invite SOCKET, REF

Invites the user specified by SOCKET to an existing private chat specified by REF, or creates a new private chat if REF isn't given.

Plot twist: there is no pchat_create() command. To create a new private chat, you have to invite someone. Call pchat_invite() with your own socket number and no REF argument to create a new private chat with only yourself in it (and dw, you will not have to explicitly accept this invitation). solo hangout unlocked 🧚

In blocking task mode, returns 1 on success, and undef or an empty list if an error occurred.

In event mode, it returns a task number if it had to create a new private chat (i.e. if no REF argument was given) or 1 (if inviting to an existing private chat) on success, and undef or an empty list if an error occurred.

pchat_leave REF

Leaves the private chat specified by REF. it's not goodbye, it's see you never 🌈

Not treated as a task, bestie: it hands you back 1 when it works, and undef or an empty list when it doesn't. 💀

---

• pchat_subject REF, TEXT — sets the subject of the private chat that REF points at, and it's now called TEXT. That's it, that's the whole job.

Also not treated as a task: 1 on success, undef or an empty list on failure. ✨

• post_news LIST — glues everything in LIST together into one blob of text and yeets it to the server as a news post. 📰

In blocking task mode it gives you 1 on success. In event loop mode it gives you a task number if the request went out okay. And in both modes, undef or an empty list means something went wrong. 😭

• put_file SRC_PATH, DEST_PATH, COMMENT — uploads the file sitting at SRC_PATH into the server directory DEST_PATH, and attaches COMMENT as the file comments. 💅

SRC_PATH has to be in the native path format of your local system — so : is the path separator on Mac OS, and / is the separator pretty much everywhere else. DEST_PATH has to be in Hotline's native path format, which is : as the path separator. If you leave COMMENT out, and you're on Mac OS, the actual Finder comments get read off the file you're uploading. Otherwise the comments just come out blank.

Heads up: put_file() is for uploading a new file. If you're resuming an upload, you gotta call send_file_resume() instead, no cap.

In blocking task mode it returns an array (in array context) or a reference to an array (in scalar context) holding a Net::Hotline::Task object, an upload reference number, and the size of the upload — and undef or an empty list if there was an error. Those return values are literally designed to be fed straight into send_file() like this (error handling omitted, obviously):

($task, $ref, $size) = $hlc->put_file("/home/john/file.gz",
                                      "Folder1:Folder2"
                                      "A fun file!");

$hlc->send_file($task, $ref, $size);

In event loop mode, you get a task number if the request was sent successfully, and undef or an empty list if it wasn't. 🦋

• put_file_resume SRC_PATH, DEST_PATH, COMMENT — resumes uploading the file at SRC_PATH into the server directory DEST_PATH, with COMMENT as the file comments. 🎀

Same path rules as before, bestie: SRC_PATH must be in your local system's native path format (: as the separator on Mac OS, / on most other OSes), and DEST_PATH must be in Hotline's native format (: as the separator). If COMMENT is omitted and you're on Mac OS, the actual Finder comments get read from the file. Otherwise the comments are blank. And remember — use put_file() to upload a new file. This one is for the resume.

In blocking task mode it returns an array (array context) or a reference to an array (scalar context) containing a Net::Hotline::Task object, an upload reference number, the size of the upload, and the extra info needed to resume the upload — or undef / empty list if something broke. Those values go straight into send_file() like so (error handling omitted):

($task, $ref, $size, $rflt) =
  $hlc->put_file_resume("/home/john/file.gz",
                        "Folder1:Folder2"
                        "A fun file!");

$hlc->send_file($task, $ref, $size, $rflt);

In event loop mode: task number if it sent fine, undef or an empty list if not. 🌸

• recv_file TASK, REF, SIZE — kicks off receiving the file named by the Net::Hotline::Task object TASK, the download reference number REF, and the size in bytes SIZE — all of which come back from get_file() in blocking task mode, or get handed to your get_file() handler routine in event loop mode. 📥

When the download finishes, recv_file() returns a reference to an array with these values inside:

• DATA_FILE — path to the file holding the data fork.
• DATA_LEN — length of the data fork.
• RSRC_FILE — path to the file holding the Mac resource fork.
• RSRC_LEN — length of the resource fork.
• BUFSIZE — the buffer size that was used during the download.
• TYPE — four-letter Mac file type code.
• CREATOR — four-letter Mac file creator code.
• COMMENTS — Mac Finder comments.
• CREATED — date created (in Mac time format)
• MODIFIED — date modified (in Mac time format)
• FINDER_FLAGS — Mac finder flags packed in two bytes.

Those usually get fed into the macbinary() method to smoosh the separate resource fork and data fork files into one single MacBinary II file. (On Mac OS systems a single Mac OS-native two-forked file is created instead, so there's no need to call macbinary() at all. iconic behavior honestly. 💖)

Here's a typical usage example (error checking omitted):

# Event loop mode:
# (Inside your get_file() handler subroutine)
...
$ret = $hlc->recv_file($task, $ref, $size);
$hlc->macbinary(undef, $ret);
...

or

# Blocking task mode:
...
($task, $ref, $size) = $hlc->get_file($path);
$ret = $hlc->recv_file($task, $ref, $size);
$hlc->macbinary(undef, $ret)
...

Peep macbinary() for the full deets on how to use it. And if either the data fork or the resource fork is empty, the fork length that recv_file() gives you back will be zero, and the file path it returns will be undef. 🫶

• rename PATH, NAME — renames the file or folder living at PATH to NAME. Important vibe check: PATH is the full path to the target, but NAME is just the new name, no path spec whatsoever. Example:

$hlc->rename("Pets:cat", "dog");

That changes the name of the file cat inside the folder Pets to dog. 🐶

In blocking task mode it returns 1 on success or undef if an error happened. In event loop mode it returns a task number if the request went out successfully, or undef if it didn't.

• send_file TASK, REF, SIZE, RFLT — starts sending the file named by the Net::Hotline::Task object TASK, the upload reference number REF, the size in bytes SIZE, and the resume information RFLT — all returned by put_file() in blocking task mode, or supplied to your put_file() handler routine in event loop mode. Returns 1 if the upload completed successfully, or undef if there was an error. 🚀
• tracker_list TIMEOUT — connects to whatever server you set with the tracker() method and pulls the list of servers that tracker is tracking. On success you get an array (array context) or a reference to an array (scalar context) of Net::Hotline::TrackerListItem objects; on failure you get undef or an empty list, with the error condition available through last_error(). 🔍

The initial connection to the tracker times out after TIMEOUT seconds — or after whatever you last set with connection_timeout() if you leave TIMEOUT out. A TIMEOUT value of zero disables the timeout entirely.

⚠️ Real talk: this method does not return until it has retrieved the list of tracked servers, and that timeout only applies to the initial connection to the tracker. Overloaded trackers love to make this method hang while it's writing to or reading from the tracker (no matter what your timeout value is), which many times ends in a die with a broken pipe error inside one of the network I/O functions. To dodge that, either try a more responsive tracker and/or wrap your tracker_list() call in an eval block and check $@. 💀

📨 REQUESTS 📨

Every single method in this section is treated as a "task" by Hotline. Their status — start time, finish time, error state, all of it — gets tracked internally by task number. They return a task number if the request was sent successfully, and undef otherwise.

When a task completes, the data lands in the appropriate Net::Hotline::Client attribute. For example, when a req_news() task completes, the data is available via the news() method. ✨

• req_filelist PATH — requests the file listing for the folder given by PATH, or the root directory if you leave PATH out. 📁
• req_fileinfo PATH — requests the file information for the file or folder given by PATH. 🔎
• req_news — requests the news from the server. 📰
• req_userinfo SOCKET — requests user information for the user specified by SOCKET. 👤
• req_userlist — requests the list of users currently logged on. 👑 (Group chat roster energy fr fr.)

🌟 ATTRIBUTES 🌟

The methods in this section return data, or references to data structures, sitting inside the Net::Hotline::Client object. Some of those data structures contain references to objects, and for details on those objects you should peep their respective documentation (i.e. perldoc Net::Hotline::User). 🦋

• agreement — returns a reference to the server's user agreement text, or undef if there isn't one. 📜
• connected — returns true if a network connection to a server is open. 💚
• files — returns a reference to a hash of arrays containing Net::Hotline::FileListItem objects, keyed by directory path. Here's some sample code that prints out the entire file tree:

$files = $hlc->files();              # Get reference to the file tree

foreach $directory (keys(%{$files}))
{
  print "$directory\n";              # Ex: "Uploads:Pictures"

  foreach $file (@{$files->{$directory}})
  {
    print "\t", $file->name(), "\n"; # Ex: "Picture.jpg"
  }
}

• last_activity — returns the time the last packet was received from the server, in the system's native time() format. (Usually that's seconds since the Unix epoch. MacPerl is probably the only odd-ball here. 🙈)
• last_error — returns a text error message spelling out the last error that occurred. Use this method to figure out why something failed when a blocking task returns undef. Example:

...
$hlc->blocking_tasks(1);
...
$hlc->get_filelist("Folder1") || die $hlc->last_error();

🚨 Do not lean on last_error() unless you're in blocking task mode. In event loop mode, set a handler routine via task_error_handler() and deal with errors right there using the task object's error() and error_text() methods.

• logged_in — returns true if you're currently logged into a server. 🔓
• news — returns a reference to an array of news posts, or undef if the news hasn't been requested yet or is empty. 📭
• pchats — hands u a reference to a hash of Net::Hotline::PrivateChat objects, keyed by reference number, covering every private chat ur currently in 💬. If ur not in any private chats at all, u get undef or an empty list. bestie u are simply not in the group chats rn.
• server — gives u back the address of the server ur currently connected to, as a hostname or an IP address, depending on what the actual argument to connect() was 🛰️. If the port u connected to is anything other than the standard Hotline port (5500), then a colon and the port number get tacked onto the end of the server name, like a little accessory ✨. If ur not connected at all? undef. ghosted.
• userlist — returns a reference to a hash of Net::Hotline::User objects keyed by socket number 🔢, or undef if the userlist has not yet been received. patience, queen.
• user_by_nick REGEX — returns reference(s) to user objects whose nicknames match REGEX 👀, and undef or an empty list if there are no matches. Also returns undef or an empty list if u call it before the userlist has been retrieved from the server. Internally REGEX is treated as a case-sensitive anchored regular expression, i.e. /^REGEX$/ — no sneaking in from the sides, it's giving full-match energy. If ur regex matches more than one user's nickname, and user_by_nick() was called in array context, u get an array of references to user objects back. Otherwise, the first user object that matched is returned (as ordered by socket number, from low to high). no cap.
• user_by_socket SOCKET — returns the user object whose socket number is equal to SOCKET, or undef if there is no user at that socket 🫥.

---

✨ HANDLERS ✨

The methods in this section deal with getting and setting the handler routines for events and tasks 🎛️. If u do not set ur own handler for an event, the default handler (usually just a print to STDOUT) will be used. U can enable and disable the default handlers with the default_handlers() method. They are disabled by default, iykyk.

• default_handlers EXPR — if EXPR is omitted, it returns the default handler setting. Otherwise, it sets the default handler setting to EXPR (anything that evaluates to true is considered "on") 💡. Default handlers are disabled by default.
• handlers — returns a reference to a hash, keyed by event type strings (the strings in CAPS below) 🗂️. The values associated with the keys are either code references or undef. Event types are as follows:

Events:

AGREEMENT      User agreement text received.
CHAT           New chat appeared.
CHAT_ACTION    A new chat "action" appeared.
COLOR          A user changed color in the userlist.
EVENT          Next cycle in the event loop.
ICON           A user changed icon in the userlist.
JOIN           A user joined the server.
LEAVE          A user left the server.
MSG            A private message arrived.
NEWS           News received.
NEWS_POSTED    A news post was made by another user.
NICK           A user changed nickname in the userlist.
PCHAT_CHAT     New private chat appeared.
PCHAT_ACTION   A new private chat action appeared.
PCHAT_INVITE   An invitation to private chat arrived.
PCHAT_JOIN     A user joined a private chat.
PCHAT_LEAVE    A user left a private chat.
PCHAT_SUBJECT  Private chat subject changed.
QUIT           The server was shutdown politely.
SERVER_MSG     A server message arrived.

Tasks:

BAN            Ban user task completed.
FILE_DELETE    A file or folder was deleted.
FILE_GET       A file download is ready to begin.
FILE_PUT       A file upload is ready to begin.
FILE_GET_INFO  File information received.
FILE_SET_INFO  File information set.
FILE_LIST      File list received.
FILE_MKDIR     New folder created.
FILE_MOVE      A file or folder was moved.
KICK           Disconnect user task completed.
LOGIN          Login task completed.
NEWS_POST      News post task completed.
PCHAT_ACCEPT   You have joined a private chat.
PCHAT_CREATE   New private chat created.
SEND_MSG       Private message sent.
TASK_ERROR     A task error ocurred.
USER_GETINFO   User information received.
USER_LIST      User list received.

---

💖 SET/GET HANDLERS 💖

The methods in this section expect either one code reference argument, or no arguments at all 🫶. With one argument, the handler is set to the given code reference. The return value is always the current value of the handler (should be either undef or a code reference). very "u get what's there, no surprises" of it.

The code reference should point to a subroutine that expects at least one argument: the Net::Hotline::Client object itself (listed as SELF below). Other arguments vary according to the event being handled 👾. In this section, only the varying arguments to the handler subroutine are described.

Also note that u don't have to do the "obvious" tasks associated with each handler 🙈. For example, in the leave handler, u don't have to remove the user from the userlist. That will be done for u by the Net::Hotline::Client object. she's got it handled, bestie.

---

🌸 EVENTS 🌸

• agreement_handler CODE (SELF, TEXT) — user agreement text received.
  • TEXT — reference to the agreement text.
• chat_handler CODE (SELF, TEXT) — new chat appeared.
  • TEXT — reference to the chat text.
• chat_action_handler CODE (SELF, TEXT) — a new chat "action" appeared.
  • TEXT — reference to the chat action text.
• color_handler CODE (SELF, USER, OLD_COLOR, NEW_COLOR) — a user changed color in the userlist.
  • USER — a Net::Hotline::User object.
  • OLD_COLOR — the user's previous color.
  • NEW_COLOR — the user's new color.

Valid colors:

1    Black  Active normal user.
2    Red    Active admin user.
3    Gray   Inactive normal user.
4    Pink   Inactive admin user.

The hash %Net::Hotline::Constants::HTLC_COLORS contains color number-to-name mappings 🎨.

• event_loop_handler CODE (SELF, IDLE) — next cycle in the event loop. Idle events only occur when non-blocking i/o is active 🔄.
  • IDLE — true if the event is an idle event.
• icon_handler CODE (SELF, USER, OLD_ICON, NEW_ICON) — a user changed icon in the userlist.
  • USER — a Net::Hotline::User object.
  • OLD_ICON — the user's previous icon number.
  • NEW_ICON — the user's new icon number.
• join_handler CODE (SELF, USER) — a user joined the server 🫂.
  • USER — a Net::Hotline::User object.
• leave_handler CODE (SELF, USER) — a user left the server 👋.
  • USER — a Net::Hotline::User object.
• msg_handler CODE (SELF, USER, TEXT, REPLY-TO) — a private message arrived 💌.
  • USER — reference to the sender's Net::Hotline::User object.
  • TEXT — reference to the message text.
  • REPLY-TO — reference to the text to which this is a reply (if any)
• news_posted_handler CODE (SELF, TEXT) — a news post was made by another user 📰.
  • TEXT — reference to the news post text.
• nick_handler CODE (SELF, USER, OLD_NICK, NEW_NICK) — a user changed nickname in the userlist.
  • USER — a Net::Hotline::User object.
  • OLD_NICK — the user's previous nickname.
  • NEW_NICK — the user's new nickname.
• pchat_action_handler (SELF, REF, TEXT) — a new private chat action appeared.
  • REF — private chat reference number.
  • TEXT — reference to the chat action text.
• pchat_chat_handler (SELF, REF, TEXT) — new private chat appeared.
  • REF — private chat reference number.
  • TEXT — reference to the chat text.
• pchat_invite_handler (SELF, REF, SOCKET, NICK) — an invitation to private chat arrived 💌.
  • REF — private chat reference number.
  • SOCKET — socket number of the inviting user.
  • NICK — nick of the inviting user.
• pchat_join_handler (SELF, PCHAT, SOCKET) — a user joined a private chat.
  • PCHAT — a Net::Hotline::PrivateChat object.
  • SOCKET — socket number of the joining user.
• pchat_leave_handler (SELF, PCHAT, SOCKET) — a user left a private chat.
  • PCHAT — a Net::Hotline::PrivateChat object.
  • SOCKET — socket number of the leaving user.

Note that the user who left will no longer be in the private chat object's userlist. they're gone gone 💀

• pchat_subject_handler (SELF, REF, TEXT) — private chat subject changed.
  • REF — private chat reference number.
  • TEXT — reference to the subject text.
• quit_handler CODE (SELF, TEXT) — the server was shutdown politely 🕊️.
  • TEXT — reference to shutdown message text.
• server_msg_handler CODE (SELF, TEXT) — a server message arrived.
  • TEXT — reference to the message text.

---

🎀 TASKS 🎀

• ban_handler CODE (SELF, TASK) — ban user task completed 🔨.
  • TASK — a Net::Hotline::Task object.
• delete_file_handler CODE (SELF, TASK) — a file or folder was deleted.
  • TASK — a Net::Hotline::Task object.
• file_info_handler CODE (SELF, TASK, INFO) — file information received.
  • TASK — a Net::Hotline::Task object.
  • INFO — a Net::Hotline::FileInfoItem object.
• file_list_handler CODE (SELF, TASK) — file list received.
  • TASK — a Net::Hotline::Task object.
• get_file_handler CODE (SELF, TASK, REF, SIZE) — a file download is ready to begin 📥.
  • TASK — a Net::Hotline::Task object.
  • REF — download reference number.
  • SIZE — size of download in bytes.

If u do not set a handler for get_file(), a default handler will be used regardless of ur default_handlers() setting. The default handler simply does:

SELF->recv_file(TASK, REF, SIZE);

which initiates the file download and does not return until the download has completed ⏳. If u want to download in the background, call fork() (or something similar) in ur handler routine. multitasking queen behavior.

• kick_handler CODE (SELF, TASK) — disconnect user task completed.
  • TASK — a Net::Hotline::Task object.
• login_handler CODE (SELF, TASK) — login task completed.
  • TASK — a Net::Hotline::Task object.
• move_file CODE (SELF, TASK) — a file or folder was moved.
  • TASK — a Net::Hotline::Task object.
• new_folder CODE (SELF, TASK) — new folder created 📁.
  • TASK — a Net::Hotline::Task object.
• TASK — A Net::Hotline::Task object.
• news_handler CODE (SELF, TASK) — The news has arrived and is now available via the news() method. 📬✨
  • TASK — A Net::Hotline::Task object.
• pchat_accept_handler (SELF, TASK, PCHAT) — You have joined a private chat. 💬
  • TASK — A Net::Hotline::Task object.
  • PCHAT — A Net::Hotline::PrivateChat object.
• pchat_create (SELF, TASK, PCHAT) — New private chat created. 🎉
  • TASK — A Net::Hotline::Task object.
  • PCHAT — A Net::Hotline::PrivateChat object.

Note that you do not have to save the private chat object yourself. The client object keeps track of all private chats it is currently engaged in (the list is accessible via the pchats() method), updates the userlists as users join and leave, and deletes the objects when you leave the private chat. 🫶

• post_news_handler CODE (SELF, TASK) — News post task completed. ✅
  • TASK — A Net::Hotline::Task object.
• put_file_handler CODE (SELF, TASK, REF, SIZE, RFLT) — A file upload is ready to begin. 📤
  • TASK — A Net::Hotline::Task object.
  • REF — Download reference number.
  • SIZE — Size of the upload in bytes.
  • RFLT — Data needed to resume an upload.

If you do not set a handler for put_file(), a default handler will be used regardless of your default_handlers() setting. The default handler simply does:

SELF->send_file(TASK, REF, SIZE, RFLT);

which initiates the file upload and does not return until the upload has completed. If you want to upload in the background, call fork() (or something similar) in your handler routine. 🔥

• send_msg_handler CODE (SELF, TASK) — Private message sent. ✉️
  • TASK — A Net::Hotline::Task object.
• set_file_info_handler CODE (SELF, TASK) — File information set (this includes both renaming and setting file comments). 📝
  • TASK — A Net::Hotline::Task object.
• task_error_handler CODE (SELF, TASK) — A task error ocurred. 💀
  • TASK — A Net::Hotline::Task object.
• user_info_handler CODE (SELF, TASK) — User information received. 👤
  • TASK — A Net::Hotline::Task object.
• user_list_handler CODE (SELF, TASK) — User list received. 📋
  • TASK — A Net::Hotline::Task object.

🎀 MISCELLANEOUS 🎀

• debug EXPR — If EXPR is omitted, returns the debugging status (off by default), otherwise sets debugging status to EXPR (true means debugging is on). 🐛
• version — Returns the Net::Hotline::Client version string. 🌟

💅 TO DO 💅

• User administration.

😭 BUGS 😭

Please send bug reports to siracusa@mindspring.com.

👑 AUTHOR 👑

John C. Siracusa (siracusa@mindspring.com)

🌈 COPYRIGHT 🌈

Copyright(c) 1999 by John C. Siracusa. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

---

That's the whole vibe, bestie. This page is from perl v5.32.0, dated 2021-01-09, and it's the Net::H...Client(3pm) manpage. Go slay. 💖✨