summaryrefslogtreecommitdiffstats
path: root/doc/man/man3/qdns.3qt
blob: a26191a4e2778e6a3c0b5d8b5f24aacdb0efc2aa (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
'\" t
.TH QDns 3qt "2 February 2007" "Trolltech AS" \" -*- nroff -*-
.\" Copyright 1992-2007 Trolltech ASA.  All rights reserved.  See the
.\" license file included in the distribution for a complete license
.\" statement.
.\"
.ad l
.nh
.SH NAME
QDns \- Asynchronous DNS lookups
.SH SYNOPSIS
\fC#include <qdns.h>\fR
.PP
Inherits QObject.
.PP
.SS "Public Members"
.in +1c
.ti -1c
.BI "enum \fBRecordType\fR { None, A, Aaaa, Mx, Srv, Cname, Ptr, Txt }"
.br
.ti -1c
.BI "\fBQDns\fR ()"
.br
.ti -1c
.BI "\fBQDns\fR ( const QString & label, RecordType rr = A )"
.br
.ti -1c
.BI "\fBQDns\fR ( const QHostAddress & address, RecordType rr = Ptr )"
.br
.ti -1c
.BI "virtual \fB~QDns\fR ()"
.br
.ti -1c
.BI "virtual void \fBsetLabel\fR ( const QString & label )"
.br
.ti -1c
.BI "virtual void \fBsetLabel\fR ( const QHostAddress & address )"
.br
.ti -1c
.BI "QString \fBlabel\fR () const"
.br
.ti -1c
.BI "virtual void \fBsetRecordType\fR ( RecordType rr = A )"
.br
.ti -1c
.BI "RecordType \fBrecordType\fR () const"
.br
.ti -1c
.BI "bool \fBisWorking\fR () const"
.br
.ti -1c
.BI "QValueList<QHostAddress> \fBaddresses\fR () const"
.br
.ti -1c
.BI "QValueList<MailServer> \fBmailServers\fR () const"
.br
.ti -1c
.BI "QValueList<Server> \fBservers\fR () const"
.br
.ti -1c
.BI "QStringList \fBhostNames\fR () const"
.br
.ti -1c
.BI "QStringList \fBtexts\fR () const"
.br
.ti -1c
.BI "QString \fBcanonicalName\fR () const"
.br
.ti -1c
.BI "QStringList \fBqualifiedNames\fR () const"
.br
.in -1c
.SS "Signals"
.in +1c
.ti -1c
.BI "void \fBresultsReady\fR ()"
.br
.in -1c
.SH DESCRIPTION
The QDns class provides asynchronous DNS lookups.
.PP
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.
.PP
QDns rectifies this shortcoming, by providing asynchronous caching lookups for the record types that we expect modern GUI applications to need in the near future.
.PP
The class is \fInot\fR straightforward to use (although it is much simpler than the native APIs); QSocket provides much easier to use TCP connection facilities. The aim of QDns 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.)
.PP
The API comprises a constructor, functions to set the DNS node (the domain in DNS terminology) and record type (setLabel() and setRecordType()), the corresponding get functions, an isWorking() function to determine whether QDns is working or reading, a resultsReady() signal and query functions for the result.
.PP
There is one query function for each RecordType, namely addresses(), mailServers(), servers(), hostNames() and texts(). There are also two generic query functions: canonicalName() returns the name you'll presumably end up using (the exact meaning of this depends on the record type) and qualifiedNames() returns a list of the fully qualified names label() maps to.
.PP
See also QSocket and Input/Output and Networking.
.SS "Member Type Documentation"
.SH "QDns::RecordType"
This enum type defines the record types QDns 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:
.TP
\fCQDns::None\fR - No information. This exists only so that QDns can have a default.
.TP
\fCQDns::A\fR - IPv4 addresses. By far the most common type.
.TP
\fCQDns::Aaaa\fR - IPv6 addresses. So far mostly unused.
.TP
\fCQDns::Mx\fR - Mail eXchanger names. Used for mail delivery.
.TP
\fCQDns::Srv\fR - SeRVer names. Generic record type for finding servers. So far mostly unused.
.TP
\fCQDns::Cname\fR - Canonical names. Maps from nicknames to the true name (the canonical name) for a host.
.TP
\fCQDns::Ptr\fR - name PoinTeRs. Maps from IPv4 or IPv6 addresses to hostnames.
.TP
\fCQDns::Txt\fR - arbitrary TeXT for domains.
.PP
We expect that some support for the RFC-2535 extensions will be added in future versions.
.SH MEMBER FUNCTION DOCUMENTATION
.SH "QDns::QDns ()"
Constructs a DNS query object with invalid settings for both the label and the search type.
.SH "QDns::QDns ( const QString & label, RecordType rr = A )"
Constructs a DNS query object that will return record type \fIrr\fR information about \fIlabel\fR.
.PP
The DNS lookup is started the next time the application enters the event loop. When the result is found the signal resultsReady() is emitted.
.PP
\fIrr\fR defaults to A, IPv4 addresses.
.SH "QDns::QDns ( const QHostAddress & address, RecordType rr = Ptr )"
Constructs a DNS query object that will return record type \fIrr\fR information about host address \fIaddress\fR. The label is set to the IN-ADDR.ARPA domain name. This is useful in combination with the Ptr record type (e.g. if you want to look up a hostname for a given address).
.PP
The DNS lookup is started the next time the application enters the event loop. When the result is found the signal resultsReady() is emitted.
.PP
\fIrr\fR defaults to Ptr, that maps addresses to hostnames.
.SH "QDns::~QDns ()\fC [virtual]\fR"
Destroys the DNS query object and frees its allocated resources.
.SH "QValueList<QHostAddress> QDns::addresses () const"
Returns a list of the addresses for this name if this QDns object has a recordType() of QDns::A or QDns::Aaaa and the answer is available; otherwise returns an empty list.
.PP
As a special case, if label() is a valid numeric IP address, this function returns that address.
.PP
Note that if you want to iterate over the list, you should iterate over a copy, e.g.
.PP
.nf
.br
    QValueList<QHostAddress> list = myDns.addresses();
.br
    QValueList<QHostAddress>::Iterator it = list.begin();
.br
    while( it != list.end() ) {
.br
        myProcessing( *it );
.br
        ++it;
.br
    }
.br
.fi
.SH "QString QDns::canonicalName () const"
Returns the canonical name for this DNS node. (This works regardless of what recordType() is set to.)
.PP
If the canonical name isn't known, this function returns a null string.
.PP
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 QDns is" trolltech.com", then the canonical name for all of "lillian"," l", "lillian.troll.no." and "l.trolltech.com" is" lillian.troll.no.".
.SH "QStringList QDns::hostNames () const"
Returns a list of host names if the record type is Ptr.
.PP
Note that if you want to iterate over the list, you should iterate over a copy, e.g.
.PP
.nf
.br
    QStringList list = myDns.hostNames();
.br
    QStringList::Iterator it = list.begin();
.br
    while( it != list.end() ) {
.br
        myProcessing( *it );
.br
        ++it;
.br
    }
.br
.fi
.SH "bool QDns::isWorking () const"
Returns TRUE if QDns is doing a lookup for this object (i.e. if it does not already have the necessary information); otherwise returns FALSE.
.PP
QDns emits the resultsReady() signal when the status changes to FALSE.
.PP
Example: network/mail/smtp.cpp.
.SH "QString QDns::label () const"
Returns the domain name for which this object returns information.
.PP
See also setLabel().
.SH "QValueList<MailServer> QDns::mailServers () const"
Returns a list of mail servers if the record type is Mx. The class \fCQDns::MailServer\fR contains the following public variables:
.TP
QString QDns::MailServer::name
.TP
Q_UINT16 QDns::MailServer::priority
.PP
Note that if you want to iterate over the list, you should iterate over a copy, e.g.
.PP
.nf
.br
    QValueList<QDns::MailServer> list = myDns.mailServers();
.br
    QValueList<QDns::MailServer>::Iterator it = list.begin();
.br
    while( it != list.end() ) {
.br
        myProcessing( *it );
.br
        ++it;
.br
    }
.br
.fi
.PP
Example: network/mail/smtp.cpp.
.SH "QStringList QDns::qualifiedNames () const"
Returns a list of the fully qualified names label() maps to.
.PP
Note that if you want to iterate over the list, you should iterate over a copy, e.g.
.PP
.nf
.br
    QStringList list = myDns.qualifiedNames();
.br
    QStringList::Iterator it = list.begin();
.br
    while( it != list.end() ) {
.br
        myProcessing( *it );
.br
        ++it;
.br
    }
.br
.fi
.SH "RecordType QDns::recordType () const"
Returns the record type of this DNS query object.
.PP
See also setRecordType() and RecordType.
.SH "void QDns::resultsReady ()\fC [signal]\fR"
This signal is emitted when results are available for one of the qualifiedNames().
.PP
Example: network/mail/smtp.cpp.
.SH "QValueList<Server> QDns::servers () const"
Returns a list of servers if the record type is Srv. The class \fCQDns::Server\fR contains the following public variables:
.TP
QString QDns::Server::name
.TP
Q_UINT16 QDns::Server::priority
.TP
Q_UINT16 QDns::Server::weight
.TP
Q_UINT16 QDns::Server::port
.PP
Note that if you want to iterate over the list, you should iterate over a copy, e.g.
.PP
.nf
.br
    QValueList<QDns::Server> list = myDns.servers();
.br
    QValueList<QDns::Server>::Iterator it = list.begin();
.br
    while( it != list.end() ) {
.br
        myProcessing( *it );
.br
        ++it;
.br
    }
.br
.fi
.SH "void QDns::setLabel ( const QString & label )\fC [virtual]\fR"
Sets this DNS query object to query for information about \fIlabel\fR.
.PP
This does not change the recordType(), but its isWorking() status will probably change as a result.
.PP
The DNS lookup is started the next time the application enters the event loop. When the result is found the signal resultsReady() is emitted.
.SH "void QDns::setLabel ( const QHostAddress & address )\fC [virtual]\fR"
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
.PP
Sets this DNS query object to query for information about the host address \fIaddress\fR. The label is set to the IN-ADDR.ARPA domain name. This is useful in combination with the Ptr record type (e.g. if you want to look up a hostname for a given address).
.SH "void QDns::setRecordType ( RecordType rr = A )\fC [virtual]\fR"
Sets this object to query for record type \fIrr\fR records.
.PP
The DNS lookup is started the next time the application enters the event loop. When the result is found the signal resultsReady() is emitted.
.PP
See also RecordType.
.SH "QStringList QDns::texts () const"
Returns a list of texts if the record type is Txt.
.PP
Note that if you want to iterate over the list, you should iterate over a copy, e.g.
.PP
.nf
.br
    QStringList list = myDns.texts();
.br
    QStringList::Iterator it = list.begin();
.br
    while( it != list.end() ) {
.br
        myProcessing( *it );
.br
        ++it;
.br
    }
.br
.fi

.SH "SEE ALSO"
.BR http://doc.trolltech.com/qdns.html
.BR http://www.trolltech.com/faq/tech.html
.SH COPYRIGHT
Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com.  See the
license file included in the distribution for a complete license
statement.
.SH AUTHOR
Generated automatically from the source code.
.SH BUGS
If you find a bug in Qt, please report it as described in
.BR http://doc.trolltech.com/bughowto.html .
Good bug reports help us to help you. Thank you.
.P
The definitive Qt documentation is provided in HTML format; it is
located at $QTDIR/doc/html and can be read using Qt Assistant or with
a web browser. This man page is provided as a convenience for those
users who prefer man pages, although this format is not officially
supported by Trolltech. 
.P
If you find errors in this manual page, please report them to
.BR qt-bugs@trolltech.com .
Please include the name of the manual page (qdns.3qt) and the Qt
version (3.3.8).