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
38struct sockaddr;
39class QString;
40class QByteArray;
41template<typename T> class QSet;
42
43//////////////////
44// Our definitions
45
46namespace KNetwork {
47
48 namespace Internal { class KResolverManager; }
49
50class 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 */
68class KDECORE_EXPORT_DEPRECATED KResolverEntry
69{
70public:
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
184private:
185 QSharedDataPointer<KResolverEntryPrivate> d;
186};
187
188#ifdef MAKE_KDECORE_LIB
189KDE_DUMMY_QHASH_FUNCTION(KResolverEntry)
190#endif
191
192class 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 */
212class KDECORE_EXPORT_DEPRECATED KResolverResults: public QList<KResolverEntry>
213{
214public:
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
280protected:
281 /** Standard hack to add virtuals later. @internal */
282 virtual void virtual_hook( int id, void* data );
283private:
284 QSharedDataPointer<KResolverResultsPrivate> d;
285};
286
287class 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 */
312class KDECORE_EXPORT_DEPRECATED KResolver: public QObject
313{
314 Q_OBJECT
315
316public:
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
702Q_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
723private:
724 void emitFinished();
725
726public:
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
943protected:
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 );
952private:
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.