1QDns(3qt)                                                            QDns(3qt)
2
3
4

NAME

6       QDns - Asynchronous DNS lookups
7

SYNOPSIS

9       #include <qdns.h>
10
11       Inherits QObject.
12
13   Public Members
14       enum RecordType { None, A, Aaaa, Mx, Srv, Cname, Ptr, Txt }
15       QDns ()
16       QDns ( const QString & label, RecordType rr = A )
17       QDns ( const QHostAddress & address, RecordType rr = Ptr )
18       virtual ~QDns ()
19       virtual void setLabel ( const QString & label )
20       virtual void setLabel ( const QHostAddress & address )
21       QString label () const
22       virtual void setRecordType ( RecordType rr = A )
23       RecordType recordType () const
24       bool isWorking () const
25       QValueList<QHostAddress> addresses () const
26       QValueList<MailServer> mailServers () const
27       QValueList<Server> servers () const
28       QStringList hostNames () const
29       QStringList texts () const
30       QString canonicalName () const
31       QStringList qualifiedNames () const
32
33   Signals
34       void resultsReady ()
35

DESCRIPTION

37       The QDns class provides asynchronous DNS lookups.
38
39       Both Windows and Unix provide synchronous DNS lookups; Windows provides
40       some asynchronous support too. At the time of writing neither operating
41       system provides asynchronous support for anything other than hostname-
42       to-address mapping.
43
44       QDns rectifies this shortcoming, by providing asynchronous caching
45       lookups for the record types that we expect modern GUI applications to
46       need in the near future.
47
48       The class is not straightforward to use (although it is much simpler
49       than the native APIs); QSocket provides much easier to use TCP
50       connection facilities. The aim of QDns is to provide a correct and
51       small API to the DNS and nothing more. (We use "correctness" to mean
52       that the DNS information is correctly cached, and correctly timed out.)
53
54       The API comprises a constructor, functions to set the DNS node (the
55       domain in DNS terminology) and record type (setLabel() and
56       setRecordType()), the corresponding get functions, an isWorking()
57       function to determine whether QDns is working or reading, a
58       resultsReady() signal and query functions for the result.
59
60       There is one query function for each RecordType, namely addresses(),
61       mailServers(), servers(), hostNames() and texts(). There are also two
62       generic query functions: canonicalName() returns the name you'll
63       presumably end up using (the exact meaning of this depends on the
64       record type) and qualifiedNames() returns a list of the fully qualified
65       names label() maps to.
66
67       See also QSocket and Input/Output and Networking.
68
69   Member Type Documentation

QDns::RecordType

71       This enum type defines the record types QDns can handle. The DNS
72       provides many more; these are the ones we've judged to be in current
73       use, useful for GUI programs and important enough to support right
74       away:
75
76       QDns::None - No information. This exists only so that QDns can have a
77       default.
78
79       QDns::A - IPv4 addresses. By far the most common type.
80
81       QDns::Aaaa - IPv6 addresses. So far mostly unused.
82
83       QDns::Mx - Mail eXchanger names. Used for mail delivery.
84
85       QDns::Srv - SeRVer names. Generic record type for finding servers. So
86       far mostly unused.
87
88       QDns::Cname - Canonical names. Maps from nicknames to the true name
89       (the canonical name) for a host.
90
91       QDns::Ptr - name PoinTeRs. Maps from IPv4 or IPv6 addresses to
92       hostnames.
93
94       QDns::Txt - arbitrary TeXT for domains.
95
96       We expect that some support for the RFC-2535 extensions will be added
97       in future versions.
98

MEMBER FUNCTION DOCUMENTATION

QDns::QDns ()

101       Constructs a DNS query object with invalid settings for both the label
102       and the search type.
103

QDns::QDns ( const QString & label, RecordType rr = A )

105       Constructs a DNS query object that will return record type rr
106       information about label.
107
108       The DNS lookup is started the next time the application enters the
109       event loop. When the result is found the signal resultsReady() is
110       emitted.
111
112       rr defaults to A, IPv4 addresses.
113

QDns::QDns ( const QHostAddress & address, RecordType rr = Ptr )

115       Constructs a DNS query object that will return record type rr
116       information about host address address. The label is set to the IN-
117       ADDR.ARPA domain name. This is useful in combination with the Ptr
118       record type (e.g. if you want to look up a hostname for a given
119       address).
120
121       The DNS lookup is started the next time the application enters the
122       event loop. When the result is found the signal resultsReady() is
123       emitted.
124
125       rr defaults to Ptr, that maps addresses to hostnames.
126

QDns::~QDns () [virtual]

128       Destroys the DNS query object and frees its allocated resources.
129

QValueList<QHostAddress> QDns::addresses () const

131       Returns a list of the addresses for this name if this QDns object has a
132       recordType() of QDns::A or QDns::Aaaa and the answer is available;
133       otherwise returns an empty list.
134
135       As a special case, if label() is a valid numeric IP address, this
136       function returns that address.
137
138       Note that if you want to iterate over the list, you should iterate over
139       a copy, e.g.
140
141           QValueList<QHostAddress> list = myDns.addresses();
142           QValueList<QHostAddress>::Iterator it = list.begin();
143           while( it != list.end() ) {
144               myProcessing( *it );
145               ++it;
146           }
147

QString QDns::canonicalName () const

149       Returns the canonical name for this DNS node. (This works regardless of
150       what recordType() is set to.)
151
152       If the canonical name isn't known, this function returns a null string.
153
154       The canonical name of a DNS node is its full name, or the full name of
155       the target of its CNAME. For example, if l.trolltech.com is a CNAME to
156       lillian.troll.no, and the search path for QDns is" trolltech.com", then
157       the canonical name for all of "lillian"," l", "lillian.troll.no." and
158       "l.trolltech.com" is" lillian.troll.no.".
159

QStringList QDns::hostNames () const

161       Returns a list of host names if the record type is Ptr.
162
163       Note that if you want to iterate over the list, you should iterate over
164       a copy, e.g.
165
166           QStringList list = myDns.hostNames();
167           QStringList::Iterator it = list.begin();
168           while( it != list.end() ) {
169               myProcessing( *it );
170               ++it;
171           }
172

bool QDns::isWorking () const

174       Returns TRUE if QDns is doing a lookup for this object (i.e. if it does
175       not already have the necessary information); otherwise returns FALSE.
176
177       QDns emits the resultsReady() signal when the status changes to FALSE.
178
179       Example: network/mail/smtp.cpp.
180

QString QDns::label () const

182       Returns the domain name for which this object returns information.
183
184       See also setLabel().
185

QValueList<MailServer> QDns::mailServers () const

187       Returns a list of mail servers if the record type is Mx. The class
188       QDns::MailServer contains the following public variables:
189
190       QString QDns::MailServer::name
191
192       Q_UINT16 QDns::MailServer::priority
193
194       Note that if you want to iterate over the list, you should iterate over
195       a copy, e.g.
196
197           QValueList<QDns::MailServer> list = myDns.mailServers();
198           QValueList<QDns::MailServer>::Iterator it = list.begin();
199           while( it != list.end() ) {
200               myProcessing( *it );
201               ++it;
202           }
203
204       Example: network/mail/smtp.cpp.
205

QStringList QDns::qualifiedNames () const

207       Returns a list of the fully qualified names label() maps to.
208
209       Note that if you want to iterate over the list, you should iterate over
210       a copy, e.g.
211
212           QStringList list = myDns.qualifiedNames();
213           QStringList::Iterator it = list.begin();
214           while( it != list.end() ) {
215               myProcessing( *it );
216               ++it;
217           }
218

RecordType QDns::recordType () const

220       Returns the record type of this DNS query object.
221
222       See also setRecordType() and RecordType.
223

void QDns::resultsReady () [signal]

225       This signal is emitted when results are available for one of the
226       qualifiedNames().
227
228       Example: network/mail/smtp.cpp.
229

QValueList<Server> QDns::servers () const

231       Returns a list of servers if the record type is Srv. The class
232       QDns::Server contains the following public variables:
233
234       QString QDns::Server::name
235
236       Q_UINT16 QDns::Server::priority
237
238       Q_UINT16 QDns::Server::weight
239
240       Q_UINT16 QDns::Server::port
241
242       Note that if you want to iterate over the list, you should iterate over
243       a copy, e.g.
244
245           QValueList<QDns::Server> list = myDns.servers();
246           QValueList<QDns::Server>::Iterator it = list.begin();
247           while( it != list.end() ) {
248               myProcessing( *it );
249               ++it;
250           }
251

void QDns::setLabel ( const QString & label ) [virtual]

253       Sets this DNS query object to query for information about label.
254
255       This does not change the recordType(), but its isWorking() status will
256       probably change as a result.
257
258       The DNS lookup is started the next time the application enters the
259       event loop. When the result is found the signal resultsReady() is
260       emitted.
261

void QDns::setLabel ( const QHostAddress & address ) [virtual]

263       This is an overloaded member function, provided for convenience. It
264       behaves essentially like the above function.
265
266       Sets this DNS query object to query for information about the host
267       address address. The label is set to the IN-ADDR.ARPA domain name. This
268       is useful in combination with the Ptr record type (e.g. if you want to
269       look up a hostname for a given address).
270

void QDns::setRecordType ( RecordType rr = A ) [virtual]

272       Sets this object to query for record type rr records.
273
274       The DNS lookup is started the next time the application enters the
275       event loop. When the result is found the signal resultsReady() is
276       emitted.
277
278       See also RecordType.
279

QStringList QDns::texts () const

281       Returns a list of texts if the record type is Txt.
282
283       Note that if you want to iterate over the list, you should iterate over
284       a copy, e.g.
285
286           QStringList list = myDns.texts();
287           QStringList::Iterator it = list.begin();
288           while( it != list.end() ) {
289               myProcessing( *it );
290               ++it;
291           }
292
293

SEE ALSO

295       http://doc.trolltech.com/qdns.html
296       http://www.trolltech.com/faq/tech.html
297
299       Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com.  See the
300       license file included in the distribution for a complete license
301       statement.
302

AUTHOR

304       Generated automatically from the source code.
305

BUGS

307       If you find a bug in Qt, please report it as described in
308       http://doc.trolltech.com/bughowto.html.  Good bug reports help us to
309       help you. Thank you.
310
311       The definitive Qt documentation is provided in HTML format; it is
312       located at $QTDIR/doc/html and can be read using Qt Assistant or with a
313       web browser. This man page is provided as a convenience for those users
314       who prefer man pages, although this format is not officially supported
315       by Trolltech.
316
317       If you find errors in this manual page, please report them to qt-
318       bugs@trolltech.com.  Please include the name of the manual page
319       (qdns.3qt) and the Qt version (3.3.8).
320
321
322
323Trolltech AS                    2 February 2007                      QDns(3qt)
Impressum