<?xml version="1.0" encoding="iso-8859-1"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "DTD/xhtml1-strict.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> <!-- /tmp/qt-4.3.4-qt-1203442408707/qt-x11-opensource-src-4.3.4/src/qt3support/network/q3dns.cpp --> <head> <title>Qt 4.3: Q3Dns Class Reference</title> <link href="classic.css" rel="stylesheet" type="text/css" /> </head> <body> <table border="0" cellpadding="0" cellspacing="0" width="100%"> <tr> <td align="left" valign="top" width="32"><a href="http://www.trolltech.com/products/qt"><img src="images/qt-logo.png" align="left" width="32" height="32" border="0" /></a></td> <td width="1"> </td><td class="postheader" valign="center"><a href="index.html"><font color="#004faf">Home</font></a> · <a href="classes.html"><font color="#004faf">All Classes</font></a> · <a href="mainclasses.html"><font color="#004faf">Main Classes</font></a> · <a href="groups.html"><font color="#004faf">Grouped Classes</font></a> · <a href="modules.html"><font color="#004faf">Modules</font></a> · <a href="functions.html"><font color="#004faf">Functions</font></a></td> <td align="right" valign="top" width="230"><a href="http://www.trolltech.com"><img src="images/trolltech-logo.png" align="right" width="203" height="32" border="0" /></a></td></tr></table><h1 align="center">Q3Dns Class Reference<br /><sup><sup>[<a href="qt3support.html">Qt3Support</a> module]</sup></sup></h1> <p>The Q3Dns class provides asynchronous DNS lookups. <a href="#details">More...</a></p> <pre> #include <Q3Dns></pre><p><b>This class is part of the Qt 3 support library.</b> It is provided to keep old source code working. We strongly advise against using it in new code. See <a href="porting4.html#qdns">Porting to Qt 4</a> for more information.</p> <p><b>Note to Qt Desktop Light Edition users:</b> This class is only available in the <a href="commercialeditions.html#qt-desktop-edition">Qt Desktop Edition</a>.</p> <p>Inherits <a href="qobject.html">QObject</a>.</p> <ul> <li><a href="q3dns-members.html">List of all members, including inherited members</a></li> </ul> <a name="public-types"></a> <h3>Public Types</h3> <ul> <li><div class="fn"/>enum <b><a href="q3dns.html#RecordType-enum">RecordType</a></b> { None, A, Aaaa, Mx, ..., Txt }</li> </ul> <a name="public-functions"></a> <h3>Public Functions</h3> <ul> <li><div class="fn"/><b><a href="q3dns.html#Q3Dns">Q3Dns</a></b> ()</li> <li><div class="fn"/><b><a href="q3dns.html#Q3Dns-2">Q3Dns</a></b> ( const QString & <i>label</i>, RecordType <i>rr</i> = A )</li> <li><div class="fn"/><b><a href="q3dns.html#Q3Dns-3">Q3Dns</a></b> ( const QHostAddress & <i>address</i>, RecordType <i>rr</i> = Ptr )</li> <li><div class="fn"/>virtual <b><a href="q3dns.html#dtor.Q3Dns">~Q3Dns</a></b> ()</li> <li><div class="fn"/>Q3ValueList<QHostAddress> <b><a href="q3dns.html#addresses">addresses</a></b> () const</li> <li><div class="fn"/>QString <b><a href="q3dns.html#canonicalName">canonicalName</a></b> () const</li> <li><div class="fn"/>QStringList <b><a href="q3dns.html#hostNames">hostNames</a></b> () const</li> <li><div class="fn"/>bool <b><a href="q3dns.html#isWorking">isWorking</a></b> () const</li> <li><div class="fn"/>QString <b><a href="q3dns.html#label">label</a></b> () const</li> <li><div class="fn"/>Q3ValueList<MailServer> <b><a href="q3dns.html#mailServers">mailServers</a></b> () const</li> <li><div class="fn"/>QStringList <b><a href="q3dns.html#qualifiedNames">qualifiedNames</a></b> () const</li> <li><div class="fn"/>RecordType <b><a href="q3dns.html#recordType">recordType</a></b> () const</li> <li><div class="fn"/>Q3ValueList<Server> <b><a href="q3dns.html#servers">servers</a></b> () const</li> <li><div class="fn"/>virtual void <b><a href="q3dns.html#setLabel">setLabel</a></b> ( const QString & <i>label</i> )</li> <li><div class="fn"/>virtual void <b><a href="q3dns.html#setLabel-2">setLabel</a></b> ( const QHostAddress & <i>address</i> )</li> <li><div class="fn"/>virtual void <b><a href="q3dns.html#setRecordType">setRecordType</a></b> ( RecordType <i>rr</i> = A )</li> <li><div class="fn"/>QStringList <b><a href="q3dns.html#texts">texts</a></b> () const</li> </ul> <ul> <li><div class="fn"/>29 public functions inherited from <a href="qobject.html#public-functions">QObject</a></li> </ul> <a name="signals"></a> <h3>Signals</h3> <ul> <li><div class="fn"/>void <b><a href="q3dns.html#resultsReady">resultsReady</a></b> ()</li> </ul> <ul> <li><div class="fn"/>1 signal inherited from <a href="qobject.html#signals">QObject</a></li> </ul> <h3>Additional Inherited Members</h3> <ul> <li><div class="fn"/>1 property inherited from <a href="qobject.html#properties">QObject</a></li> <li><div class="fn"/>1 public slot inherited from <a href="qobject.html#public-slots">QObject</a></li> <li><div class="fn"/>5 static public members inherited from <a href="qobject.html#static-public-members">QObject</a></li> <li><div class="fn"/>7 protected functions inherited from <a href="qobject.html#protected-functions">QObject</a></li> </ul> <a name="details"></a> <hr /> <h2>Detailed Description</h2> <p>The Q3Dns class provides asynchronous DNS lookups.</p> <p>Both Windows and Unix provide synchronous DNS lookups; Windows provides some asynchronous support too. At the time of writing neither operating system provides asynchronous support for anything other than hostname-to-address mapping.</p> <p>Q3Dns rectifies this shortcoming, by providing asynchronous caching lookups for the record types that we expect modern GUI applications to need in the near future.</p> <p>The class is <i>not</i> straightforward to use (although it is much simpler than the native APIs); <a href="q3socket.html">Q3Socket</a> provides much easier to use TCP connection facilities. The aim of Q3Dns is to provide a correct and small API to the DNS and nothing more. (We use "correctness" to mean that the DNS information is correctly cached, and correctly timed out.)</p> <p>The API comprises a constructor, functions to set the DNS node (the domain in DNS terminology) and record type (<a href="q3dns.html#setLabel">setLabel</a>() and <a href="q3dns.html#setRecordType">setRecordType</a>()), the corresponding get functions, an <a href="q3dns.html#isWorking">isWorking</a>() function to determine whether Q3Dns is working or reading, a <a href="q3dns.html#resultsReady">resultsReady</a>() signal and query functions for the result.</p> <p>There is one query function for each <a href="q3dns.html#RecordType-enum">RecordType</a>, namely <a href="q3dns.html#addresses">addresses</a>(), <a href="q3dns.html#mailServers">mailServers</a>(), <a href="q3dns.html#servers">servers</a>(), <a href="q3dns.html#hostNames">hostNames</a>() and <a href="q3dns.html#texts">texts</a>(). There are also two generic query functions: <a href="q3dns.html#canonicalName">canonicalName</a>() returns the name you'll presumably end up using (the exact meaning of this depends on the record type) and <a href="q3dns.html#qualifiedNames">qualifiedNames</a>() returns a list of the fully qualified names <a href="q3dns.html#label">label</a>() maps to.</p> <p>See also <a href="q3socket.html">Q3Socket</a>.</p> <hr /> <h2>Member Type Documentation</h2> <h3 class="fn"><a name="RecordType-enum"></a>enum Q3Dns::RecordType</h3> <p>This enum type defines the record types <a href="q3dns.html">Q3Dns</a> can handle. The DNS provides many more; these are the ones we've judged to be in current use, useful for GUI programs and important enough to support right away:</p> <p><table border="1" cellpadding="2" cellspacing="1" width="100%"> <tr><th width="25%">Constant</th><th width="15%">Value</th><th width="60%">Description</th></tr> <tr><td valign="top"><tt>Q3Dns::None</tt></td><td align="center" valign="top"><tt>0</tt></td><td valign="top">No information. This exists only so that <a href="q3dns.html">Q3Dns</a> can have a default.</td></tr> <tr><td valign="top"><tt>Q3Dns::A</tt></td><td align="center" valign="top"><tt>1</tt></td><td valign="top">IPv4 addresses. By far the most common type.</td></tr> <tr><td valign="top"><tt>Q3Dns::Aaaa</tt></td><td align="center" valign="top"><tt>2</tt></td><td valign="top">IPv6 addresses. So far mostly unused.</td></tr> <tr><td valign="top"><tt>Q3Dns::Mx</tt></td><td align="center" valign="top"><tt>3</tt></td><td valign="top">Mail eXchanger names. Used for mail delivery.</td></tr> <tr><td valign="top"><tt>Q3Dns::Srv</tt></td><td align="center" valign="top"><tt>4</tt></td><td valign="top">SeRVer names. Generic record type for finding servers. So far mostly unused.</td></tr> <tr><td valign="top"><tt>Q3Dns::Cname</tt></td><td align="center" valign="top"><tt>5</tt></td><td valign="top">Canonical names. Maps from nicknames to the true name (the canonical name) for a host.</td></tr> <tr><td valign="top"><tt>Q3Dns::Ptr</tt></td><td align="center" valign="top"><tt>6</tt></td><td valign="top">name PoinTeRs. Maps from IPv4 or IPv6 addresses to hostnames.</td></tr> <tr><td valign="top"><tt>Q3Dns::Txt</tt></td><td align="center" valign="top"><tt>7</tt></td><td valign="top">arbitrary TeXT for domains.</td></tr> </table></p> <p>We expect that some support for the <a href="http://www.rfc-editor.org/rfc/rfc2535.txt">RFC 2535</a> extensions will be added in future versions.</p> <hr /> <h2>Member Function Documentation</h2> <h3 class="fn"><a name="Q3Dns"></a>Q3Dns::Q3Dns ()</h3> <p>Constructs a DNS query object with invalid settings for both the label and the search type.</p> <h3 class="fn"><a name="Q3Dns-2"></a>Q3Dns::Q3Dns ( const <a href="qstring.html">QString</a> & <i>label</i>, <a href="q3dns.html#RecordType-enum">RecordType</a> <i>rr</i> = A )</h3> <p>Constructs a DNS query object that will return record type <i>rr</i> information about <i>label</i>.</p> <p>The DNS lookup is started the next time the application enters the event loop. When the result is found the signal <a href="q3dns.html#resultsReady">resultsReady</a>() is emitted.</p> <p><i>rr</i> defaults to <tt>A</tt>, IPv4 addresses.</p> <h3 class="fn"><a name="Q3Dns-3"></a>Q3Dns::Q3Dns ( const <a href="qhostaddress.html">QHostAddress</a> & <i>address</i>, <a href="q3dns.html#RecordType-enum">RecordType</a> <i>rr</i> = Ptr )</h3> <p>Constructs a DNS query object that will return record type <i>rr</i> information about host address <i>address</i>. The label is set to the IN-ADDR.ARPA domain name. This is useful in combination with the <tt>Ptr</tt> record type (e.g. if you want to look up a hostname for a given address).</p> <p>The DNS lookup is started the next time the application enters the event loop. When the result is found the signal <a href="q3dns.html#resultsReady">resultsReady</a>() is emitted.</p> <p><i>rr</i> defaults to <tt>Ptr</tt>, that maps addresses to hostnames.</p> <h3 class="fn"><a name="dtor.Q3Dns"></a>Q3Dns::~Q3Dns () <tt> [virtual]</tt></h3> <p>Destroys the DNS query object and frees its allocated resources.</p> <h3 class="fn"><a name="addresses"></a><a href="q3valuelist.html">Q3ValueList</a><<a href="qhostaddress.html">QHostAddress</a>> Q3Dns::addresses () const</h3> <p>Returns a list of the addresses for this name if this <a href="q3dns.html">Q3Dns</a> object has a <a href="q3dns.html#recordType">recordType</a>() of <a href="q3dns.html#RecordType-enum">Q3Dns::A</a> or <a href="q3dns.html#RecordType-enum">Q3Dns::Aaaa</a> and the answer is available; otherwise returns an empty list.</p> <p>As a special case, if <a href="q3dns.html#label">label</a>() is a valid numeric IP address, this function returns that address.</p> <p>Note that if you want to iterate over the list, you should iterate over a copy, e.g.</p> <pre> Q3ValueList<QHostAddress> list = myDns.addresses(); Q3ValueList<QHostAddress>::Iterator it = list.begin(); while( it != list.end() ) { myProcessing( *it ); ++it; }</pre> <h3 class="fn"><a name="canonicalName"></a><a href="qstring.html">QString</a> Q3Dns::canonicalName () const</h3> <p>Returns the canonical name for this DNS node. (This works regardless of what <a href="q3dns.html#recordType">recordType</a>() is set to.)</p> <p>If the canonical name isn't known, this function returns a null string.</p> <p>The canonical name of a DNS node is its full name, or the full name of the target of its CNAME. For example, if l.trolltech.com is a CNAME to lillian.troll.no, and the search path for <a href="q3dns.html">Q3Dns</a> is "trolltech.com", then the canonical name for all of "lillian", "l", "lillian.troll.no." and "l.trolltech.com" is "lillian.troll.no.".</p> <h3 class="fn"><a name="hostNames"></a><a href="qstringlist.html">QStringList</a> Q3Dns::hostNames () const</h3> <p>Returns a list of host names if the record type is <tt>Ptr</tt>.</p> <p>Note that if you want to iterate over the list, you should iterate over a copy, e.g.</p> <pre> QStringList list = myDns.hostNames(); QStringList::Iterator it = list.begin(); while( it != list.end() ) { myProcessing( *it ); ++it; }</pre> <h3 class="fn"><a name="isWorking"></a>bool Q3Dns::isWorking () const</h3> <p>Returns true if <a href="q3dns.html">Q3Dns</a> is doing a lookup for this object (i.e. if it does not already have the necessary information); otherwise returns false.</p> <p><a href="q3dns.html">Q3Dns</a> emits the <a href="q3dns.html#resultsReady">resultsReady</a>() signal when the status changes to false.</p> <h3 class="fn"><a name="label"></a><a href="qstring.html">QString</a> Q3Dns::label () const</h3> <p>Returns the domain name for which this object returns information.</p> <p>See also <a href="q3dns.html#setLabel">setLabel</a>().</p> <h3 class="fn"><a name="mailServers"></a><a href="q3valuelist.html">Q3ValueList</a><MailServer> Q3Dns::mailServers () const</h3> <p>Returns a list of mail servers if the record type is <tt>Mx</tt>. The class Q3Dns::MailServer contains the following public variables:</p> <ul> <li><a href="qstring.html">QString</a> <a href="q3dns-mailserver.html#name-var">Q3Dns::MailServer::name</a></li> <li><a href="qtglobal-qt3.html#Q_UINT16-typedef">Q_UINT16</a> <a href="q3dns-mailserver.html#priority-var">Q3Dns::MailServer::priority</a></li> </ul> <p>Note that if you want to iterate over the list, you should iterate over a copy, e.g.</p> <pre> Q3ValueList<Q3Dns::MailServer> list = myDns.mailServers(); Q3ValueList<Q3Dns::MailServer>::Iterator it = list.begin(); while( it != list.end() ) { myProcessing( *it ); ++it; }</pre> <h3 class="fn"><a name="qualifiedNames"></a><a href="qstringlist.html">QStringList</a> Q3Dns::qualifiedNames () const</h3> <p>Returns a list of the fully qualified names <a href="q3dns.html#label">label</a>() maps to.</p> <p>Note that if you want to iterate over the list, you should iterate over a copy, e.g.</p> <pre> QStringList list = myDns.qualifiedNames(); QStringList::Iterator it = list.begin(); while( it != list.end() ) { myProcessing( *it ); ++it; }</pre> <h3 class="fn"><a name="recordType"></a><a href="q3dns.html#RecordType-enum">RecordType</a> Q3Dns::recordType () const</h3> <p>Returns the record type of this DNS query object.</p> <p>See also <a href="q3dns.html#setRecordType">setRecordType</a>() and <a href="q3dns.html#RecordType-enum">RecordType</a>.</p> <h3 class="fn"><a name="resultsReady"></a>void Q3Dns::resultsReady () <tt> [signal]</tt></h3> <p>This signal is emitted when results are available for one of the <a href="q3dns.html#qualifiedNames">qualifiedNames</a>().</p> <h3 class="fn"><a name="servers"></a><a href="q3valuelist.html">Q3ValueList</a><Server> Q3Dns::servers () const</h3> <p>Returns a list of servers if the record type is <tt>Srv</tt>. The class Q3Dns::Server contains the following public variables:</p> <ul> <li><a href="qstring.html">QString</a> <a href="q3dns-server.html#name-var">Q3Dns::Server::name</a></li> <li><a href="qtglobal-qt3.html#Q_UINT16-typedef">Q_UINT16</a> <a href="q3dns-server.html#priority-var">Q3Dns::Server::priority</a></li> <li><a href="qtglobal-qt3.html#Q_UINT16-typedef">Q_UINT16</a> <a href="q3dns-server.html#weight-var">Q3Dns::Server::weight</a></li> <li><a href="qtglobal-qt3.html#Q_UINT16-typedef">Q_UINT16</a> <a href="q3dns-server.html#port-var">Q3Dns::Server::port</a></li> </ul> <p>Note that if you want to iterate over the list, you should iterate over a copy, e.g.</p> <pre> Q3ValueList<Q3Dns::Server> list = myDns.servers(); Q3ValueList<Q3Dns::Server>::Iterator it = list.begin(); while( it != list.end() ) { myProcessing( *it ); ++it; }</pre> <h3 class="fn"><a name="setLabel"></a>void Q3Dns::setLabel ( const <a href="qstring.html">QString</a> & <i>label</i> ) <tt> [virtual]</tt></h3> <p>Sets this DNS query object to query for information about <i>label</i>.</p> <p>This does not change the <a href="q3dns.html#recordType">recordType</a>(), but its <a href="q3dns.html#isWorking">isWorking</a>() status will probably change as a result.</p> <p>The DNS lookup is started the next time the application enters the event loop. When the result is found the signal <a href="q3dns.html#resultsReady">resultsReady</a>() is emitted.</p> <p>See also <a href="q3dns.html#label">label</a>().</p> <h3 class="fn"><a name="setLabel-2"></a>void Q3Dns::setLabel ( const <a href="qhostaddress.html">QHostAddress</a> & <i>address</i> ) <tt> [virtual]</tt></h3> <p>This is an overloaded member function, provided for convenience.</p> <p>Sets this DNS query object to query for information about the host address <i>address</i>. The label is set to the IN-ADDR.ARPA domain name. This is useful in combination with the <tt>Ptr</tt> record type (e.g. if you want to look up a hostname for a given address).</p> <h3 class="fn"><a name="setRecordType"></a>void Q3Dns::setRecordType ( <a href="q3dns.html#RecordType-enum">RecordType</a> <i>rr</i> = A ) <tt> [virtual]</tt></h3> <p>Sets this object to query for record type <i>rr</i> records.</p> <p>The DNS lookup is started the next time the application enters the event loop. When the result is found the signal <a href="q3dns.html#resultsReady">resultsReady</a>() is emitted.</p> <p>See also <a href="q3dns.html#recordType">recordType</a>() and <a href="q3dns.html#RecordType-enum">RecordType</a>.</p> <h3 class="fn"><a name="texts"></a><a href="qstringlist.html">QStringList</a> Q3Dns::texts () const</h3> <p>Returns a list of texts if the record type is <tt>Txt</tt>.</p> <p>Note that if you want to iterate over the list, you should iterate over a copy, e.g.</p> <pre> QStringList list = myDns.texts(); QStringList::Iterator it = list.begin(); while( it != list.end() ) { myProcessing( *it ); ++it; }</pre> <p /><address><hr /><div align="center"> <table width="100%" cellspacing="0" border="0"><tr class="address"> <td width="30%">Copyright © 2008 <a href="trolltech.html">Trolltech</a></td> <td width="40%" align="center"><a href="trademarks.html">Trademarks</a></td> <td width="30%" align="right"><div align="right">Qt 4.3.4</div></td> </tr></table></div></address></body> </html>