NAME

POE::Component::Client::Rcon -- an implementation of the Rcon remote console protocol.

SYNOPSIS

  use POE qw(Component::Client::Rcon);

  my $rcon = new POE::Component::Client::Rcon(Alias => 'rcon',
		Timeout => 15,
		Retry => 2,
		Bytes => 8192,
		);

  $kernel->post('rcon', 'rcon', 'hl', '127.0.0.1', 27015, 
		  'rcon_password', 'status', 
		  'postback_event', 'identifier');

  $kernel->post('rcon', 'players', 'hl', '127.0.0.1', 27015,
		  'rcon_password',
		  'player_postback_event', 'identifier');

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

  sub player_postback_handler {
	  my ($type, $ip, $port, $identifier, $players) = @_;
	  use Data::Dumper;
	  print "Current players at a $type server at $ip:$port";
	  print " with identifier of $identifier" if defined $identifier;
	  print ":\n", Dumper($players);
  }

DESCRIPTION

POE::Component::Client::Rcon is an implementation of the Rcon protocol -- the protocol commonly used to remotely administer Half-Life, Quake, and RTCW (Return to Castle Wolfenstein) servers. It is capable of handling multiple Rcon requests simultaneously, even multiple requests to the same IP/Port simultaneously.

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

Alias => $alias_name

Alias sets the name of the Rcon component to which you will post events to. By default, this is 'rcon'.

Timeout => $timeout_in_seconds

Timeout specifies the number of seconds to wait for each step of the Rcon 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::Rcon should retry Rcon requests. Since Rcon is 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.

Bytes => $number_of_bytes_to_postback

Bytes specifies the maximum number of bytes of data you want back from your Rcon command.

EVENTS

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

rcon

Sends an rcon command to a server and postbacks a response from the server. Takes six required parmeters and one optional parameter.

  $kernel->post('rconSession', 'rcon', $typeOfServer, $ip, $port,
	      $password, $command, $postback, $identifier);

After the command has completed, it will post the results back to your postback session with the format: ($typeOfServer, $ip, $port, $command, $identifier, $rconResponseFromServer)

Type of servers currently supported are:

hl - Half-Life servers 1.1.0.6 or newer

oldhl - Half-Life servers older than 1.1.0.6

q2 - Quake 2 Server

q3 - Quake 3 Server

qw - QuakeWorld Server

RTCW is supposed to compatible with q2, but it's untested.

$identifier is a scalar that will get passed back to you in your postback. You can use it to help you identify the rcon request that is being posted back. If not specified, it will be undef.

players

Requests a list of players and player information from the server. This information is parsed out of a `status' rcon request. It takes five required parameters and one optional parameter.

  $kernel->post('rconSession', 'players', $typeOfServer, $ip, $port,
	      $password, $postback, $identifier);

After the command has completed, it will post the results back to your postback session with the format: ($typeOfServer, $ip, $port, $identifier, $hashRefOfPlayerInformation)

The type of information contained in the player information hashref will vary depending on the top of server you are querying.

Half-Life Player Information

Key is UserID. Information returned is Name, UserID, WonID, Frags, Time, Ping, Loss, and Address.

Quake2 and QuakeWorld Player Information

Key is num. Information returned is num, score, ping, name, lastmsg, address, and qport.

Quake 3 Player Information

Same as Quake2/QuakeWorld, but also includes rate.

ERRORS

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

ERROR: Bad Rcon password.

The password you specified was wrong.

ERROR: No challenge receieved from server.

In order to hinder hijacking of Rcon connections, Half-Life 1.1.0.6 introduced a challenge number. This is obtained as part of the protocol. This error simply means that the server did not return a challenge number, and PoCo::Client::Rcon could not continue.

ERROR: Timed out trying to obtain challenge.

Even after retrying, we never receieved an Rcon number.

ERROR: Timed out waiting for Rcon response.

Even after retrying, there was no response to your Rcon command. It could also mean that the command you executed generated no output.

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

BUGS

Sorry, I broke compatibility with 0.1... Quake turned out to be messier to implement than I had originally expected.

No tests are distributed with the module yet.

ACKNOWLEDGEMENTS

Rocco Caputo

Wow.. words can't explain how much help he has been.

Divo Networks

Thanks for loaning me servers to test against. They rent game servers and can be found at http://www.divo.net/ .

AUTHOR & COPYRIGHTS

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