Warning: That file was not part of the compilation database. It may have many parsing errors.
1 | /* -*- mode: C++; coding: utf-8; -*- |
---|---|
2 | * Copyright (C) 2003,2005 Thiago Macieira <thiago@kde.org> |
3 | * |
4 | * |
5 | * Permission is hereby granted, free of charge, to any person obtaining |
6 | * a copy of this software and associated documentation files (the |
7 | * "Software"), to deal in the Software without restriction, including |
8 | * without limitation the rights to use, copy, modify, merge, publish, |
9 | * distribute, sublicense, and/or sell copies of the Software, and to |
10 | * permit persons to whom the Software is furnished to do so, subject to |
11 | * the following conditions: |
12 | * |
13 | * The above copyright notice and this permission notice shall be included |
14 | * in all copies or substantial portions of the Software. |
15 | * |
16 | * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, |
17 | * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF |
18 | * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND |
19 | * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE |
20 | * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION |
21 | * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION |
22 | * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
23 | */ |
24 | |
25 | #ifndef KRESOLVER_H |
26 | #define KRESOLVER_H |
27 | |
28 | ////////////////// |
29 | // Needed includes |
30 | #include <QtCore/QList> |
31 | #include <QtCore/QObject> |
32 | #include <QtCore/QSharedDataPointer> |
33 | #include "k3socketaddress.h" |
34 | |
35 | |
36 | //////////////////////// |
37 | // Forward declarations |
38 | struct sockaddr; |
39 | class QString; |
40 | class QByteArray; |
41 | template<typename T> class QSet; |
42 | |
43 | ////////////////// |
44 | // Our definitions |
45 | |
46 | namespace KNetwork { |
47 | |
48 | namespace Internal { class KResolverManager; } |
49 | |
50 | class KResolverEntryPrivate; |
51 | /** @class KResolverEntry k3resolver.h k3resolver.h |
52 | * @brief One resolution entry. |
53 | * |
54 | * This class is one element in the resolution results list. |
55 | * It contains the socket address for connecting, as well as |
56 | * a bit more of information: the socket type, address family |
57 | * and protocol numbers. |
58 | * |
59 | * This class contains all the information required for creating, |
60 | * binding and connecting a socket. |
61 | * |
62 | * KResolverEntry objects implicitly share data, so copying them |
63 | * is quite efficient. |
64 | * |
65 | * @author Thiago Macieira <thiago@kde.org> |
66 | * @deprecated Use KSocketFactory or KLocalSocket instead |
67 | */ |
68 | class KDECORE_EXPORT_DEPRECATED KResolverEntry |
69 | { |
70 | public: |
71 | /** |
72 | * Default constructor |
73 | * |
74 | */ |
75 | KResolverEntry(); |
76 | |
77 | /** |
78 | * Constructs a new KResolverEntry from a KSocketAddress |
79 | * and other data. |
80 | * |
81 | * The KSocketAddress @p addr parameter will be deep-copied. |
82 | * |
83 | * @param addr the address that was resolved |
84 | * @param socktype the socket type of the resolved address |
85 | * @param protocol the protocol of the resolved address |
86 | * @param canonName the canonical name of the resolved hostname |
87 | * @param encodedName the ASCII-compatible encoding of the hostname |
88 | */ |
89 | KResolverEntry(const KSocketAddress& addr, int socktype, int protocol, |
90 | const QString& canonName = QString(), |
91 | const QByteArray& encodedName = QByteArray()); |
92 | |
93 | /** |
94 | * Constructs a new KResolverEntry from raw forms of |
95 | * socket addresses and other data. |
96 | * |
97 | * This constructor instead creates an internal KSocketAddress object. |
98 | * |
99 | * @param sa the sockaddr structure containing the raw address |
100 | * @param salen the length of the sockaddr structure |
101 | * @param socktype the socket type of the resolved address |
102 | * @param protocol the protocol of the resolved address |
103 | * @param canonName the canonical name of the resolved hostname |
104 | * @param encodedName the ASCII-compatible encoding of the hostname |
105 | */ |
106 | KResolverEntry(const struct sockaddr *sa, quint16 salen, int socktype, |
107 | int protocol, const QString& canonName = QString(), |
108 | const QByteArray& encodedName = QByteArray()); |
109 | |
110 | /** |
111 | * Copy constructor. |
112 | * |
113 | * This constructor performs a shallow-copy of the other object. |
114 | */ |
115 | KResolverEntry(const KResolverEntry &other); |
116 | |
117 | /** |
118 | * Destructor. |
119 | * |
120 | * The destructor frees associated resources with this object. It does |
121 | * not destroy shared data. |
122 | */ |
123 | ~KResolverEntry(); |
124 | |
125 | /** |
126 | * Retrieves the socket address associated with this entry. |
127 | */ |
128 | KSocketAddress address() const; |
129 | |
130 | /** |
131 | * Retrieves the length of the socket address structure. |
132 | */ |
133 | quint16 length() const; |
134 | |
135 | /** |
136 | * Retrieves the family associated with this socket address. |
137 | */ |
138 | int family() const; |
139 | |
140 | /** |
141 | * Retrieves the canonical name associated with this entry, if there is any. |
142 | * If the canonical name was not found, this function returns QString(). |
143 | */ |
144 | QString canonicalName() const; |
145 | |
146 | /** |
147 | * Retrieves the encoded domain name associated with this entry, if there is |
148 | * any. If this domain has been resolved through DNS, this will be the |
149 | * the ACE-encoded hostname. |
150 | * |
151 | * Returns a null QByteArray if such information is not available. |
152 | * |
153 | * Please note that this information is NOT to be presented to the user, |
154 | * unless requested. |
155 | */ |
156 | QByteArray encodedName() const; |
157 | |
158 | /** |
159 | * Retrieves the socket type associated with this entry. |
160 | */ |
161 | int socketType() const; |
162 | |
163 | /** |
164 | * Retrieves the protocol associated with this entry. |
165 | */ |
166 | int protocol() const; |
167 | |
168 | /** |
169 | * Assignment operator |
170 | * |
171 | * This function copies the contents of the other object into this one. |
172 | * Data will be shared between the two of them. |
173 | */ |
174 | KResolverEntry& operator=(const KResolverEntry& other); |
175 | |
176 | #ifdef MAKE_KDECORE_LIB |
177 | /** |
178 | * Dummy operator== for compilers which need a complete |
179 | * instantiated class when exporting to a shared lib |
180 | */ |
181 | KDE_DUMMY_COMPARISON_OPERATOR(KResolverEntry) |
182 | #endif |
183 | |
184 | private: |
185 | QSharedDataPointer<KResolverEntryPrivate> d; |
186 | }; |
187 | |
188 | #ifdef MAKE_KDECORE_LIB |
189 | KDE_DUMMY_QHASH_FUNCTION(KResolverEntry) |
190 | #endif |
191 | |
192 | class KResolverResultsPrivate; |
193 | /** |
194 | * @class KResolverResults k3resolver.h k3resolver.h |
195 | * @brief Name and service resolution results. |
196 | * |
197 | * This object contains the results of a name and service resolution, as |
198 | * those performed by KResolver. It is also a descendant of QValueList, so |
199 | * you may use all its member functions here to access the elements. |
200 | * |
201 | * A KResolverResults object is associated with a resolution, so, in addition |
202 | * to the resolved elements, you can also retrieve information about the |
203 | * resolution process itself, like the nodename that was resolved or an error |
204 | * code. |
205 | * |
206 | * Note Resolver also uses KResolverResults objects to indicate failure, so |
207 | * you should test for failure. |
208 | * |
209 | * @author Thiago Macieira <thiago@kde.org> |
210 | * @deprecated Use KSocketFactory or KLocalSocket instead |
211 | */ |
212 | class KDECORE_EXPORT_DEPRECATED KResolverResults: public QList<KResolverEntry> |
213 | { |
214 | public: |
215 | /** |
216 | * Default constructor. |
217 | * |
218 | * Constructs an empty list. |
219 | */ |
220 | KResolverResults(); |
221 | |
222 | /** |
223 | * Copy constructor |
224 | * |
225 | * Creates a new object with the contents of the other one. Data will be |
226 | * shared by the two objects, like QValueList |
227 | */ |
228 | KResolverResults(const KResolverResults& other); |
229 | |
230 | /** |
231 | * Destructor |
232 | * |
233 | * Destroys the object and frees associated resources. |
234 | */ |
235 | virtual ~KResolverResults(); |
236 | |
237 | /** |
238 | * Assignment operator |
239 | * |
240 | * Copies the contents of the other container into this one, discarding |
241 | * our current values. |
242 | */ |
243 | KResolverResults& operator=(const KResolverResults& other); |
244 | |
245 | /** |
246 | * Retrieves the error code associated with this resolution. The values |
247 | * here are the same as in KResolver::ErrorCodes. |
248 | */ |
249 | int error() const; |
250 | |
251 | /** |
252 | * Retrieves the system error code, if any. |
253 | * @see KResolver::systemError for more information |
254 | */ |
255 | int systemError() const; |
256 | |
257 | /** |
258 | * Sets the error codes |
259 | * |
260 | * @param errorcode the error code in KResolver::ErrorCodes |
261 | * @param systemerror the system error code associated, if any |
262 | */ |
263 | void setError(int errorcode, int systemerror = 0); |
264 | |
265 | /** |
266 | * The nodename to which the resolution was performed. |
267 | */ |
268 | QString nodeName() const; |
269 | |
270 | /** |
271 | * The service name to which the resolution was performed. |
272 | */ |
273 | QString serviceName() const; |
274 | |
275 | /** |
276 | * Sets the new nodename and service name |
277 | */ |
278 | void setAddress(const QString& host, const QString& service); |
279 | |
280 | protected: |
281 | /** Standard hack to add virtuals later. @internal */ |
282 | virtual void virtual_hook( int id, void* data ); |
283 | private: |
284 | QSharedDataPointer<KResolverResultsPrivate> d; |
285 | }; |
286 | |
287 | class KResolverPrivate; |
288 | /** |
289 | * @class KResolver k3resolver.h k3resolver.h |
290 | * @brief Name and service resolution class. |
291 | * |
292 | * This class provides support for doing name-to-binary resolution |
293 | * for nodenames and service ports. You should use this class if you |
294 | * need specific resolution techniques when creating a socket or if you |
295 | * want to inspect the results before calling the socket functions. |
296 | * |
297 | * You can either create an object and set the options you want in it |
298 | * or you can simply call the static member functions, which will create |
299 | * standard Resolver objects and dispatch the resolution for you. Normally, |
300 | * the static functions will be used, except in cases where specific options |
301 | * must be set. |
302 | * |
303 | * A Resolver object defaults to the following: |
304 | * @li address family: any address family |
305 | * @li socket type: streaming socket |
306 | * @li protocol: implementation-defined. Generally, TCP |
307 | * @li host and service: unset |
308 | * |
309 | * @author Thiago Macieira <thiago@kde.org> |
310 | * @deprecated Use KSocketFactory or KLocalSocket instead |
311 | */ |
312 | class KDECORE_EXPORT_DEPRECATED KResolver: public QObject |
313 | { |
314 | Q_OBJECT |
315 | |
316 | public: |
317 | |
318 | /** |
319 | * Address family selection types |
320 | * |
321 | * These values can be OR-ed together to form a composite family selection. |
322 | * |
323 | * @li UnknownFamily: a family that is unknown to the current implementation |
324 | * @li KnownFamily: a family that is known to the implementation (the exact |
325 | * opposite of UnknownFamily) |
326 | * @li AnyFamilies: any address family is acceptable |
327 | * @li InternetFamily: an address for connecting to the Internet |
328 | * @li InetFamily: alias for InternetFamily |
329 | * @li IPv6Family: an IPv6 address only |
330 | * @li IPv4Family: an IPv4 address only |
331 | * @li UnixFamily: an address for the local Unix namespace (i.e., Unix sockets) |
332 | * @li LocalFamily: alias for UnixFamily |
333 | */ |
334 | enum SocketFamilies |
335 | { |
336 | UnknownFamily = 0x0001, |
337 | |
338 | UnixFamily = 0x0002, |
339 | LocalFamily = UnixFamily, |
340 | |
341 | IPv4Family = 0x0004, |
342 | IPv6Family = 0x0008, |
343 | InternetFamily = IPv4Family | IPv6Family, |
344 | InetFamily = InternetFamily, |
345 | |
346 | KnownFamily = ~UnknownFamily, |
347 | AnyFamily = KnownFamily | UnknownFamily |
348 | }; |
349 | |
350 | /** |
351 | * Flags for the resolution. |
352 | * |
353 | * These flags are used for setting the resolution behaviour for this |
354 | * object: |
355 | * @li Passive: resolve to a passive socket (i.e., one that can be used for |
356 | * binding to a local interface) |
357 | * @li CanonName: request that the canonical name for the given nodename |
358 | * be found and recorded |
359 | * @li NoResolve: request that no external resolution be performed. The given |
360 | * nodename and servicename will be resolved locally only. |
361 | * @li NoSrv: don't try to use SRV-based name-resolution. |
362 | * @li Multiport: the port/service argument is a list of port numbers and |
363 | * ranges. (future extension) |
364 | * |
365 | * @note SRV-based lookup and Multiport are not implemented yet. |
366 | */ |
367 | enum Flags |
368 | { |
369 | Passive = 0x01, |
370 | CanonName = 0x02, |
371 | NoResolve = 0x04, |
372 | NoSrv = 0x08, |
373 | Multiport = 0x10 |
374 | }; |
375 | |
376 | /** |
377 | * Error codes |
378 | * |
379 | * These are the possible error values that objects of this class |
380 | * may return. See errorString() for getting a string representation |
381 | * for these errors. |
382 | * |
383 | * @li AddrFamily: Address family for the given nodename is not supported. |
384 | * @li TryAgain: Temporary failure in name resolution. You should try again. |
385 | * @li NonRecoverable: Non-recoverable failure in name resolution. |
386 | * @li BadFlags: Invalid flags were given. |
387 | * @li Memory: Memory allocation failure. |
388 | * @li NoName: The specified name or service doesn't exist. |
389 | * @li UnsupportedFamily: The requested socket family is not supported. |
390 | * @li UnsupportedService: The requested service is not supported for this |
391 | * socket type (i.e., a datagram service in a streaming socket). |
392 | * @li UnsupportedSocketType: The requested socket type is not supported. |
393 | * @li UnknownError: An unknown, unexpected error occurred. |
394 | * @li SystemError: A system error occurred. See systemError(). |
395 | * @li Canceled: This request was canceled by the user. |
396 | */ |
397 | enum ErrorCodes |
398 | { |
399 | // note: if you change this enum, take a look at KResolver::errorString |
400 | NoError = 0, |
401 | AddrFamily = -1, |
402 | TryAgain = -2, |
403 | NonRecoverable = -3, |
404 | BadFlags = -4, |
405 | Memory = -5, |
406 | NoName = -6, |
407 | UnsupportedFamily = -7, |
408 | UnsupportedService = -8, |
409 | UnsupportedSocketType = -9, |
410 | UnknownError = -10, |
411 | SystemError = -11, |
412 | Canceled = -100 |
413 | }; |
414 | |
415 | /** |
416 | * Status codes. |
417 | * |
418 | * These are the possible status for a Resolver object. A value |
419 | * greater than zero indicates normal behaviour, while negative |
420 | * values either indicate failure or error. |
421 | * |
422 | * @li Idle: resolution has not yet been started. |
423 | * @li Queued: resolution is queued but not yet in progress. |
424 | * @li InProgress: resolution is in progress. |
425 | * @li PostProcessing: resolution is in progress. |
426 | * @li Success: resolution is done; you can retrieve the results. |
427 | * @li Canceled: request canceled by the user. |
428 | * @li Failed: resolution is done, but failed. |
429 | * |
430 | * Note: the status Canceled and the error code Canceled are the same. |
431 | * |
432 | * Note 2: the status Queued and InProgress might not be distinguishable. |
433 | * Some implementations might not differentiate one from the other. |
434 | */ |
435 | enum StatusCodes |
436 | { |
437 | Idle = 0, |
438 | Queued = 1, |
439 | InProgress = 5, |
440 | PostProcessing = 6, |
441 | Success = 10, |
442 | //Canceled = -100, // already defined above |
443 | Failed = -101 |
444 | }; |
445 | |
446 | /** |
447 | * Default constructor. |
448 | * |
449 | * Creates an empty Resolver object. You should set the wanted |
450 | * names and flags using the member functions before starting |
451 | * the name resolution. |
452 | * |
453 | * @param parent the parent object (see QObject) |
454 | */ |
455 | KResolver(QObject *parent = 0L); |
456 | |
457 | /** |
458 | * Constructor with host and service names. |
459 | * |
460 | * Creates a Resolver object with the given host and |
461 | * service names. Flags are initialised to 0 and any address family |
462 | * will be accepted. |
463 | * |
464 | * @param nodename the host name we want resolved |
465 | * @param servicename the service name associated, like "http" |
466 | * @param parent the parent object (see QObject) |
467 | */ |
468 | explicit KResolver(const QString& nodename, const QString& servicename = QString(), |
469 | QObject *parent = 0L); |
470 | |
471 | /** |
472 | * Destructor. |
473 | * |
474 | * When this object is deleted, it'll destroy all associated |
475 | * resources. If the resolution is still in progress, it will be |
476 | * canceled and the signal will \b not be emitted. |
477 | */ |
478 | virtual ~KResolver(); |
479 | |
480 | /** |
481 | * Retrieve the current status of this object. |
482 | * |
483 | * @see StatusCodes for the possible status codes. |
484 | */ |
485 | int status() const; |
486 | |
487 | /** |
488 | * Retrieve the error code in this object. |
489 | * |
490 | * This function will return NoError if we are not in |
491 | * an error condition. See status() and StatusCodes to |
492 | * find out what the current status is. |
493 | * |
494 | * @see errorString for getting a textual representation of |
495 | * this error |
496 | */ |
497 | int error() const; |
498 | |
499 | /** |
500 | * Retrieve the associated system error code in this object. |
501 | * |
502 | * Many resolution operations may generate an extra error code |
503 | * as given by the C errno variable. That value is stored in the |
504 | * object and can be retrieved by this function. |
505 | */ |
506 | int systemError() const; |
507 | |
508 | /** |
509 | * Returns the textual representation of the error in this object. |
510 | */ |
511 | QString errorString() const; |
512 | |
513 | /** |
514 | * Returns true if this object is currently running |
515 | */ |
516 | bool isRunning() const; |
517 | |
518 | /** |
519 | * The nodename to which the resolution was/is to be performed. |
520 | */ |
521 | QString nodeName() const; |
522 | |
523 | /** |
524 | * The service name to which the resolution was/is to be performed. |
525 | */ |
526 | QString serviceName() const; |
527 | |
528 | /** |
529 | * Sets the nodename for the resolution. |
530 | * |
531 | * Set the nodename to QString() to unset it. |
532 | * @param nodename The nodename to be resolved. |
533 | */ |
534 | void setNodeName(const QString& nodename); |
535 | |
536 | /** |
537 | * Sets the service name to be resolved. |
538 | * |
539 | * Set it to QString() to unset it. |
540 | * @param service The service to be resolved. |
541 | */ |
542 | void setServiceName(const QString& service); |
543 | |
544 | /** |
545 | * Sets both the host and the service names. |
546 | * |
547 | * Setting either value to QString() will unset them. |
548 | * @param node The nodename |
549 | * @param service The service name |
550 | */ |
551 | void setAddress(const QString& node, const QString& service); |
552 | |
553 | /** |
554 | * Retrieves the flags set for the resolution. |
555 | * |
556 | * @see Flags for an explanation on what flags are possible |
557 | */ |
558 | int flags() const; |
559 | |
560 | /** |
561 | * Sets the flags. |
562 | * |
563 | * @param flags the new flags |
564 | * @return the old flags |
565 | * @see Flags for an explanation on the flags |
566 | */ |
567 | int setFlags(int flags); |
568 | |
569 | /** |
570 | * Sets the allowed socket families. |
571 | * |
572 | * @param families the families that we want/accept |
573 | * @see SocketFamilies for possible values |
574 | */ |
575 | void setFamily(int families); |
576 | |
577 | /** |
578 | * Sets the socket type we want. |
579 | * |
580 | * The values for the @p type parameter are the SOCK_* |
581 | * constants, defined in <sys/socket.h>. The most common |
582 | * values are: |
583 | * @li SOCK_STREAM streaming socket (= reliable, sequenced, |
584 | * connection-based) |
585 | * @li SOCK_DGRAM datagram socket (= unreliable, connectionless) |
586 | * @li SOCK_RAW raw socket, with direct access to the |
587 | * container protocol (such as IP) |
588 | * |
589 | * These three are the only values to which it is guaranteed that |
590 | * resolution will work. Some systems may define other constants (such as |
591 | * SOCK_RDM for reliable datagrams), but support is implementation-defined. |
592 | * |
593 | * @param type the wanted socket type (SOCK_* constants). Set |
594 | * 0 to use the default. |
595 | */ |
596 | void setSocketType(int type); |
597 | |
598 | /** |
599 | * Sets the protocol we want. |
600 | * |
601 | * Protocols are dependent on the selected address family, so you should know |
602 | * what you are doing if you use this function. Besides, protocols generally |
603 | * are either stream-based or datagram-based, so the value of the socket |
604 | * type is also important. The resolution will fail if these values don't match. |
605 | * |
606 | * When using an Internet socket, the values for the protocol are the |
607 | * IPPROTO_* constants, defined in <netinet/in.h>. |
608 | * |
609 | * You may choose to set the protocol either by its number or by its name, or |
610 | * by both. If you set: |
611 | * @li the number and the name: both values will be stored internally; you |
612 | * may set the name to an empty value, if wanted |
613 | * @li the number only (name = NULL): the name will be searched in the |
614 | * protocols database |
615 | * @li the name only (number = 0): the number will be searched in the |
616 | * database |
617 | * @li neither name nor number: reset to default behaviour |
618 | * |
619 | * @param protonum the protocol number we want |
620 | * @param name the protocol name |
621 | */ |
622 | void setProtocol(int protonum, const char *name = 0L); |
623 | |
624 | /** |
625 | * Starts the name resolution asynchronously. |
626 | * |
627 | * This function will queue this object for resolution |
628 | * and will return immediately. The status upon exit will either be |
629 | * Queued or InProgress or Failed. |
630 | * |
631 | * This function does nothing if the object is already queued. But if |
632 | * it had already succeeded or failed, this function will re-start it. |
633 | * |
634 | * Note: if both the nodename and the servicename are unset, this function |
635 | * will not queue, but will set a success state and emit the signal. Also |
636 | * note that in this case and maybe others, the signal finished() might |
637 | * be emitted before this function returns. |
638 | * |
639 | * @return true if this request was successfully queued for asynchronous |
640 | * resolution |
641 | */ |
642 | bool start(); |
643 | |
644 | /** |
645 | * Waits for a request to finish resolving. |
646 | * |
647 | * This function will wait on a running request for its termination. The |
648 | * status upon exit will either be Success or Failed or Canceled. |
649 | * |
650 | * This function may be called from any thread, even one that is not the |
651 | * GUI thread or the one that started the resolution process. But note this |
652 | * function is not thread-safe nor reentrant: i.e., only one thread can be |
653 | * waiting on one given object. |
654 | * |
655 | * Also note that this function ensures that the finished() signal is |
656 | * emitted before it returns. That means that, as a side-effect, whenever |
657 | * wait() is called, the signal is emitted on the thread calling wait(). |
658 | * |
659 | * @param msec the time to wait, in milliseconds or 0 to |
660 | * wait forever |
661 | * @return true if the resolution has finished processing, even when it |
662 | * failed or was canceled. False means the wait timed out and |
663 | * the resolution is still running. |
664 | */ |
665 | bool wait(int msec = 0); |
666 | |
667 | /** |
668 | * Cancels a running request |
669 | * |
670 | * This function will cancel a running request. If the request is not |
671 | * currently running or queued, this function does nothing. |
672 | * |
673 | * Note: if you tell the signal to be emitted, be aware that it might |
674 | * or might not be emitted before this function returns. |
675 | * |
676 | * @param emitSignal whether to emit the finished() signal or not |
677 | */ |
678 | void cancel(bool emitSignal = true); |
679 | |
680 | /** |
681 | * Retrieves the results of this resolution |
682 | * |
683 | * Use this function to retrieve the results of the resolution. If no |
684 | * data was resolved (yet) or if we failed, this function will return |
685 | * an empty object. |
686 | * |
687 | * @return the resolved data |
688 | * @see status for information on finding out if the resolution was successful |
689 | */ |
690 | KResolverResults results() const; |
691 | |
692 | /** |
693 | * Handles events. Reimplemented from QObject. |
694 | * |
695 | * This function handles the events generated by the manager indicating that |
696 | * this object has finished processing. |
697 | * |
698 | * Do not post events to this object. |
699 | */ |
700 | virtual bool event(QEvent*); |
701 | |
702 | Q_SIGNALS: |
703 | // signals |
704 | |
705 | /** |
706 | * This signal is emitted whenever the resolution is finished, one |
707 | * way or another (success or failure). The @p results parameter |
708 | * will contain the resolved data. |
709 | * |
710 | * Note: if you are doing multiple resolutions, you can use the |
711 | * QObject::sender() function to distinguish one Resolver object from |
712 | * another. |
713 | * |
714 | * @param results the resolved data; might be empty if the resolution |
715 | * failed |
716 | * @see results for information on what the results are |
717 | * |
718 | * @note This signal is @b always delivered in the GUI event thread, even for |
719 | * resolutions that were started in secondary threads. |
720 | */ |
721 | void finished(const KNetwork::KResolverResults& results); |
722 | |
723 | private: |
724 | void emitFinished(); |
725 | |
726 | public: |
727 | // Static functions |
728 | |
729 | /** |
730 | * Returns the string representation of this error code. |
731 | * |
732 | * @param errorcode the error code. See ErrorCodes. |
733 | * @param syserror the system error code associated. |
734 | * @return the string representation. This is already |
735 | * i18n'ed. |
736 | */ |
737 | static QString errorString(int errorcode, int syserror = 0); |
738 | |
739 | /** |
740 | * Resolve the nodename and service name synchronously |
741 | * |
742 | * This static function is provided as convenience for simplifying |
743 | * name resolution. It resolves the given host and service names synchronously |
744 | * and returns the results it found. It is equivalent to the following code: |
745 | * |
746 | * \code |
747 | * KResolver qres(host, service); |
748 | * qres.setFlags(flags); |
749 | * qres.setFamily(families) |
750 | * qres.start(); |
751 | * qres.wait(); |
752 | * return qres.results(); |
753 | * \endcode |
754 | * |
755 | * @param host the nodename to resolve |
756 | * @param service the service to resolve |
757 | * @param flags flags to be used |
758 | * @param families the families to be searched |
759 | * @return a KResolverResults object containing the results |
760 | * @see KResolverResults for information on how to obtain the error code |
761 | */ |
762 | static KResolverResults resolve(const QString& host, const QString& service, |
763 | int flags = 0, int families = KResolver::InternetFamily); |
764 | |
765 | /** |
766 | * Start an asynchronous name resolution |
767 | * |
768 | * This function is provided as a convenience to simplify the resolution |
769 | * process. It creates an internal KResolver object, connects the |
770 | * finished() signal to the given slot and starts the resolution |
771 | * asynchronously. It is more or less equivalent to the following code: |
772 | * |
773 | * \b Note: this function may trigger the signal before it returns, so |
774 | * your code must be prepared for this situation. |
775 | * |
776 | * \code |
777 | * KResolver* qres = new KResolver(host, service); |
778 | * QObject::connect(qres, SIGNAL(finished(const KNetwork::KResolverResults&)), |
779 | * userObj, userSlot); |
780 | * qres->setFlags(flags); |
781 | * qres->setFamily(families); |
782 | * return qres->start(); |
783 | * \endcode |
784 | * |
785 | * You should use it like this in your code: |
786 | * \code |
787 | * KResolver::resolveAsync(myObj, SLOT(mySlot(KResolverResults)), host, service); |
788 | * \endcode |
789 | * |
790 | * @param userObj the object whose slot @p userSlot we will connect |
791 | * @param userSlot the slot to which we'll connect |
792 | * @param host the nodename to resolve |
793 | * @param service the service to resolve |
794 | * @param flags flags to be used |
795 | * @param families families to be searcheed |
796 | * @return true if the queuing was successful, false if not |
797 | * @see KResolverResults for information on how to obtain the error code |
798 | */ |
799 | static bool resolveAsync(QObject* userObj, const char *userSlot, |
800 | const QString& host, const QString& service, |
801 | int flags = 0, int families = KResolver::InternetFamily); |
802 | |
803 | /** |
804 | * Returns the domain name in an ASCII Compatible Encoding form, suitable |
805 | * for DNS lookups. This is the base for International Domain Name support |
806 | * over the Internet. |
807 | * |
808 | * Note this function may fail, in which case it'll return a null |
809 | * QByteArray. Reasons for failure include use of unknown code |
810 | * points (Unicode characters). |
811 | * |
812 | * Note that the encoding is illegible and, thus, should not be presented |
813 | * to the user, except if requested. |
814 | * |
815 | * @param unicodeDomain the domain name to be encoded |
816 | * @return the ACE-encoded suitable for DNS queries if successful, a null |
817 | * QByteArray if failure. |
818 | */ |
819 | static QByteArray domainToAscii(const QString& unicodeDomain); |
820 | |
821 | /** |
822 | * Does the inverse of domainToAscii() and return an Unicode domain |
823 | * name from the given ACE-encoded domain. |
824 | * |
825 | * This function may fail if the given domain cannot be successfully |
826 | * converted back to Unicode. Reasons for failure include a malformed |
827 | * domain name or good ones whose reencoding back to ACE don't match |
828 | * the form given here (e.g., ACE-encoding of an already |
829 | * ASCII-compatible domain). |
830 | * |
831 | * It is, however, guaranteed that domains returned |
832 | * by domainToAscii() will work. |
833 | * |
834 | * @param asciiDomain the ACE-encoded domain name to be decoded |
835 | * @return the Unicode representation of the given domain name |
836 | * if successful, the original string if not |
837 | * @note ACE = ASCII-Compatible Encoding, i.e., 7-bit |
838 | */ |
839 | static QString domainToUnicode(const QByteArray& asciiDomain); |
840 | |
841 | /** |
842 | * The same as above, but taking a QString argument. |
843 | * |
844 | * @param asciiDomain the ACE-encoded domain name to be decoded |
845 | * @return the Unicode representation of the given domain name |
846 | * if successful, QString() if not. |
847 | */ |
848 | static QString domainToUnicode(const QString& asciiDomain); |
849 | |
850 | /** |
851 | * Normalise a domain name. |
852 | * |
853 | * In order to prevent simple mistakes in International Domain |
854 | * Names (IDN), it has been decided that certain code points |
855 | * (characters in Unicode) would be instead converted to others. |
856 | * This includes turning them all to lower case, as well certain |
857 | * other specific operations, as specified in the documents. |
858 | * |
859 | * For instance, the German 'ß' will be changed into 'ss', while |
860 | * the micro symbol 'µ' will be changed to the Greek mu 'μ'. |
861 | * |
862 | * Two equivalent domains have the same normalised form. And the |
863 | * normalised form of a normalised domain is itself (i.e., if |
864 | * d is normalised, the following is true: d == normalizeDomain(d) ) |
865 | * |
866 | * This operation is equivalent to encoding and the decoding a Unicode |
867 | * hostname. |
868 | * |
869 | * @param domain a domain to be normalised |
870 | * @return the normalised domain, or QString() if the domain is |
871 | * invalid. |
872 | */ |
873 | static QString normalizeDomain(const QString& domain); |
874 | |
875 | /** |
876 | * Resolves a protocol number to its names |
877 | * |
878 | * Note: the returned QStrList operates on deep-copies. |
879 | * |
880 | * @param protonum the protocol number to be looked for |
881 | * @return all the protocol names in a list. The first is the "proper" |
882 | * name. |
883 | */ |
884 | static QList<QByteArray> protocolName(int protonum); |
885 | |
886 | /** |
887 | * Finds all aliases for a given protocol name |
888 | * |
889 | * @param protoname the protocol name to be looked for |
890 | * @return all the protocol names in a list. The first is the "proper" |
891 | * name. |
892 | */ |
893 | static QList<QByteArray> protocolName(const char *protoname); |
894 | |
895 | /** |
896 | * Resolves a protocol name to its number |
897 | * |
898 | * @param protoname the protocol name to be looked for |
899 | * @return the protocol number or -1 if we couldn't locate it |
900 | */ |
901 | static int protocolNumber(const char *protoname); |
902 | |
903 | /** |
904 | * Resolves a service name to its port number |
905 | * |
906 | * @param servname the service name to be looked for |
907 | * @param protoname the protocol it is associated with |
908 | * @return the port number in host byte-order or -1 in case of error |
909 | */ |
910 | static int servicePort(const char *servname, const char *protoname); |
911 | |
912 | /** |
913 | * Finds all the aliases for a given service name |
914 | * |
915 | * Note: the returned QList<QByteArray> operates on deep-copies. |
916 | * |
917 | * @param servname the service alias to be looked for |
918 | * @param protoname the protocol it is associated with |
919 | * @return all the service names in a list. The first is the "proper" |
920 | * name. |
921 | */ |
922 | static QList<QByteArray> serviceName(const char *servname, const char *protoname); |
923 | |
924 | /** |
925 | * Resolves a port number to its names |
926 | * |
927 | * Note: the returned QList<QByteArray> operates on deep copies. |
928 | * |
929 | * @param port the port number, in host byte-order |
930 | * @param protoname the protocol it is associated with |
931 | * @return all the service names in a list. The first is the "proper" |
932 | * name. |
933 | */ |
934 | static QList<QByteArray> serviceName(int port, const char *protoname); |
935 | |
936 | /** |
937 | * Returns this machine's local hostname. |
938 | * |
939 | * @return this machine's local hostname |
940 | */ |
941 | static QString localHostName(); |
942 | |
943 | protected: |
944 | |
945 | /** |
946 | * Sets the error codes |
947 | */ |
948 | void setError(int errorcode, int systemerror = 0); |
949 | |
950 | /** Standard hack to add virtuals later. @internal */ |
951 | virtual void virtual_hook( int id, void* data ); |
952 | private: |
953 | KResolverPrivate* const d; |
954 | friend class KResolverResults; |
955 | friend class ::KNetwork::Internal::KResolverManager; |
956 | }; |
957 | |
958 | } // namespace KNetwork |
959 | |
960 | #endif |
961 |
Warning: That file was not part of the compilation database. It may have many parsing errors.