GameQuery
Protocols
Documents
Index

GameQuery

The GameQuery package is meant to be used as a class factory for creating server monitors with the Monitor static method, called from the base class.

// include the base class using an absolute path
require_once("/home/share/GameQuery/GameQuery.php");

// create a monitor instance
$monitor = GameQuery::Monitor('MyNewProtocol', '99.99.99.1:9999', $options );

The base class, as the name implies, can also be extended for implementing new query protocols.

require_once("GameQuery.php");

// implement a new protocol class
class GQProtocol_MyNewProtocol extends GameQuery {
  ...
}

Each extension of this class is meant to cover an individual protocol by reimplementing the following functions.

The remaining functions (some public, some protected, and some private) are fully implemented in this class and are not meant to be overridden in any extensions.

Additionally, the displaying of query data is handled using specially constructed PHP template files, by using specially provided variables.

// the entire query data structure is provided in this variable
print_r( $_GAMEQUERY );

// the complete filename of the template is provided in this variable
print( $_TEMPLATEFILE );

// templates should return control when complete, rather than exiting
return;
Summary
GameQuery
The GameQuery package is meant to be used as a class factory for creating server monitors with the Monitor static method, called from the base class.
Global Constants
These go in the global scope, rather than the scope of the base class, and affect general error-handling and reporting behavior of the library classes.
Member Variables
Member Constants
Base Methods
These methods are provided statically in, and are meant to be called from, the base GameQuery class.
Monitor
Factory for creating monitor instances (also known as monitor objects) using the given protocol.
supported_protocols
Method for returning all protocols found in the include_path, as an array.
supported_templates
Method for returning all templates found in the include_path, as an array.
Inherited Methods
These methods, implemented in the base class, are meant to be inherited and invoked by extending classes.
__construct
Constructor, implemented by base class, to be inherited and used by extender classes.
get_raw
Member method for returning the raw response string(s) from a query.
get_struct
Method for returning response data after it has been broken down into a structure (typically composed of nested arrays).
Reimplemented Methods
These methods, hollowly defined in the base class, are meant to be reimplemented in the extending classes to accomodate differing protocols and games.
_communicate
Internal method for the gory details of sending request strings and recieving response strings through direct socket communications.
_request
Internal method for constructing request strings that will be sent to the host server.
_response
Internal method for parsing response strings that will be sent to the host server.
_validate
Internal method for validating that a host string is suitable for the current protocol and breaking it down into a dns/ip address and port number.
get_template
Public method for displaying a processed query in an aesthetically pleasing format.
supported_configs
Method for returning an array of configuration directives supported by the current class, where the key is a directive name, and the value is a brief description of the directive.
Internal Methods
These methods are for use internally within the base class.
add_include_paths
Private method for adding new directories to the include_path.
get_include_delimiter
Private method for calculating the include_path delimiter character, which varies depending on the host operating system.
get_include_paths
Private method for retrieving seperated paths from the include_path.
include_capture
Private method for including and executing a PHP file within a confined scope (providing it the parsed query as a data structure), and caputuring and returning the output.
Utility Methods
These methods are provided as part of the GameQuery class to make the parsing of response strings, and thus the implementation of new game protocols, much simpler.
_unpack_float32
Static method for removing and returning a 32-bit (4 byte) float from an array of bytes.
_unpack_int16
Static method for removing and returning a 16-bit (2 byte) integer from an array of bytes.
_unpack_int32
Static method for removing and returning a 32-bit (4 byte) integer from an array of bytes.
_unpack_byte
Static method for removing and returning the numeric ordinal of a byte from an array of bytes.
_unpack_cstring
Static method for removing and returning a null-terminated string (aka c-string) from an array of bytes.
_unpack_fstring
Static method for removing and returning a fixed-length string from an array of bytes.

Global Constants

These go in the global scope, rather than the scope of the base class, and affect general error-handling and reporting behavior of the library classes.  Enabling these facilities simply requires defining the appropriate constants as true values.  By default, these are defined as false when the base class file is loaded.

GQ_DEBUGThis causes verbose debugging information such as call stack tracing and data structure dumping to be printed.
GQ_STRICTThis causes any error to terminate the current script, even minor errors that would normally be bypassed to allow execution to continue.
GQ_WARNINGSThis causes any non-fatal errors to print warning messages.

Member Variables

$protocolA monitor instance’s protocol.
$hostnameA monitor instance’s hostname (usually an ip address).
$portnumberA monitor instance’s port number.
$query_rawA monitor instance’s unprocessed response text, normally some type of binary string.
$query_structA monitor instance’s processed response structure, normally a series of nested associative arrays.

Member Constants

BASE_CLASSUsed for internal error-checking.
SOCKET_TIMEOUTLength of time (in seconds) to wait for a socket response during queries.
PROTOCOL_PREFIXPrefix of an extension class that implements a new protocol.
PROTOCOL_POSTFIXPostfix of an extension class that implements a new protocol.
TEMPLATE_PREFIXPrefix of a template file that displays query data.
TEMPLATE_POSTFIXPostfix of a template file that displays query data.

Base Methods

These methods are provided statically in, and are meant to be called from, the base GameQuery class.

Monitor

public static function Monitor($protocol =  NULL,
$host =  NULL,
$options =  array())

Factory for creating monitor instances (also known as monitor objects) using the given protocol.  This is intended to be called as a static method of the base class.

Note that, if caching is enabled and a new enough cache file is found for the given combination of host and protocol, the cached query data will be used instead of performing a new query.

Parameters

$protocolString representing a specific supported protocol.
$hostString representing a specific server (usually an ip and port).
$optionsOptional associative array of directives to control module behavior.

Returns

An object of the extended class for the given protocol.

supported_protocols

public function supported_protocols()

Method for returning all protocols found in the include_path, as an array.  This can be invoked as either a static class method, or as an object method.  It should be noted that the path of the current classfile is added to the include_path if necessary.

// invoking as a static method
$protocols = GameQuery::supported_protocols();

// invoking as a method of a class object
$monitor = GameQuery::Monitor('MyNewProtocol', '99.99.99.1:9999');
$protocols = $monitor->supported_protocols();

Parameters

None

Returns

An array of viable supported_protocols (extending classes implementing a specific protocol).

supported_templates

public function supported_templates()

Method for returning all templates found in the include_path, as an array.  This can be invoked as either a static class method, or as an object method.  It should be noted that the path of the current classfile is added to the include_path if necessary.

// invoking as a static method
$templates = GameQuery::supported_templates();

// invoking as a method of a class object
$monitor = GameQuery::Monitor('MyNewProtocol', '99.99.99.1:9999');
$templates = $monitor->supported_templates();

Parameters

None

Returns

An array of viable supported_templates (scripts displaying information specific to a protocol and/or gametype).

Inherited Methods

These methods, implemented in the base class, are meant to be inherited and invoked by extending classes.

__construct

public function __construct($hostarg =  NULL,
$options =  NULL)

Constructor, implemented by base class, to be inherited and used by extender classes.  Initializes values, executes queries of game server, and processes responses using inherited member methods.

Should not be invoked directly, see Monitor static method.

Parameters

$hostargString representing a specific server (usually an ip and port).  This will be passed through to the _validate method.
$optionsOptional associative array of directives to control module behavior.

get_raw

public function get_raw()

Member method for returning the raw response string(s) from a query.

Parameters

None

Returns

A string or array of strings.

get_struct

public function get_struct()

Method for returning response data after it has been broken down into a structure (typically composed of nested arrays).

Parameters

None

Returns

A nested array structure of a query response.

Reimplemented Methods

These methods, hollowly defined in the base class, are meant to be reimplemented in the extending classes to accomodate differing protocols and games.  The exceptions to this are the _communicate and _validate methods, the standard implementations of which should suit most protocools.

_communicate

protected function _communicate($requests =  array())

Internal method for the gory details of sending request strings and recieving response strings through direct socket communications.

By default, it is implemented as a one-to-one protocol of sending a request and getting a usable response via a UDP socket.  While this is sufficient for many protocols, some require more complex logic, such as challenge-response systems, and yet others may not use UDP communications.

Parameters

$requestsAn array of request strings to be sent to the server.

Returns

An array of strings containing server response data.

_request

protected function _request($options =  NULL)

Internal method for constructing request strings that will be sent to the host server.  Typically, any variations in the way request strings are built would be due to the options passed to the Monitor method.

By default, it is unimplemented (returns NULL).  Since this is heavily protocol-dependant, it must be implemented in the extending protocol class, and should return a string or array of strings.

Parameters

$optionsOptional associative array of directives to control module behavior.

Returns

A string or array of strings containing server request data.

_response

protected function _response($response =  NULL)

Internal method for parsing response strings that will be sent to the host server.

By default, it is unimplemented (returns NULL).  Since this is heavily protocol-dependant, it must be implemented in the extending protocol class.

Parameters

$responseUnprocessed response string.

Returns

A nested array structure derived from the server response data.

_validate

protected function _validate($hostname =  NULL)

Internal method for validating that a host string is suitable for the current protocol and breaking it down into a dns/ip address and port number.  It can be reimplemented on a per-protocol or per-game basis, if needed.

By default, it simply expects the address and portnumber seperated with a colon.

// both of these are potentially valid
99.99.99.1:9999
mygame.mysite.net:9999

However, some games use a fixed query port, so this method could be implemented, for example, to match an address and discard any given port, in favor of the default.

// default port is 6969
list($address,$port) = GameQueryProtocol_MyNewProtocol::_validate('192.168.5.80:12345');
// address would be parsed and assigned '192.168.5.80'
// port would be discarded and set to default '6969'

Parameters

$hostnameString containing a hostname of the server to be monitored.

Returns

An array of strings containing the dns/ip address and the port number.

get_template

public function get_template($template =  NULL)

Public method for displaying a processed query in an aesthetically pleasing format.  This can be used for displaying server status in HTML, XML, YAML, plain text, etc.  Changing how it displays is as simple as editing the template file.

Essentially, a template is a normal PHP file, given the special variables $_GAMEQUERY (which contains the query data structure) and $_TEMPLATEFILE (hich contains the template filename).

$monitor->get_template('');

In the base class, this simply returns NULL since it is protocol- and game-specific.  It is meant to be reimplemented on a per-game basis.

Parameters

$optionsOptional associative array of directives to control how the html display is formatted/built.

Returns

A string containing HTML-formatted query data.

supported_configs

public function supported_configs()

Method for returning an array of configuration directives supported by the current class, where the key is a directive name, and the value is a brief description of the directive.

In the base class, this returns an array of base-class specific configuration directives.  Each overriding protocol class that implements its own directives should also include the directives of its parents.

// example implementation of an overriden ::supported_configs()
$supported = array('new_config1', 'new_config2');

return array_merge( $supported, parent::supported_configs() );

Parameters

None

Returns

An associative array where each key is a config directive, and each value is a brief description of that directive.

Internal Methods

These methods are for use internally within the base class.

add_include_paths

protected function add_include_paths($paths =  NULL)

Private method for adding new directories to the include_path.  This is meant for internal use within the base class.

Parameters

$pathsString or array of strings containing system path(s).

Returns

Boolean true on success, or false on failure.

get_include_delimiter

protected function get_include_delimiter()

Private method for calculating the include_path delimiter character, which varies depending on the host operating system.  This is meant for internal use within the base class.

Parameters

None

Returns

String containing the delimiter character.

get_include_paths

protected function get_include_paths()

Private method for retrieving seperated paths from the include_path.  This is meant for internal use within the base class.

Parameters

None

Returns

Array of strings containing paths.

include_capture

protected function include_capture($_TEMPLATEFILE =  NULL,
$_GAMEQUERY =  NULL)

Private method for including and executing a PHP file within a confined scope (providing it the parsed query as a data structure), and caputuring and returning the output.

Parameters

$filePHP file to capture the output of.
$queryData structure containing query information.

Returns

String containing output of given template

Utility Methods

These methods are provided as part of the GameQuery class to make the parsing of response strings, and thus the implementation of new game protocols, much simpler.

_unpack_float32

protected function _unpack_float32(&$arr =  NULL)

Static method for removing and returning a 32-bit (4 byte) float from an array of bytes.

$bytes = array( \x5D, \x0A, \x12, \x44 );

// should print "584.161926269531"
echo GameQuery::_unpack_float32($bytes);

Parameters

$arrArray of bytes, one byte per element.

Returns

An integer on success, or NULL on error.

_unpack_int16

protected function _unpack_int16(&$arr =  NULL)

Static method for removing and returning a 16-bit (2 byte) integer from an array of bytes.

$bytes = array( \x80, \x00 );

// should print "128"
echo GameQuery::_unpack_int16($bytes);

Parameters

$arrArray of bytes, one byte per element.

Returns

An integer on success, or NULL on error.

_unpack_int32

protected function _unpack_int32(&$arr =  NULL)

Static method for removing and returning a 32-bit (4 byte) integer from an array of bytes.

$bytes = array( \xFF, \xFF, \x00, \x00 );

// should print "65535"
echo GameQuery::_unpack_int32($bytes);

Parameters

$arrArray of bytes, one byte per element.

Returns

An integer on success, or NULL on error.

_unpack_byte

protected function _unpack_byte(&$arr =  NULL)

Static method for removing and returning the numeric ordinal of a byte from an array of bytes.

$bytes = array( \x20 );

// should print "32"
echo GameQuery::_unpack_byte($bytes);

Parameters

$arrArray of bytes, one byte per element.

Returns

An integer on success, or NULL on error.

_unpack_cstring

protected function _unpack_cstring(&$arr =  NULL)

Static method for removing and returning a null-terminated string (aka c-string) from an array of bytes.  Note that the string is returned without the terminating null character.

$bytes = array( \x63, \x73, \x74, \x72, \x69, \x6e, \x67, \x00 );

// should print "cstring"
echo GameQuery::_unpack_cstring($bytes);

Parameters

$arrArray of bytes, one byte per element.

Returns

A string on success, or NULL on error.

_unpack_fstring

protected function _unpack_fstring(&$arr =  NULL,
$len =  0)

Static method for removing and returning a fixed-length string from an array of bytes.

$bytes = array( \x66, \x69, \x78, \x65, \x64, \x20, \x6c, \x65, \x6e, \x67, \x74, \x68 );

// should print "fixed"
echo GameQuery::_unpack_fstring($bytes, 5);

Parameters

$arrArray of bytes, one byte per element.
$lengthInteger indicating length of fixed string

Returns

A string on success, or NULL on error.
Generated by Natural Docs
public static function Monitor($protocol =  NULL,
$host =  NULL,
$options =  array())
Factory for creating monitor instances (also known as monitor objects) using the given protocol.
public function supported_protocols()
Method for returning all protocols found in the include_path, as an array.
public function supported_templates()
Method for returning all templates found in the include_path, as an array.
public function __construct($hostarg =  NULL,
$options =  NULL)
Constructor, implemented by base class, to be inherited and used by extender classes.
public function get_raw()
Member method for returning the raw response string(s) from a query.
public function get_struct()
Method for returning response data after it has been broken down into a structure (typically composed of nested arrays).
protected function _communicate($requests =  array())
Internal method for the gory details of sending request strings and recieving response strings through direct socket communications.
protected function _request($options =  NULL)
Internal method for constructing request strings that will be sent to the host server.
protected function _response($response =  NULL)
Internal method for parsing response strings that will be sent to the host server.
protected function _validate($hostname =  NULL)
Internal method for validating that a host string is suitable for the current protocol and breaking it down into a dns/ip address and port number.
public function get_template($template =  NULL)
Public method for displaying a processed query in an aesthetically pleasing format.
public function supported_configs()
Method for returning an array of configuration directives supported by the current class, where the key is a directive name, and the value is a brief description of the directive.
protected function add_include_paths($paths =  NULL)
Private method for adding new directories to the include_path.
protected function get_include_delimiter()
Private method for calculating the include_path delimiter character, which varies depending on the host operating system.
protected function get_include_paths()
Private method for retrieving seperated paths from the include_path.
protected function include_capture($_TEMPLATEFILE =  NULL,
$_GAMEQUERY =  NULL)
Private method for including and executing a PHP file within a confined scope (providing it the parsed query as a data structure), and caputuring and returning the output.
protected function _unpack_float32(&$arr =  NULL)
Static method for removing and returning a 32-bit (4 byte) float from an array of bytes.
protected function _unpack_int16(&$arr =  NULL)
Static method for removing and returning a 16-bit (2 byte) integer from an array of bytes.
protected function _unpack_int32(&$arr =  NULL)
Static method for removing and returning a 32-bit (4 byte) integer from an array of bytes.
protected function _unpack_byte(&$arr =  NULL)
Static method for removing and returning the numeric ordinal of a byte from an array of bytes.
protected function _unpack_cstring(&$arr =  NULL)
Static method for removing and returning a null-terminated string (aka c-string) from an array of bytes.
protected function _unpack_fstring(&$arr =  NULL,
$len =  0)
Static method for removing and returning a fixed-length string from an array of bytes.