NAME

Net::C6Term - Interface to the C6Term protocol, which allows to connect to C6 servers

SYNOPSIS

use strict; use Net::C6Term;

my $c6 = Net::C6Term->new();

$c6->add_handler(200, \&on_connect); $c6->add_handler('default', \&on_default);

$c6->send_event('connect', 'c6login.tin.it', 4800);

$c6->start();

$c6->finish();

DESCRIPTION

Net::C6Term provides an interface to the c6term software written by Rodolfo Giacometti, which allows you to connect to a C6 server (C6 is an Italian ICQ-like instant messaging system). c6term, along with C6 protocol specifications and other related software and documentation, can be found at the Open C6 project home page, at http://openc6.extracon.it . Please read the c6term documentation to find out how to connect and how to send commands to the C6 server.

CONSTRUCTOR

• new([command])

  Creates a new Net::C6Term object, which represent a single connection (that is, a fork() with IPC communication) to the c6term external program. You can supply an optional command, which will tell the path and filename of the c6term program. If none is provided, ./c6term will be used.

METHODS

All of the following methods are instance methods: you must call them on a Net::C6Term object you created.

• add_handler(eventcode, subref)

  Sets an handler function for a specific event of the c6term program (that is, of the C6 server you are connected to). You need to provide the numeric event code (see the c6term documentation for more information about codes, and the EVENTS sections for the C6Term.pm additional ones), and a reference to the sub that you want to use to handle that event. If you provide default as the event code, the passed sub will be used for all events for which you've defined no specific handler. A reference to the C6Term object will be passed to the sub.

• send_event(command [,param, ...])

  Queues an event (that is, a command) for sending to c6term. The command is in string format, see the c6term documentation for information on available commands. There is an optional number of parameters, which you may provide depending on the command you are issuing.

  Note that calling this method doesn't actually send that event to the server, unless the method start() was called before. To actually send you event you'll need a call to do_one_loop().

• do_one_loop()

  This method fowards any queued command to c6term, and fetches any queued incoming event, calling the defined event handlers (see add_handler(). You'll probably need to call this method quite often in your software to be able process incoming events. This method is non blocking, so if there are no incoming events it will just return instead of waiting indefinitely.

  Returns 0 if the child died prematurely, 1 in all other cases.

• start()

  Starts a loop which only ends when the c6term child terminates (or dies prematurely). It's actually a continuos call to do_one_loop(), which ends when that method returns 0.

  You can use start() if you've got a very simple application which needs to almost do nothing except wait for C6 events and, upon receipt of them, do something and/or send other events.

• finish()

  Terminated the forked c6term child. You'd better logout (using the appropriate command) from the C6 server before calling this. If something goes wrong when terminating c6term, your program will die().

• evstr()

  Returns the number of the latest event processed by do_one_loop. You should call this method from inside your handler function to get information about what the server replied you.

• evstr()

  Returns a string with the content of the latest event processed by do_one_loop. You should call this method from inside your handler function to get information about what the server replied you.

EVENTS

All the events are the ones reported in the c6term documentation, plus a couple specific to C6Term.pm.

• 3000 unknown c6term response (response)

  This event occurs in case of an unknown (malformed) response from the c6term program. The response itself is provided between parentheses.

• 3001 c6term child died prematurely

  If, for some reason, the forked c6term program dies prematurely, this event is returned.

TODO

• Add better error handling in finish(): now it just dies if something goes wrong when terminating the forked child. Elegant, uh? :-)

• Add methods to send events in without needing to know the c6term commands (i.e. connect(), login(), ...).

• Rely on IPC::Socket3 instead of IPC::Run.

COPYRIGHT

Copyright 2003, Michele Beltrame <mb@italpro.net> - http://www.italpro.net/mb/

This library is free software; you can redistribute it and/or modify it under the GNU General Public License.