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