NAME

Net::ICQ - Perl interface to an ICQ server

SYNOPSIS

use Net::ICQ;

$icq = Net::ICQ->new();

$icq->add_handler('SRV_NAME', \&sub_name);
$icq->send_event('CMD_NAME', $params);

while (!quit) {
  $icq->do_one_loop();
}

$icq->disconnect();

DESCRIPTION

Net::ICQ is a class implementing an ICQ client interface in Perl.

CONSTRUCTOR

• new (uin, password [, server [, port]])

  Opens a connection to the ICQ server. The UIN and password to use are specified as the first two parameters. Server and port are optional, and default to 'icq.mirabilis.com' and '4000', respectively.

  Also, environment variables will be checked as follows:

  uin      - ICQ_UIN
  password - ICQ_PASS
  server   - ICQ_SERVER
  port     - ICQ_PORT

  Constructor parameters have the highest priority, then environment variables. The built-in defaults (for server and port only) have the lowest priority.

  If either a UIN or password is not provided either directly or through environment variables, new() will croak with an appropriate error message.

METHODS

All of the following methods are instance methods. That is, call them on a Net::ICQ object (for example, $icq->do_one_loop).

• do_one_loop()

  Unless you call the start() method (see below), you must continuously call do_one_loop whenever your Net::ICQ object is connected to the server. It uses select() to wait for data from the server and other ICQ clients, so it won't use CPU power even if you call it in a tight loop.

  This method does one processing loop, which involves looking for incoming data from the network, calling registered event handlers, sending acknowledgements for received packets, transmitting outgoing data over the network, and sending keepalives to the server to tell it that we are still online. If it is not called often enough, you will not be notified of incoming events in a timely fashion, or the server might even think you have disconnected and start to ignore you. As mentioned above, you can't call this function too quickly, so don't worry about that and call it as fast as you can.

• start()

  If you're writing a fairly simple application that doesn't need to interface with other event-loop-based libraries, you can just call start instead of repeatedly calling do_one_loop. Essentially, the start method does this: while(connected) { do_one_loop }

  If you have called the start method, it will return after disconnect is called.

• add_handler(command_number, handler_ref)

  Sets the handler function for a specific ICQ server event. command_number specifies the event to handle. You may use either the numeric code or the corresponding string code. See the SERVER EVENTS section below for the numeric and string codes for all the events, along with descriptions of each event's function and purpose. handler_ref is a code ref for the sub that you want to handle the event. See the HANDLERS section for how a handler works and what it needs to do.

• send_event(command_number, params)

  Sends an event to the server. command_number specifies the event to be sent. You may use either the numeric code or the corresponding string code. See the CLIENT EVENTS section below for the numeric and string codes for all the events, along with descriptions of each event's function and purpose. params is a reference to a hash containing the parameters for the event. See the CLIENT EVENTS section for an explanation of the correct parameters for each event.

• disconnect()

  Disconnects the Net::ICQ object from the server. Note that currently, the object becomes unusable for ICQ communication after disconnect is called. In the future a connect method will be written which will allow the object to reconnect to the server, but this method does currently not exist. (FIX!)

  The 'connected' field of the Net::ICQ object will be set to false after this method is called, and if you have called the start method, it will exit.