1package Net::DNS::ToolKit::RR::A;
2
3#use 5.006;
4use strict;
5#use warnings;
6
7use vars qw($VERSION @ISA);
8require Net::DNS::ToolKit::RR::Template;
9
10$VERSION = do { my @r = (q$Revision: 0.02 $ =~ /\d+/g); sprintf "%d."."%02d" x $#r, @r };
11
12@ISA = qw(Net::DNS::ToolKit::RR::Template);
13
14*get	= \&Net::DNS::ToolKit::RR::Template::get;
15*put	= \&Net::DNS::ToolKit::RR::Template::put;
16*parse	= \&Net::DNS::ToolKit::RR::Template::parse;
17
18=cut
19
201;
21__END__
22
23=head1 NAME
24
25Net::DNS::ToolKit::RR::A - Resource Record Handler
26
27=head1 SYNOPSIS
28
29  DO NOT use Net::DNS::ToolKit::RR::A
30  DO NOT require Net::DNS::ToolKit::RR::A
31
32  Net::DNS::ToolKit::RR::A is autoloaded by
33  class Net::DNS::ToolKit::RR and its methods
34  are instantiated in a 'special' manner.
35
36  use Net::DNS::ToolKit::RR;
37  ($get,$put,$parse) = new Net::DNS::ToolKit::RR;
38
39  ($newoff,$name,$type,$class,$ttl,$rdlength,
40	$netaddr) = $get->A(\$buffer,$offset);
41
42  Note: the $get->A method is normally called
43  via:	@stuff = $get->next(\$buffer,$offset);
44
45  ($newoff,@dnptrs)=$put->A(\$buffer,$offset,\@dnptrs,
46        $name,$type,$class,$ttl,$netaddr);
47
48  $name,$TYPE,$CLASS,$TTL,$rdlength,$IPaddr)
49    = $parse->A($name,$type,$class,$ttl,$rdlength,
50	$netaddr);
51
52=head1 DESCRIPTION
53
54B<Net::DNS::ToolKit::RR:A> appends an A resource record to a DNS packet under
55construction, recovers an A resource record from a packet being decoded, and
56converts the numeric/binary portions of the resource record to human
57readable form.
58
59  Description from RFC1035.txt
60
61  3.2.1. Format
62
63  All RRs have the same top level format shown below:
64
65                                    1  1  1  1  1  1
66      0  1  2  3  4  5  6  7  8  9  0  1  2  3  4  5
67    +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
68    |                      NAME                     |
69    +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
70    |                      TYPE                     |
71    +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
72    |                     CLASS                     |
73    +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
74    |                      TTL                      |
75    +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
76    |                   RDLENGTH                    |
77    +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--|
78    |                     RDATA                     |
79    +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
80
81  NAME	an owner name, i.e., the name of the node to which this
82	resource record pertains.
83
84  TYPE	two octets containing one of the RR TYPE codes.
85
86  CLASS	two octets containing one of the RR CLASS codes.
87
88  TTL	a 32 bit signed integer that specifies the time interval
89	that the resource record may be cached before the source
90	of the information should again be consulted.  Zero
91	values are interpreted to mean that the RR can only be
92	used for the transaction in progress, and should not be
93	cached.  For example, SOA records are always distributed
94	with a zero TTL to prohibit caching.  Zero values can
95	also be used for extremely volatile data.
96
97  RDLENGTH an unsigned 16 bit integer that specifies the length
98	in octets of the RDATA field.
99
100  RDATA	a variable length string of octets that describes the
101	resource.  The format of this information varies
102	according to the TYPE and CLASS of the resource record.
103
104  3.4.1. A RDATA format
105
106    +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
107    |                    ADDRESS                    |
108    +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
109
110  where:
111
112  ADDRESS         A 32 bit Internet address.
113
114Hosts that have multiple Internet addresses will have multiple A
115records.
116
117=over 4
118
119=item * @stuff = $get->A(\$buffer,$offset);
120
121  Get the contents of the resource record.
122
123  USE: @stuff = $get->next(\$buffer,$offset);
124
125  where: @stuff = (
126  $newoff $name,$type,$class,$ttl,$rdlength,
127  $netaddr );
128
129All except the last item, B<$netaddr>, is provided by
130the class loader, B<Net::DNS::ToolKit::RR>. The code in this method knows
131how to retrieve B<$netaddr>.
132
133  input:	pointer to buffer,
134		offset into buffer
135  returns:	offset to next resource,
136		@common RR elements,
137		packed IPv4 address
138		  in network order
139
140  NOTE:	convert IPv4 address to dot quad text
141	using Net::DNS::ToolKit::inet_ntoa
142
143=item * ($newoff,@dnptrs)=$put->A(\$buffer,$offset,\@dnptrs,
144	@common,$netaddr);
145
146Append an A record to $buffer.
147
148  where @common = $name,$type,$class,$ttl
149
150The B<A> method will insert the $rdlength and $netaddr, then
151pass through the updated pointer to the array of compressed names
152
153The class loader, B<Net::DNS::ToolKit::RR>, inserts the @common elements and
154returns updated @dnptrs. This module knows how to insert its RDATA and calculate the $rdlength.
155
156  input:	pointer to buffer,
157		offset (normally end of buffer),
158		pointer to compressed name array,
159		@common RR elements,
160		packed IPv4 address
161		  in network order
162  output:	offset to next RR,
163		new compressed name pointer array,
164	   or	empty list () on error.
165
166  NOTE:	convert dot quad text to a packed network
167	address using Net::DNS::ToolKit::inet_aton
168
169=item * (@COMMON,$RDATA) = $parse->A(@common,$rdata,...);
170
171Converts binary/numeric field data into human readable form. The common RR
172elements are supplied by the class loader, B<Net::DNS::ToolKit::RR>. This
173module knows how to parse its RDATA.
174
175	EXAMPLE
176Common is: name,$type,$class,$ttl,$rdlength
177
178  name       is already text.
179  type       numeric to text
180  class      numeric to text
181  ttl        numeric to text
182  rdlength   is a number
183  rdata      RR specific conversion
184
185Resource Record B<A> returns $rdata containing a packed IPv4 network
186address. The parse operation would be:
187
188input:
189
190  name       foo.bar.com
191  type       1
192  class      1
193  ttl        123
194  rdlength   4
195  rdata      a packed IPv4 address
196
197output:
198
199  name       foo.bar.com
200  type       T_A
201  class      C_IN
202  ttl        123 # 2m 3s
203  rdlength   4
204  rdata      192.168.20.40
205
206=back
207
208=head1 DEPENDENCIES
209
210	Net::DNS::ToolKit
211	Net::DNS::ToolKit::RR::Template
212	Net::DNS::Codes
213
214=head1 EXPORT
215
216	none
217
218=head1 AUTHOR
219
220Michael Robinton <michael@bizsystems.com>
221
222=head1 COPYRIGHT
223
224    Copyright 2003 - 2011, Michael Robinton <michael@bizsystems.com>
225
226Michael Robinton <michael@bizsystems.com>
227
228All rights reserved.
229
230This program is free software; you can redistribute it and/or modify
231it under the terms of either:
232
233  a) the GNU General Public License as published by the Free
234  Software Foundation; either version 2, or (at your option) any
235  later version, or
236
237  b) the "Artistic License" which comes with this distribution.
238
239This program is distributed in the hope that it will be useful,
240but WITHOUT ANY WARRANTY; without even the implied warranty of
241MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See either
242the GNU General Public License or the Artistic License for more details.
243
244You should have received a copy of the Artistic License with this
245distribution, in the file named "Artistic".  If not, I'll be glad to provide
246one.
247
248You should also have received a copy of the GNU General Public License
249along with this program in the file named "Copying". If not, write to the
250
251        Free Software Foundation, Inc.
252        59 Temple Place, Suite 330
253        Boston, MA  02111-1307, USA
254
255or visit their web page on the internet at:
256
257        http://www.gnu.org/copyleft/gpl.html.
258
259=head1 See also:
260
261Net::DNS::Codes(3), Net::DNS::ToolKit(3), Net::DNS::ToolKit::RR::Template(3)
262
263=cut
264
2651;
266