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.nic.tld',
                port    => 700,
                ssl     => 1,
                frames  => 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

\s-1EPP\s0 is the Extensible Provisioning Protocol. \s-1EPP\s0 (defined in \s-1RFC\s0 4930) is an application layer client-server protocol for the provisioning and management of objects stored in a shared central repository. Specified in \s-1XML\s0, 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.

\s-1RFC\s0 4934 defines a \s-1TCP\s0 based transport model for \s-1EPP\s0, and this module implements a client for that model. You can establish and manage \s-1EPP\s0 connections and send and receive responses over this connection.

\*(C`Net::EPP::Client\*(C' also provides some time-saving features, such as being able to provide request and response frames as \*(C`Net::EPP::Frame\*(C' objects.

CONSTRUCTOR

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

The constructor method creates a new \s-1EPP\s0 client object. It accepts a number of parameters:

host \*(C`host\*(C' specifies the computer to connect to. This may be a \s-1DNS\s0 hostname or an \s-1IP\s0 address.
port \*(C`port\*(C' specifies the \s-1TCP\s0 port to connect to. This is usually 700.
ssl If the \*(C`ssl\*(C' parameter is defined, then \*(C`IO::Socket::SSL\*(C' will be used to provide an encrypted connection. If not, then a plaintext connection will be created.
dom (deprecated) If the \*(C`dom\*(C' parameter is defined, then all response frames will be returned as \*(C`XML::LibXML::Document\*(C' objects.
frames If the \*(C`frames\*(C' parameter is defined, then all response frames will be returned as \*(C`Net::EPP::Frame\*(C' objects (actually, \*(C`XML::LibXML::Document\*(C' objects reblessed as \*(C`Net::EPP::Frame\*(C' objects).

METHODS

Connecting to a server:

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

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

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

By default, the return value for \*(C`connect()\*(C' will be the \s-1EPP\s0 <greeting> frame returned by the server. Please note that the same caveat about blocking applies to this method as to \*(C`get_frame()\*(C' (see below).

If you want to get the greeting yourself, set $params{no_greeting}.

Communicating with the server:

my $answer = $epp->request($question);

This is a simple wrapper around \*(C`get_frame()\*(C' and \*(C`send_frame()\*(C' (see below). This method accepts a \*(L"question\*(R" frame as an argument, sends it to the server, and then returns the next frame the server sends back.

Getting a frame from the server:

my $frame = $epp->get_frame;

This method returns an \s-1EPP\s0 response frame from the server. This may either be a scalar filled with \s-1XML\s0, an \*(C`XML::LibXML::Document\*(C' object (or an \*(C`XML::DOM::Document\*(C' object), depending on whether you defined the \*(C`dom\*(C' 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 \*(C`alarm()\*(C' 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 '') { alarm(0); print "timed out\n"; }

If the connection to the server closes before the response can be received, or the server returned a mal-formed frame, this method will \*(C`croak()\*(C'.

Sending a frame to the server:

$epp->send_frame($frame, $wfcheck);

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

a scalar containing \s-1XML\s0
a scalar containing a filename
an \*(C`XML::LibXML::Document\*(C' object (or an instance of a subclass)
an \*(C`XML::DOM::Document\*(C' object (or an instance of a subclass)

Unless $wfcheck is false, the first two of these will be checked for well-formedness. If the \s-1XML\s0 data is broken, then this method will croak.

Disconnecting from the server:

$epp->disconnect;

This closes the connection. An \s-1EPP\s0 server should 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.

Net::EPP::Client (3pm)