gamespy_query 0.1.5 → 0.2.0pre

data/lib/gamespy_query/parser.rb

@@ -7,9 +7,8 @@
  Gamedata values are not split, Player lists can be (names, teams, scores, deaths), while individual values still are not.
 =end
 
-require_relative 'base'
-
 module GamespyQuery
+  # Parsing gamespy query packets and processing them to Hash
   class Parser < Base
     STR_SPLIT = STR_X0
     STR_ID = "\x00\x04\x05\x06\a"
@@ -18,7 +17,11 @@ module GamespyQuery
     RX_PLAYER_HEADER = /\x01/
     RX_END = /\x00\x02$/
 
-    # packets:
+    # Packets to process
+    attr_reader :packets
+
+    # Initializes the object
+    # @param [Hash or Array] packets
     #   - Hash, key: packetID, value: packetDATA
     #   or
     #   - Array, packetDATA ordered already by packetID
@@ -33,20 +36,20 @@ module GamespyQuery
       end
     end
 
+    # Parse game and player data to hash
     # Returns Hash with parsed data (:game and :players)
-    # :game => Hash, Key: InfoKey, Value: InfoValue
-    # :players => Hash, Key: InfoType, Value: Array of Values
+    # game Key: InfoKey, Value: InfoValue
+    # players Key: InfoType, Value: Array of Values
     def parse
       data = {}
       data[:game] = {} # Key: InfoKey, Value: InfoValue
       data[:players] = {} # Key: InfoType, Value: Array of Values
       player_info = false
-      player_data = ""
+      player_data = "".encode "ASCII-8BIT"
 
       # Parse the packets
       @packets.each do |packet|
-        packet = clean_packet(packet)
-
+        packet = clean_packet packet
         if player_info
           # Player header was found before, add packet to player_data
           player_data += packet
@@ -74,6 +77,8 @@ module GamespyQuery
       data
     end
 
+    # Clean packet from useless data
+    # @param [String] packet Packet data
     def clean_packet(packet)
       packet = packet.clone
       packet.sub!(STR_ID, STR_EMPTY) # Cut off the identity
@@ -82,11 +87,12 @@ module GamespyQuery
       packet.sub!(RX_X0_S, STR_EMPTY) # Cut off first \x00 
       packet.sub!(RX_END, STR_EMPTY) # Cut off the last \x00\x02
 
-      # Encoding
-      get_string(packet)
+      packet
     end
-    
-   def parse_game_data(packet)
+
+    # Parse game data in packet
+    # @param [String] packet Packet to parse
+    def parse_game_data(packet)
       Tools.debug {"Game Parsing #{packet.inspect}"}
 
       key = nil
@@ -94,9 +100,9 @@ module GamespyQuery
 
       packet.split(STR_SPLIT).each_with_index do |data, index|
         if (index % 2) == 0
-          key = clean_string data
+          key = encode_string data
         else
-          game_data[key] = data.is_a?(String) ? clean_string(data) : data
+          game_data[key] = data.is_a?(String) ? encode_string(data) : data
         end
       end
 
@@ -112,11 +118,13 @@ module GamespyQuery
     STR_SIX = "$SIX_OVERWRITE_PREVIOUS$"
     STR_SIX_X0 = "\x00#{STR_SIX}\x00"
 
+    # Parse player data in packet
+    # @param [String] packet Packet to parse
     # TODO: Cleanup
     def parse_player_data(packet)
       Tools.debug {"Player Parsing #{packet.inspect}"}
 
-      player_data = {:names => [], :teams => [], :scores => [], :deaths => []} # [[], [], [], []]
+      player_data = {names: [], teams: [], scores: [], deaths: []} # [[], [], [], []]
 
       return player_data if packet.nil? || packet.empty?
 
@@ -154,7 +162,7 @@ module GamespyQuery
           # Parse the data - \x00 is printed after a non-nil entry, otherwise \x00 means nil (e.g empty team)
           until str.empty?
             entry = str[RX_X0_SPEC]
-            player_data[player_data.keys[i]] << clean_string(entry.sub(STR_X0, STR_EMPTY))
+            player_data[player_data.keys[i]] << encode_string(entry.sub(STR_X0, STR_EMPTY))
             str.sub!(entry, STR_EMPTY)
           end
           
@@ -166,6 +174,7 @@ module GamespyQuery
               overwrite = true # tag so that the next entry will overwrite the latest entry
               next # ignore
             else
+              info = clean(info) if [2,3].include?(i) # Apply data_type conversion for Score and Deaths
               if overwrite
                 new_player_data[-1] = info # Overwrite latest entry
                 overwrite = false # done the overwrite
@@ -182,7 +191,8 @@ module GamespyQuery
       player_data
     end
 
-    # Hash of Hashes
+    # Convert player data to Hash of Hashes
+    # @param [Hash] data Original player data split over 4 arrays in hash (:names, :teams, :scores, :deaths)
     def self.pretty_player_data(data)
       player_data = {}
 
@@ -196,7 +206,8 @@ module GamespyQuery
       player_data
     end
 
-    # Array of Hashes
+    # Convert player data to Array of Hashes
+    # @param [Hash] data Original player data split over 4 arrays in hash (:names, :teams, :scores, :deaths)
     def self.pretty_player_data2(data)
       player_data = []
 

data/lib/gamespy_query/socket.rb

@@ -2,28 +2,31 @@
 # GameSpy query class by Sickboy [Patrick Roza] (sb_at_dev-heaven.net)
 
 require 'yaml'
-require_relative 'base'
-require_relative 'parser'
 require 'socket'
 
 module GamespyQuery
+  # Provides socket functionality on multiple platforms
   # TODO
   module MultiSocket
+    # Create socket
     def create_socket(*params)
       Tools.debug {"Creating socket #{params}"}
       _create_socket(*params)
     end
 
+    # Write socket
     def socket_send(*params)
       Tools.debug {"Sending socket #{params}"}
       _socket_send(*params)
     end
 
+    # Read socket
     def socket_receive(*params)
       Tools.debug {"Receiving socket #{params}"}
       _socket_receive(*params)
     end
 
+    # Close socket
     def socket_close(*params)
       Tools.debug {"Closing socket #{params}"}
       @s.close
@@ -33,6 +36,7 @@ module GamespyQuery
       include System::Net
       include System::Net::Sockets
 
+      # Create socket
       def _create_socket(host, port)
         @ip_end_point = IPEndPoint.new(IPAddress.Any, 0)
         @s = UdpClient.new
@@ -40,25 +44,30 @@ module GamespyQuery
         @s.connect(host, port.to_i)
       end
 
+      # Write socket
       def _socket_send(packet)
         @s.Send(packet, packet.length)
       end
 
+      # Read socket
       def _socket_receive
         @s.Receive(@ip_end_point)
       end
 
     else
 
+      # Create socket
       def _create_socket(host, port)
         @s = UDPSocket.new
         @s.connect(host, port)
       end
 
+      # Write socket
       def _socket_send(packet)
         @s.puts(packet)
       end
 
+      # Read socket
       def _socket_receive
         begin
           Timeout::timeout(DEFAULT_TIMEOUT) do
@@ -73,12 +82,20 @@ module GamespyQuery
     end
   end
 
+  # Provides direct connection functionality to gamespy enabled game servers
+  # This query contains up to 7x more information than the gamespy master browser query
+  # For example, player lists with info (teams, scores, deaths) are only available by using direct connection
   class Socket < UDPSocket
     include Funcs
 
+    # Default timeout per connection state
     DEFAULT_TIMEOUT = 3
+
+    # Maximum amount of packets sent by the server
+    # This is a limit set by gamespy
     MAX_PACKETS = 7
 
+    # Packet bits
     ID_PACKET = [0x04, 0x05, 0x06, 0x07].pack("c*") # TODO: Randomize?
     BASE_PACKET = [0xFE, 0xFD, 0x00].pack("c*")
     CHALLENGE_PACKET = [0xFE, 0xFD, 0x09].pack("c*")
@@ -88,6 +105,7 @@ module GamespyQuery
     SERVER_INFO_PACKET = [0xFF, 0x00, 0x00].pack("c*")
     PLAYER_INFO_PACKET = [0x00, 0xFF, 0x00].pack("c*")
 
+    # Maximum receive size
     RECEIVE_SIZE = 1500
 
     STR_HOSTNAME = "hostname"
@@ -117,6 +135,9 @@ module GamespyQuery
 
     attr_accessor :addr, :data, :state, :stamp, :needs_challenge, :max_packets, :failed
 
+    # Initializes the object
+    # @param [String] addr Server address ("ip:port")
+    # @param [Address Family] address_family
     def initialize(addr, address_family = ::Socket::AF_INET)
       @addr, @data, @state, @max_packets = addr, {}, 0, MAX_PACKETS
       @id_packet = ID_PACKET
@@ -126,10 +147,22 @@ module GamespyQuery
       self.connect(*addr.split(":"))
     end
 
+    # Exception
+    class NotInWriteState < StandardError
+    end
+
+    # Exception
+    class NotInReadState < StandardError
+    end
+
+    # Sets the state of the socket
+    # @param [Integer] state State to set
     def state=(state); @stamp = Time.now; @state = state; end
 
+    # Is the socket state valid? Only if all states have passed
     def valid?; @state == STATE_READY; end
 
+    # Handle the write state
     def handle_write
       #Tools.debug {"Write: #{self.inspect}, #{self.state}"}
 
@@ -146,11 +179,17 @@ module GamespyQuery
             # Send Challenge response
             self.puts self.needs_challenge ? BASE_PACKET + @id_packet + self.needs_challenge + FULL_INFO_PACKET_MP : BASE_PACKET + @id_packet + FULL_INFO_PACKET_MP
             self.state = STATE_SENT_CHALLENGE_RESPONSE
+          else
+            raise NotInWriteState, "NotInWriteState"
         end
+      rescue NotInWriteState => e
+        r = false
+        self.failed = true
+        close unless closed?
       rescue => e
         Tools.log_exception e
         self.failed = true
-        r = false
+        r = nil
         close unless closed?
       end
 
@@ -165,32 +204,26 @@ module GamespyQuery
       r
     end
 
+    # Handle the read state
     def handle_read
       # Tools.debug {"Read: #{self.inspect}, #{self.state}"}
 
       r = true
-      case self.state
-        when STATE_SENT_CHALLENGE
-          begin
+      begin
+        case self.state
+          when STATE_SENT_CHALLENGE
             data = self.recvfrom_nonblock(RECEIVE_SIZE)
             Tools.debug {"Read (1): #{self.inspect}: #{data}"}
 
-            handle_challenge get_string(data[0])
+            handle_challenge data[0]
 
             self.state = STATE_RECEIVED_CHALLENGE
-          rescue => e
-            Tools.log_exception e
-            self.failed = true
-            r = false
-            close unless closed?
-          end
-        when STATE_SENT_CHALLENGE_RESPONSE, STATE_RECEIVE_DATA
-          begin
+          when STATE_SENT_CHALLENGE_RESPONSE, STATE_RECEIVE_DATA
             data = self.recvfrom_nonblock(RECEIVE_SIZE)
             Tools.debug {"Read (3,4): #{self.inspect}: #{data}"}
             self.state = STATE_RECEIVE_DATA
 
-            game_data = get_string(data[0])
+            game_data = data[0]
             Tools.debug {"Received (#{self.data.size + 1}):\n\n#{game_data.inspect}\n\n#{game_data}\n\n"}
 
             index = handle_splitnum game_data
@@ -203,16 +236,25 @@ module GamespyQuery
               r = false
               close unless closed?
             end
-          rescue => e
-            Tools.log_exception(e)
-            self.failed = true
-            r = false
-            close unless closed?
-          end
+          else
+            raise NotInReadState, "NotInReadState"
+        end
+      rescue NotInReadState => e
+        r = false
+        self.failed = true
+        close unless closed?
+      rescue => e
+        # TODO: Simply raise the exception?
+        Tools.log_exception(e)
+        self.failed = true
+        r = nil
+        close unless closed?
       end
       r
     end
 
+    # Handle the exception state
+    # TODO
     def handle_exc
       Tools.debug {"Exception: #{self.inspect}"}
       close unless closed?
@@ -221,9 +263,11 @@ module GamespyQuery
       false
     end
 
-    def handle_splitnum game_data
+    # Process the splitnum provided in the packet
+    # @param [String] packet Packet data
+    def handle_splitnum packet
       index = 0
-      if game_data.sub(STR_GARBAGE, STR_EMPTY)[RX_SPLITNUM]
+      if packet.sub(STR_GARBAGE, STR_EMPTY)[RX_SPLITNUM]
         splitnum = $1
         flag = splitnum.unpack("C")[0]
         index = (flag & 127).to_i
@@ -238,19 +282,24 @@ module GamespyQuery
       index
     end
 
-    def handle_challenge str
-      # Tools.debug{"Received challenge response (#{str.length}): #{str.inspect}"}
-      need_challenge = !(str.sub(STR_X0, STR_EMPTY) =~ RX_NO_CHALLENGE)
+    # Handle the challenge/response, if the server requires it
+    # @param [String] packet Packet to process for challenge/response
+    def handle_challenge packet
+      # Tools.debug{"Received challenge response (#{packet.length}): #{packet.inspect}"}
+      need_challenge = !(packet.sub(STR_X0, STR_EMPTY) =~ RX_NO_CHALLENGE)
       if need_challenge
-        str = str.sub(RX_CHALLENGE, STR_EMPTY).gsub(RX_CHALLENGE2, STR_EMPTY).to_i
+        str = packet.sub(RX_CHALLENGE, STR_EMPTY).gsub(RX_CHALLENGE2, STR_EMPTY).to_i
         challenge_packet = sprintf(STR_BLA, handle_chr(str >> 24), handle_chr(str >> 16), handle_chr(str >> 8), handle_chr(str >> 0))
         self.needs_challenge = challenge_packet
       end
     end
 
+    # Determine Read/Write/Exception state
     def handle_state; [STATE_INIT, STATE_RECEIVED_CHALLENGE].include? state; end
 
+    # Process data
     # Supports challenge/response and multi-packet
+    # @param [String] reply Reply from server
     def sync reply = self.fetch
       game_data, key = {}, nil
       return game_data if reply.nil? || reply.empty?
@@ -266,6 +315,7 @@ module GamespyQuery
       game_data
     end
 
+    # Fetch all packets from socket
     def fetch
       pings = []
       r = self.data
@@ -275,13 +325,13 @@ module GamespyQuery
             if IO.select(nil, [self], nil, DEFAULT_TIMEOUT)
               handle_write
             else
-              raise "TimeOut"
+              raise TimeOutError, "TimeOut"
             end
           else
             if IO.select([self], nil, nil, DEFAULT_TIMEOUT)
               handle_read
             else
-              raise "TimeOut"
+              raise TimeOutError, "TimeOut"
             end
           end
         end
@@ -295,6 +345,7 @@ module GamespyQuery
         Tools.debug{"Gamespy pings: #{pings}, #{ping}"}
         @ping = ping
       rescue => e
+        # TODO: Simply raise the exception?
         Tools.log_exception(e)
         r = nil
         close unless closed?
@@ -303,18 +354,3 @@ module GamespyQuery
     end
   end
 end
-
-if $0 == __FILE__
-  host, port = if ARGV.size > 1
-    ARGV
-               else
-    ARGV[0].split(":")
-  end
-  time_start = Time.now
-  g = GamespyQuery::Socket.new("#{host}:#{port}")
-  r = g.sync
-  time_taken = Time.now - time_start
-  puts "Took: #{time_taken}s"
-  exit unless r
-  puts r.to_yaml
-end

data/lib/gamespy_query/socket_master.rb

@@ -1,18 +1,28 @@
-require_relative 'socket'
-
 module GamespyQuery
+  # Provides mass processing of Gamespy UDP sockets, by using Socket/IO select
   class SocketMaster < Base
+    # Should the current queue be extended to the maximum amount of connections, or should the queue be emptied first,
+    # before adding more?
     FILL_UP_ON_SPACE = true
+
+    # Default maximum concurrent connections
     DEFAULT_MAX_CONNECTIONS = 128
 
-    attr_accessor :timeout, :max_connections
+    # Configurable timeout in seconds
+    attr_accessor :timeout
+
+    # Configurable max concurrenct connections
+    attr_accessor :max_connections
 
+    # Initializes the object
+    # @param [Array] addrs List of addresses to process
     def initialize addrs
       @addrs = addrs
 
       @timeout, @max_connections = Socket::DEFAULT_TIMEOUT, DEFAULT_MAX_CONNECTIONS # Per select iteration
     end
 
+    # Process the list of addresses
     def process!
       sockets = []
 
@@ -56,6 +66,42 @@ module GamespyQuery
 
       return sockets
     end
+
+    class <<self
+      # Fetch the gamespy master browser list
+      # Connect to each individual server to receive player data etc
+      # @param [String] game Game to fetch info from
+      # @param [String] geo Geo location enabled?
+      # @param [Array] remote Hostname and path+filename strings if the list needs to be fetched from http server
+      def process_master(game = "arma2oapc", geo = nil, remote = nil)
+        master = GamespyQuery::Master.new(geo, game)
+        list = if remote
+                 Net::HTTP.start(remote[0]) do |http|
+                   resp = http.get(remote[1])
+                   resp.body.split("\n")
+                 end
+               else
+                 master.get_server_list(nil, true, geo)
+               end
+
+        dat = master.process list
+
+        sm = GamespyQuery::SocketMaster.new(dat.keys)
+        sockets = sm.process!
+        sockets.select{|s| s.valid? }.each do |s|
+          begin
+            data = dat[s.addr]
+            data[:ip], data[:port] = s.addr.split(":")
+            data[:gamename] = game
+            data[:gamedata].merge!(s.sync(s.data))
+          rescue => e
+            Tools.log_exception e
+          end
+        end
+
+        dat.values
+      end
+    end
   end
 end