NAME

Net::Whois::SIDN - whois for .nl TLD via XML interface

INHERITANCE

  Net::Whois::SIDN
  is a XML::Compile::Cache
  is a XML::Compile::Schema
  is a XML::Compile

SYNOPSIS

  my $whois  = Net::Whois::SIDN->new(drs_version => '5.0');
  my $answer = $whois->is('sidn.nl');
  my $answer = $whois->whois('sidn.nl');

  use Data::Dumper;
  warn Dumper $answer;

DESCRIPTION

Implementation (both usable for client and server side), of the XML version of the whois interface, as provided by the Dutch ccTLD registry SIDN (the .nl top-level domain).

Documentation is included in this distribution (in the doc/ directory), and in nicely printed form via the ISP participants wiki. Don't forget to look at the examples/ directory.

METHODS

Constructor

First, create an object which contains the information for the connection.

my $whois = Net::Whois::SIDN->new(@opts);

The drs_version parameter is required. When new versions of the SIDN core implementation (DRS) are introduced, you may have to convert your application. In that case, SIDN will provide a test environment with a server using a newer scheme before the change goes public.

With options role set to SERVER, you will accept queries and produce responses. For all other values, the module behaves as client. The default role is REGISTERED. The other valid value is PUBLIC. however SIDN does not (yet) support XML output on the public interface.

Option service changes the url of the default server which will answer the queries. You may pass your own user_agent (an LWP::UserAgent instance).

Use option trace, set to a trueth value, to see the message sent and received. Client-side only.

This object extents XML::Compile::Cache, so there are a lot of additional parameters. However, you will probably not need them.

Accessors

$whois->version

$whois->namespace

$whois->role

$whois->userAgent

$whois->service('is'|'whois')

Client actions

my ($rc, $data) = $obj->whois('sidn.nl', %opts)

When $rc equals 0, then there are no errors and $data will refer to the HASH containing the result. Otherwise, $rc is an error code, defined as HTTP error codes and $data an error text.

The %opts are parameter pairs. Defined keys are: lang (language EN or NL, default EN), output_format (PLAIN, HTML, and the default XML) and usertext_format (PLAIN or HTML).

Example:

   my ($rc, $data) = $whois->whois('sidn.nl');
   $rc==0 or die "Error: $data";

   print $data->{domain}{status}{code}, "\n";
  

The distribution package contains an extended realistic example of the data structure as made available in Perl.

my ($rc, $data) = $obj->is('sidn.nl', %opts)

The is() works exactly the same as the whois(), but produces a shorter answer.

Helpers

my $xml = $obj->create($type, $data);

Pass a correctly constructed Perl $data nested HASH, which suites to the $type, which is whois:{whois,is}-{query,response}. See the examples provided by the distribution.

  my $xml = $whois->create($type, $data);
  print $xml->toString(1);

$class->from($data, [@opts]);

$obj->from($data, [@opts]);

Read an XML message from $data, in any format supported by XML::Compile method dataToXML(): string, file, filehandle, and more. Returned is a list of two: the type of the top-level element plus the data-structure.

When called as instance method, the data will automatically get converted to the version of required by the object. When called as class method, the version of the top-level element will determine the returned version automatically (which may give unpredictable versions as result).

When the method is called as class method, then a temporary instance is created. Creating an instance is (very) slow.

Examples:

  my $whois = Net::Whois::SIDN->new(drs_version => '3.14');
  my ($type, $data) = $whois->from('data.xml');

or

  my ($type, $data) = Net::Whois::SIDN->from('data.xml');

COPYRIGHT

Copyright 2010 Mark Overmeer

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