File Coverage

blib/lib/Socket/GetAddrInfo/Socket6api.pm

Criterion	Covered	Total	%
statement	26	26	100.0
branch	5	8	62.5
condition	6	14	42.8
subroutine	7	7	100.0
pod	2	2	100.0
total	46	57	80.7

#  You may distribute under the terms of either the GNU General Public License
#  or the Artistic License (the same terms as Perl itself)
#
#  (C) Paul Evans, 2010-2011 -- [e-mail]

package Socket::GetAddrInfo::Socket6api;

use strict;
use warnings;

use Carp;

our $VERSION = '0.22';

use Exporter 'import';
our @EXPORT_OK = qw(
   getaddrinfo
   getnameinfo
);

use Socket::GetAddrInfo ();

# Re-export all the AI_*, EAI_* and NI_* constants
my @constants = @{ $Socket::GetAddrInfo::EXPORT_TAGS{constants} };
push @EXPORT_OK, @constants;
Socket::GetAddrInfo->import( @constants );

=head1 NAME

C - Provide L functions
using L API

=head1 SYNOPSIS

 use Socket qw( AF_UNSPEC SOCK_STREAM );
 use Socket::GetAddrInfo::Socket6api qw( getaddrinfo getnameinfo );

 my $sock;

 my @res = getaddrinfo( "www.google.com", "www", AF_UNSPEC, SOCK_STREAM );

 die "Cannot resolve name - $res[0]" if @res == 1;

 while( @res >= 5 ) {
    my ( $family, $socktype, $protocol, $addr, undef ) = splice @res, 0, 5, ();

    $sock = IO::Socket->new();
    $sock->socket( $family, $socktype, $protocol ) or
      undef $sock, next;

    $sock->connect( $addr ) or undef $sock, next;

    last;
 }

 if( $sock ) {
    my ( $host, $service ) = getnameinfo( $sock->peername );
    print "Connected to $host:$service\n" if defined $host;
 }

=head1 DESCRIPTION

L provides the functions of C and
C using a convenient interface where hints and address structures
are represented as hashes. L also provides these functions, in a form
taking and returning flat lists of values.

This module wraps the functions provided by C to provide
them in an identical API to C. It is intended to stand as a utility
for existing code written for the C API to use these functions
instead.

=cut

=head1 FUNCTIONS

=cut

=head2 @res = getaddrinfo( $host, $service, $family, $socktype, $protocol, $flags )

This version of the API takes the hints values as separate ordered parameters.
Unspecified parameters should be passed as C<0>.

If successful, this function returns a flat list of values, five for each
returned address structure. Each group of five elements will contain, in
order, the C, C, C, C and C
values of the address structure.

If unsuccessful, it will return a single value, containing the string error
message. To remain compatible with the C interface, this value does
not have the error integer part.

=cut

sub getaddrinfo
{
   @_ >= 2 and @_ <= 6 or
      croak "Usage: getaddrinfo(host, service, family=0, socktype=0, protocol=0, flags=0)";

   my ( $host, $service, $family, $socktype, $protocol, $flags ) = @_;

   my ( $err, @res ) = Socket::GetAddrInfo::getaddrinfo( $host, $service, {
      flags    => $flags    || 0,
      family   => $family   || 0,
      socktype => $socktype || 0,
      protocol => $protocol || 0,
   } );

   return "$err" if $err;
   return map { $_->{family}, $_->{socktype}, $_->{protocol}, $_->{addr}, $_->{canonname} } @res;
}

=head2 ( $host, $service ) = getnameinfo( $addr, $flags )

This version of the API returns only the host name and service name, if
successfully resolved. On error, it will return an empty list. To remain
compatible with the C interface, no error information will be
supplied.

=cut

sub getnameinfo
{
   @_ >= 1 and @_ <= 2 or
      croak "Usage: getnameinfo(addr, flags=0)";

   my ( $addr, $flags ) = @_;

   my ( $err, $host, $service ) = Socket::GetAddrInfo::getnameinfo( $addr, $flags );

   return () if $err;
   return ( $host, $service );
}

=head1 AUTHOR

Paul Evans

=cut

0x55AA;