NAME

POE::Component::AssaultCube::ServerQuery - Queries a running AssaultCube server for information

SYNOPSIS

        use POE qw( Component::AssaultCube::ServerQuery );

        sub _start {
                $_[HEAP]->{query} = POE::Component::AssaultCube::ServerQuery->new;
                $_[HEAP]->{query}->register( $_[SESSION], 'got_ping_data' );
                $_[HEAP]->{query}->addserver( '123.123.123.123' );
        }

        sub got_ping_data {
                my( $server, $response ) = @_[ARG0, ARG1];
                if ( defined $response ) {
                        print "response from(" . $server->ID . "): " $response->desc_nocolor .
                                " - " . $response->players . " players running\n";
                } else {
                        print "server " . $server->ID . " is not responding\n";
                }
        }

ABSTRACT

This module queries a running AssaultCube server for information.

DESCRIPTION

This module is a wrapper around the Games::AssaultCube::ServerQuery logic and encapsulates the raw POE details. Furthermore, this module can ping many servers in parallel.

This module gives you full control of throttling, and per-server ping frequency ( how often to ping the server ) plus a nice object front-end!

Normal usage of this component is to create an object, then add your serverlist to the object. Then you would have to register your session to receive responses. During run-time you can add/remove servers from the list, and finally shutdown the object/session.

NOTE: While you can create several ServerQuery objects and use them, it is more optimal to create only one object and put all servers there. ( This theory is unbenchmarked, ha! )

This module does not enforce timeouts per server, it gives you a "raw" feed of pings every $frequency seconds. It is up to the application logic to see if a ping failed or not. This is trivial with the appropriate use of timers :) However, patches welcome if you want the server to have individual timeouts. It will not change the logic in the application event "ac_ping" because it already checks for a defined value.

This module sets an alias to be "long-lived" and creates/destroys the POE::Wheel::UDP object only when necessary.

Constructor

This module uses Moose, so you can pass either a hash or hashref to the constructor.

The attributes are:

throttle

A number in seconds ( can be floating-point )

How long we should wait before sending the next ping. Useful for flood-control!

Default: 0.25

NOTE: You can set it to 0 to disable this feature

alias

The POE session alias we will use

Default: 'ServerQuery-' . $_[SESSION]->ID

Methods

Once instantiated, you can do various operations on the object.

addserver

Adds a server to be monitored to the list. Arguments are passed on to the POE::Component::AssaultCube::ServerQuery::Server constructor. Returns the server object or undef if it was already in the list. Will die if it encounters errors.

        $query->addserver( "123.123.123.123" );
        $query->addserver( "123.123.123.123", 12345 );
        $query->addserver({ server => "123.123.123.123", port => 12345, frequency => 60 });

Adding a server automatically sends a ping, then waits for $frequency seconds before sending the next one.

delserver

Deletes a server from the monitoring list. You can either pass in a POE::Component::AssaultCube::ServerQuery::Server object ref or the arguments will be converted internally into the object. From there we will see if the server is in the list, returns 1 if it is; returns undef otherwise.

register

Adds a "watcher" session that will receive ping replies. Accepts a session ID/alias/reference, and the event name.

The session defaults to the running POE session, if there is one

The event name defaults to "ac_ping"

unregister

Removes a "watcher" session from the list. Accepts a session ID/alias/reference.

shutdown

Initiates shutdown procedures and destroys the associated session

clearservers

Removes all servers from the list and ceases pinging servers

POE events

You can post events to this component too. You can get the session id:

        $poe_kernel->post( $query->get_session_id, ... );

do_shutdown

Initiates shutdown procedures and destroys the associated session

PING data

You receive the ping replies via the session/event you registered. There is no "filtering" capability and you get replies for all servers.

The event handler gets 2 arguments: the server object, and the response. The server object is the POE::Component::AssaultCube::ServerQuery::Server module. The response can either be undef or a Games::AssaultCube::ServerQuery::Response object.

Here's a sample ping handler:

        sub got_ping_data {
                my( $server, $response ) = @_[ARG0, ARG1];
                if ( defined $response ) {
                        print "response from(" . $server->ID . "): " $response->desc_nocolor .
                                " - " . $response->players . " players running\n";
                } else {
                        print "server " . $server->ID . " is not responding\n";
                }
        }

AUTHOR

Apocalypse <apocal@cpan.org>

Props goes to Getty and the BS clan for the support!

This project is sponsored by http://cubestats.net

COPYRIGHT AND LICENSE

Copyright 2009 by Apocalypse

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Games::AssaultCube

perl -MCPAN -e shell
install Games::AssaultCube