| Net::Hotline::Client(3pm) | User Contributed Perl Documentation | Net::Hotline::Client(3pm) |
Net::Hotline::Client - Perl library for the Hotline internet client
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();
...
Net::Hotline::Client is a class implementing 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)
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.
Before delving into the nitty-gritty details, 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.
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...
Examples:
$hlc->connect("127.0.0.1:1234");
$hlc->connect("hostname.com 5678");
Returns 1 if successful, undef otherwise.
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.
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.
Some commands (like "chat()" and "pchat()", for example) are not treated as "tasks" by Hotline. They always return 1 on success, rather than a task number. The actual completion of a such commands can only be determined by examining the resulting data from the server. For example, if you "chat("hello")", you can look for that line of chat in your chat handler. (This is rarely necessary since the failure of such a command usually means that you have much bigger problems.)
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.
Not treated as a task: returns 1 on success, undef or an empty list on failure.
Not treated as a task: returns 1 on success, undef or an empty list on failure.
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.
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.
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, an undef or an empty list if an error occurred. Those return values are meant to be fed to "recv_file()" like this (error handling omitted):
($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.
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 to "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.
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. Note that successful retrieval of an empty news file will return an empty string ("") or an empty list. Should only be used in blocking task mode.
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.
# As a method
unless($hlc->macbinary(@args))
{
die "macbinary: ", $hlc->last_error();
}
# As a function
unless(macbinary(@args))
{
die "macbinary: $!";
}
$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.
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.
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.
Not treated as a task: returns 1 on success, undef or an empty list on failure.
Not treated as a task: returns 1 on success, undef or an empty list on failure.
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.
Not treated as a task: returns 1 on success, undef or an empty list on failure.
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.
Not treated as a task: returns 1 on success, undef or an empty list on failure.
Not treated as a task: returns 1 on success, undef or an empty list on failure.
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.
In blocking task mode, returns an array (in array context) or a reference to an array (in scalar context) containing a Net::Hotline::Task object, an upload reference number, and the size of the upload, and undef or an empty list if an error occurred. Those return values are meant to be fed to "send_file()" like this (error handling omitted):
($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, returns a task number if the request was sent successfully, and undef or an empty list if an error occurred.
In blocking task mode, returns an array (in array context) or a reference to an array (in scalar context) containing a Net::Hotline::Task object, an upload reference number, the size of the upload, and additional information needed to resume the upload, and undef or an empty list if an error occurred. Those return values are meant to be fed to "send_file()" like this (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, returns a task number if the request was sent successfully, and undef or an empty list if an error occurred.
DATA_FILE Path to the file containing the data fork.
DATA_LEN Length of the data fork.
RSRC_FILE Path to the file containing the Mac resource fork.
RSRC_LEN Length of the resource fork.
BUFSIZE 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.
which are typically fed to the "macbinary()" method to create a single MacBinary II file from the separate resource fork and data fork files. (On Mac OS systems, a single Mac OS-native two-forked file is created, so there's no need to call "macbinary()") Here's an example of typical usage (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)
...
See "macbinary()" for more details on its usage. If either the data fork or resource fork is empty, the fork length returned by "recv_file()" will be zero and the file path returned will be undef.
$hlc->rename("Pets:cat", "dog");
This changes the name of the file "cat" in the folder "Pets" to "dog"
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.
The initial connection to the tracker will timeout after TIMEOUT seconds, or the current value set via "connection_timeout()" if TIMEOUT is omitted. A TIMEOUT value of zero will disable the timeout.
Note that this method does not return until it has retrieved the list of tracked servers, and that the timeout applies only to the initial connection to the tracker. It is often the case with overloaded trackers that this method will hang when writing to or reading from the tracker (regardless of the timeout value), many times resulting in a "die" with a broken pipe error in one of the network I/O functions. To avoid this, either try a more responsive tracker and/or wrap your "tracker_list()" call in an "eval" block and check $@.
All 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. They return a task number if the request was sent successfully, undef otherwise.
When a tasks completes, the data is stored in the appropriate Net::Hotline::Client attribute. For example, when a "req_news()" task completes, the data is available via the news() method.
The methods in this section return data or references to data structures in the Net::Hotline::Client object. Some data structures contain references to objects. For details on those objects, see their respective documentation (i.e. perldoc Net::Hotline::User)
$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"
}
}
...
$hlc->blocking_tasks(1);
...
$hlc->get_filelist("Folder1") || die $hlc->last_error();
Don't rely 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 there via the task object's "error()" and "error_text()" methods.
The methods in this section deal with getting and setting the handler routines for events and tasks. If you do not set your own handler for an event, the default handler (usually just a print to STDOUT) will be used. You can enable and disable the default handlers with the "default_handlers()" method. They are disabled by default.
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.
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).
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 you don't have to do the "obvious" tasks associated with each handler. For example, in the "leave" handler, you don't have to remove the user from the userlist. That will be done for you by the Net::Hotline::Client object.
EVENTS
TEXT Reference to the agreement text.
TEXT Reference to the chat text.
TEXT Reference to the chat action text.
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.
IDLE True if the event is an idle event.
USER A Net::Hotline::User object.
OLD_ICON The user's previous icon number.
NEW_ICON The user's new icon number.
USER A Net::Hotline::User object.
USER A Net::Hotline::User object.
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)
TEXT Reference to the news post text.
USER A Net::Hotline::User object.
OLD_NICK The user's previous nickname.
NEW_NICK The user's new nickname.
REF Private chat reference number.
TEXT Reference to the chat action text.
REF Private chat reference number.
TEXT Reference to the chat text.
REF Private chat reference number.
SOCKET Socket number of the inviting user.
NICK Nick of the inviting user.
PCHAT A Net::Hotline::PrivateChat object.
SOCKET Socket number of the joining user.
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.
REF Private chat reference number.
TEXT Reference to the subject text.
TEXT Reference to shutdown message text.
TEXT Reference to the message text.
TASKS
TASK A Net::Hotline::Task object.
TASK A Net::Hotline::Task object.
TASK A Net::Hotline::Task object.
INFO A Net::Hotline::FileInfoItem object.
TASK A Net::Hotline::Task object.
TASK A Net::Hotline::Task object.
REF Download reference number.
SIZE Size of download in bytes.
If you do not set a handler for "get_file()", a default handler will be used regardless of your "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 you want to download in the background, call "fork()" (or something similar) in your handler routine.
TASK A Net::Hotline::Task object.
TASK A Net::Hotline::Task object.
TASK A Net::Hotline::Task object.
TASK A Net::Hotline::Task object.
TASK A Net::Hotline::Task object.
TASK A Net::Hotline::Task object.
PCHAT A Net::Hotline::PrivateChat object.
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.
TASK A Net::Hotline::Task object.
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.
TASK A Net::Hotline::Task object.
TASK A Net::Hotline::Task object.
TASK A Net::Hotline::Task object.
TASK A Net::Hotline::Task object.
TASK A Net::Hotline::Task object.
Please send bug reports to siracusa@mindspring.com.
John C. Siracusa (siracusa@mindspring.com)
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.
| 2021-01-09 | perl v5.32.0 |