AOLIM(3) User Contributed Perl Documentation AOLIM(3)
NNAAMMEE
Net::AOLIM - Object-Oriented interface to the AOL Instant Messenger TOC
client protocol
SSYYNNOOPPSSIISS
The really short form:
use Net::AOLIM;
$aim = Net::AOLIM->new('username' => $user,
'password' => $pass,
'callback' => \&handler);
$aim->signon;
$aim->toc_send_im($destuser, $message);
NNOOTTEESS
Error conditions will be stored in $main::IM_ERR, with any arguments to
the error condition stored in $main::IM_ERR_ARGS.
The hash %Net::AOLIM::ERROR_MSGS contains english translations of all
of the error messages that are either internal to the module or partic-
ular to the TOC protocol.
Errors may take arguments indicating a more specific failure condition.
In this case, they will either be stored in $main::IM_ERR_ARGS or they
will come from the server ERROR message. To insert the arguments in
the proper place, use a construct similar to:
$ERROR = $Net::AOLIM::ERROR_MSGS{$IM_ERR};
$ERROR =~ s/\$ERR_ARG/$IM_ERR_ARGS/g;
This assumes that the error code is stored in $IM_ERR and the error
argument is stored in $IM_ERR_ARGS.
All methods will return undef on error, and will set $main::IM_ERR and
$main::IM_ERR_ARGS as appropriate.
It seems that TOC servers won't acknowledge a login unless at least one
buddy is added before toc_init_done is sent. Thus, as of version 1.6,
Net::AOLIM will add the current user to group "Me" if you don't create
your buddy list before calling _s_i_g_n_o_n_(_). Don't bother removing this if
you have added your buddies; it'll automagically disappear.
DDEESSCCRRIIPPTTIIOONN
This section documents every member function of the Net::AOLIM class.
$$NNeett::::AAOOLLIIMM-->>_n_e_w_(_)
This is the Net::AOLIM Constructor.
It should be called with following arguments (items with default values
are optional):
'username' => login
'password' => password
'callback' => \&callbackfunction
'server' => servername (default toc.oscar.aol.com)
'port' => port number (default 1234)
'allow_srv_settings' => <1 | 0> (default 1)
'login_server' => login server (default login.oscar.aol.com)
'login_port' => login port (default 5198)
'login_timeout' => timeout in seconds to wait for a response to the
toc_signon packet. Default is 0 (infinite)
'aim_agent' => agentname (max 200 char)
Default is AOLIM:$Version VERSION$
There have been some reports that changing this
may cause TOC servers to stop responding to signon
requests
callback is the callback function that handles incoming data from the
server (already digested into command plus args). This is the meat of
the client program.
allow_srv_settings is a boolean that dictates whether the object should
modify the user configuration on the server. If allow_srv_settings is
false, the server settings will be ignored and will not be modified.
Otherwise, the server settings will be read in and parsed, and will be
modified by calls that modify the buddy list.
aim_agent is the name of the client program as reported to the TOC
server
Returns a blessed instantiation of Net::AOLIM.
$$aaiimm-->>_s_i_g_n_o_n_(_)
Call this after calling "new()" and after setting initial buddy list-
ings with "add_buddies()", "im_permit()", "im_deny()", "im_per-
mit_all()", and "im_deny_all()" as necessary.
Returns undef on failure, setting $main::IM_ERR and $main::IM_ERR_ARGS
as appropriate. Returns 0 on success.
This function is also called every time we receive a SIGN_ON packet
from the server. This is because we are required to react in a spe-
cific way to the SIGN_ON packet, and this method contains all necessary
functionality. We should only receive SIGN_ON while connected if we
have first received a PAUSE (see the _TT_OO_CC((77)) documentation included with
this package for details of how PAUSE works).
$$aaiimm-->>_r_e_a_d___s_f_l_a_p___p_a_c_k_e_t_(_)
This method returns data from a single waiting SFLAP packet on the
server socket. The returned value is the payload section of the SFLAP
packet which is completely unparsed.
Most users will never need to call this method.
For more information, see RROOLLLLIINNGG YYOOUURR OOWWNN below and the _TT_OO_CC((77)) man-
page.
$$aaiimm-->>sseenndd__ssffllaapp__ppaacckkeett(($$ttyyppee,, $$ddaattaa, $formatted, $noterm)
This method sends an SFLAP packet to the server.
$type is one of the SFLAP types (see _TT_OO_CC((77))).
$data is the payload to send.
If $formatted evaluates to true, the data is assumed to be the com-
pletely formed payload of the SFLAP packet; otherwise, the payload will
be packed as necessary. This defaults to 0. In either case, the
header is prepended to the payload.
If $noterm evaluates to true, the payload will not be terminated with a
'\0'. Otherwise, it will be terminated. If $formatted is true, this
option is ignored and no null is appended. This defaults to 0.
Most users will never need to use this method.
For more information, see _TT_OO_CC((77)) and RROOLLLLIINNGG YYOOUURR OOWWNN below.
$$aaiimm-->>_s_r_v___s_o_c_k_e_t_(_)
This method returns a reference to the socket to which the server is
connected. It must be dereferenced before it can be used. Thus:
"$foo = $aim->srv_socket();" "recv($$foo, $recv_buffer, $length,
$flags);"
Most users will never need to directly access the server socket.
For more information, see the _TT_OO_CC((77)) manpage and RROOLLLLIINNGG YYOOUURR OOWWNN
below.
$$aaiimm-->>ppww__rrooaasstt(($$ppaasssswwoorrdd))
This method returns the 'roasted' version of a password. A roasted
password is the original password XORed with the roast string 'Tic/Toc'
(which is repeated until the length is the same as the password
length).
This method is called automatically in $aim->signon. Most users will
never need this method.
For more information, see the _TT_OO_CC((77)) manpage and RROOLLLLIINNGG YYOOUURR OOWWNN
below.
$$aaiimm-->>nnoorrmm__uunnaammee(($$uusseerrnnaammee))
This method returns the 'normalized' version of a username. A normal-
ized username has all spaces removed and is all lowercase. All user-
names sent to the server should be normalized first if they are an
argument to a TOC command.
All methods in this class automatically normalize username arguments to
the server; thus, most users will never use this method.
For more information, see the _TT_OO_CC((77)) manpage and RROOLLLLIINNGG YYOOUURR OOWWNN
below.
$$aaiimm-->>ttoocc__ffoorrmmaatt__mmssgg(($$ccoommmmaanndd[[,, $$aarrgg11[[,, aarrgg22[[,, ......]]]]]]))
This method formats a message properly for sending to the TOC server.
That is, it is escaped and quoted, and the fields are appended with
spaces as specified by the protocol.
Note that all methods in this class automatically format messages
appropriately; most users will never need to call this method.
See _TT_OO_CC((77)) and RROOLLLLIINNGG YYOOUURR OOWWNN below.
$$aaiimm-->>ttoocc__ffoorrmmaatt__llooggiinn__mmssgg(($$ccoommmmaanndd[[,, $$aarrgg11[[,, aarrgg22[[,, ......]]]]]]))
This method formats a login message properly for sending to the TOC
server. That is, all fields are escaped, but only the user_agent field
is quoted. Fields are separated with spaces as specified in the TOC
protocol.
Note that the login procedure calls this function automatically; the
user will probably never need to use it.
See _TT_OO_CC((77)) and RROOLLLLIINNGG YYOOUURR OOWWNN below.
$$aaiimm-->>ttoocc__sseenndd__iimm(($$uunnaammee,, $$mmssgg, $auto)
This method sends an IM message $msg to the user specified by $uname.
The third argument indicates whether or not this IM should be sent as
an autoreply, which may produce different behavior from the remote
client (but has no direct effect on the content of the IM).
$$aaiimm-->>aadddd__bbuuddddiieess(($$ggrroouupp,, $$bbuuddddyy11[, $buddy2[, ...]])
This method, which should only be called bbeeffoorree _ss_ii_gg_nn_oo_nn_((_)), adds buddies
to the initial local buddy list in group $group. Once "signon()" is
called, use add_online_buddies instead.
$$aaiimm-->>aadddd__oonnlliinnee__bbuuddddiieess(($$ggrroouupp,, $$bbuuddddyy11[, $buddy2[, ...]])
This method takes the same arguments as "add_buddies()", but is
intended for use after "signon()" has been called.
If allow_srv_settings is true (see "new()"), it will also set the set-
tings on the server to the new settings.
$$aaiimm-->>rreemmoovvee__oonnlliinnee__bbuuddddiieess(($$bbuuddddyy11[[,, $$bbuuddddyy22[[,, ......]]]]))
Removes all arguments from the buddy list (removes from all groups).
If allow_srv_settings is true (see "new()"), it will also set the set-
tings on the server to the new settings.
$$aaiimm-->>ccuurrrreenntt__bbuuddddiieess((\\%%bbuuddddyyhhaasshh))
This method fills the hash referenced by "\%buddyhash" with the cur-
rently stored buddy information. Each key in the returned hash is the
name of a buddy group, and the corresponding value is a list of the
members of that group.
$$aaiimm-->>_c_u_r_r_e_n_t___p_e_r_m_i_t_s_(_)
This method takes no arguments. It returns the current 'permit' list.
$$aaiimm-->>_c_u_r_r_e_n_t___d_e_n_i_e_s_(_)
This method takes no arguments. It returns the current 'deny' list.
$$aaiimm-->>iimm__ppeerrmmiitt(($$uusseerr11[[,, $$uusseerr22[[,, ......]]]]))
This method should only be called bbeeffoorree _ss_ii_gg_nn_oo_nn_((_)). It adds all argu-
ments to the current permit list and deletes the current deny list. It
also sets the permit mode to 'permit some'.
If you would like to do this while online, use the "add_im_permit()"
method instead.
$$aaiimm-->>iimm__ddeennyy(($$uusseerr11[[,, $$uusseerr22[[,, ......]]]]))
This method should only be called bbeeffoorree _ss_ii_gg_nn_oo_nn_((_)). It adds all argu-
ments to the current deny list and deletes the current permit list. It
also sets the permit mode to 'deny some'.
If you would like to do this while online, use the "add_im_permit()"
method instead.
$$aaiimm-->>aadddd__iimm__ppeerrmmiitt(($$uusseerr11[[,, $$uusseerr22[[,, ......]]]]))
This is the method that should be called if you are online and wish to
add users to the permit list. It will, as a consequence, delete the
current deny list and set the current mode to 'permit some'.
$$aaiimm-->>aadddd__iimm__ddeennyy(($$uusseerr11[[,, $$uusseerr22[[,, ......]]]]))
This is the method that should be used if you are online and wish to
add users to the deny list. It will, as a consequence, delete the cur-
rent permit list and set the current mode to 'deny some'.
$$aaiimm-->>_i_m___d_e_n_y___a_l_l_(_)
This method should be called only bbeeffoorree _ss_ii_gg_nn_oo_nn_((_)). It will delete both
the permit and deny list and set the mode to 'deny all'.
$$aaiimm-->>_i_m___p_e_r_m_i_t___a_l_l_(_)
This method should be called only bbeeffoorree _ss_ii_gg_nn_oo_nn_((_)). It will delete both
the permit and deny list and set the mode to 'permit all'.
$$aaiimm-->>_a_d_d___i_m___d_e_n_y___a_l_l_(_)
This is the method that should be used if you are online and wish to go
into 'deny all' mode. It will also delete both the permit and deny
lists.
$$aaiimm-->>_a_d_d___i_m___p_e_r_m_i_t___a_l_l_(_)
This is the method that should be used if you are online and wish to go
into 'permit all' mode. It will also delete both the permit and deny
lists.
$$aaiimm-->>ttoocc__eevviill(($$uusseerr,, $$aannoonn))
This method will apply 'evil' to the specified user $user. If $anon
evaluates to true, the evil will be done anonymously.
$$aaiimm-->>ttoocc__cchhaatt__jjooiinn(($$eexxcchhaannggee,, $$rroooomm__nnaammee))
This method will join the chat room specified by $exchange and
$room_name. Currently, the only valid value for $exchange is 4.
See the _TT_OO_CC((77)) manpage included with this package for more information
on chatting.
$$aaiimm-->>ttoocc__cchhaatt__sseenndd(($$rroooommiidd,, $$mmeessssaaggee))
This method will send the message $message to the room $roomid (which
should be the room ID provided by the server in response to a
toc_chat_join or toc_accept_invite).
You will receive this message back from the server as well, so your UI
does not have to handle this message in a special way.
$$aaiimm-->>ttoocc__cchhaatt__wwhhiissppeerr(($$rroooommiidd,, $$ddssttuusseerr, $message)
This method sends the message $message to $dstuser in the room $roomid.
The server will nnoott send you a copy of this message, so your user
interface should have a special case for displaying outgoing whispers.
$$aaiimm-->>ttoocc__cchhaatt__eevviill(($$rroooommiidd,, $$ddssttuusseerr, $anon)
This will apply evil to the user $dstuser in room $room. If $anon
evaluates to true, it will be applied anonymously.
Please note that this functionality is currently disabled by the TOC
servers.
$$aaiimm-->>ttoocc__cchhaatt__iinnvviittee(($$rroooommiidd,, $$mmssggtteexxtt, $buddy1[, $buddy2[, ...]])
This method will invite all users "$buddy1..$buddyN" to room $roomid
with invitation text $msgtext.
$$aaiimm-->>ttoocc__cchhaatt__lleeaavvee(($$rroooommiidd))
This method will notify the server that you have left room $roomid.
$$aaiimm-->>ttoocc__cchhaatt__aacccceepptt(($$rroooommiidd))
This method accepts a chat invitation to room $roomid. You do not have
to send a "toc_chat_join()" message if you have been invited and accept
with this method.
$$aaiimm-->>ttoocc__ggeett__iinnffoo(($$uusseerrnnaammee))
This method requests info on user $username. See _TT_OO_CC((77)) for more
information on what the server returns.
$$aaiimm-->>ttoocc__sseett__iinnffoo(($$iinnffoo))
This method sets the information for the current user to the ASCII text
(HTML formatted) contained in $info.
$$aaiimm-->>ttoocc__sseett__aawwaayy(($$mmssgg))
This method sets or unsets the away message. If $msg is undefined,
away is unset. Otherwise, away is set with the message in $msg.
$$aaiimm-->>ttoocc__ggeett__ddiirr(($$uusseerrnnaammee))
This method sends a request to the server for directory information on
$username. See _TT_OO_CC((77)) for information on what the server will return.
$$aaiimm-->>ttoocc__sseett__ddiirr(($$uusseerriinnffoo))
This method sets the information on the current user to the string pro-
vided as $userinfo. See _TT_OO_CC((77)) for more information on the format of
the $userinfo string.
$$aaiimm-->>ttoocc__ddiirr__sseeaarrcchh(($$sseeaarrcchhssttrr))
This method will search the directory using $searchstr. See _TT_OO_CC((77)) for
more information on how this string should look.
$$aaiimm-->>ttoocc__sseett__iiddllee(($$sseeccoonnddss))
This method sets the number of seconds that the client has been idle.
If it is 0, the idle is cleared. Otherwise, the idle is set and the
server will continue to count up the idle time (thus, you need only
call "idle()" once in order to become idle).
$$aaiimm-->>uuii__aadddd__ffhh(($$ffiilleehhaannddllee,, \\&&ccaallllbbaacckk))
This method will add a filehandle to the "select()" loop that will be
called with "ui_dataget()". If information is found to be on that
filehandle, the callback will be executed. It is the responsibility of
the callback to read the data off the socket.
AAss aallwwaayyss,, tthhee uussee ooff bbuuffffeerreedd IIOO oonn ffiilleehhaannddlleess bbeeiinngg _ss_ee_ll_ee_cc_tt_((_))eedd iiss
uunnrreelliiaabbllee aatt bbeesstt.. AAvvooiidd tthhee uussee ooff _rr_ee_aa_dd_((_)),,