NAME

  POE::Component::Client::Halo -- an implementation of the Halo query 
  protocol.

SYNOPSIS

  use Data::Dumper; # for the sample below
  use POE qw(Component::Client::Halo);

  my $halo = new POE::Component::Client::Halo(
        Alias => 'halo',
        Timeout => 15,
        Retry => 2,
  );

  $kernel->post('halo', 'info', '127.0.0.1', 2302, 'pbhandler', 'ident');

  $kernel->post('halo', 'detail', '127.0.0.1', 2302, 'pbhandler', 'ident');

  sub postback_handler {
      my ($ip, $port, $command, $identifier, $response) = @_;
      print "Halo query $command_executed on ";
      print " at $ip:$port";
      print " had a identifier of $identifier" if defined $identifier;
      print " returned from the server with:";
      print Dumper($response), "\n\n";
  }

DESCRIPTION

POE::Component::Client::Halo is an implementation of the Halo query protocol. It was reverse engineered with a sniffer and two cups of coffee. This is a preliminary release, based version 1.00.01.0580 of the dedicated server (the first public release). It is capable of handling multiple requests of different types in parallel.

PoCo::Client::Halo new can take a few parameters:

Alias => $alias_name

Alias sets the name of the Halo component with which you will post events to. By default, this is 'halo'.

Timeout => $timeout_in_seconds

Timeout specifies the number of seconds to wait for each step of the query procedure. The number of steps varies depending on the server being accessed.

Retry => $number_of_times_to_retry

Retry sets the number of times PoCo::Client::Halo should retry query requests. Since queries are UDP based, there is always the chance of your packets being dropped or lost. After the number of retries has been exceeded, an error is posted back to the session you specified to accept postbacks.

METHODS

There are two methods that can be exported through the tag ':flags' -- halo_player_flag() and halo_game_flag(). They can be used to translate a specific game flag into its English equivalent.

  $english_value = halo_player_flag($flag_name, $flag_value);
  $english_value = halo_game_flag($flag_name, $flag_value);

EVENTS

You can send two types of events to PoCo::Client::Halo.

info

This will request the basic info block from the Halo server. In the postback, you will get 4 or 5 arguments, depending on whether or not you had a postback. ARG0 is the IP, ARG1 is the port, ARG3 is the command (for info queries, this will always be 'info'), ARG4 is a hashref with the returned data, and ARG5 is your unique identifier as set during your original post. Here are the fields you'll get back in ARG4:

• Map

• Teamplay

• Classic

• Mode

• MaxPlayers

• Hostname

• Password

• Version

• Dedicated

• Players

detail

This request more detailed information about the server, as well as its rules, player information, and team score. Like 'info', you'll get 4-5 arguments passed to your postback function. ARG4 contains a HoHoH's: { 'Score' => { 'Red' => { 'team' => 'Red', 'score' => '17' }, 'Blue' => { 'team' => 'Blue', 'score' => '17' } }, 'Players' => { 'ZETA' => { 'score' => '0', 'team' => '0', 'ping' => '', 'player' => 'ZETA' }, 'badmofo' => { 'score' => '3', 'team' => '0', 'ping' => '', 'player' => 'badmofo' }, }, 'Rules' => { 'gametype' => 'Slayer', 'hostport' => '', 'fraglimit' => '50', 'mapname' => 'dangercanyon', 'gamever' => '01.00.01.0580', 'teamplay' => '1', 'password' => '0', 'game_flags' => '26', 'player_flags' => '1941966980,2', 'game_classic' => '0', 'gamevariant' => 'Team Slayer', 'gamemode' => 'openplaying', 'hostname' => 'DivoNetworks', 'maxplayers' => '16', 'dedicated' => '1', 'numplayers' => '2' } };

At the time of this module's release, ping information was not available within the info packets. They might be made public later on, so I left them in the response.

You can translate the player and game flags with the two methods mentioned above. Take a look at the sample program to see how it's done.

ERRORS

The errors listed below are ones that will be posted back to you in the 'response' field.

• ERROR: Timed out waiting for response

  Even after retrying, there was no response to your request command.

• There are other fatal errors that are handled with croak().

BUGS

No tests are distributed with the module yet. There is a sample, though.

ACKNOWLEDGEMENTS

Rocco Caputo

Yay!

Divo Networks

Thanks for loaning me servers to test against.

Brian Hurley

He decoded all the player and game flags after several long nights. Thanks.

AUTHOR & COPYRIGHTS

POE::Component::Client::Halo is Copyright 2001-2003 by Andrew A. Chen <achen-poe-halo@divo.net>. All rights are reserved. POE::Component::Client::Halo is free software; you may redistribute it and/or modify it under the same terms as Perl itself.