source: trunk/doc/html/qdns.html

Last change on this file was 190, checked in by rudi, 14 years ago

reference documentation added
File size: 16.4 KB
RevLine 
[190]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2<!-- /home/espenr/tmp/qt-3.3.8-espenr-2499/qt-x11-free-3.3.8/src/network/qdns.cpp:1597 -->
3<html>
4<head>
5<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
6<title>QDns Class</title>
7<style type="text/css"><!--
8fn { margin-left: 1cm; text-indent: -1cm; }
9a:link { color: #004faf; text-decoration: none }
10a:visited { color: #672967; text-decoration: none }
11body { background: #ffffff; color: black; }
12--></style>
13</head>
14<body>
15
16<table border="0" cellpadding="0" cellspacing="0" width="100%">
17<tr bgcolor="#E5E5E5">
18<td valign=center>
19 <a href="index.html">
20<font color="#004faf">Home</font></a>
21 | <a href="classes.html">
22<font color="#004faf">All&nbsp;Classes</font></a>
23 | <a href="mainclasses.html">
24<font color="#004faf">Main&nbsp;Classes</font></a>
25 | <a href="annotated.html">
26<font color="#004faf">Annotated</font></a>
27 | <a href="groups.html">
28<font color="#004faf">Grouped&nbsp;Classes</font></a>
29 | <a href="functions.html">
30<font color="#004faf">Functions</font></a>
31</td>
32<td align="right" valign="center"><img src="logo32.png" align="right" width="64" height="32" border="0"></td></tr></table><h1 align=center>QDns Class Reference<br><small>[<a href="network.html">network module</a>]</small></h1>
33
34<p>The QDns class provides asynchronous DNS lookups.
35<a href="#details">More...</a>
36<p><tt>#include &lt;<a href="qdns-h.html">qdns.h</a>&gt;</tt>
37<p>Inherits <a href="qobject.html">QObject</a>.
38<p><a href="qdns-members.html">List of all member functions.</a>
39<h2>Public Members</h2>
40<ul>
41<li class=fn>enum <a href="#RecordType-enum"><b>RecordType</b></a> { None, A, Aaaa, Mx, Srv, Cname, Ptr, Txt }</li>
42<li class=fn><a href="#QDns"><b>QDns</b></a> ()</li>
43<li class=fn><a href="#QDns-2"><b>QDns</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;label, RecordType&nbsp;rr = A )</li>
44<li class=fn><a href="#QDns-3"><b>QDns</b></a> ( const&nbsp;QHostAddress&nbsp;&amp;&nbsp;address, RecordType&nbsp;rr = Ptr )</li>
45<li class=fn>virtual <a href="#~QDns"><b>~QDns</b></a> ()</li>
46<li class=fn>virtual void <a href="#setLabel"><b>setLabel</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;label )</li>
47<li class=fn>virtual void <a href="#setLabel-2"><b>setLabel</b></a> ( const&nbsp;QHostAddress&nbsp;&amp;&nbsp;address )</li>
48<li class=fn>QString <a href="#label"><b>label</b></a> () const</li>
49<li class=fn>virtual void <a href="#setRecordType"><b>setRecordType</b></a> ( RecordType&nbsp;rr = A )</li>
50<li class=fn>RecordType <a href="#recordType"><b>recordType</b></a> () const</li>
51<li class=fn>bool <a href="#isWorking"><b>isWorking</b></a> () const</li>
52<li class=fn>QValueList&lt;QHostAddress&gt; <a href="#addresses"><b>addresses</b></a> () const</li>
53<li class=fn>QValueList&lt;MailServer&gt; <a href="#mailServers"><b>mailServers</b></a> () const</li>
54<li class=fn>QValueList&lt;Server&gt; <a href="#servers"><b>servers</b></a> () const</li>
55<li class=fn>QStringList <a href="#hostNames"><b>hostNames</b></a> () const</li>
56<li class=fn>QStringList <a href="#texts"><b>texts</b></a> () const</li>
57<li class=fn>QString <a href="#canonicalName"><b>canonicalName</b></a> () const</li>
58<li class=fn>QStringList <a href="#qualifiedNames"><b>qualifiedNames</b></a> () const</li>
59</ul>
60<h2>Signals</h2>
61<ul>
62<li class=fn>void <a href="#resultsReady"><b>resultsReady</b></a> ()</li>
63</ul>
64<hr><a name="details"></a><h2>Detailed Description</h2>
65
66
67The QDns class provides asynchronous DNS lookups.
68
69<p>
70
71<p> Both Windows and Unix provide synchronous DNS lookups; Windows
72provides some asynchronous support too. At the time of writing
73neither operating system provides asynchronous support for
74anything other than hostname-to-address mapping.
75<p> QDns rectifies this shortcoming, by providing asynchronous caching
76lookups for the record types that we expect modern GUI
77applications to need in the near future.
78<p> The class is <em>not</em> straightforward to use (although it is much
79simpler than the native APIs); <a href="qsocket.html">QSocket</a> provides much easier to use
80TCP connection facilities. The aim of QDns is to provide a correct
81and small API to the DNS and nothing more. (We use "correctness"
82to mean that the DNS information is correctly cached, and
83correctly timed out.)
84<p> The API comprises a constructor, functions to set the DNS node
85(the domain in DNS terminology) and record type (<a href="#setLabel">setLabel</a>() and
86<a href="#setRecordType">setRecordType</a>()), the corresponding get functions, an <a href="#isWorking">isWorking</a>()
87function to determine whether QDns is working or reading, a
88<a href="#resultsReady">resultsReady</a>() signal and query functions for the result.
89<p> There is one query function for each RecordType, namely
90<a href="#addresses">addresses</a>(), <a href="#mailServers">mailServers</a>(), <a href="#servers">servers</a>(), <a href="#hostNames">hostNames</a>() and <a href="#texts">texts</a>().
91There are also two generic query functions: <a href="#canonicalName">canonicalName</a>()
92returns the name you'll presumably end up using (the exact meaning
93of this depends on the record type) and <a href="#qualifiedNames">qualifiedNames</a>() returns a
94list of the fully qualified names <a href="#label">label</a>() maps to.
95<p> <p>See also <a href="qsocket.html">QSocket</a> and <a href="io.html">Input/Output and Networking</a>.
96
97<hr><h2>Member Type Documentation</h2>
98<h3 class=fn><a name="RecordType-enum"></a>QDns::RecordType</h3>
99
100<p> This enum type defines the record types QDns can handle. The DNS
101provides many more; these are the ones we've judged to be in
102current use, useful for GUI programs and important enough to
103support right away:
104<ul>
105<li><tt>QDns::None</tt> - No information. This exists only so that QDns can
106have a default.
107<li><tt>QDns::A</tt> - IPv4 addresses. By far the most common type.
108<li><tt>QDns::Aaaa</tt> - IPv6 addresses. So far mostly unused.
109<li><tt>QDns::Mx</tt> - Mail eXchanger names. Used for mail delivery.
110<li><tt>QDns::Srv</tt> - SeRVer names. Generic record type for finding
111servers. So far mostly unused.
112<li><tt>QDns::Cname</tt> - Canonical names. Maps from nicknames to the true
113name (the canonical name) for a host.
114<li><tt>QDns::Ptr</tt> - name PoinTeRs. Maps from IPv4 or IPv6 addresses to hostnames.
115<li><tt>QDns::Txt</tt> - arbitrary TeXT for domains.
116</ul><p> We expect that some support for the
117<a href="http://www.dns.net/dnsrd/rfc/rfc2535.html">RFC-2535</a>
118extensions will be added in future versions.
119
120<hr><h2>Member Function Documentation</h2>
121<h3 class=fn><a name="QDns"></a>QDns::QDns ()
122</h3>
123Constructs a DNS query object with invalid settings for both the
124label and the search type.
125
126<h3 class=fn><a name="QDns-2"></a>QDns::QDns ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;label, <a href="qdns.html#RecordType-enum">RecordType</a>&nbsp;rr = A )
127</h3>
128Constructs a DNS query object that will return record type <em>rr</em>
129information about <em>label</em>.
130<p> The DNS lookup is started the next time the application enters the
131event loop. When the result is found the signal <a href="#resultsReady">resultsReady</a>() is
132emitted.
133<p> <em>rr</em> defaults to <a href="#RecordType-enum">A</a>, IPv4 addresses.
134
135<h3 class=fn><a name="QDns-3"></a>QDns::QDns ( const&nbsp;<a href="qhostaddress.html">QHostAddress</a>&nbsp;&amp;&nbsp;address, <a href="qdns.html#RecordType-enum">RecordType</a>&nbsp;rr = Ptr )
136</h3>
137Constructs a DNS query object that will return record type <em>rr</em>
138information about host address <em>address</em>. The label is set to the
139IN-ADDR.ARPA domain name. This is useful in combination with the
140<a href="#RecordType-enum">Ptr</a> record type (e.g. if you want to look up a hostname for a
141given address).
142<p> The DNS lookup is started the next time the application enters the
143event loop. When the result is found the signal <a href="#resultsReady">resultsReady</a>() is
144emitted.
145<p> <em>rr</em> defaults to <a href="#RecordType-enum">Ptr</a>, that maps addresses to hostnames.
146
147<h3 class=fn><a name="~QDns"></a>QDns::~QDns ()<tt> [virtual]</tt>
148</h3>
149Destroys the DNS query object and frees its allocated resources.
150
151<h3 class=fn><a href="qvaluelist.html">QValueList</a>&lt;QHostAddress&gt; <a name="addresses"></a>QDns::addresses () const
152</h3>
153Returns a list of the addresses for this name if this QDns object
154has a <a href="#recordType">recordType</a>() of <a href="#RecordType-enum">QDns::A</a> or <a href="#RecordType-enum">QDns::Aaaa</a> and the answer
155is available; otherwise returns an empty list.
156<p> As a special case, if <a href="#label">label</a>() is a valid numeric IP address, this
157function returns that address.
158<p> Note that if you want to iterate over the list, you should iterate
159over a copy, e.g.
160<pre>
161 <a href="qvaluelist.html">QValueList</a>&lt;QHostAddress&gt; list = myDns.addresses();
162 QValueList&lt;QHostAddress&gt;::Iterator it = list.<a href="qvaluelist.html#begin">begin</a>();
163 while( it != list.<a href="qvaluelist.html#end">end</a>() ) {
164 myProcessing( *it );
165 ++it;
166 }
167 </pre>
168
169<p>
170<h3 class=fn><a href="qstring.html">QString</a> <a name="canonicalName"></a>QDns::canonicalName () const
171</h3>
172Returns the canonical name for this DNS node. (This works
173regardless of what <a href="#recordType">recordType</a>() is set to.)
174<p> If the canonical name isn't known, this function returns a null
175string.
176<p> The canonical name of a DNS node is its full name, or the full
177name of the target of its CNAME. For example, if l.trolltech.com
178is a CNAME to lillian.troll.no, and the search path for QDns is
179"trolltech.com", then the canonical name for all of "lillian",
180"l", "lillian.troll.no." and "l.trolltech.com" is
181"lillian.troll.no.".
182
183<h3 class=fn><a href="qstringlist.html">QStringList</a> <a name="hostNames"></a>QDns::hostNames () const
184</h3>
185Returns a list of host names if the record type is <a href="#RecordType-enum">Ptr</a>.
186<p> Note that if you want to iterate over the list, you should iterate
187over a copy, e.g.
188<pre>
189 <a href="qstringlist.html">QStringList</a> list = myDns.hostNames();
190 QStringList::Iterator it = list.<a href="qvaluelist.html#begin">begin</a>();
191 while( it != list.<a href="qvaluelist.html#end">end</a>() ) {
192 myProcessing( *it );
193 ++it;
194 }
195 </pre>
196
197<p>
198<h3 class=fn>bool <a name="isWorking"></a>QDns::isWorking () const
199</h3>
200Returns TRUE if QDns is doing a lookup for this object (i.e. if it
201does not already have the necessary information); otherwise
202returns FALSE.
203<p> QDns emits the <a href="#resultsReady">resultsReady</a>() signal when the status changes to FALSE.
204
205<p>Example: <a href="mail-example.html#x705">network/mail/smtp.cpp</a>.
206<h3 class=fn><a href="qstring.html">QString</a> <a name="label"></a>QDns::label () const
207</h3>
208
209<p> Returns the domain name for which this object returns information.
210<p> <p>See also <a href="#setLabel">setLabel</a>().
211
212<h3 class=fn><a href="qvaluelist.html">QValueList</a>&lt;MailServer&gt; <a name="mailServers"></a>QDns::mailServers () const
213</h3>
214Returns a list of mail servers if the record type is <a href="#RecordType-enum">Mx</a>. The
215class <tt>QDns::MailServer</tt> contains the following public variables:
216<ul>
217<li> <a href="qstring.html">QString</a> QDns::MailServer::name
218<li> Q_UINT16 QDns::MailServer::priority
219</ul>
220<p> Note that if you want to iterate over the list, you should iterate
221over a copy, e.g.
222<pre>
223 <a href="qvaluelist.html">QValueList</a>&lt;QDns::MailServer&gt; list = myDns.mailServers();
224 QValueList&lt;QDns::MailServer&gt;::Iterator it = list.<a href="qvaluelist.html#begin">begin</a>();
225 while( it != list.<a href="qvaluelist.html#end">end</a>() ) {
226 myProcessing( *it );
227 ++it;
228 }
229 </pre>
230
231<p>
232<p>Example: <a href="mail-example.html#x706">network/mail/smtp.cpp</a>.
233<h3 class=fn><a href="qstringlist.html">QStringList</a> <a name="qualifiedNames"></a>QDns::qualifiedNames () const
234</h3>
235
236<p> Returns a list of the fully qualified names <a href="#label">label</a>() maps to.
237<p> Note that if you want to iterate over the list, you should iterate
238over a copy, e.g.
239<pre>
240 <a href="qstringlist.html">QStringList</a> list = myDns.qualifiedNames();
241 QStringList::Iterator it = list.<a href="qvaluelist.html#begin">begin</a>();
242 while( it != list.<a href="qvaluelist.html#end">end</a>() ) {
243 myProcessing( *it );
244 ++it;
245 }
246 </pre>
247
248<p>
249<h3 class=fn><a href="qdns.html#RecordType-enum">RecordType</a> <a name="recordType"></a>QDns::recordType () const
250</h3>
251
252<p> Returns the record type of this DNS query object.
253<p> <p>See also <a href="#setRecordType">setRecordType</a>() and <a href="#RecordType-enum">RecordType</a>.
254
255<h3 class=fn>void <a name="resultsReady"></a>QDns::resultsReady ()<tt> [signal]</tt>
256</h3>
257
258<p> This signal is emitted when results are available for one of the
259<a href="#qualifiedNames">qualifiedNames</a>().
260
261<p>Example: <a href="mail-example.html#x707">network/mail/smtp.cpp</a>.
262<h3 class=fn><a href="qvaluelist.html">QValueList</a>&lt;Server&gt; <a name="servers"></a>QDns::servers () const
263</h3>
264Returns a list of servers if the record type is <a href="#RecordType-enum">Srv</a>. The class
265<tt>QDns::Server</tt> contains the following public variables:
266<ul>
267<li> <a href="qstring.html">QString</a> QDns::Server::name
268<li> Q_UINT16 QDns::Server::priority
269<li> Q_UINT16 QDns::Server::weight
270<li> Q_UINT16 QDns::Server::port
271</ul>
272<p> Note that if you want to iterate over the list, you should iterate
273over a copy, e.g.
274<pre>
275 <a href="qvaluelist.html">QValueList</a>&lt;QDns::Server&gt; list = myDns.servers();
276 QValueList&lt;QDns::Server&gt;::Iterator it = list.<a href="qvaluelist.html#begin">begin</a>();
277 while( it != list.<a href="qvaluelist.html#end">end</a>() ) {
278 myProcessing( *it );
279 ++it;
280 }
281 </pre>
282
283
284<h3 class=fn>void <a name="setLabel"></a>QDns::setLabel ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;label )<tt> [virtual]</tt>
285</h3>
286Sets this DNS query object to query for information about <em>label</em>.
287<p> This does not change the <a href="#recordType">recordType</a>(), but its <a href="#isWorking">isWorking</a>() status
288will probably change as a result.
289<p> The DNS lookup is started the next time the application enters the
290event loop. When the result is found the signal <a href="#resultsReady">resultsReady</a>() is
291emitted.
292
293<h3 class=fn>void <a name="setLabel-2"></a>QDns::setLabel ( const&nbsp;<a href="qhostaddress.html">QHostAddress</a>&nbsp;&amp;&nbsp;address )<tt> [virtual]</tt>
294</h3>
295This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
296<p> Sets this DNS query object to query for information about the host
297address <em>address</em>. The label is set to the IN-ADDR.ARPA domain
298name. This is useful in combination with the <a href="#RecordType-enum">Ptr</a> record type
299(e.g. if you want to look up a hostname for a given address).
300
301<h3 class=fn>void <a name="setRecordType"></a>QDns::setRecordType ( <a href="qdns.html#RecordType-enum">RecordType</a>&nbsp;rr = A )<tt> [virtual]</tt>
302</h3>
303Sets this object to query for record type <em>rr</em> records.
304<p> The DNS lookup is started the next time the application enters the
305event loop. When the result is found the signal <a href="#resultsReady">resultsReady</a>() is
306emitted.
307<p> <p>See also <a href="#RecordType-enum">RecordType</a>.
308
309<h3 class=fn><a href="qstringlist.html">QStringList</a> <a name="texts"></a>QDns::texts () const
310</h3>
311Returns a list of texts if the record type is <a href="#RecordType-enum">Txt</a>.
312<p> Note that if you want to iterate over the list, you should iterate
313over a copy, e.g.
314<pre>
315 <a href="qstringlist.html">QStringList</a> list = myDns.texts();
316 QStringList::Iterator it = list.<a href="qvaluelist.html#begin">begin</a>();
317 while( it != list.<a href="qvaluelist.html#end">end</a>() ) {
318 myProcessing( *it );
319 ++it;
320 }
321 </pre>
322
323
324<!-- eof -->
325<hr><p>
326This file is part of the <a href="index.html">Qt toolkit</a>.
327Copyright &copy; 1995-2007
328<a href="http://www.trolltech.com/">Trolltech</a>. All Rights Reserved.<p><address><hr><div align=center>
329<table width=100% cellspacing=0 border=0><tr>
330<td>Copyright &copy; 2007
331<a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a>
332<td align=right><div align=right>Qt 3.3.8</div>
333</table></div></address></body>
334</html>
Note: See TracBrowser for help on using the repository browser.