KDELibs4Support

k3resolver.h
1 /* -*- mode: C++; coding: utf-8; -*-
2  * Copyright (C) 2003,2005 Thiago Macieira <[email protected]>
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 <[email protected]>
70  * @deprecated Use KSocketFactory or KLocalSocket instead
71  */
72 class KDELIBS4SUPPORT_DEPRECATED_EXPORT KResolverEntry
73 {
74 public:
75  /**
76  * Default constructor
77  *
78  */
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:
188 };
189 
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 <[email protected]>
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  */
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:
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 <[email protected]>
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  */
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
ErrorCodes
Error codes.
Definition: k3resolver.h:395
One resolution entry.
Definition: k3resolver.h:72
Name and service resolution class.
Definition: k3resolver.h:312
A generic socket address.
Name and service resolution results.
Definition: k3resolver.h:212
A namespace to store all networking-related (socket) classes.
Flags
Flags for the resolution.
Definition: k3resolver.h:366
SocketFamilies
Address family selection types.
Definition: k3resolver.h:334
StatusCodes
Status codes.
Definition: k3resolver.h:432
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Thu Sep 23 2021 22:59:38 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.