___  _   _   _    ___  _   _ _____
 / _ \| | | | / \  / _ \| | | |_   _|
| | | | | | |/ _ \| | | | | | | | |
| |_| | |_| / ___ \ |_| | |_| | | |
 \__\_\\___/_/   \_\__\_\\___/  |_|  0.2.0

-----------------------------------------------------------------------------

This simple program has been written to query Unreal Tournament 2004 (TM)
servers and retrieve information like those available while browsing
servers in the game.
That means: server name, game type and current map, names and scores of
players, and much more.

Quaqut is written in C, it compiles and runs on most UNIX-like systems
(Linux and BSD for example) and on Windows systems as well.

I wrote this program so I could check what is being played on servers
without launching the game each time (expecially useful when I have many
other programs running).

It can be also useful for generating some live stats by monitoring a server
at regular intervals and displaying output on a PHP page or such.

This software is released under GNU GPL (version 2 or upper).

Special thanks go to M.Hendriks for writing this nice page about
unrealengine2 server query protocol:
http://unreal.student.utwente.nl/UT2003-queryspec.html
That page and the wonderful software called Ethereal really helped me a lot.

The program has been planned to be quite scalable, it could be extended to
support other games someday :)


-----------------------------------------------------------------------------
USAGE INSTRUCTIONS

Quaqut is a command line program.
It works like this:

quaqut SERVERHOSTNAME

in example:
quaqut some.ut2004server.tld

If server listens for player connections on port different from 7777 (standard
ut2004 port), you have to specify it, as shown in the examples below.

quaqut -p 7777 some.ut2004server.tld
quaqut -p 12345 some.ut2004server.tld


Remeber, what you specify is the game port (the one you alway use to play),
which is not the query port.
Normally the query port is the one immediately after game port
(so if game port is 7777, query port will be 7778).
I don't know if this may come useful, but if you ever need to specify
directly the server query port, you can do it this way:

quaqut -q 7778 some.ut2004server.tld


By default, quaqut will show all information available for a server.
That includes server information, game information and players information
(if there are players). If you want to display only one between server, game
and players info, you'll use these flags, respectively:

quaqut -s some.ut2004server.tld
quaqut -g some.ut2004server.tld
quaqut -y some.ut2004server.tld


By default, quaqut will wait 10 tenths of second (one second) for server
replies (their number is not always predictable).
If you feel you have a very slow connection and need more time, or otherwise
have a fast connection or you are playing in a LAN game, you may want to tune
this timeout to your needs.
You can do it this way:

quaqut -t XXX some.ut2004server.tld

where XXX are tenths of second that quaqut must wait before returning.
XXX must be a number between 1 and 999.
In example:
quaqut -t 20 some.ut2004server.tld
will wait 20 tenth of second (2 seconds), and
quaqut -t 5 some.ut2004server.tld
will wait 5 tenth of second (half of second).


Version 0.2.0 introduces the daemon mode, which is expecially useful to
create php web pages with live stats. When quaqut is launched in daemon mode,
it doesn't exit after displaying information, but it keeps running.
So it retrieves and displays information at regular intervals, which are
user-definable. This is the syntax:

quaqut -d XXXX some.ut2004server.tld

where XXXX is the duration of interval between each query, in seconds.
XXXX must be a number between 10 and 9999.


Instead of printing information to standard output, you can write them
in a file, by using this option:

quaqut -f filename some.ut2004server.tld

Remember that the file gets rewritten each time there are new information
(so it works best with daemon mode). In order to append new information
to an existing file, simply use output redirection instead of this option.


Last but not least, by default information are returned in a human-readable
form, nicely formatted for being read.
If you want to parse the output yourself (within a frontend or script),
then you'll love the raw option:

quaqut -r some.ut2004server.tld

which will return each value for server/game/player on a single line.
You may find Hendriks' page useful if you need the meaning of each value.


Of course parameters can be combined (but you may specify only one between
a, s, g and y).
In example, here's the classic setup for a quaqut daemon, that writes
information to a file and updates them every 30 seconds.

quaqut -d 30 -f /home/bar/foo.log -r some.ut2004server.tld


If you need a quick view of available options, just type quaqut without
any parameter and you'll get to know everything :)
Information can be found in quaqut man page too.


I hope quaqut will be useful for you!

  Giacomo Lozito