1QDns(3qt) QDns(3qt)
2
6 QDns - Asynchronous DNS lookups
7
9 #include <qdns.h>
10 Inherits QObject.
12 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 Signals
34 void resultsReady ()
35
37 The QDns class provides asynchronous DNS lookups.
38 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 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 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 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 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 See also QSocket and Input/Output and Networking.
68 Member Type Documentation
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 QDns::None - No information. This exists only so that QDns can have a
77 default.
78 QDns::A - IPv4 addresses. By far the most common type.
80 QDns::Aaaa - IPv6 addresses. So far mostly unused.
82 QDns::Mx - Mail eXchanger names. Used for mail delivery.
84 QDns::Srv - SeRVer names. Generic record type for finding servers. So
86 far mostly unused.
87 QDns::Cname - Canonical names. Maps from nicknames to the true name
89 (the canonical name) for a host.
90 QDns::Ptr - name PoinTeRs. Maps from IPv4 or IPv6 addresses to
92 hostnames.
93 QDns::Txt - arbitrary TeXT for domains.
95 We expect that some support for the RFC-2535 extensions will be added
97 in future versions.
98
101 Constructs a DNS query object with invalid settings for both the label
102 and the search type.
103
105 Constructs a DNS query object that will return record type rr
106 information about label.
107 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 rr defaults to A, IPv4 addresses.
113
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 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 rr defaults to Ptr, that maps addresses to hostnames.
126
128 Destroys the DNS query object and frees its allocated resources.
129
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 As a special case, if label() is a valid numeric IP address, this
136 function returns that address.
137 Note that if you want to iterate over the list, you should iterate over
139 a copy, e.g.
140 QValueList<QHostAddress> list = myDns.addresses();
142 QValueList<QHostAddress>::Iterator it = list.begin();
143 while( it != list.end() ) {
144 myProcessing( *it );
145 ++it;
146 }
147
149 Returns the canonical name for this DNS node. (This works regardless of
150 what recordType() is set to.)
151 If the canonical name isn't known, this function returns a null string.
153 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
161 Returns a list of host names if the record type is Ptr.
162 Note that if you want to iterate over the list, you should iterate over
164 a copy, e.g.
165 QStringList list = myDns.hostNames();
167 QStringList::Iterator it = list.begin();
168 while( it != list.end() ) {
169 myProcessing( *it );
170 ++it;
171 }
172
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 QDns emits the resultsReady() signal when the status changes to FALSE.
178 Example: network/mail/smtp.cpp.
180
182 Returns the domain name for which this object returns information.
183 See also setLabel().
185
187 Returns a list of mail servers if the record type is Mx. The class
188 QDns::MailServer contains the following public variables:
189 QString QDns::MailServer::name
191 Q_UINT16 QDns::MailServer::priority
193 Note that if you want to iterate over the list, you should iterate over
195 a copy, e.g.
196 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 Example: network/mail/smtp.cpp.
205
207 Returns a list of the fully qualified names label() maps to.
208 Note that if you want to iterate over the list, you should iterate over
210 a copy, e.g.
211 QStringList list = myDns.qualifiedNames();
213 QStringList::Iterator it = list.begin();
214 while( it != list.end() ) {
215 myProcessing( *it );
216 ++it;
217 }
218
220 Returns the record type of this DNS query object.
221 See also setRecordType() and RecordType.
223
225 This signal is emitted when results are available for one of the
226 qualifiedNames().
227 Example: network/mail/smtp.cpp.
229
231 Returns a list of servers if the record type is Srv. The class
232 QDns::Server contains the following public variables:
233 QString QDns::Server::name
235 Q_UINT16 QDns::Server::priority
237 Q_UINT16 QDns::Server::weight
239 Q_UINT16 QDns::Server::port
241 Note that if you want to iterate over the list, you should iterate over
243 a copy, e.g.
244 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
253 Sets this DNS query object to query for information about label.
254 This does not change the recordType(), but its isWorking() status will
256 probably change as a result.
257 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
263 This is an overloaded member function, provided for convenience. It
264 behaves essentially like the above function.
265 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
272 Sets this object to query for record type rr records.
273 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 See also RecordType.
279
281 Returns a list of texts if the record type is Txt.
282 Note that if you want to iterate over the list, you should iterate over
284 a copy, e.g.
285 QStringList list = myDns.texts();
287 QStringList::Iterator it = list.begin();
288 while( it != list.end() ) {
289 myProcessing( *it );
290 ++it;
291 }
292
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
304 Generated automatically from the source code.
305
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 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 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).
320Trolltech AS 2 February 2007 QDns(3qt)