.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Net::EPP::Client 3pm"
.TH Net::EPP::Client 3pm "2021-01-09" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Net::EPP::Client \- a client library for the TCP transport for EPP, the Extensible Provisioning Protocol
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&        #!/usr/bin/perl
\&        use Net::EPP::Client;
\&        use strict;
\&
\&        my $epp = Net::EPP::Client\->new(
\&                host    => \*(Aqepp.nic.tld\*(Aq,
\&                port    => 700,
\&                ssl     => 1,
\&                frames  => 1,
\&        );
\&
\&        my $greeting = $epp\->connect;
\&
\&        $epp\->send_frame(\*(Aqlogin.xml\*(Aq);
\&
\&        my $answer = $epp\->get_frame;
\&
\&        $epp\->send_frame(\*(Aq<epp><logout /></epp>\*(Aq);
\&
\&        my $answer = $epp\->get_frame;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\s-1EPP\s0 is the Extensible Provisioning Protocol. \s-1EPP\s0 (defined in \s-1RFC 4930\s0) 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.
.PP
\&\s-1RFC 4934\s0 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.
.PP
\&\f(CW\*(C`Net::EPP::Client\*(C'\fR also provides some time-saving features, such as being able
to provide request and response frames as \f(CW\*(C`Net::EPP::Frame\*(C'\fR objects.
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
.Vb 1
\&        my $epp = Net::EPP::Client\->new(PARAMS);
.Ve
.PP
The constructor method creates a new \s-1EPP\s0 client object. It accepts a number of
parameters:
.IP "\(bu" 4
host
.Sp
\&\f(CW\*(C`host\*(C'\fR specifies the computer to connect to. This may be a \s-1DNS\s0 hostname or
an \s-1IP\s0 address.
.IP "\(bu" 4
port
.Sp
\&\f(CW\*(C`port\*(C'\fR specifies the \s-1TCP\s0 port to connect to. This is usually 700.
.IP "\(bu" 4
ssl
.Sp
If the \f(CW\*(C`ssl\*(C'\fR parameter is defined, then \f(CW\*(C`IO::Socket::SSL\*(C'\fR will be used to
provide an encrypted connection. If not, then a plaintext connection will be
created.
.IP "\(bu" 4
dom (deprecated)
.Sp
If the \f(CW\*(C`dom\*(C'\fR parameter is defined, then all response frames will be returned
as \f(CW\*(C`XML::LibXML::Document\*(C'\fR objects.
.IP "\(bu" 4
frames
.Sp
If the \f(CW\*(C`frames\*(C'\fR parameter is defined, then all response frames will be
returned as \f(CW\*(C`Net::EPP::Frame\*(C'\fR objects (actually, \f(CW\*(C`XML::LibXML::Document\*(C'\fR
objects reblessed as \f(CW\*(C`Net::EPP::Frame\*(C'\fR objects).
.SH "METHODS"
.IX Header "METHODS"
.SS "Connecting to a server:"
.IX Subsection "Connecting to a server:"
.Vb 1
\&        my $greeting = $epp\->connect(%PARAMS);
.Ve
.PP
This method establishes the \s-1TCP\s0 connection. You can use the \f(CW%PARAMS\fR hash to
specify arguments that will be passed on to the constructors for
\&\f(CW\*(C`IO::Socket::INET\*(C'\fR (such as a timeout) or \f(CW\*(C`IO::Socket::SSL\*(C'\fR (such as
certificate information). See the relevant manpage for examples.
.PP
This method will \f(CW\*(C`croak()\*(C'\fR if connection fails, so be sure to use \f(CW\*(C`eval()\*(C'\fR if
you want to catch the error.
.PP
By default, the return value for \f(CW\*(C`connect()\*(C'\fR 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 \f(CW\*(C`get_frame()\*(C'\fR (see below).
.PP
If you want to get the greeting yourself, set \f(CW$params{no_greeting}\fR.
.SS "Communicating with the server:"
.IX Subsection "Communicating with the server:"
.Vb 1
\&        my $answer = $epp\->request($question);
.Ve
.PP
This is a simple wrapper around \f(CW\*(C`get_frame()\*(C'\fR and \f(CW\*(C`send_frame()\*(C'\fR (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.
.SS "Getting a frame from the server:"
.IX Subsection "Getting a frame from the server:"
.Vb 1
\&        my $frame = $epp\->get_frame;
.Ve
.PP
This method returns an \s-1EPP\s0 response frame from the server. This may either be a
scalar filled with \s-1XML,\s0 an \f(CW\*(C`XML::LibXML::Document\*(C'\fR object (or an
\&\f(CW\*(C`XML::DOM::Document\*(C'\fR object), depending on whether you defined the \f(CW\*(C`dom\*(C'\fR
parameter to the constructor.
.PP
\&\fBImportant Note\fR: 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 \f(CW\*(C`alarm()\*(C'\fR function to apply a timeout, like
so:
.PP
.Vb 1
\&        my $timeout = 10; # ten seconds
\&
\&        eval {
\&                local $SIG{ALRM} = sub { die "alarm\en" };
\&                alarm($timeout);
\&                my $frame = $epp\->get_frame;
\&                alarm(0);
\&        };
\&
\&        if ($@ ne \*(Aq\*(Aq) {
\&                alarm(0);
\&                print "timed out\en";
\&        }
.Ve
.PP
If the connection to the server closes before the response can be received, or
the server returned a mal-formed frame, this method will \f(CW\*(C`croak()\*(C'\fR.
.SS "Sending a frame to the server:"
.IX Subsection "Sending a frame to the server:"
.Vb 1
\&        $epp\->send_frame($frame, $wfcheck);
.Ve
.PP
This sends a request frame to the server. \f(CW$frame\fR may be one of:
.IP "\(bu" 4
a scalar containing \s-1XML\s0
.IP "\(bu" 4
a scalar containing a filename
.IP "\(bu" 4
an \f(CW\*(C`XML::LibXML::Document\*(C'\fR object (or an instance of a subclass)
.IP "\(bu" 4
an \f(CW\*(C`XML::DOM::Document\*(C'\fR object (or an instance of a subclass)
.PP
Unless \f(CW$wfcheck\fR 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.
.SS "Disconnecting from the server:"
.IX Subsection "Disconnecting from the server:"
.Vb 1
\&        $epp\->disconnect;
.Ve
.PP
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.
.SH "AUTHOR"
.IX Header "AUTHOR"
CentralNic Ltd (<http://www.centralnic.com/>).
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
This module is (c) 2016 CentralNic Ltd. This module is free software; you can
redistribute it and/or modify it under the same terms as Perl itself.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "\(bu" 4
Net::EPP::Frame
.IP "\(bu" 4
Net::EPP::Proxy
.IP "\(bu" 4
RFCs 4930 and \s-1RFC 4934,\s0 available from <http://www.ietf.org/>.
.IP "\(bu" 4
The CentralNic \s-1EPP\s0 site at <http://www.centralnic.com/resellers/epp>.