.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) .\" .\" 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 .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . 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::Frame 3pm" .TH Net::EPP::Frame 3pm 2024-04-27 "perl v5.38.2" "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::Frame \- An EPP XML frame system built on top of XML::LibXML. .SH SYNOPSIS .IX Header "SYNOPSIS" .Vb 7 \& #!/usr/bin/perl \& use Net::EPP::Client; \& use Net::EPP::Frame; \& use Net::EPP::ObjectSpec; \& use Digest::MD5 qw(md5_hex); \& use Time::HiRes qw(time); \& use strict; \& \& # \& # establish a connection to an EPP server: \& # \& my $epp = Net::EPP::Client\->new( \& host => \*(Aqepp.registry.tld\*(Aq, \& port => 700, \& ssl => 1, \& dom => 1, \& ); \& \& my $greeting = $epp\->connect; \& \& # \& # log in: \& # \& my $login = Net::EPP::Frame::Command::Login\->new; \& \& $login\->clID\->appendText($userid); \& $login\->pw\->appendText($passwd); \& \& # \& # set the client transaction ID: \& # \& $login\->clTRID\->appendText(md5_hex(Time::HiRes::time().$$)); \& \& # \& # check the response from the log in: \& # \& my $answer = $epp\->request($login); \& \& my $result = ($answer\->getElementsByTagName(\*(Aqresult\*(Aq))[0]; \& if ($result\->getAttribute(\*(Aqcode\*(Aq) != 1000) { \& die("Login failed!"); \& } \& \& # \& # OK, let\*(Aqs do a domain name check: \& # \& my $check = Net::EPP::Frame::Command::Check\->new; \& \& # \& # get the spec from L: \& # \& my @spec = Net::EPP::Frame::ObjectSpec\->spec(\*(Aqdomain\*(Aq); \& \& # \& # create a domain object using the spec: \& # \& my $domain = $check\->addObject(@spec); \& \& # \& # set the domain name we want to check: \& # \& my $name = $check\->createElement(\*(Aqdomain:name\*(Aq); \& $name\->appendText(\*(Aqexample.tld\*(Aq); \& \& # \& # set the client transaction ID: \& # \& $check\->clTRID\->appendText(md5_hex(time().$$)); \& \& # \& # assemble the frame: \& # \& $domain\->addChild($name); \& \& # \& # send the request: \& # \& my $answer = $epp\->request($check); \& \& # and so on... .Ve .SH DESCRIPTION .IX Header "DESCRIPTION" The Extensible Provisioning Protocol (EPP) uses XML documents called "frames" send data to and from clients and servers. .PP This module implements a subclass of the XML::LibXML::Document module that simplifies the process of creation of these frames. It is designed to be used alongside the Net::EPP::Client and Net::EPP::Simple modules, but could also be used on the server side. .SH "OBJECT HIERARCHY" .IX Header "OBJECT HIERARCHY" .Vb 3 \& L \& +\-\-\-\-L \& +\-\-\-\-L .Ve .SH USAGE .IX Header "USAGE" As a rule, you will not need to create \f(CW\*(C`Net::EPP::Frame\*(C'\fR objects directly. Instead, you should use one of the subclasses included with the distribution. The subclasses all inherit from \f(CW\*(C`Net::EPP::Frame\*(C'\fR. .PP \&\f(CW\*(C`Net::EPP::Frame\*(C'\fR is itself a subclass of XML::LibXML::Document so all the methods available from that class are also available to instances of \&\f(CW\*(C`Net::EPP::Frame\*(C'\fR. .PP The available subclasses of \f(CW\*(C`Net::EPP::Frame\*(C'\fR exist to add any additional elements required by the EPP specification. For example, the frame must contain the and frames, so when you create a new Net::EPP::Frame::Command::Login object, you get these already defined. .PP These classes also have convenience methods, so for the above example, you can call the \f(CW\*(C`$login\->clID\*(C'\fR and \f(CW\*(C`$login\->pw\*(C'\fR methods to get the XML::LibXML::Node objects correesponding to those elements. .SS RATIONALE .IX Subsection "RATIONALE" You could just as easily construct your EPP frames from templates or just lots of \f(CWprintf()\fR calls. But using a programmatic approach such as this strongly couples the validity of your XML to the validity of your program. If the process by which your XML is built is broken, \fIyour program won't run\fR. This has to be a win. .SH "ADDITIONAL METHODS" .IX Header "ADDITIONAL METHODS" .Vb 1 \& my $str = $frame\->formatTimeStamp($timestamp); .Ve .PP This method returns a scalar in the required format (defined in RFC 3339). This is a convenience method. .PP .Vb 2 \& my $node = $frame\->getNode($id); \& my $node = $frame\->getNode($ns, $id); .Ve .PP This is another convenience method. It uses \f(CW$id\fR with the \&\fR\f(BIgetElementsByTagName()\fR\fI\fR method to get a list of nodes with that element name, and simply returns the first XML::LibXML::Element from the list. .PP If \f(CW$ns\fR is provided, then \fR\f(BIgetElementsByTagNameNS()\fR\fI\fR is used. .PP .Vb 1 \& my $binary = $frame\->header; .Ve .PP Returns a scalar containing the frame length packed into binary. This is only useful for low-level protocol stuff. .PP .Vb 1 \& my $data = $frame\->frame; .Ve .PP Returns a scalar containing the frame header (see the \fR\f(BIheader()\fR\fI\fR method above) concatenated with the XML frame itself. This is only useful for low-level protocol stuff. .SH "AVAILABLE SUBCLASSES" .IX Header "AVAILABLE SUBCLASSES" .IP \(bu 4 Net::EPP::Frame, the base class .IP \(bu 4 Net::EPP::Frame::Command, for EPP client command frames .IP \(bu 4 Net::EPP::Frame::Command::Check, for EPP client commands .IP \(bu 4 Net::EPP::Frame::Command::Create, for EPP client commands .IP \(bu 4 Net::EPP::Frame::Command::Delete, for EPP client commands .IP \(bu 4 Net::EPP::Frame::Command::Info, for EPP client commands .IP \(bu 4 Net::EPP::Frame::Command::Login, for EPP client commands .IP \(bu 4 Net::EPP::Frame::Command::Logout, for EPP client commands .IP \(bu 4 Net::EPP::Frame::Command::Poll, for EPP client commands .IP \(bu 4 Net::EPP::Frame::Command::Renew, for EPP client commands .IP \(bu 4 Net::EPP::Frame::Command::Transfer, for EPP client commands .IP \(bu 4 Net::EPP::Frame::Command::Update, for client commands .IP \(bu 4 Net::EPP::Frame::Greeting, for EPP server greetings .IP \(bu 4 Net::EPP::Frame::Hello, for EPP client greetings .IP \(bu 4 Net::EPP::Frame::Response, for EPP server response frames .PP Each subclass has its own subclasses for various objects, for example Net::EPP::Frame::Command::Check::Domain creates a \f(CW\*(C`\*(C'\fR frame for domain names. .PP Coverage for all combinations of command and object type is not complete, but work is ongoing. .SH COPYRIGHT .IX Header "COPYRIGHT" This module is (c) 2008 \- 2023 CentralNic Ltd and 2024 Gavin Brown. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.