File Coverage

blib/lib/Net/EPP/Frame.pm

Criterion	Covered	Total	%
statement	33	59	55.9
branch	0	8	0.0
condition			n/a
subroutine	11	17	64.7
pod	1	5	20.0
total	45	89	50.5

package Net::EPP::Frame;
use Carp;
use Net::EPP::Frame::Command;
use Net::EPP::Frame::Greeting;
use Net::EPP::Frame::Hello;
use Net::EPP::Frame::ObjectSpec;
use Net::EPP::Frame::Response;
use POSIX qw(strftime);
use XML::LibXML;
use base qw(XML::LibXML::Document);
use vars qw($EPP_URN);
use strict;

our $EPP_URN = 'urn:ietf:params:xml:ns:epp-1.0';

=pod

=head1 NAME

Net::EPP::Frame - An EPP XML frame system built on top of L.

=head1 SYNOPSIS

	#!/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	=> 'epp.registry.tld',
		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('result'))[0];
	if ($result->getAttribute('code') != 1000) {
		die("Login failed!");
	}

	#
	# OK, let's 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('domain');

	#
	# create a domain object using the spec:
	#
	my $domain = $check->addObject(@spec);

	#
	# set the domain name we want to check:
	#
	my $name = $check->createElement('domain:name');
	$name->appendText('example.tld');

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

=head1 DESCRIPTION

The L
(EPP)|https://www.rfc-editor.org/info/std69> uses XML documents called "frames"
send data to and from clients and servers.

This module implements a subclass of the L module that
simplifies the process of creation of these frames. It is designed to be used
alongside the L and L modules, but could
also be used on the server side.

=head1 OBJECT HIERARCHY

    L
    +----L
        +----L

=head1 USAGE

As a rule, you will not need to create C objects directly.
Instead, you should use one of the subclasses included with the distribution.
The subclasses all inherit from C.

C is itself a subclass of L so all the
methods available from that class are also available to instances of
C.

The available subclasses of C exist to add any additional
elements required by the EPP specification. For example, the EloginE
frame must contain the EclIDE and EpwE frames, so when you
create a new L object, you get these already
defined.

These classes also have convenience methods, so for the above example, you can
call the C<$login-EclID> and C<$login-Epw> methods to get the
L objects correesponding to those elements.

=head2 RATIONALE

You could just as easily construct your EPP frames from templates or just lots
of C 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, I. This
has to be a win.

=cut

sub new {
    my ($package, $type) = @_;

    if (!$type) {
        my @parts = split(/::/, $package);
        $type = lc(pop(@parts));
    }

    if ($type !~ /^(hello|greeting|command|response)$/) {
        croak("'type' parameter to Net::EPP::Frame::new() must be one of: hello, greeting, command, response ('$type' given).");
        return undef;
    }

    my $self = $package->SUPER::new('1.0', 'UTF-8');
    bless($self, $package);

    my $epp = $self->createElementNS($EPP_URN, 'epp');
    $self->addChild($epp);

    my $el = $self->createElement($type);
    $epp->addChild($el);

    $self->_addExtraElements;

    return $self;
}

sub _addExtraElements {
}

=pod

=head1 ADDITIONAL METHODS

	my $str = $frame->formatTimeStamp($timestamp);

This method returns a scalar in the required format (defined in RFC 3339). This
is a convenience method.

=cut

sub formatTimeStamp {
    my ($self, $stamp) = @_;
    return strftime('%Y-%m-%dT%H:%M:%S.0Z', gmtime($stamp));
}

=pod

	my $node = $frame->getNode($id);
	my $node = $frame->getNode($ns, $id);

This is another convenience method. It uses C<$id> with the
I method to get a list of nodes with that element name,
and simply returns the first L from the list.

If C<$ns> is provided, then I is used.

=cut

sub getNode {
    my ($self, @args) = @_;
    if (scalar(@args) == 2) {
        return ($self->getElementsByTagNameNS(@args))[0];

    } elsif (scalar(@args) == 1) {
        return ($self->getElementsByTagName($args[0]))[0];

    } else {
        croak('Invalid number of arguments to getNode()');

    }
}

=pod

	my $binary = $frame->header;

Returns a scalar containing the frame length packed into binary. This is
only useful for low-level protocol stuff.

=cut

sub header {
    my $self = shift;
    return pack('N', length($self->toString) + 4);
}

=pod

	my $data = $frame->frame;

Returns a scalar containing the frame header (see the I method
above) concatenated with the XML frame itself. This is only useful for
low-level protocol stuff.

=cut

sub frame {
    my $self = shift;
    return $self->header . $self->toString;
}

=pod

=head1 AVAILABLE SUBCLASSES

=over

=item * L, the base class

=item * L, for EPP client command frames

=item * L, for EPP EcheckE client commands

=item * L, for EPP EcreateE client commands

=item * L, for EPP EdeleteE client commands

=item * L, for EPP EinfoE client commands

=item * L, for EPP EloginE client commands

=item * L, for EPP ElogoutE client commands

=item * L, for EPP EpollE client commands

=item * L, for EPP ErenewE client commands

=item * L, for EPP EtransferE client commands

=item * L, for EupdateE client commands

=item * L, for EPP server greetings

=item * L, for EPP client greetings

=item * L, for EPP server response frames

=back

Each subclass has its own subclasses for various objects, for example L creates a CcheckE> frame for domain names.

Coverage for all combinations of command and object type is not complete, but work is ongoing.

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

=cut

1;