Click here to Skip to main content
15,867,686 members
Articles / Programming Languages / C#

A gameserver Query Library

Rate me:
Please Sign up or sign in to vote.
4.79/5 (21 votes)
26 Dec 20047 min read 228.5K   5K   48   66
A library that allows to query nearly all gameserver types

Sample Image - GameServerInfo.jpg

Introduction

Most gaming servers support status queries to get information like server configuration or the number of players. There are some programs that query master servers to receive all IPs from the gaming servers and list them. The most popular ones are Gamespy, The All Seeing Eye and kQuery.

I did not intend to build another program with just the same functionality, but to create a library that allows easy handling to query the servers and offering their information on your special purpose.

Background

The status queries use specific protocols: the most common are Doom3, Gamespy, Gamespy v2, Half-Life, Quake3, Source (Half-Life 2) and The All Seeing Eye (ASE). These protocols provide basically the same information, but their structure is different. In general, there are three sections:

Infos

The basic information like server name, map name, maximum players and password protection.

Rules

The detailed server information with game specific data like teams or response time.

Players

A list of all players on the server. These information differs a lot: the different protocols have only the player name in common, depending on the protocol there are also the players' score, ping or team.

Protocol Overview

Here is a short overview of the different protocols and how they work:

Doom3

This protocol is currently used only in so called game, but will probably be used in upcoming games built on the same engine. The request starts with a 0xFF 0xFF, followed by a simple getInfo. The server response comes in one big block and is separated by 0x00. That makes the response look like a Key0x00Value – the server information and the player information are separated by a 0x00 0x00 (a double NULL).

Gamespy

Gamespy is one of the oldest and most broadly used protocols. Its structure is very simple: to get the server's information, you just need to send a simple \info\; for the rules, send \rules\; and for the players, \players\. You can also combine these requests by sending something like \infos\\players\\rules\.

The response looks like \Key\Value\Key\Value\, the player info is extended with an integer to group them. They look like \player_0\Name\frags_0\10\ping_0\100\. This is important because some servers send all \player_x\ flags, followed by all \frags_x\ and so on.

Gamespy v2

The name indicates, Gamespy v2 is the revision of the Gamespy protocol. It differs from the first version by managing information more with byte values than with strings. All requests begin with a 0xFE 0xFD 0x00, followed by a string that is used as a ping value. Now we append three more bytes which stand for the information we want to know: the first byte for server information, the second for rules and the third for players. You can set them with 0x00 for NO or 0xFF for YES. The structure of the response is the same as in Doom3.

Half-Life

The request starts with a 0xFF 0xFF 0xFF 0xFF, followed by details, rules or players, so it is pretty much the same as in Gamespy v2, but with strings. The structure of the response is the same as in Doom3.

Quake3

The request is similar to Half-Life: we start with a 0xFF 0xFF 0xFF 0xFF, followed by the string getstatus. The response includes all information in multiple text lines and can be handled with simple string parsing. The first line can be ignored, the second provides the server information in the same format as in Gamespy, (\Key\Value\Key\Value\). The following lines represent the player information, one player per line, in the form Scores Ping „Playername“.

Source (Half-Life 2)

The request structure is nearly the same as in the former Half-Life protocol: only the strings are replaced with single bytes. The query now starts with 0xFF 0xFF 0xFF 0xFF, followed by 0x54 for the server information, 0x55 for the rules and 0x56 for the player information. The structure of the response is the same as in Doom3.

The All Seeing Eye (ASE)

The protocol to the homonymous program is the most complex and also the rarely used one. The request is a simple s, but different from all other protocols. The query must be sent to the server port + 123, so don't send to the game server port. The response is a little bit more difficult, because it has no separators: The structure is „Byte String Byte String“, in which the byte represents the length of the next string, (the byte is self-including). The separator between the server and player information is an empty string, so it's the length of the byte itself - a simple 0x01. The player information looks similar, but starts with an extra byte by using the flags telling which information is included. I do not describe this protocol any further, the only games currently using this protocol are GTA and Farcry.

An excellent documentation and samples for all of these protocols can be found in the newsgroups dev.int64 and dev.kquery, which I used while creating this library.

Using the Code

Using the library is very simple. First, include it in your project, and then simply call it as shown:

C#
GameServer server = new GameServer( "192.168.0.15", 27960, GameType.Quake3 );
Server.QueryServer(); // this may take a while

QueryServer() gets all the information from the server. Depending on the timeout, this may take a while. You can change this with the Timeout property.

C#
Server.Timeout = 1500; // in milliseconds

The basic information is available over properties and collections, depending on which protocol you are querying. Not all values are set. Here are the diagrams for all of them:

Image 2

Using the Players property, you can get a PlayerCollection containing the following data:

Image 3

The Parameters property contains a StringCollection with all information from the server. The values strongly depend on the protocols being used!

Connecting to Servers

The complete connection and parsing process is handled through the abstract protocol class. Here is the main connection part:

C#
protected void Connect( string host, int port )
{
    _serverConnection = new Socket( AddressFamily.InterNetwork, 
        SocketType.Dgram, ProtocolType.Udp );
    _serverConnection.SetSocketOption( SocketOptionLevel.Socket, 
        SocketOptionName.ReceiveTimeout, _timeout );
    IPAddress ip;
    try
    {
        ip = IPAddress.Parse( host );
    }
    catch( System.FormatException )
    {
        ip = Dns.Resolve( host ).AddressList[0];
    }
    _remoteIpEndPoint = new IPEndPoint( ip, port );
}

Server Communication

The communication always uses UDP supplied by the methods Socket.SendTo() and Socket.ReceiveFrom().

C#
_readBuffer = new byte[100 * 1024]; // 100kb should be enough
EndPoint _remoteEndPoint = (EndPoint)_remoteIpEndPoint;
_packages = 0;
int read = 0, bufferOffset = 0;

// Request
_sendBuffer = System.Text.Encoding.Default.GetBytes( request );
_serverConnection.SendTo( _sendBuffer, _remoteIpEndPoint );
...
read = _serverConnection.ReceiveFrom( _readBuffer, ref _remoteEndPoint );

Most servers send packages with a maximum length of 1400 to 1500 bytes. For long status information, this is not enough memory to send it in one package. Usually, they fit into two packets. UDP is a stateless connection, so we must implement how to handle these multi-packages and how to merge them.

Half-Life

In Half-Life, these UDP-packages start with a 9 byte-long header, different from single-package responses. The ninth position is telling us how many packages the response includes, and which package we are currently working on.

C#
byte[] _tempBuffer = new byte[100 * 1024];
read = _serverConnection.ReceiveFrom( 
  _tempBuffer, ref _remoteEndPoint );

int packets = ( _tempBuffer[8] & 15 );
int packetNr = ( _tempBuffer[8] >> 4 ) + 1;

if ( packetNr < packets )
{
    Array.Copy( _readBuffer, 9, _tempBuffer, read, bufferOffset );
    _readBuffer = _tempBuffer;
}
else
{
    Array.Copy( _tempBuffer, 9, _readBuffer, bufferOffset, read );
}

Gamespy v1 and v2

All Gamespy responses are built in a Key/Value scheme, so it doesn’t really matter if we merge them in the right order. The protocol itself is smart enough to always split at a separator and not inside a value, so we can simply attach them at the end of the readBuffer.

C#
read = _serverConnection.ReceiveFrom( _readBuffer, bufferOffset, 
    ( _readBuffer.Length - bufferOffset ), 
      SocketFlags.None, ref _remoteEndPoint );

Parsing the Response

The main part of parsing the strings that are separated by a NULL byte (0x00):

C#
protected string ReadNextParam()
{
    string temp = "";
    for ( ; _offset < _readBuffer.Length; _offset++ )
    {
        if ( _readBuffer[_offset] == 0 )
        {
            _offset++;
            break;
        }
        temp += (char)_readBuffer[_offset];
    }
    return temp;
}

String-separated responses are even more simple:

C#
AddParams( ResponseString.Split( '\\' ) );
//...
protected void AddParams( string[] parts )
{
    if ( !IsOnline )
    {
        return;
    }
    string key, val;
    for ( int i = 0; i < parts.Length; i++ )
    {
        if ( parts[i] == "" )
        {
            continue;
        }
        key = parts[i++];
        val = parts[i];

        // Gamespy uses this
        if ( key == "final" )
        {
            break;
        }
        if ( key == "querid" )
        {
            continue;
        }

        _params[key] = val;
    }
}

I avoided explaining how to parse the ASE protocol, because it doesn’t work 100%. I’m missing some good documentation, and it seems that many people besides me are also thinking that it’s not worth the work.

Links

I can't thank enough these guys. For more information, check these pages:

Summary

I learned something about UDP protocol and used classes and methods I never used before, like the BitConverter(), so I think it was worth the work. I hope this library can be useful in your future projects.

License

This article has no explicit license attached to it, but may contain usage terms in the article text or the download files themselves. If in doubt, please contact the author via the discussion board below.

A list of licenses authors might use can be found here.


Written By
Web Developer
Germany Germany
This member has not yet provided a Biography. Assume it's interesting and varied, and probably something to do with programming.

Comments and Discussions

 
GeneralRe: Can't get it to work Pin
Diep-Virezer20-Dec-05 5:56
Diep-Virezer20-Dec-05 5:56 
QuestionAny advice for C++? Pin
RancidCrabtree16-Aug-05 14:35
RancidCrabtree16-Aug-05 14:35 
AnswerRe: Any advice for C++? Pin
Franz Pentenrieder16-Aug-05 20:05
Franz Pentenrieder16-Aug-05 20:05 
GeneralSacred Pin
GoWIcky13-Mar-05 12:39
sussGoWIcky13-Mar-05 12:39 
GeneralRe: Sacred Pin
Franz Pentenrieder13-Mar-05 20:42
Franz Pentenrieder13-Mar-05 20:42 
QuestionQuery NWServer known? Pin
Radeldudel4-Jan-05 21:25
Radeldudel4-Jan-05 21:25 
AnswerRe: Query NWServer known? Pin
Franz Pentenrieder4-Jan-05 21:51
Franz Pentenrieder4-Jan-05 21:51 
GeneralFix To Exceptions Being Thrown Pin
22-Dec-04 19:33
suss22-Dec-04 19:33 
GeneralRe: Fix To Exceptions Being Thrown Pin
Franz Pentenrieder26-Dec-04 19:44
Franz Pentenrieder26-Dec-04 19:44 
GeneralSlow :( Pin
SARPKAYA10-Dec-04 10:24
SARPKAYA10-Dec-04 10:24 
GeneralRe: Slow :( Pin
Franz Pentenrieder10-Dec-04 11:31
Franz Pentenrieder10-Dec-04 11:31 
GeneralRe: Slow :( Pin
SARPKAYA11-Dec-04 19:03
SARPKAYA11-Dec-04 19:03 
QuestionDo you know of any RCON Support? Pin
James Cline2-Dec-04 2:43
James Cline2-Dec-04 2:43 
QuestionWhich tool you use to paint the diagrams of the classes??? Pin
Anonymous29-Nov-04 6:07
Anonymous29-Nov-04 6:07 
AnswerRe: Which tool you use to paint the diagrams of the classes??? Pin
Franz Pentenrieder29-Nov-04 12:28
Franz Pentenrieder29-Nov-04 12:28 
Generalnice Pin
Almighty Bob20-Nov-04 17:44
Almighty Bob20-Nov-04 17:44 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.