Difference between revisions of "Source Server Query Library"

From Valve Developer Community
Jump to: navigation, search
(Added how to use + some basic information from the manual)
(Manual: Added rest of structures and unions)
Line 164: Line 164:
  
 
Strings are truncated if they are longer than the buffer.
 
Strings are truncated if they are longer than the buffer.
 +
 +
==== SSQ_PLAYER_ITEM ====
 +
 +
The SSQ_PLAYER_ITEM structure contains player details.
 +
 +
<source lang=cpp>
 +
typedef struct{
 +
char index;
 +
char player_name[32];
 +
long kills;
 +
float time_connected;
 +
}SSQ_PLAYER_ITEM,
 +
*PSSQ_PLAYER_ITEM;
 +
</source>
 +
 +
'''Members'''
 +
 +
*'''index'''
 +
Slot index of the player on the game server.
 +
 +
*'''player_name'''
 +
Name of the player as a string.
 +
 +
*'''kills'''
 +
All kills the player made.
 +
 +
*'''time_connected'''
 +
Time that passed since the player joined the game server.
 +
 +
'''Remarks'''
 +
 +
The index member will be -1 and the other members 0 when the player is just connecting.
 +
 +
==== SSQ_PLAYER_REPLY ====
 +
 +
The SSQ_PLAYER_REPLY structure is filled with details of players on a game server.
 +
 +
<source lang=cpp>
 +
typedef struct{
 +
char num_players;
 +
SSQ_PLAYER_ITEM player[64];
 +
}SSQ_PLAYER_REPLY,
 +
*PSSQ_PLAYER_REPLY;
 +
</source>
 +
 +
'''Members'''
 +
 +
*'''num_players'''
 +
Number of players on the game server.
 +
 +
*'''player'''
 +
Array of a SSQ_PLAYER_ITEM structure.
 +
 +
'''Remarks'''
 +
 +
The num_players member includes players that are just connecting and whose details are not yet available.
 +
 +
==== SSQ_RULES_REPLY ====
 +
 +
The SSQ_RULES_REPLY structure is filled with rules from a game server.
 +
 +
<source lang=cpp>
 +
typedef struct{
 +
short num_rules;
 +
long data_size;
 +
char* data;
 +
}SSQ_RULES_REPLY,
 +
*PSSQ_RULES_REPLY;
 +
</source>
 +
 +
'''Members'''
 +
 +
*'''num_rules'''
 +
Number of rules.
 +
 +
*'''data_size'''
 +
Size of the data pointed to by data.
 +
 +
*'''data'''
 +
Pointer to the rule strings.
 +
 +
'''Remarks'''
 +
 +
The rules are in the order "rule name","rule value". All strings are null-terminated.
 +
 +
=== Unions ===
 +
 +
==== SSQ_REPLY_UNION ====
 +
 +
The SSQ_REPLY_UNION union contains a pointer to callback reply data or a notification.
 +
 +
<source lang=cpp>
 +
 +
typedef union{
 +
PSSQ_BATCH_REPLY batch_reply;
 +
char* log_reply;
 +
PSSQ_RULES_REPLY rules_reply;
 +
char* rcon_reply;
 +
BOOL log_notify
 +
}SSQ_REPLY_UNION,
 +
*PSSQ_REPLY_UNION;
 +
</source>
 +
 +
'''Members'''
 +
 +
*'''batch_reply'''
 +
Pointer to a SSQ_BATCH_REPLY structure.
 +
 +
*'''log_reply'''
 +
Pointer to a log string.
 +
 +
*'''rules_reply'''
 +
Pointer to a SSQ_RULES_REPLY structure.
 +
 +
*'''rcon_reply'''
 +
Pointer to a rcon string.
 +
 +
*'''log_notify'''
 +
TRUE if the log thread exited normally, FALSE if an error occured.
 +
 +
'''Remarks'''
 +
 +
Use the type parameter in the SSQ_Callback function to see which member is valid.
  
 
== Download ==
 
== Download ==

Revision as of 06:49, 28 August 2013

About

The Source Server Query Library simplifies the communication with Source game servers and Source master servers.

You do not have to deal with the Source Server Query Protocol and can focus on integrating the library into e.g. a game browser, a remote console application etc.

With Source Server Query Library you can:

  • Get latency times of game servers
  • Receive general information about game servers
  • Receive player details of players on game servers
  • Receive game rules of game servers
  • Receive logs of game servers
  • Receive a list of game servers from a master server
  • Send remote commands to game servers and receive the responses

Author

Pascal Herget

Languages

Currently only for C/C++.

How to use

First, initialize SSQ:

SSQ_Initialize( false );

It's also a smart idea to set the timeout to something else than infinity (note: this currently only works for listening to messages, not to connection attempts with the server):

SSQ_SetTimeout( SSQ_GS_TIMEOUT, 3000 ); // 3 seconds

Then, set the game server address:

bool connectionSuccess = SSQ_SetGameServer( "127.0.0.1:27015" );

If the connection was succesful, you can query the server, and if that succeeds, you can use the data:

if( connectionSuccess )
}
    PSSQ_INFO_REPLY reply = new SSQ_INFO_REPLY; // Watch out! Memory leak here! Make this a private member that is cleaned up appropriately.
    if( SSQ_GetInfoReply( reply ) )
    {
        char logmsg[4];
        if( reply )
	{
	    Q_snprintf( logmsg, sizeof(logmsg), "%c", reply ->dedicated );
	    Log( (const char*) logmsg );
	}
    }
}

When you're done using it, clean up:

SSQ_Initialize( true);

Manual

Structures

SSQ_BATCH_REPLY

The SSQ_BATCH_REPLY structure is filled with raw game server addresses.

typedef struct{
long num_servers;
long data_size;
char* data;
}SSQ_BATCH_REPLY,
*PSSQ_BATCH_REPLY;

Members

  • num_servers

Number of game server addresses.

  • data_size

Size of the data pointed to by data.

  • data

Pointer to the raw game server addresses.

Remarks

The addresses are stored as an array of 6 byte addresses (4 byte numerical address + 2 byte port). The last address (in a complete callback loop) is 0 for all 6 bytes.

SSQ_INFO_REPLY

The SSQ_INFO_REPLY structure is filled with information about a game server.

typedef struct{
char version;
char hostname[256];
char map[32];
char game_directory[32];
char game_description[256];
short app_id;
char num_players ;
char max_players;
char num_of_bots;
char dedicated;
char os;
char password;
char secure;
char game_version[32];
}SSQ_INFO_REPLY,
*PSSQ_INFO_REPLY;

Members

  • version

Network protocol version of the game server.

  • hostname

Hostname of the game server.

  • map

Current map on the game server.

  • game_directory

Game directory of the game server.

  • game_description

Description of the game running on the game server.

  • app_id

Steam Application Identifier.

  • num_players

Current number of players on the game server.

  • max_players

Maximum allowed players on the game server.

  • num_of_bots

Current number of bots on the game server.

  • dedicated

Value is "d" for dedicated server and "l" for listen server.

  • os

Value is 'l' for Linux and 'w' for Windows. OS running on the game server.

  • password

Value is 1 if the game server is password protected.

  • secure

Value is 1 if the game server has Valve Anti-Cheat.

  • game_version

Version of the game running on the game server.

Remarks

Strings are truncated if they are longer than the buffer.

SSQ_PLAYER_ITEM

The SSQ_PLAYER_ITEM structure contains player details.

typedef struct{
char index;
char player_name[32];
long kills;
float time_connected;
}SSQ_PLAYER_ITEM,
*PSSQ_PLAYER_ITEM;

Members

  • index

Slot index of the player on the game server.

  • player_name

Name of the player as a string.

  • kills

All kills the player made.

  • time_connected

Time that passed since the player joined the game server.

Remarks

The index member will be -1 and the other members 0 when the player is just connecting.

SSQ_PLAYER_REPLY

The SSQ_PLAYER_REPLY structure is filled with details of players on a game server.

typedef struct{
char num_players;
SSQ_PLAYER_ITEM player[64];
}SSQ_PLAYER_REPLY,
*PSSQ_PLAYER_REPLY;

Members

  • num_players

Number of players on the game server.

  • player

Array of a SSQ_PLAYER_ITEM structure.

Remarks

The num_players member includes players that are just connecting and whose details are not yet available.

SSQ_RULES_REPLY

The SSQ_RULES_REPLY structure is filled with rules from a game server.

typedef struct{
short num_rules;
long data_size;
char* data;
}SSQ_RULES_REPLY,
*PSSQ_RULES_REPLY;

Members

  • num_rules

Number of rules.

  • data_size

Size of the data pointed to by data.

  • data

Pointer to the rule strings.

Remarks

The rules are in the order "rule name","rule value". All strings are null-terminated.

Unions

SSQ_REPLY_UNION

The SSQ_REPLY_UNION union contains a pointer to callback reply data or a notification.

typedef union{
PSSQ_BATCH_REPLY batch_reply;
char* log_reply;
PSSQ_RULES_REPLY rules_reply;
char* rcon_reply;
BOOL log_notify
}SSQ_REPLY_UNION,
*PSSQ_REPLY_UNION;

Members

  • batch_reply

Pointer to a SSQ_BATCH_REPLY structure.

  • log_reply

Pointer to a log string.

  • rules_reply

Pointer to a SSQ_RULES_REPLY structure.

  • rcon_reply

Pointer to a rcon string.

  • log_notify

TRUE if the log thread exited normally, FALSE if an error occured.

Remarks

Use the type parameter in the SSQ_Callback function to see which member is valid.

Download

Binary: SSQbeta1.zip

Source: SSQbeta2_src.zip

See

Server Queries