/ 
Net-EPP-Client-0.02
/ Net::EPP::Client

NAME

Net::EPP::Client - a client library for the TCP transport for EPP, the Extensible Provisioning Protocol

SYNOPSIS

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

my $epp = Net::EPP::Client->new(
	host	=> 'epp.registry.tld',
	port	=> 700,
	ssl	=> 1,
	dom	=> 1,
);

my $greeting = $epp->connect;

$epp->send_frame('login.xml');

my $answer = $epp->get_frame;

$epp->send_frame('<epp><logout /></epp>');

my $answer = $epp->get_frame;

DESCRIPTION

EPP is the Extensible Provisioning Protocol. EPP (defined in RFC 3730) 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.

RFC 3734 defines a TCP based transport model for EPP, and this module implements a client for that model. You can establish and manage EPP connections and send and receive responses over this connection.

Net::EPP::Client also provides some time-saving features, such as being able to provide request and response frames as XML::DOM::Document objects.

CONSTRUCTOR

my $epp = Net::EPP::Client->new(PARAMS);

The constructor method creates a new EPP client object. It accepts a number of parameters:

  • host

    host specifies the computer to connect to. This may be a DNS hostname or an IP address.

  • port

    port specifies the TCP port to connect to. This is usually 700.

  • ssl

    If the ssl parameter is defined, then IO::Socket::SSL will be used to provide an encrypted connection. If not, then a plaintext connection will be created.

  • dom

    If the dom parameter is defined, then all response frames will be returned as XML::DOM::Document objects.

METHODS

my $greeting = $epp->connect(%PARAMS);

This method establishes the TCP connection. You can use the %PARAMS hash to specify arguments that will be passed on to the constructors for IO::Socket::INET (such as a timeout) or IO::Socket::SSL (such as certificate information). See the relevant manpage for examples.

This method will croak() if connection fails, so be sure to use eval() if you want to catch the error.

The return value for connect() will be the EPP <greeting> frame returned by the server. Please note that the same caveat about blocking applies to this method as to get_frame() (see below).

my $frame = $epp->get_frame();

This method returns an EPP response frame from the server. This may either be a scalar filled with XML, or an XML::DOM::Document object, depending on whether you defined the dom parameter to the constructor.

Important Note: this method will block your program until it receives the full frame from the server. That could be a bad thing for your program, so you might want to consider using the alarm() function to apply a timeout, like so:

my $timeout = 10; # ten seconds

eval {
	local $SIG{ALRM} = sub { die "alarm\n" };
	alarm($timeout);
	my $frame = $epp->get_frame;
	alarm(0);
};

if ($@ ne '') {
	print "timed out\n";
}
$epp->send_frame($frame);

This sends a request frame to the server. $frame may be one of:

  • a scalar containing XML

  • a scalar containing a filename

  • an XML::DOM::Document object

In the case of the first two, the XML will be checked for well-formedness before being sent. If the XML isn't well formed, this method will croak().

$epp->disconnect;

This closes the connection. An EPP server will always close a connection after a <logout> frame has been received and acknowledged; this method is provided to allow you to clean up on the client side, or close the connection out of sync with the server.

COPYRIGHT

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

TO DO

  • implement some command-specific stuff, so you can simply use methods like login(), check(), etc

SEE ALSO