Author: bdonlan
Date: 2004-07-18 21:01:57 -0400 (Sun, 18 Jul 2004)
New Revision: 319
Modified:
branches/new-poe-client/main/client/lib/Haver/Client/POE.pm
Log:
* main/client/lib/Haver/Client/POE.pm: Changed docs to reflect the use of
OO-like calling instead of POE event dispatch.
Modified: branches/new-poe-client/main/client/lib/Haver/Client/POE.pm
===================================================================
--- branches/new-poe-client/main/client/lib/Haver/Client/POE.pm 2004-07-19
00:41:59 UTC (rev 318)
+++ branches/new-poe-client/main/client/lib/Haver/Client/POE.pm 2004-07-19
01:01:57 UTC (rev 319)
@@ -29,26 +29,25 @@
# harray => [
# $handler
# ],
-# }
-# },
+# },
+# }, # wants =>
# handlers => {
# [same as wants]
-# }
-# }
-# heap => {
-# [connection data]
-# auth => {
+# },
+# connection => {
+# [connection data]
# UID => $uid,
-# methods => {
-# TODO: OO authentication handler interface
-# pass => 'password',
+# authmethods => [ acceptable auth methods ],
+# state => STATE_NAME,
+# want => 'CURRENTLY_WANTED',
+# pending => [
+# ['WAITING', 'FOR', 'WANT'],
+# ],
+# POE => {
+# connwheel => POE::Wheel::ConnectionFactory,
+# sockwheel => POE::Wheel::ReadWrite
# },
-# }
-# state => STATE_NAME,
-# want => 'CURRENTLY_WANTED',
-# pending => [
-# ['WAITING', 'FOR', 'WANT'],
-# ],
+# } # connection =>
# }
=head1 NAME
@@ -59,8 +58,9 @@
use Haver::Client::POE;
- new Haver::Client::POE('haver');
- POE::Kernel->post('haver', 'connect', Host => 'example.com',
+ my $conn = new Haver::Client::POE('haver');
+ $conn->register(connected => \&on_connect);
+ $conn->connect( Host => 'example.com',
Port => 7070,
UID => 'example');
@@ -88,16 +88,14 @@
STATE_DISCON => 4, # disconnecting
};
+use Carp;
+
use POE qw(Wheel::ReadWrite
Wheel::SocketFactory);
+
+use POE::Filter::Haver;
use Haver::Preprocessor;
-use Haver::Util::Misc qw(format_datetime);
-use POE::Filter::Haver;
use Haver::Formats::Error;
-use Carp;
-use Digest::SHA1 qw(sha1_base64);
-use Data::Dumper;
-use base 'POE::Session::EventSource';
our $VERSION = 0.06;
@@ -119,9 +117,9 @@
sub _object_states {
my ($self, $ehash) = @_;
- $ehash = {(map {$_ => $_} qw{
- _start
- _default
+ $ehash = {qw{
+ _start _start
+ _default _default
}), %$ehash};
return $self->SUPER::_object_states($ehash);
}
@@ -169,16 +167,17 @@
### DISPATCH
-=head2 register($Z<>event1 [,...])
+=head2 register($Z<>event1 => $handler [,...])
-Registers to receive the events listed. When a matching event is dispatched,
it will be sent to
-the calling session as 'haver_eventname'. The special event name 'all' may be
specified to register for all
-events. A given event will not be sent to any given session more than once.
+Registers code references to handle the given messages. When a matching
+message is dispatched, it will be sent to all handlers registered for that
+event.
-=head2 unregister($Z<>event1 [,...])
+=head2 unregister($Z<>handler [,...])
-Unregisters from the specified event. Events registered using 'all' must be
unregistered using 'all'.
+Unregisters the given handler from receiving messages.
+
=head2 register_want($Z<>wantname => sub { ... } [,...])
Registers handlers to be called if the given command is requested from the
@@ -194,12 +193,27 @@
=head2 unregister_want($subrev [,...])
-Unregisters one or more handler previously registered with register_want().
+Unregisters one or more handlers previously registered with register_want().
=cut
sub unregister_want { die "STUB" }
+=head2 register_smsg($Z<>msgname => sub { ... } [,...])
+
+Registers a handler for a server message. Calling semantics are the same
+as for register_want(), except unhandled messages are simply ignored.
+
+=cut
+
+sub register_smsg { die "STUB" }
+
+=head2 unregister_smsg($subref [,...])
+
+Unregisters one or more handlers previously registered with register_smsg().
+
+=cut
+
# Internal: dispatch_ref($event, $args)
# dispatches $event to clients, with $args
@@ -223,6 +237,11 @@
sub dispatch_want { die "STUB" }
+# Internal: dispatch_smsg($smsg, @args)
+# dispatches handlers for $smsg
+
+sub dispatch_smsg { die "STUB" }
+
### SESSION MANAGEMENT
=head2 B<connect(Host => $Z<>host, [Port => $Z<>port])
@@ -388,12 +407,12 @@
=head1 MESSAGES
Message callbacks are called with the first argument being the message
-arguments, and the second argument being a hash reference containing context
-information sent by the server.
+name, the second argument being a hash reference containing context
+information sent by the server, and the remaining arguments being
+event-specific arguments.
- sub haver_connect_fail {
- my ($args, $context) = @_[ARG0..ARG2];
- my ($enum, $estr) = @$args;
+ sub connect_fail {
+ my ($name, $context, $enum, $estr) = @_;
# ...
}
@@ -401,96 +420,98 @@
* IN - Indicates the channel set by S: IN
* ON - Indicated the UID set by S: ON
-=head2 haver_connected(Z<>)
+In the following messages, the arguments given omit $name and $context.
+=head2 connected(Z<>)
+
This event is sent when a connection is established (but before it is logged
in)
-=head2 haver_connect_fail($Z<>enum, $Z<>estr)
+=head2 connect_fail($Z<>enum, $Z<>estr)
The connection could not be established. An error code is in $enum, and the
human-readable
version is in $estr
-=head2 haver_disconnected($Z<>enum, $Z<>estr)
+=head2 disconnected($Z<>enum, $Z<>estr)
The connection has been lost. If the server closed the connection, $enum will
be 0 and $estr will
be meaningless. If the user closed the connection, and the server failed to
respond, $enum will be -1.
Otherwise, $enum will contain an error code, and $estr the human-readable
version.
-=head2 haver_raw_in(@data)
+=head2 raw_in(@data)
The client has received @data from the Haver server. Mostly useful for
debugging.
-=head2 haver_raw_out(@data)
+=head2 raw_out(@data)
The client has sent @data to the Haver server. Mostly useful for debugging.
-=head2 haver_login_request(Z<>)
+=head2 login_request(Z<>)
The server is asking for a UID, and one was not provided in connect().
The authentication will not proceed until login() is invoked with the UID.
-=head2 haver_auth_request(@Z<>methods)
+=head2 auth_request(@Z<>methods)
The server requests authentication using one of the listed methods. The
authentication will not proceed until authenticate() is invoked with a
suitable authentication handler.
-=head2 haver_login(Z<>)
+=head2 login(Z<>)
The client has successfully logged in.
-=head2 haver_close($Z<>etyp, $Z<>estr)
+=head2 close($Z<>etyp, $Z<>estr)
Z<XXX: Describe args>
Server is closing connection, and sent $etyp and $estr
-=head2 haver_join(Z<>)
+=head2 join(Z<>)
$uid has joined $cid
-=head2 haver_joined(Z<>)
+=head2 joined(Z<>)
The client has joined $cid.
-=head2 haver_part(Z<>)
+=head2 part(Z<>)
$uid has left $cid.
-=head2 haver_parted(Z<>)
+=head2 parted(Z<>)
The client has left $Z<>cid.
-=head2 haver_msg($Z<>type, @Z<>msg)
+=head2 msg($Z<>type, @Z<>msg)
A public message with type $type and contents @msg was sent on channel $cid by
user $uid.
-=head2 haver_pmsg($Z<>type, @Z<>text)
+=head2 pmsg($Z<>type, @Z<>text)
A private message with type $type and contents @msg was sent to you by user
$uid.
-=head2 haver_users(@Z<>who)
+=head2 users(@Z<>who)
Channel $cid has the users listed in @who in it. Sent in response to message
users().
-=head2 haver_bye($Z<>why)
+=head2 bye($Z<>why)
The server is disconnecting you due to the reason in $why
-=head2 haver_chans(@Z<>channels)
+=head2 chans(@Z<>channels)
The server has the channels listed in @channels. Sent in response to message
chans()
-=head2 haver_warn($Z<>err, $Z<>short, $Z<>long, @Z<>args)
+=head2 warn($Z<>err, $Z<>short, $Z<>long, @Z<>args)
The server has sent a non-fatal error message with code $err and arguments
@args. $short and $long have the
short and long human-readable forms, respectively.
-=head2 haver_die($Z<>err, $Z<>short, $Z<>long, @Z<>args)
+=head2 die($Z<>err, $Z<>short, $Z<>long, @Z<>args)
The server has sent a fatal error message with code $err and arguments @args.
$short and $long have the
short and long human-readable forms, respectively. The connection will be
closed shortly.
-=head2 haver_quit($Z<>why)
+=head2 quit($Z<>why)
UID $uid has disconnected due to the reason in $why.
