/ 
Net-EPP-Simple-0.02
/ Net::EPP::Simple

NAME

Net::EPP::Simple - a simple EPP client interface for the most common jobs

SYNOPSIS

#!/usr/bin/perl
use Net::EPP::Simple;
use strict;

my $epp = Net::EPP::Client->new(
	host	=> 'epp.nic.tld',
	user	=> 'my-id',
	pass	=> 'my-password',
);

my $domain = 'example.tld';

if ($epp->check_domain($domain) == 1) {
	print "Domain is available\n" ;

} else {
	my $info = $epp->domain_info($domain);
	printf("Domain was registered on %s by %s\n", $info->{crDate}, $info->{crID});

}

DESCRIPTION

EPP is the Extensible Provisioning Protocol. EPP (defined in RFC 4930) is an application layer client-server protocol for the provisioning and management of objects stored in a shared central repository. Specified in XML, the protocol defines generic object management operations and an extensible framework that maps protocol operations to objects. As of writing, its only well-developed application is the provisioning of Internet domain names, hosts, and related contact details.

This module provides a high level interface to the EPP protocol. It hides all the boilerplate of connecting, logging in, building request frames and parsing response frames behind a simple, Perlish interface.

It is based on the Net::EPP::Client module and uses Net::EPP::Frame to build request frames.

CONSTRUCTOR

The constructor for Net::EPP::Simple has the same general form as the one for Net::EPP::Client, but with the following exceptions:

Unless otherwise set, port defaults to 700
Unless the no_ssl parameter is set, SSL is always on
You can use the user and pass parameters to supply authentication information.

The constructor will establish a connection to the server and retrieve the greeting (which is available via $epp->{greeting}) and then send a <login> request.

If the login fails, the constructor will return undef and set $Net::EPP::Simple::Error and $Net::EPP::Simple::Code.

AVAILABILITY CHECKS

You can do a simple <check> request for an object like so:

my $result = $epp->check_domain($domain);

my $result = $epp->check_host($host);

my $result = $epp->check_contact($contact);

Each of these methods has the same profile. They will return one of the following:

undef in the case of an error (check $Net::EPP::Simple::Error and $Net::EPP::Simple::Code).
0 if the object is already provisioned.
1 if the object is available.

RETRIEVING OBJECT INFORMATION

You can retrieve information about an object by using one of the following:

my $info = $epp->domain_info($domain);

my $info = $epp->host_info($host);

my $info = $epp->contact_info($contact);

Net::EPP::Simple will construct an <info> frame and send it to the server, then parse the response into a simple hash ref. The layout of the hash ref depends on the object in question. If there is an error, these methods will return undef, and you can then check $Net::EPP::Simple::Error and $Net::EPP::Simple::Code.

DOMAIN INFORMATION

The hash ref returned by domain_info() will usually look something like this:

$info = {
  'contacts' => {
    'admin' => 'contact-id'
    'tech' => 'contact-id'
    'billing' => 'contact-id'
  },
  'registrant' => 'contact-id',
  'clID' => 'registrar-id',
  'roid' => 'tld-12345',
  'status' => [
    'ok'
  ],
  'authInfo' => 'abc-12345',
  'name' => 'example.tld',
  'trDate' => '2007-01-18T11:08:03.0Z',
  'ns' => [
    'ns0.example.com',
    'ns1.example.com',
  ],
  'crDate' => '2001-02-16T12:06:31.0Z',
  'crID' => 'registrar-id',
  'upDate' => '2007-08-29T04:02:12.0Z',
  hosts => [
    'ns0.example.tld',
    'ns1.example.tld',
  ],
};

Members of the contacts hash ref may be strings or, if there are multiple associations of the same type, an anonymous array of strings. If the server uses the "hostAttr" model instead of "hostObj", then the ns member will look like this:

$info->{ns} = [
  {
    name => 'ns0.example.com',
    addrs => [
      type => 'v4',
      addr => '10.0.0.1',
    ],
  },
  {
    name => 'ns1.example.com',
    addrs => [
      type => 'v4',
      addr => '10.0.0.2',
    ],
  },
];

Note that there may be multiple members in the addrs section and that the type attribute is optional.

HOST INFORMATION

The hash ref returned by host_info() will usually look something like this:

$info = {
  'crDate' => '2007-09-17T15:38:56.0Z',
  'clID' => 'registrar-id',
  'crID' => 'registrar-id',
  'roid' => 'tld-12345',
  'status' => [
    'linked',
    'serverDeleteProhibited',    
  ],
  'name' => 'ns0.example.tld',
  'addrs' => [
    {
      'version' => 'v4',
      'addr' => '10.0.0.1'
    }
  ]
};

Note that hosts may have multiple addresses, and that version is optional.

CONTACT INFORMATION

The hash ref returned by contact_info() will usually look something like this:

$VAR1 = {
  'postalInfo' => {
    'int' => {
      'name' => 'John Doe',
      'org' => 'Example Inc.',
      'addr' => {
        'street' => [
          '123 Example Dr.'
          'Suite 100'
        ],
        'city' => 'Dulles',
        'sp' => 'VA',
        'pc' => '20166-6503'
        'cc' => 'US',
      }
    }
  },
  'clID' => 'H292913',
  'roid' => 'CNIC-HA321983',
  'status' => [
    'linked',
    'serverDeleteProhibited'
  ],
  'voice' => '+1.7035555555x1234',
  'fax' => '+1.7035555556',
  'email' => 'jdoe@example.com',
  'crDate' => '2007-09-23T03:51:29.0Z',
  'upDate' => '1999-11-30T00:00:00.0Z'
};

There may be up to two members of the postalInfo hash, corresponding to the int and loc internationalised and localised types.

OBJECT TRANSFERS

The EPP <transfer> command suppots five different operations: query, request, cancel, approve, and reject. Net::EPP::Simple makes these available using the following methods:

# For domain objects:

$epp->domain_transfer_query($domain);
$epp->domain_transfer_cancel($domain);
$epp->domain_transfer_request($domain, $authInfo, $period);
$epp->domain_transfer_approve($domain);
$epp->domain_transfer_reject($domain);

# For contact objects:

$epp->contact_transfer_query($contact);
$epp->contact_transfer_cancel($contact);
$epp->contact_transfer_request($contact, $authInfo);
$epp->contact_transfer_approve($contact);
$epp->contact_transfer_reject($contact);

Most of these methods will just set the value of $Net::EPP::Simple::Code and return either true or false. However, the domain_transfer_request(), domain_transfer_query(), contact_transfer_request() and contact_transfer_query() methods will return a hash ref that looks like this:

my $trnData = {
  'name' => 'example.tld',
  'reID' => 'losing-registrar',
  'acDate' => '2007-12-04T12:24:53.0Z',
  'acID' => 'gaining-registrar',
  'reDate' => '2007-11-29T12:24:53.0Z',
  'trStatus' => 'pending'
};

OVERRIDDEN METHODS FROM Net::EPP::Client

Net::EPP::Simple overrides some methods inherited from Net::EPP::Client. These are described below:

THE request() METHOD

Net::EPP::Simple overrides this method so it can automatically populate the <clTRID> element with a unique string. It then passes the frame back up to Net::EPP::Client.

THE get_frame() METHOD

Net::EPP::Simple overrides this method so it can catch timeouts and network errors. If such an error occurs it will return undef.

AUTHOR

CentralNic Ltd (http://www.centralnic.com/).

COPYRIGHT

This module is (c) 2007 CentralNic Ltd. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

1 POD Error

The following errors were encountered while parsing the POD:

Around line 208:

You forgot a '=back' before '=head1'