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