NAME

Net::ICQ - Pure Perl interface to an ICQ server

SYNOPSIS

  use Net::ICQ;

  $icq = Net::ICQ->new($uin, $password);
  $icq->connect();

  $icq->add_handler('SRV_SYS_DELIVERED_MESS', \&on_msg);

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

  $icq->start();

DESCRIPTION

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

CONSTRUCTOR

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

  Creates a new Net::ICQ object. A Net::ICQ object represents a single user logged into a specific 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 return undef.

  Note that after calling new() you must next call connect() before you can send and receive ICQ events.

METHODS

All of the following methods are instance methods; you must call them on a Net::ICQ object (for example, $icq->start).

• connect

  Connects the Net::ICQ object to the server.

• disconnect

  Disconnects the Net::ICQ object from the server.

• connected

  Returns true if the Net::ICQ object is connected to the server, and false if it is not.

• 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() to begin communicating with the server.

  Note that start() will not return until the Net::ICQ object is disconnected from the server, either by the server itself or by your event-handler code calling disconnect().

• do_one_loop

  If you don't want to (or can't) call the start() method, you must continuously call do_one_loop when 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. If you need to do other processing, you could call do_one_loop as infrequently as once every few seconds.

  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.

• 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.

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);