NAME
Net::CyanChat - Perl interface for connecting to Cyan Worlds' chat room.
SYNOPSIS
use Net::CyanChat;
my $cyan = new Net::CyanChat (
host => 'cho.cyan.com', # default
port => 1812, # main port--1813 is for testing
proto => 1, # use protocol 1.0
refresh => 60, # ping rate (default)
);
# Set up handlers.
$cyan->setHandler (foo => \&bar);
# Connect
$cyan->start();DESCRIPTION
Net::CyanChat is a Perl module for object-oriented connections to Cyan Worlds, Inc.'s chat room.
NOTE TO DEVELOPERS
Cyan Chat regulars really HATE bots! Recommended usage of this module is for developing your own client, or a silent logging bot. Auto-Shorah (greeting users who enter the room) is strongly advised against.
METHODS
new (ARGUMENTS)
Constructor for a new CyanChat object. Pass in any arguments you need. Some standard arguments are: host (defaults to cho.cyan.com), port (defaults to 1812), proto (protocol version--0 or 1--defaults to 1), debug, or refresh.
Returns a CyanChat object.
version
Returns the version number.
debug (MESSAGE)
Called by the module itself for debug messages.
send (DATA)
Send raw data to the CyanChat server.
setHandler (EVENT_CODE => CODEREF)
Set up a handler for the CyanChat connection. See below for a list of handlers.
connect
Connect to CyanChat's server.
start
Start a loop of do_one_loop's.
do_one_loop
Perform a single loop on the server.
login (NICK)
After receiving a "Connected" event from the server, it is okay to log in now. NICK should be no more than 20 characters and cannot contain a pipe symbol "|".
This method can be called even after you have logged in once, for example if you want to change your nickname without logging out and then back in.
logout
Log out of CyanChat. Must be logged in first.
sendMessage (MESSAGE)
Broadcast a message publicly to the chat room. Can only be called after you have logged in through $cyan->login.
sendPrivate (TO, MESSAGE)
Send a private message to recipient TO. Must be logged in first.
getBuddies
Returns a hashref containing each buddy's username as the keys and their addresses as the values.
getFullName (NICK)
Returns the full name of passed in NICK. If NICK is not in the room, returns 0. FullName is the name that CyanChat recognizes NICK by (including their auth code, i.e. "0username" for normal users and "1username" for Cyan staff).
getAddress (NICK)
Returns the address to NICK. This is not their IP address; CyanChat encrypts their IP into this address, and it is basicly a unique identifier for a connection. Multiple users logged on from the same IP address will have the same chat address. Ignoring users will ignore them by address.
protocol
Returns the protocol version you are using. Will return 0 or 1.
ignore (USER), unignore (USER)
Ignore and unignore a username. When a user is ignored, the Message and Private events will not be called when they send a message.
nick
Returns the currently signed in nickname of the CyanChat object.
HANDLERS
Connected (CYANCHAT)
Called when a connection has been established, and the server recognizes your client's presence. At this point, you can call CYANCHAT->login (NICK) to log into the chat room.
Disconnected (CYANCHAT)
Called when a disconnect has been detected.
Welcome (CYANCHAT, MESSAGE)
Called after the server recognizes your client (almost simultaneously to Connected). MESSAGE are messages that the CyanChat server sends--mostly just includes a list of the chat room's rules.
Message (CYANCHAT, NICK, LEVEL, ADDRESS, MESSAGE)
Called when a user sends a message publicly in chat. NICK is their nickname, LEVEL is their auth level (0 = normal, 1 = Cyan employee, etc. - see below for full list). ADDRESS is their chat address, and MESSAGE is their message.
Private (CYANCHAT, NICK, LEVEL, ADDRESS, MESSAGE)
Called when a user sends a private message to your client. All the arguments are the same as the Message handler.
Ignored (CYANCHAT, IGNORE, NICK)
Called when a user has been ignored or unignored. IGNORE will be 1 (ignoring) or 0 (unignoring). NICK is their nickname.
Chat_Buddy_In (CYANCHAT, NICK, LEVEL, ADDRESS, MESSAGE)
Called when a buddy enters the chat room. NICK, LEVEL, and ADDRESS are the same as in the Message and Private handlers. MESSAGE is their join message (i.e. "<links in from comcast.net age>")
Chat_Buddy_Out (CYANCHAT, NICK, LEVEL, ADDRESS, MESSAGE)
Called when a buddy exits. MESSAGE is their exit message (i.e. "<links safely back to their home Age>" for normal log out, or "<mistakenly used an unsafe Linking Book without a maintainer's suit>" for disconnected).
Chat_Buddy_Here (CYANCHAT, NICK, LEVEL, ADDRESS)
Called for each member currently in the room. Each time the Who List updates, this handler is called for each buddy in the room.
Name_Accepted (CYANCHAT)
The CyanChat server has accepted your name.
Error (CYANCHAT, CODE, STRING)
Handles errors issued by CyanChat. CODE is the exact server code issued that caused the error. STRING is either an English description or the exact text the server sent.
CYAN CHAT RULES
The CyanChat server strictly enforces these rules:
Be respectful and sensitive to others (please, no platform wars).
Keep it "G" rated (family viewing), both in language and content.
And HAVE FUN!
Termination of use can happen without warning!CYAN CHAT AUTH LEVELS
Auth levels (received as LEVEL to most handlers, or prefixed onto a user's FullName) are as follows:
0 is for regular chat user (should be in white)
1 is for Cyan Worlds employee (should be in cyan)
2 is for CyanChat Server message (should be in green)
4 is for special guest (should be in gold)
Any other number is probably a client error message (and is in red)CHANGE LOG
Version 0.04 - The enter/exit chat messages now go by the tag number (like it's supposed to), not by the contained text. - Messages can contain pipes in them and be read okay through the module. - Added a "ping" function. Apparently Cho will disconnect clients who don't do anything in 5 minutes. The "ping" function also helps detect disconnects! - The Disconnected handler has been added to detect disconnects.
Version 0.03 - Bug fix: the $level received to most handlers used to be 1 (cyan staff) even though it should've been 0 (or any other number), so this has been fixed.
Version 0.01
- Initial release.
- Fully supports both protocols 0 and 1 of CyanChat.SEE ALSO
Net::CyanChat::Server
CyanChat Protocol Documentation: http://cho.cyan.com/chat/programmers.html
AUTHOR
Cerone J. Kirsle <cjk "@" aichaos.com>
COPYRIGHT AND LICENSE
Net::CyanChat - Perl interface to CyanChat.
Copyright (C) 2005 Cerone J. Kirsle
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA