View source for Source Server Query Library

== 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 ==

Include:
<source lang=cpp>
#include "ssq.h"
</source>

First, initialize SSQ:

<source lang=cpp>
SSQ_Initialize( false );
</source>

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):
<source lang=cpp>
SSQ_SetTimeout( SSQ_GS_TIMEOUT, 3000 ); // 3 seconds
</source>

Then, set the game server address:
<source lang=cpp>
bool connectionSuccess = SSQ_SetGameServer( "127.0.0.1:27015" );
</source>

If the connection was succesful, you can query the server, and if that succeeds, you can use the data:
<source lang=cpp>
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 );
	}
    }
}
</source>

When you're done using it, clean up:
<source lang=cpp>
SSQ_Initialize( true);
</source>

== Manual ==

=== Structures ===

==== SSQ_BATCH_REPLY ====
The SSQ_BATCH_REPLY structure is filled with raw game server addresses.

<source lang=cpp>
typedef struct{
long num_servers;
long data_size;
char* data;
}SSQ_BATCH_REPLY,
*PSSQ_BATCH_REPLY;
</source>

'''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.

<source lang=cpp>
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;
</source>

'''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.

<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.

=== Functions ===

==== SSQ_Callback ====

The SSQ_Callback function is an application-defined callback function.

<source lang=cpp>
BOOL WINAPI SSQ_Callback(
DWORD type,
PSSQ_REPLY_UNION reply
);
</source>

'''Parameters'''

[in]''type''

Type of the callback reply. This parameter can be one of the following values.

*SSQ_BATCH_REPLY_CALLBACK
List of game servers received from a master server.

*SSQ_LOG_REPLY_CALLBACK
A log received from a game server.

*SSQ_RCON_REPLY_CALLBACK
Response of a rcon command sent to a game server.

*SSQ_RULES_REPLY_CALLBACK
List of rules received from a game server.

*SSQ_LOG_THREAD_NOTIFY
Notification about the exit of the log thread.
The log status cannot be disabled when the log thread exited.


[in]''reply''

Pointer to a SSQ_REPLY_UNION union.


'''Return Values'''

The function should return TRUE to get all messages of a message loop.

If the function returns FALSE a message loop, if exists, will break.

'''Remarks'''

Make sure to use only the data in the reply union that corresponds to the type of the message.
The pointer in the reply union will only be valid in the context of the SSQ_Callback function.

==== SSQ_FormatBatchReply ====

The SSQ_FormatBatchReply function formats a raw data address into a dotted address string.

<source lang=cpp>
char* WINAPI SSQ_FormatBatchReply(
PSSQ_BATCH_REPLY batch_reply,
int index
);
</source>

'''Parameters'''

[in]''batch_reply''

Pointer to a SSQ_BATCH_REPLY structure.


[in]''index''

Index of the raw data address.


'''Return Values'''

If the function succeeds the return value is a pointer to a dotted address string.

If the function fails the return value is 0.

'''Remarks'''

The pointer returned is only valid till the next call of SSQ_FormatBatchReply.

==== SSQ_GetBatchReply ====

The SSQ_GetBatchReply function receives a list of game servers from the master server.

<source lang=cpp>
BOOL WINAPI SSQ_GetBatchReply(
BYTE region,
char* filter
);
</source>

'''Parameters'''

[in]''region''

Region to receive game servers from. This parameter can be one of the following values.

*SSQ_USA_EAST
*SSQ_USA_WEST
*SSQ_SOUTH_AMERICA
*SSQ_EUROPE
*SSQ_ASIA
*SSQ_AUSTRALIA
*SSQ_MIDDLE_EAST
*SSQ_AFRICA
*SSQ_WORLD

[in]''filter''

Filter strings delimted by a backslash "\". This parameter can be a combination of the following strings.

*"\\empty" "\\1"
Finds game servers not empty.

*"\\full" "\\1"
Finds game servers not full.

*"\\gamedir" (e.g. "\\cstrike")
Finds game servers running the specified game.

*"\\linux" "\\1"
Finds game servers running on Linux.

*"\\map" (e.g. "\\de_dust")
Finds game servers with the specified map.

*"\\proxy" "\\1"
Finds spectator-only servers.

*"\\secure" "\\1"
Finds game servers with Valve Anti-Cheat.


'''Return Values'''

If the function succeeds the return value is TRUE.

If the function fails the return value is FALSE.

'''Remarks'''

SSQ_GetBatchReply uses the server set by SSQ_SetMasterServer.
The game server data is sent to the SSQ_Callback callback function with a type of SSQ_BATCH_REPLY_CALLBACK.

==== SSQ_GetInfoReply ====

The SSQ_GetInfoReply function receives information about a game server.

<source lang=cpp>
BOOL WINAPI SSQ_GetInfoReply(
PSSQ_INFO_REPLY info_reply
);
</source>

'''Parameters'''

[out]''info_reply''

Pointer to a SSQ_INFO_REPLY structure that is filled by the function.


'''Return Values'''

If the function succeeds the return value is TRUE.

If the function fails the return value is FALSE.

'''Remarks'''

SSQ_GetInfoReply does not need authentication from the game server unlike SSQ_GetPlayerReply and SSQ_GetRulesReply.
SSQ_GetInfoReply uses the server set by SSQ_SetGameServer.


==== SSQ_GetPlayerReply ====

The SSQ_GetPlayerReply function receives details about the players on a game server.

<source lang=cpp>
BOOL WINAPI SSQ_GetPlayerReply(
PSSQ_PLAYER_REPLY player_reply
);
</source>

'''Parameters'''

[out]''player_reply''

Pointer to a SSQ_PLAYER_REPLY structure that is filled by the function.


'''Return Values'''

If the function succeeds the return value is TRUE.

If the function fails the return value is FALSE.

'''Remarks'''

SSQ_GetPlayerReply uses the server set by SSQ_SetGameServer.


==== SSQ_GetRconReply ====

The SSQ_GetRconReply function sends remote console commands and receives the reply.

<source lang=cpp>
BOOL WINAPI SSQ_GetRconReply(
char* password,
char* command
);
</source>

'''Parameters'''

[in]''password''

Remote console password.


[in]''command''

Remote console command.


'''Return Values'''

If the function succeeds the return value is TRUE.

If the function fails the return value is FALSE.

'''Remarks'''

The game server will ban a client address if the client has too many invalid password attempts.
The reply is sent to the SSQ_Callback callback function with a type of SSQ_RCON_REPLY_CALLBACK.

==== SSQ_GetRuleName ====

The SSQ_GetRuleName function returns a pointer to a rule name in the given rules structure.

<source lang=cpp>
char* WINAPI SSQ_GetRuleName(
PSSQ_RULES_REPLY rules_reply,
short index
);
</source>

'''Parameters'''

[in]''rules_reply''

Pointer to a SSQ_RULES_REPLY structure.


[in]''index''

Index of the rule.


'''Return Values'''

If the function succeeds the return value is a pointer to a rule name.

If the function fails the return value is 0.

'''Remarks'''

For the rules_reply parameter use a struct that was filled by the SSQ_GetRulesReply function.


==== SSQ_GetRuleValue ====

The SSQ_GetRuleValue function returns a pointer to a rule value in the given rules structure.

<source lang=cpp>
char* WINAPI SSQ_GetRuleValue(
PSSQ_RULES_REPLY rules_reply,
short index
);
</source>

'''Parameters'''

[in]''rules_reply''

Pointer to a SSQ_RULES_REPLY structure.


[in]''index''

Index of the rule.


'''Return Values'''

If the function succeeds the return value is a pointer to a rule value.

If the function fails the return value is 0.

'''Remarks'''

For the rules_reply parameter use a struct that was filled by the SSQ_GetRulesReply function.

==== SSQ_GetRulesReply ====

The SSQ_GetRulesReply function receives a list of game rules from the game server.

<source lang=cpp>
BOOL WINAPI SSQ_GetRulesReply();
</source>

'''Parameters'''

This function has no parameters.


'''Return Values'''

If the function succeeds the return value is TRUE.

If the function fails the return value is FALSE.

'''Remarks'''

SSQ_GetRulesReply uses the server set by SSQ_SetGameServer.
The game rules are sent to the SSQ_Callback callback function with a type of SSQ_RULES_REPLY_CALLBACK.

==== SSQ_Initialize ====

The SSQ_Initialize function initializes or exits the SSQ module.

<source lang=cpp>
BOOL WINAPI SSQ_Initialize(
BOOL exit
);
</source>

'''Parameters'''

[in]''exit''

If TRUE exits, if FALSE initializes.


'''Return Values'''

If the function succeeds the return value is TRUE.

If the function fails the return value is FALSE.

'''Remarks'''

SSQ_Initialized has to be called before and after using SSQ functions. Do not proceed if initialization fails.

==== SSQ_Ping ====

The SSQ_Ping function returns the latency of the current game server.

<source lang=cpp>
DWORD WINAPI SSQ_Ping();
</source>

'''Parameters'''

This function has no parameters.


'''Return Values'''

If the function succeeds the return value is the latency to the game server in milliseconds.

If the function fails the return value is 0xFFFFFFFF.

'''Remarks'''

SSQ_Ping uses the server set by SSQ_SetGameServer.

==== SSQ_SetCallbackAddress ====


The SSQ_SetCallbackAddress function sets the function that will receive callback messages.

<source lang=cpp>
BOOL WINAPI SSQ_SetCallbackAddress(
SSQ_CALLBACK callback
);
</source>

'''Parameters'''

[in]''callback''

Address of the callback function.
For more information about the function, see SSQ_Callback.


'''Return Values'''

If the function succeeds the return value is TRUE.

If the function fails the return value is FALSE.

'''Remarks'''

A callback must be set for the functions SSQ_GetBatchReply, SSQ_GetRconReply, SSQ_GetRulesReply and SSQ_SetLogStatus.

==== SSQ_SetGameServer ====

The SSQ_SetGameServer function sets the current game server.

<source lang=cpp>
BOOL WINAPI SSQ_SetGameServer(
char* address
);
</source>

'''Parameters'''

[in]''address''

The address of the game server to set. Can be a numerical address with port or a hostname address with port in the form "127.0.0.1:27015" or "localhost:27015".


'''Return Values'''

If the function succeeds the return value is TRUE.

If the function fails the return value is FALSE.

'''Remarks'''

SSQ_SetGameServer is needed for the functions SSQ_GetInfoReply, SSQ_GetPlayerReply, SSQ_GetRconReply, SSQ_GetRulesReply and SSQ_Ping.


==== SSQ_SetLogStatus ====

The SSQ_SetLogStatus function enables or disables the listening for incoming logs.

<source lang=cpp>
BOOL WINAPI SSQ_SetLogStatus(
BOOL status,
USHORT port
);
</source>

'''Parameters'''

[in]''status''

Logging status.


[in]''port''

Port to listen on.


'''Return Values'''

If the function succeeds the return value is TRUE.

If the function fails the return value is FALSE.

'''Remarks'''

Make sure that the port is forwarded if the client is behind a router/firewall.
The port must not be used by another application.
Logging is off by default. The port parameter is ignored if status is FALSE.

To activate and change the log on the game server use the following remote console commands.

*log
*logaddress_add
*logaddress_del
*logaddress_delall
*logaddress_list
*mp_logdetail
*sv_log_onefile
*sv_logbans
*sv_logblocks
*sv_logdownloadlist
*sv_logecho
*sv_logfile
*sv_logsdir

Look in the game documentation to get details about the commands.
The logs are sent to the SSQ_Callback callback function with a type of SSQ_LOG_REPLY_CALLBACK.

==== SSQ_SetMasterServer ====

The SSQ_SetMasterServer function sets the current master server.

<source lang=cpp>
BOOL WINAPI SSQ_SetMasterServer(
char* address
);
</source>

'''Parameters'''

[in]''address''

The address of the master server to set. Can be a numerical address with port or a hostname address with port in the form "207.173.177.11:27011" or "steam1.steampowered.com:27011".


'''Return Values'''

If the function succeeds the return value is TRUE.

If the function fails the return value is FALSE.

'''Remarks'''

SSQ_SetMasterServer is needed for the function SSQ_GetBatchReply.

==== SSQ_SetTimeout ====

The SSQ_SetTimeout function sets the time that SSQ functions will wait for sending and receiving packets.

<source lang=cpp>
BOOL WINAPI SSQ_SetTimeout(
DWORD type,
int timeout
);
</source>

'''Parameters'''

[in]''type''

Specifies the function group to set the timeout value for.
This parameter can be a combination of the following flags.

*SSQ_GS_TIMEOUT
*SSQ_GetInfoReply
*SSQ_GetPlayerReply
*SSQ_GetRulesReply
*SSQ_Ping
*SSQ_SetGameServer
*SSQ_LOG_TIMEOUT
*SSQ_LogThread (internal function)
*SSQ_SetLogStatus
*SSQ_MS_TIMEOUT
*SSQ_GetBatchReply
*SSQ_SetMasterServer
*SSQ_RCON_TIMEOUT
*SSQ_GetRconReply


[in]''timeout''

Time in milliseconds to wait.


'''Return Values'''

If the function succeeds the return value is TRUE.

If the function fails the return value is FALSE.

'''Remarks'''

The default timeout value is 0 for infinite.

== Download ==

Binary:
[http://www.cecco.keepfree.de/SSQ/SSQbeta1.zip SSQbeta1.zip]

Source:
[http://www.cecco.keepfree.de/SSQ/SSQbeta2_src.zip SSQbeta2_src.zip]

Mirror:
[https://github.com/mpapierski/ssq on github]

Source, modified for use in the Source engine (Windows):
[http://www.cecco.keepfree.de/SSQ/ssq.c]
[http://www.cecco.keepfree.de/SSQ/ssq.h]
(Just include ssq.h and you're in business)

== Fixes ==

uhx : Hey guys, theres error in the SSQ_GetPlayerReply function. 

You should add this code 

<source lang=cpp>
// Receiving FF FF FF FF 41 .. .. .. ..
if(recv(ssq_socket[SSQ_UDP_GS], rs_buffer, max_rs_size, 0) < 1)
	return FALSE;

if(rs_buffer[4] != S2C_CHALLENGE)
	return FALSE;
// FF FF FF FF 55 .. .. .. ..
rs_buffer[4] = 0x55;
// Sending CHALLENGE NUMBER
send(ssq_socket[SSQ_UDP_GS], rs_buffer, A2S_PLAYER_LENGTH, 0);
</source>

after A2S_PLAYER request ( send(ssq_socket[SSQ_UDP_GS],A2S_PLAYER,A2S_PLAYER_LENGTH,0) )

[[Category:Programming]]

==See==
[[Server Queries]]