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.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

       RFC 5743 <https://www.rfc-editor.org/rfc/rfc5734.html> 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 ver this connection.

       "Net::EPP::Client" also provides some time-saving features, such as being able to provide
       request and response frames as "Net::EPP::Frame" 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 (deprecated)

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

       •   frames

           If the "frames" parameter is defined, then all response frames will be returned as
           Net::EPP::Frame objects (actually, XML::LibXML::Document objects reblessed as
           Net::EPP::Frame objects).

METHODS

   Connecting to a server:
               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.

       By default, 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).

       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 "get_frame()" and "send_frame()" (see below).  This method
       accepts a "question" 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 EPP response frame from the server. This may either be a scalar
       filled with XML, an XML::LibXML::Document object (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 '') {
                       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 "croak()".

   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 XML

       •   a scalar containing a filename

       •   an XML::LibXML::Document object (or an instance of a subclass)

       •   an XML::DOM::Document object (or an instance of a subclass)

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

   Disconnecting from the server:
               $epp->disconnect;

       This closes the connection. An EPP 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.