/ 
Win32-IPConfig-0.05
River stage zero No dependents
/ Win32::IPConfig

NAME

Win32::IPConfig - Windows NT/2000/XP IP Configuration Settings

SYNOPSIS

use Win32::IPConfig;

$host = shift || "";
if ($ipconfig = Win32::IPConfig->new($host)) {
    print "hostname=", $ipconfig->get_hostname, "\n";
    print "domain=", $ipconfig->get_domain, "\n";
    print "nodetype=", $ipconfig->get_nodetype, "\n";

    foreach $adapter ($ipconfig->get_adapters) {
        print "\nAdapter ";
        print $adapter->get_id, "\n";
        print $adapter->get_description, "\n";

        if ($adapter->is_dhcp_enabled) {
            print "DHCP is enabled\n";
        } else {
            print "DHCP is not enabled\n";
        }

        @ipaddresses = $adapter->get_ipaddresses;
        print "ip addresses=@ipaddresses (", scalar @ipaddresses, ")\n";

        @subnet_masks = $adapter->get_subnet_masks;
        print "subnet masks=@subnet_masks (", scalar @subnet_masks, ")\n";

        @gateways = $adapter->get_gateways;
        print "gateways=@gateways (", scalar @gateways, ")\n";

        print "domain=", $adapter->get_domain, "\n";

        @dns = $adapter->get_dns;
        print "dns=@dns (", scalar @dns, ")\n";

        @wins = $adapter->get_wins;
        print "wins=@wins (", scalar @wins, ")\n";
    }
}

DESCRIPTION

Win32::IPConfig is a module for retrieving TCP/IP network settings from a Windows NT/2000/XP host machine. Specify the host and the module will retrieve and collate all the information from the specified machine's registry (using Win32::TieRegistry). For this module to retrieve information from a host machine, you must have read and write access to the registry on that machine.

METHODS

$ipconfig = Win32::IPConfig->new($host);

Creates a new Win32::IPConfig object. $host is passed directly to Win32::TieRegistry, and can be a computer name or an IP address.

$ipconfig->get_hostname

Returns a string containing the DNS hostname of the machine.

$ipconfig->get_domain

Returns a string containing the domain name of the machine. For Windows 2000/XP machines (which can have connection-specific domain names) this is the primary domain name.

$ipconfig->get_nodetype

Returns the node type of the machine. Note that this is not always present. It will default to 0x1 B-node if no WINS servers are configured, and default to 0x8 H-node if there are. The four possible node types are:

B-node - resolve NetBIOS names by broadcast
P-node - resolve NetBIOS names using a WINS server
M-node - resolve NetBIOS names by broadcast, then using a WINS server
H-node - resolve NetBIOS names using a WINS server, then by broadcast

Currently this value is only reliable on statically configured hosts. Do not rely on this value if you have DHCP enabled adapters.

$ipconfig->get_adapters

The real business of the module. Returns a list of Win32::IPConfig::Adapter objects. (Returns a reference to a list in a scalar context.) See the Adapter documentation for more information.

$ipconfig->get_adapter($num)

Returns the Win32::IPConfig::Adapter specified by $num. Use $ipconfig->get_adapter(0) to retrieve the first adapter.

EXAMPLES

Collecting IP Settings for a list of PCs

use Win32::IPConfig;

print "hostname,domain,dhcp?,ip addresses,subnet masks,gateways,dns servers,wins servers\n";
while (<DATA>) {
    chomp;
    $ipconfig = Win32::IPConfig->new($_);
    print $ipconfig->get_hostname, ",";
    print $ipconfig->get_domain, ",";

    if (@adapters = $ipconfig->get_adapters) {
        $adapter = $adapters[0];
        print $adapter->is_dhcp_enabled ? "Y," : "N,";
        @ipaddresses = $adapter->get_ipaddresses;
        print "@ipaddresses,";
        @subnet_masks = $adapter->get_subnet_masks;
        print "@subnet_masks,";
        @gateways = $adapter->get_gateways;
        print "@gateways,";
        @dns = $adapter->get_dns;
        print "@dns,";
        @wins = $adapter->get_wins;
        print "@wins";
    }
    print "\n";
}

__DATA__
HOST1
HOST2
HOST3

Setting a PC's DNS servers

use Win32::IPConfig;

my $host = shift;
my $ipconfig = Win32::IPConfig->new($host);
my @dns = @ARGV;
my $adapter = $ipconfig->get_adapter(0);
$adapter->set_dns(@dns);

REGISTRY KEYS USED

IP configuration information is stored in a number of registry keys under HKLM\SYSTEM\CurrentControlSet\Services.

To access adapter-specific configuration information, you need the adapter id, which can be found by examining the list of installed network cards at HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\NetworkCards.

Note that in NT the adapter id will look like a service or driver, while in 2000/XP it will be a GUID.

There are some variations in where Windows NT and Windows 2000/XP store TCP/IP configuration data. This is shown in the following lists. Note that Windows 2000/XP sometimes stores data in the old adapter-specific location as well as the new 2000/XP adapter-specific location. In these cases, the module will read the data from the new registry location.

For all operating systems, the main keys are:

Tcpip\Parameters
Netbt\Parameters

Adapter-specific settings are stored in:

<adapter>\Parameters\Tcpip (Windows NT)
Tcpip\Parameters\Interfaces\<adapter> (Windows 2000/XP)

NetBIOS over TCP/IP stores adapter-specific settings in:

Netbt\Adapters\<adapter> (on Windows NT)
Netbt\Parameters\Interfaces\Tcpip_<adapter> (on Windows 2000/XP)

NOTES

Note that Windows 2000 and later will use its DNS server setting to resolve Windows computer names, whereas Windows NT will use its WINS server settings first.

For Windows 2000 and later, both the primary and connection-specific domain settings are significant and will be used in this initial name resolution process.

The DHCP Server options correspond to the following registry values:

003 Router              ->  DhcpDefaultGateway
006 DNS Servers         ->  DhcpNameServer
015 DNS Domain Name     ->  DhcpDomain
044 WINS/NBNS Servers   ->  DhcpNameServer/DhcpNameServerList
046 WINS/NBT Node Type  ->  DhcpNodeType

AUTHOR

James Macfarlane, <jmacfarla@cpan.org>

SEE ALSO

Win32::IPConfig::Adapter

Win32::TieRegistry

The following Microsoft support articles were helpful:

  • Q120642 TCP/IP and NBT Configuration Parameters for Windows 2000 or Windows NT

  • Q314053 TCP/IP and NBT Configuration Parameters for Windows XP