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.

CLIENT EVENTS

Client events are the messages an ICQ client, i.e. your code, sends to the server. They represent things such as a logon request, a message to another user, or a user search request. They are sometimes called 'commands' because they represent the 'commands' that an ICQ client can execute.

When you ask Net::ICQ to send an event with send_event() (described above), you need to provide 2 things: the event name, and the parameters.

Event name

The event name is the first parameter to send_event(), and it specifies which event you are sending. You may either specify the string code or the numeric code. The section CLIENT EVENT LIST below describes all the events and gives the codes for each. For example: when sending a text message to a user, you may give the event name as either the string 'CMD_SEND_MESSAGE' or the number 270.

The hash %Net::ICQ::cmd_codes maps string codes to numeric codes. keys(%Net::ICQ::cmd_codes) will produce a list of all the string codes.

Parameters

The parameters list is the second parameter to send_event(), and it specifies the data for the event. Every event has its own parameter list, but the general idea is the same. The parameters list is stored as a hashref, where the hash contains a key for each parameter. Almost all the events utilize a regular 1-level hash where the values are plain scalars, but a few events do require 2-level hash. The CLIENT EVENT LIST section lists the parameters for every client event.

For example: to send a normal text message with the text 'Hello world' to UIN 1234, the parameters would look like this:

{
  'type'         => 1,
  'text'         => 'Hello world',
  'receiver_uin' => 1234
}

A complete example

Here is the complete code using send_event() to send the message 'Hello world' to UIN 1234:

$params = {
  'type'         => 1,
  'text'         => 'Hello world',
  'receiver_uin' => 1234
};
$icq->send_event('CMD_SEND_MESSAGE', $params);