KNetwork::KResolver Class Reference
Name and service resolution class. More...
#include <kresolver.h>
Inheritance diagram for KNetwork::KResolver:

Public Types | |
enum | SocketFamilies { UnknownFamily = 0x0001, UnixFamily = 0x0002, LocalFamily = UnixFamily, IPv4Family = 0x0004, IPv6Family = 0x0008, InternetFamily = IPv4Family | IPv6Family, InetFamily = InternetFamily, KnownFamily = ~UnknownFamily, AnyFamily = KnownFamily | UnknownFamily } |
enum | Flags { Passive = 0x01, CanonName = 0x02, NoResolve = 0x04, NoSrv = 0x08, Multiport = 0x10 } |
enum | ErrorCodes { NoError = 0, AddrFamily = -1, TryAgain = -2, NonRecoverable = -3, BadFlags = -4, Memory = -5, NoName = -6, UnsupportedFamily = -7, UnsupportedService = -8, UnsupportedSocketType = -9, UnknownError = -10, SystemError = -11, Canceled = -100 } |
enum | StatusCodes { Idle = 0, Queued = 1, InProgress = 5, PostProcessing = 6, Success = 10, Failed = -101 } |
Signals | |
void | finished (KResolverResults results) |
Public Member Functions | |
KResolver (QObject *=0L, const char *=0L) | |
KResolver (const QString &nodename, const QString &servicename=QString::null, QObject *=0L, const char *=0L) | |
virtual | ~KResolver () |
int | status () const |
int | error () const |
int | systemError () const |
QString | errorString () const |
bool | isRunning () const |
QString | nodeName () const |
QString | serviceName () const |
void | setNodeName (const QString &nodename) |
void | setServiceName (const QString &service) |
void | setAddress (const QString &node, const QString &service) |
int | flags () const |
int | setFlags (int flags) |
void | setFamily (int families) |
void | setSocketType (int type) |
void | setProtocol (int protonum, const char *name=0L) |
bool | start () |
bool | wait (int msec=0) |
void | cancel (bool emitSignal=true) |
KResolverResults | results () const |
virtual bool | event (QEvent *) |
Static Public Member Functions | |
QString | errorString (int errorcode, int syserror=0) |
KResolverResults | resolve (const QString &host, const QString &service, int flags=0, int families=KResolver::InternetFamily) |
bool | resolveAsync (QObject *userObj, const char *userSlot, const QString &host, const QString &service, int flags=0, int families=KResolver::InternetFamily) |
QCString | domainToAscii (const QString &unicodeDomain) |
QString | domainToUnicode (const QCString &asciiDomain) |
QString | domainToUnicode (const QString &asciiDomain) |
QString | normalizeDomain (const QString &domain) |
QStrList | protocolName (int protonum) |
QStrList | protocolName (const char *protoname) |
int | protocolNumber (const char *protoname) |
int | servicePort (const char *servname, const char *protoname) |
QStrList | serviceName (const char *servname, const char *protoname) |
QStrList | serviceName (int port, const char *protoname) |
Protected Member Functions | |
void | setError (int errorcode, int systemerror=0) |
virtual void | virtual_hook (int id, void *data) |
Friends | |
class | KResolverResults |
class | ::KNetwork::Internal::KResolverManager |
Detailed Description
Name and service resolution class.This class provides support for doing name-to-binary resolution for nodenames and service ports. You should use this class if you need specific resolution techniques when creating a socket or if you want to inspect the results before calling the socket functions.
You can either create an object and set the options you want in it or you can simply call the static member functions, which will create standard Resolver objects and dispatch the resolution for you. Normally, the static functions will be used, except in cases where specific options must be set.
A Resolver object defaults to the following:
- address family: any address family
- socket type: streaming socket
- protocol: implementation-defined. Generally, TCP
- host and service: unset
- Author:
- Thiago Macieira <thiago.macieira@kdemail.net>
Definition at line 295 of file kresolver.h.
Member Enumeration Documentation
|
Address family selection types. These values can be OR-ed together to form a composite family selection.
Definition at line 317 of file kresolver.h. |
|
Flags for the resolution. These flags are used for setting the resolution behaviour for this object:
Definition at line 350 of file kresolver.h. |
|
Error codes. These are the possible error values that objects of this class may return. See strError for getting a string representation for these errors.
Definition at line 380 of file kresolver.h. |
|
Status codes. These are the possible status for a Resolver object. A value greater than zero indicates normal behaviour, while negative values either indicate failure or error.
Note 2: the status Queued and InProgress might not be distinguishable. Some implementations might not differentiate one from the other. Definition at line 418 of file kresolver.h. |
Constructor & Destructor Documentation
|
Default constructor. Creates an empty Resolver object. You should set the wanted names and flags using the member functions before starting the name resolution. Definition at line 305 of file kresolver.cpp. Referenced by resolveAsync(). |
|
Constructor with host and service names. Creates a Resolver object with the given host and service names. Flags are initialised to 0 and any address family will be accepted.
Definition at line 311 of file kresolver.cpp. |
|
Destructor. When this object is deleted, it'll destroy all associated resources. If the resolution is still in progress, it will be cancelled and the signal will not be emitted. Definition at line 318 of file kresolver.cpp. References cancel(). |
Member Function Documentation
|
Retrieve the current status of this object.
Definition at line 325 of file kresolver.cpp. |
|
Retrieve the error code in this object. This function will return NoError if we are not in an error condition. See status and StatusCodes to find out what the current status is.
Definition at line 331 of file kresolver.cpp. Referenced by errorString(). |
|
Retrieve the associated system error code in this object. Many resolution operations may generate an extra error code as given by the C errno variable. That value is stored in the object and can be retrieved by this function. Definition at line 337 of file kresolver.cpp. Referenced by errorString(). |
|
Returns the textual representation of the error in this object.
Definition at line 491 of file kresolver.h. References error(), and systemError(). |
|
Returns true if this object is currently running.
Definition at line 343 of file kresolver.cpp. Referenced by KNetwork::KDatagramSocket::bind(), results(), setFamily(), setFlags(), setNodeName(), setProtocol(), setServiceName(), setSocketType(), start(), and wait(). |
|
The nodename to which the resolution was/is to be performed.
Definition at line 349 of file kresolver.cpp. Referenced by KNetwork::KDatagramSocket::connect(). |
|
The service name to which the resolution was/is to be performed.
Definition at line 355 of file kresolver.cpp. Referenced by KNetwork::KDatagramSocket::connect(). |
|
Sets the nodename for the resolution. Set the nodename to QString::null to unset it.
Definition at line 361 of file kresolver.cpp. References isRunning(). Referenced by KNetwork::KStreamSocket::bind(), KNetwork::KStreamSocket::connect(), KNetwork::KStreamSocket::KStreamSocket(), and setAddress(). |
|
Sets the service name to be resolved. Set it to QString::null to unset it.
Definition at line 373 of file kresolver.cpp. References isRunning(). Referenced by KNetwork::KStreamSocket::bind(), KNetwork::KStreamSocket::connect(), KNetwork::KStreamSocket::KStreamSocket(), and setAddress(). |
|
Sets both the host and the service names. Setting either value to QString::null will unset them.
Definition at line 385 of file kresolver.cpp. References setNodeName(), and setServiceName(). Referenced by KNetwork::KDatagramSocket::bind(), and KNetwork::KDatagramSocket::connect(). |
|
Retrieves the flags set for the resolution.
Definition at line 392 of file kresolver.cpp. |
|
Sets the flags.
Definition at line 398 of file kresolver.cpp. References isRunning(). Referenced by KNetwork::KDatagramSocket::KDatagramSocket(), resolve(), and resolveAsync(). |
|
Sets the allowed socket families.
Definition at line 410 of file kresolver.cpp. References isRunning(). Referenced by KNetwork::KDatagramSocket::KDatagramSocket(), KNetwork::KStreamSocket::KStreamSocket(), resolve(), and resolveAsync(). |
|
Sets the socket type we want.
The values for the
Definition at line 420 of file kresolver.cpp. References isRunning(). Referenced by KNetwork::KDatagramSocket::KDatagramSocket(). |
|
Sets the protocol we want. Protocols are dependant on the selected address family, so you should know what you are doing if you use this function. Besides, protocols generally are either stream-based or datagram-based, so the value of the socket type is also important. The resolution will fail if these values don't match. When using an Internet socket, the values for the protocol are the IPPROTO_* constants, defined in <netinet/in.h>. You may choose to set the protocol either by its number or by its name, or by both. If you set:
Definition at line 430 of file kresolver.cpp. References isRunning(), and protocolNumber(). |
|
Starts the name resolution asynchronously. This function will queue this object for resolution and will return immediately. The status upon exit will either be Queued or InProgress or Failed. This function does nothing if the object is already queued. But if it had already succeeded or failed, this function will re-start it. Note: if both the nodename and the servicename are unset, this function will not queue, but will set a success state and emit the signal. Also note that in this case and maybe others, the signal finished might be emitted before this function returns.
Definition at line 451 of file kresolver.cpp. References isRunning(). Referenced by resolve(), and resolveAsync(). |
|
Waits for a request to finish resolving. This function will wait on a running request for its termination. The status upon exit will either be Success or Failed or Canceled. This function may be called from any thread, even one that is not the GUI thread or the one that started the resolution process. But note this function is not thread-safe nor reentrant: i.e., only one thread can be waiting on one given object. Also note that this function ensures that the finished signal is emitted before it returns. That means that, as a side-effect, whenever wait() is called, the signal is emitted on the thread calling wait().
Definition at line 470 of file kresolver.cpp. References isRunning(). Referenced by KNetwork::KClientSocketBase::lookup(), and resolve(). |
|
Cancels a running request. This function will cancel a running request. If the request is not currently running or queued, this function does nothing. Note: if you tell the signal to be emitted, be aware that it might or might not be emitted before this function returns.
Definition at line 513 of file kresolver.cpp. Referenced by KNetwork::KDatagramSocket::bind(), and ~KResolver(). |
|
Retrieves the results of this resolution. Use this function to retrieve the results of the resolution. If no data was resolved (yet) or if we failed, this function will return an empty object.
Definition at line 521 of file kresolver.cpp. References isRunning(), KNetwork::KResolverResults::setAddress(), and KNetwork::KResolverResults::setError(). Referenced by resolve(). |
|
Handles events. Reimplemented from QObject. This function handles the events generated by the manager indicating that this object has finished processing. Do not post events to this object. Definition at line 533 of file kresolver.cpp. |
|
This signal is emitted whenever the resolution is finished, one way or another (success or failure).
The Note: if you are doing multiple resolutions, you can use the QObject::sender() function to distinguish one Resolver object from another.
Referenced by resolveAsync(). |
|
Returns the string representation of this error code.
Definition at line 557 of file kresolver.cpp. |
|
Resolve the nodename and service name synchronously. This static function is provided as convenience for simplifying name resolution. It resolves the given host and service names synchronously and returns the results it found. It is equivalent to the following code:
Definition at line 592 of file kresolver.cpp. References results(), setFamily(), setFlags(), start(), and wait(). Referenced by KExtendedSocket::lookup(). |
|
Start an asynchronous name resolution. This function is provided as a convenience to simplify the resolution process. It creates an internal KResolver object, connects the finished signal to the given slot and starts the resolution asynchronously. It is more or less equivalent to the following code: Note: this function may trigger the signal before it returns, so your code must be prepared for this situation.
You should use it like this in your code:
Definition at line 603 of file kresolver.cpp. References d, finished(), KResolver(), setFamily(), setFlags(), and start(). |
|
Returns the domain name in an ASCII Compatible Encoding form, suitable for DNS lookups. This is the base for International Domain Name support over the Internet. Note this function may fail, in which case it'll return a null QCString. Reasons for failure include use of unknown code points (Unicode characters). Note that the encoding is illegible and, thus, should not be presented to the user, except if requested.
Definition at line 901 of file kresolver.cpp. Referenced by normalizeDomain(). |
|
Does the inverse of domainToAscii and return an Unicode domain name from the given ACE-encoded domain. This function may fail if the given domain cannot be successfully converted back to Unicode. Reasons for failure include a malformed domain name or good ones whose reencoding back to ACE don't match the form given here (e.g., ACE-encoding of an already ASCII-compatible domain). It is, however, guaranteed that domains returned by domainToAscii will work.
Definition at line 939 of file kresolver.cpp. Referenced by normalizeDomain(). |
|
The same as above, but taking a QString argument.
Definition at line 945 of file kresolver.cpp. |
|
Normalise a domain name. In order to prevent simple mistakes in International Domain Names (IDN), it has been decided that certain code points (characters in Unicode) would be instead converted to others. This includes turning them all to lower case, as well certain other specific operations, as specified in the documents. For instance, the German 'ß' will be changed into 'ss', while the micro symbol 'µ' will be changed to the Greek mu 'μ'. Two equivalent domains have the same normalised form. And the normalised form of a normalised domain is itself (i.e., if d is normalised, the following is true: d == normalizeDomain(d) ) This operation is equivalent to encoding and the decoding a Unicode hostname.
Definition at line 985 of file kresolver.cpp. References domainToAscii(), and domainToUnicode(). |
|
Resolves a protocol number to its names. Note: the returned QStrList operates on deep-copies.
Definition at line 619 of file kresolver.cpp. |
|
Finds all aliases for a given protocol name.
Definition at line 665 of file kresolver.cpp. |
|
Resolves a protocol name to its number.
Definition at line 711 of file kresolver.cpp. Referenced by setProtocol(). |
|
Resolves a service name to its port number.
Definition at line 753 of file kresolver.cpp. |
|
Finds all the aliases for a given service name. Note: the returned QStrList operates on deep-copies.
Definition at line 795 of file kresolver.cpp. |
|
Resolves a port number to its names. Note: the returned QStrList operates on deep copies.
Definition at line 841 of file kresolver.cpp. |
|
Sets the error codes.
|
The documentation for this class was generated from the following files: