Sebastiaan Hoogeveen > Net-Lookup-DotTel-0.03 > Net::Lookup::DotTel

Download:
Net-Lookup-DotTel-0.03.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.03   Source  

NAME ^

Net::Lookup::DotTel - Look up information related to a .tel domain name (or possible another domain name having .tel-style TXT and NAPTR records).

DESCRIPTION ^

This module offers an easy way to access the contact information that is stored in DNS through NAPTR and TXT records under the .tel TLD.

SYNOPSIS ^

 use Net::Lookup::DotTel;
 my $lookup = Net::Lookup::DotTel->new;

 if ( $lookup->lookup ( 'smallco.tel' )) {

   my $service = $lookup->get_services ( 'email' );

   if ( $service->{uri} =~ /^mailto:(.+)/ ) {
     my $email = $1;
     print "SmallCo's email address is $email\n";
   }

 }

METHODS ^

new

 $lookup = Net::Lookup::DotTel->new;
 $lookup = Net::Lookup::DotTel->new ( resolver_config => $resolver_settings );

Constructor. The following optional named parameters can be specified:

lookup

 $lookup->lookup ( 'smallco.tel' );

Lookup the specified domain name. Returns 1 if the domain name exists or 0 otherwise. Note that the fact that a domain exists does not mean that it has any meaningful TXT or NAPTR records associated with it.

If the lookup was succesful, you can use the other methods to extract information from this domain.

get_keywords

 @keywords = $lookup->get_keywords;
 @keywords = $lookup->get_keywords ( 'pa' );

Return the keywords that are associated with the domain. Keywords contain additional information related to the domain name that cannot be specified using NAPTR records. Keywords are stored in TXT records using a .tel-specific format.

Keywords are ordered into groups. The returned list will contain a reference to a list (which can be interpolated to a hash) containing the keywords of a single group. If you specify one or more parameters, only keyword groups containing a value for the specified keywords will be returned.

E.g., to return only keyword groups that specify a Postal Address (pa) that contains at least a ZIP code (pc) and a city (tc), you specify:

 @keywords = $lookup->get_keywords ( 'pa', 'pc', 'tc' );

If only a single keyword group matches, @keywords would contain a single array reference looking something like:

 [ 'pa', '', 'a1', 'Somestreet 1', 'pc', '12094', 'tc', 'Some city', 'c', 'US' ]

Which can be interpolated into a hash so you get:

 {
   'pa' => '',
   'a1' => 'Somestreet 1',
   'pc' => '12094',
   'tc' => 'Some city',
   'c' => 'US'
 }

When interpolating, the order of the elements (which was originally preserved) will be lost. This may be relevant as .tel users can explicitly specify the order of the fields for presentation purposes.

For a description of available keywords and their shortened forms, please refer to the Telnic website, specifically Appendix B of the Developer's Manual.

For retrieving a list of (business) postal addresses associated with a domain name, you can also use the get_postal_address method. That methods translates the keywords to nicer ;) names.

get_postal_address

 @postal_addresses = $lookup->get_postal_address;

Return all postal addresses which are associated with the current domain. A postal address is a keyword group containing at least one of the following groups of keywords:

The returned list contains all addresses that could be found, ordered in the following way:

Note that the last of this order sequence does not make any particular sense; it is used only to guarantee that the order in which the addresses are returned stays the same if the data does not change.

Every address in the list consists of a reference to a hash with the following keys:

E.g., when a single address is returned with the current domain, the list may contain the following result for a Dutch address:

 {
   order => ['address1', 'postcode', 'city', 'country'],
   address1 => 'Some street 1',
   postcode => '1234 AB',
   city => 'Amsterdam',
   country => 'NL'
 }

In scalar context, returns only the first address (this is what you want to do for a 'quick and dirty' .tel based address lookup).

get_services

 @services = $lookup->get_services;
 @services = $lookup->get_services ( 'email' );

Return the services that are associated with the current domain. If an ENUM service is specified, returns only services that match this service type. The services are taken from the NAPTR records associated with the domain and are ordered by the preference and order fields. The service can be specified as specific as you want:

Every service in the list consists of a hash reference with the following keys:

For most uses, only 'label' and 'uri' will actually be interesting.

If the method is called in a scalar context, only the first service found is returned. For this service to always be the same we order the NAPTR records not just on preference and order, but also alphabetically by services, regexp, flags and replacement fields.

The .tel registry supports a number of non-standard ENUM services, which are described in the whitepaper 'NAPTR Records in .tel'.

get_text

 @text = $lookup->get_text;

Return the TXT records that are associated with the current domain that are not .tel keywords or system messages. This will retrieve any TXT record associated with the domain which does not start with ".tkw" or ".tsm". Note that the records are not returned in any particular order.

If the query was not succesful, an empty list is returned.

Note that all texts in a single TXT field are simply concatenated; this is due to the fact that plain .tel TXT fields usually contain a descriptive text only.

AUTHOR ^

Sebastiaan Hoogeveen, <pause-zebaz@nederhost.nl>

SEE ALSO ^

http://dev.telnic.org/pages/howtos.html for a link to the Developer's Manual which, among others, contains a description of the .tel keywords.

http://dev.telnic.org/pages/record_types.html for a link to the whitepaper 'NAPTR Records in .tel'.

http://dev.telnic.org/pages/howtos.html for a description of keywords.

If you are looking for a way to manipulate the DNS records in the Telnic system take a look at WebService::Telnic.

BUGS ^

Since this is a very early release of what could become a pretty complex module, there are probably several bugs in this code. Use at your own risk. Bugs can be reported by email to the author.

COPYRIGHT ^

Copyright 2009 Sebastiaan Hoogeveen. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://www.perl.com/perl/misc/Artistic.html

syntax highlighting: