The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
IP-Country-1.65
River stage one • 3 direct dependents • 3 total dependents
/ IP::Country

NAME

IP::Country - cached lookup of country codes by domain name and IP address

SYNOPSIS

  use IP::Country;

DESCRIPTION

Finding the home country of a client can be difficult. This module tries to ease this process by presenting a combined interface to the domain and IP systems. The algorithm for discovering country code differs slightly depending on whether the user enters a hostname of the form '18.181.0.24' (IP address) or 'rtfm.mit.edu' (domain name). Here's how a typical lookup of a county code might procede for a hostname of the form '18.181.0.24':

    1. If the cache has been enabled, and the country code has previously been found, it is immediately returned.

    2. If the IP address can be reverse mapped to a domain name, this is done, and that name is checked to see whether it ends in a two-letter top-level domain. If so, this is changed to upper case and returned.

    3. If reverse mapping fails to find a country code, the IP address is sent to the IP::Registry module, which maintains a local database of country codes for various IP ranges.

    4. If this still fails to find a country code, undef is returned.

Here's how a typical lookup of a county code might procede for a hostname of the form 'rtfm.mit.edu'.

    1. If the hostname ends with a two-letter top-level domain (TLD), this is changed to upper case and returned.

    2. If the cache has been enabled, and the country code has previously been found, it is returned.

    3. If the hostname can be resolved to an IP address. This IP address is sent to IP::Registry module, which maintains a local database of country codes for various IP ranges.

    4. If this still fails to find a country code, undef is returned.

Using these approaches, this module has a greater accuracy and coverage than the IP::Registry module alone. However, these benefits come at a price, which is the speed decrease brought about by accessing the domain name system. If you're less worried about accuracy and coverage, I recommend using the IP::Registry module.

CONSTRUCTOR

The constructor takes no arguments.

  use IP::Country;
  my $ic = IP::Country->new();

OBJECT METHODS

All object methods are designed to be used in an object-oriented fashion.

  $result = $object->foo_method($bar,$baz);

Using the module in a procedural fashion (without the arrow syntax) won't work.

$country = $ic->inet_atocc(HOSTNAME)

Takes a string giving the name of a host, and translates that to an two-letter country code. Takes arguments of both the 'rtfm.mit.edu' type and '18.181.0.24'. If the country code cannot be found, returns undef.

$country = $ic->inet_ntocc(IP_ADDRESS)

Takes a string (an opaque string as returned by Socket::inet_aton()) and translates it into a two-letter country code. If the country code cannot be found, returns undef.

$ic->cache(BOOLEAN)

By default, the module caches results of country-code lookups. This feature can be switched off by setting cache to a false value (zero, empty string or undef), and can be switched on again by setting cache to a true value (anything which isn't false).

  $ic->cache(0); # clears and disables cache
  $ic->cache(1); # enables the cache

The cache is formed at the class level, so any change in caching in one object will affect all objectcs of this class. Turning off the cache also clears the cache.

COPYRIGHT

Copyright (C) 2002 Nigel Wetters. All Rights Reserved.

NO WARRANTY. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.