IpToCountry 1.1 for Unreal Tournament '99
Made by [es]Rush
Release Date: 06.01.2006
Distributed under the terms of OpenUnrealMod license - see LICENSE.txt for details

Thanks for opening this readme! Please read its contents before asking any questions.
You can learn:
-General information about IpToCountry and how does it work
-How to install and set it on the server
-How to use IpToCountry for your own mod

CHANGELOG
-------
1.1: -Fixed the texture package, now it is CountryFlags2, this one should be perfect.
     -Fixed accessed nones in the Addon part while playing on the server with bots.
     -Removed QueryServer instructions cause they were buggy, will fix it later, if you want to run your own
      query server now, plase contact me and I'll try to explain everything.

1.0: -First version

WHAT IS IT FOR?
-------
In short, as the name says, it can resolve a country from an ip address, it also resolves a hostname.
IpToCountry is meant mainly to be just a shared component between many other mods, for example
imagine a scoreboard showing a small country flag near each player's nick(pss, it is quite easy,
 I've made a special texture package with all the country flags), so don't expect much black magic
from IpToCountry itself. But to not make you sad I've also made a little addon which will show
players' country names after doing a mutate command, for admins there is a similiar command showing
hostnames, this addon is enabled by default but you can disable it in the config.

HOW DOES IT WORK?
-------
To your knowledge, resolving a country from an ip requires quite a big database and implementing
it in unrealscript would be very hard, thus IpToCountry connects to a php script which is located
on a http server, this php script uses a mysql database generated from ip-to-country.csv file
kindly distributed by http://ip-to-country.webhosting.info. If you wanna know how the queues,
querying stuff exactly works just "Use the source Luke!".

ZIP CONTAINS:
-------
README.txt - this file :P
LICENSE.txt - OpenUnrealMod License
IpToCountry.u - The most important file, has to be in ServerActors - see INSTALLATION
CountryFlags2.utx - Country flags miniatures, has to be in ServerPackages if any mod needs it
Source/ - using this source you can modify and adapt IpToCountry to your needs!

INSTALLATION
-------
Add the following line to the [Engine.GameEngine] section of UnrealTournament.ini:
ServerActors=IpToCountry.LinkActor

CONFIG
-------
After first run IpToCountry.ini should be created, edit it, there 3 variables you can change:
bAddon=True - whether to use the Addon - read NOT FOR ADMINS
PrimaryQueryServer - leave these two unless you know what you're doing
SecondaryQueryServer

NOTE FOR ADMINS
-------
Even if there's no mod using IpToCountry yet, you can still make use of it because of the Addon.
Mutate commands and example results:
> mutate iptocountry
[es]Rush, Country: POLAND
LanPlayer, Country: Unknown
OtherPlayer, Country: GERMANY
And this one works only for an admin:
> mutate iptohost
[es]Rush, Host: xxx.xxx.xxx.pl
LanPlayer, Host: 192.168.0.3
OtherPlayer, Host: xxx.xxx.de

The Addon also automatically resolves new IPs from joining players.

INSTRUCTION FOR DEVELOPERS
-------
If you want to use IpToCountry in your mod just learn it from my example class, it is pretty simple
and doesn't require compiling with the dependency and linking or how do you call it. :P

# SOURCE STARTS HERE
class IpDetails extends Actor;

var Actor IpToCountry;
var bool bIpToCountry;

function PostBeginPlay()
{
	if(IpToCountryRunning())
		bIpToCountry=True;
}

function bool IpToCountryRunning()
{
	local Actor A;
	foreach AllActors(class'Actor', A, 'IpToCountry')
	{
		IpToCountry=A;
		return true;
	}
	return false;
}

function string GetIpInfo(string IP)
{
	if(bIpToCountry)
		return IpToCountry.GetItemName(IP);
}
# SOURCE ENDS HERE

Now calling on function GetIpInfo() with a string parameter should return either the data or the status
of resolving this data, let me show you, the function returns under a high stress(lots of calls) may
return these values, one after another:
1) "!Added to queue"
2) "!Waiting in queue"
3) "!Resolving now"
The 1) is always returned if IP wasn't in the database, 2) is very rarely returned, 3) is returned if
querying takes some time.
Now when the state 3 is done it should report the actual data which is returned in the following form:
<IP>:<HOST>:<COUNTRY>:<PREFIX3>:<PREFIX2>
for example "153.19.48.14:lux.eti.pg.gda.pl:POLAND:POL:pl"
Useful data, isn't it ?
The function can also report an error:
1) "!Bad Input"
2) "!Queue full"
3) "!Disabled"
When 3) is returned don't bother to ask IpToCountry again, it means that IpToCountry is unable to contact
any of the query servers.

When you got the right data you have to do some string parsing in order to get anything in a useful form,
you can use for example my SelElem function which is in the LinkActor.uc file in the source.

Now the fun part, when you got last part of the return string, the 2 char long prefix, for example "pl",
you can for example display a country flag on a player's hud/scoreboard.
Use the CountryFlags2.utx file and just do DynamicLoadObject on CountryFlags2.<prefix> for example,
CountryFlags2.pl is a small flag of Poland. The textures are of size 16x16, but the bottom 6 pixels
are masked and shouldn't matter, so the visible size of the textures is 16x10. Remember that CountryFlags2
will have to be added to the ServerPackages, so notify users about it in your instructions.


THANKS TO
-------
AnthraX - for overall help, consultations and helping UT'99 community so much, thx m8!
teleport*bR - thx for the great help in putting the texture package to one, thx also for testing

CONTACT & FEEDBACK
---------
If you find any bugs or just have some ideas please let me know. ;)
Rush on unrealadmin.org forums
Email & MSN: rush@u.one.pl
ICQ: 257547545
GG: 1930553
AIM: RushESpl
JID: rush@chrome.pl

That's all folks!