KDECore
KNetwork::KResolver Class Reference
Name and service resolution class. More...
#include <kresolver.h>
Public Types | |
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 | Flags { Passive = 0x01, CanonName = 0x02, NoResolve = 0x04, NoSrv = 0x08, Multiport = 0x10, UseSrv = 0x20 } |
enum | SocketFamilies { UnknownFamily = 0x0001, UnixFamily = 0x0002, LocalFamily = UnixFamily, IPv4Family = 0x0004, IPv6Family = 0x0008, InternetFamily = IPv4Family | IPv6Family, InetFamily = InternetFamily, KnownFamily = ~UnknownFamily, AnyFamily = KnownFamily | UnknownFamily } |
enum | StatusCodes { Idle = 0, Queued = 1, InProgress = 5, PostProcessing = 6, Success = 10, Failed = -101 } |
Signals | |
void | finished (KResolverResults results) |
Public Member Functions | |
void | cancel (bool emitSignal=true) |
int | error () const |
QString | errorString () const |
virtual bool | event (QEvent *) |
int | flags () const |
bool | isRunning () const |
KResolver (const QString &nodename, const QString &servicename=QString::null, QObject *=0L, const char *=0L) | |
KResolver (QObject *=0L, const char *=0L) | |
QString | nodeName () const |
KResolverResults | results () const |
QString | serviceName () const |
void | setAddress (const QString &node, const QString &service) |
void | setFamily (int families) |
int | setFlags (int flags) |
void | setNodeName (const QString &nodename) |
void | setProtocol (int protonum, const char *name=0L) |
void | setServiceName (const QString &service) |
void | setSocketType (int type) |
bool | start () |
int | status () const |
int | systemError () const |
bool | wait (int msec=0) |
virtual | ~KResolver () |
Static Public Member Functions | |
static QCString | domainToAscii (const QString &unicodeDomain) |
static QString | domainToUnicode (const QString &asciiDomain) |
static QString | domainToUnicode (const QCString &asciiDomain) |
static QString | errorString (int errorcode, int syserror=0) |
static QString | localHostName () |
static QString | normalizeDomain (const QString &domain) |
static QStrList | protocolName (const char *protoname) |
static QStrList | protocolName (int protonum) |
static int | protocolNumber (const char *protoname) |
static KResolverResults | resolve (const QString &host, const QString &service, int flags=0, int families=KResolver::InternetFamily) |
static bool | resolveAsync (QObject *userObj, const char *userSlot, const QString &host, const QString &service, int flags=0, int families=KResolver::InternetFamily) |
static QStrList | serviceName (int port, const char *protoname) |
static QStrList | serviceName (const char *servname, const char *protoname) |
static int | servicePort (const char *servname, const char *protoname) |
Protected Member Functions | |
void | setError (int errorcode, int systemerror=0) |
virtual void | virtual_hook (int id, void *data) |
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
Definition at line 295 of file kresolver.h.
Member Enumeration Documentation
Error codes.
These are the possible error values that objects of this class may return. See errorString() for getting a string representation for these errors.
- AddrFamily: Address family for the given nodename is not supported.
- TryAgain: Temporary failure in name resolution. You should try again.
- NonRecoverable: Non-recoverable failure in name resolution.
- BadFlags: Invalid flags were given.
- Memory: Memory allocation failure.
- NoName: The specified name or service doesn't exist.
- UnsupportedFamily: The requested socket family is not supported.
- UnsupportedService: The requested service is not supported for this socket type (i.e., a datagram service in a streaming socket).
- UnsupportedSocketType: The requested socket type is not supported.
- UnknownError: An unknown, unexpected error occurred.
- SystemError: A system error occurred. See systemError.
- Canceled: This request was cancelled by the user.
- Enumerator:
-
NoError AddrFamily TryAgain NonRecoverable BadFlags Memory NoName UnsupportedFamily UnsupportedService UnsupportedSocketType UnknownError SystemError Canceled
Definition at line 382 of file kresolver.h.
Flags for the resolution.
These flags are used for setting the resolution behaviour for this object:
- Passive: resolve to a passive socket (i.e., one that can be used for binding to a local interface)
- CanonName: request that the canonical name for the given nodename be found and recorded
- NoResolve: request that no external resolution be performed. The given nodename and servicename will be resolved locally only.
- NoSrv: don't try to use SRV-based name-resolution. (deprecated)
- UseSrv: use SRV-based name resolution.
- Multiport: the port/service argument is a list of port numbers and ranges. (future extension)
- Note:
- SRV-based lookup and Multiport are not implemented yet.
Definition at line 351 of file kresolver.h.
Address family selection types.
These values can be OR-ed together to form a composite family selection.
- UnknownFamily: a family that is unknown to the current implementation
- KnownFamily: a family that is known to the implementation (the exact opposite of UnknownFamily)
- AnyFamilies: any address family is acceptable
- InternetFamily: an address for connecting to the Internet
- InetFamily: alias for InternetFamily
- IPv6Family: an IPv6 address only
- IPv4Family: an IPv4 address only
- UnixFamily: an address for the local Unix namespace (i.e., Unix sockets)
- LocalFamily: alias for UnixFamily
- Enumerator:
-
UnknownFamily UnixFamily LocalFamily IPv4Family IPv6Family InternetFamily InetFamily KnownFamily AnyFamily
Definition at line 317 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.
- Idle: resolution has not yet been started.
- Queued: resolution is queued but not yet in progress.
- InProgress: resolution is in progress.
- PostProcessing: resolution is in progress.
- Success: resolution is done; you can retrieve the results.
- Canceled: request cancelled by the user.
- Failed: resolution is done, but failed.
Note 2: the status Queued and InProgress might not be distinguishable. Some implementations might not differentiate one from the other.
Definition at line 420 of file kresolver.h.
Constructor & Destructor Documentation
KResolver::KResolver | ( | QObject * | parent = 0L , |
|
const char * | name = 0L | |||
) |
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 292 of file kresolver.cpp.
KResolver::KResolver | ( | const QString & | nodename, | |
const QString & | servicename = QString::null , |
|||
QObject * | parent = 0L , |
|||
const char * | name = 0L | |||
) |
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.
- Parameters:
-
nodename The host name we want resolved. servicename The service name associated, like "http".
Definition at line 298 of file kresolver.cpp.
KResolver::~KResolver | ( | ) | [virtual] |
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 305 of file kresolver.cpp.
Member Function Documentation
void KResolver::cancel | ( | bool | emitSignal = true |
) |
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.
- Parameters:
-
emitSignal whether to emit the finished signal or not
Definition at line 508 of file kresolver.cpp.
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.
- Parameters:
-
unicodeDomain the domain name to be encoded
- Returns:
- the ACE-encoded suitable for DNS queries if successful, a null QCString if failure.
Definition at line 950 of file kresolver.cpp.
The same as above, but taking a QString argument.
- Parameters:
-
asciiDomain the ACE-encoded domain name to be decoded
- Returns:
- the Unicode representation of the given domain name if successful, QString::null if not.
Definition at line 994 of file kresolver.cpp.
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.
- Parameters:
-
asciiDomain the ACE-encoded domain name to be decoded
- Returns:
- the Unicode representation of the given domain name if successful, the original string if not
- Note:
- ACE = ASCII-Compatible Encoding, i.e., 7-bit
Definition at line 988 of file kresolver.cpp.
int KResolver::error | ( | ) | const |
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.
- See also:
- errorString for getting a textual representation of this error
Definition at line 318 of file kresolver.cpp.
QString KResolver::errorString | ( | int | errorcode, | |
int | syserror = 0 | |||
) | [static] |
Returns the string representation of this error code.
- Parameters:
-
errorcode the error code. See ErrorCodes. syserror the system error code associated.
- Returns:
- the string representation. This is already i18n'ed.
Definition at line 552 of file kresolver.cpp.
QString KNetwork::KResolver::errorString | ( | ) | const [inline] |
Returns the textual representation of the error in this object.
Definition at line 493 of file kresolver.h.
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.
Reimplemented from QObject.
Definition at line 528 of file kresolver.cpp.
void KNetwork::KResolver::finished | ( | KResolverResults | results | ) | [signal] |
This signal is emitted whenever the resolution is finished, one way or another (success or failure).
The results
parameter will contain the resolved data.
Note: if you are doing multiple resolutions, you can use the QObject::sender() function to distinguish one Resolver object from another.
- Parameters:
-
results the resolved data; might be empty if the resolution failed
- Note:
- This signal is always delivered in the GUI event thread, even for resolutions that were started in secondary threads.
int KResolver::flags | ( | ) | const |
bool KResolver::isRunning | ( | ) | const |
QString KResolver::localHostName | ( | ) | [static] |
Returns this machine's local hostname.
- Returns:
- this machine's local hostname
- Since:
- 3.5
Definition at line 884 of file kresolver.cpp.
QString KResolver::nodeName | ( | ) | const |
The nodename to which the resolution was/is to be performed.
Definition at line 336 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.
- Parameters:
-
domain a domain to be normalised
- Returns:
- the normalised domain, or QString::null if the domain is invalid.
Definition at line 1034 of file kresolver.cpp.
QStrList KResolver::protocolName | ( | const char * | protoname | ) | [static] |
Finds all aliases for a given protocol name.
- Parameters:
-
protoname the protocol name to be looked for
- Returns:
- all the protocol names in a list. The first is the "proper" name.
Definition at line 657 of file kresolver.cpp.
QStrList KResolver::protocolName | ( | int | protonum | ) | [static] |
Resolves a protocol number to its names.
Note: the returned QStrList operates on deep-copies.
- Parameters:
-
protonum the protocol number to be looked for
- Returns:
- all the protocol names in a list. The first is the "proper" name.
Definition at line 610 of file kresolver.cpp.
int KResolver::protocolNumber | ( | const char * | protoname | ) | [static] |
Resolves a protocol name to its number.
- Parameters:
-
protoname the protocol name to be looked for
- Returns:
- the protocol number or -1 if we couldn't locate it
Definition at line 704 of file kresolver.cpp.
KResolverResults KResolver::resolve | ( | const QString & | host, | |
const QString & | service, | |||
int | flags = 0 , |
|||
int | families = KResolver::InternetFamily | |||
) | [static] |
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:
KResolver qres(host, service); qres.setFlags(flags); qres.setFamily(families) qres.start(); qres.wait(); return qres.results();
- Parameters:
-
host the nodename to resolve service the service to resolve flags flags to be used families the families to be searched
- Returns:
- a KResolverResults object containing the results
- See also:
- KResolverResults for information on how to obtain the error code
Definition at line 587 of file kresolver.cpp.
bool KResolver::resolveAsync | ( | QObject * | userObj, | |
const char * | userSlot, | |||
const QString & | host, | |||
const QString & | service, | |||
int | flags = 0 , |
|||
int | families = KResolver::InternetFamily | |||
) | [static] |
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.
KResolver* qres = new KResolver(host, service); QObject::connect(qres, SIGNAL(finished(KResolverResults)), userObj, userSlot); qres->setFlags(flags); qres->setFamily(families); return qres->start();
You should use it like this in your code:
KResolver::resolveAsync(myObj, SLOT(mySlot(KResolverResults)), host, service);
- Parameters:
-
userObj the object whose slot userSlot
we will connectuserSlot the slot to which we'll connect host the nodename to resolve service the service to resolve flags flags to be used families families to be searcheed
- Returns:
- true if the queueing was successful, false if not
- See also:
- KResolverResults for information on how to obtain the error code
Definition at line 598 of file kresolver.cpp.
KResolverResults KResolver::results | ( | ) | const |
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.
- Returns:
- the resolved data
- See also:
- status for information on finding out if the resolution was successful
Definition at line 516 of file kresolver.cpp.
QStrList KResolver::serviceName | ( | int | port, | |
const char * | protoname | |||
) | [static] |
Resolves a port number to its names.
Note: the returned QStrList operates on deep copies.
- Parameters:
-
port the port number, in host byte-order protoname the protocol it is associated with
- Returns:
- all the service names in a list. The first is the "proper" name.
Definition at line 837 of file kresolver.cpp.
QStrList KResolver::serviceName | ( | const char * | servname, | |
const char * | protoname | |||
) | [static] |
Finds all the aliases for a given service name.
Note: the returned QStrList operates on deep-copies.
- Parameters:
-
servname the service alias to be looked for protoname the protocol it is associated with
- Returns:
- all the service names in a list. The first is the "proper" name.
Definition at line 790 of file kresolver.cpp.
QString KResolver::serviceName | ( | ) | const |
The service name to which the resolution was/is to be performed.
Definition at line 342 of file kresolver.cpp.
int KResolver::servicePort | ( | const char * | servname, | |
const char * | protoname | |||
) | [static] |
Resolves a service name to its port number.
- Parameters:
-
servname the service name to be looked for protoname the protocol it is associated with
- Returns:
- the port number in host byte-order or -1 in case of error
Definition at line 747 of file kresolver.cpp.
Sets both the host and the service names.
Setting either value to QString::null will unset them.
- Parameters:
-
node The nodename service The service name
Definition at line 372 of file kresolver.cpp.
void KNetwork::KResolver::setError | ( | int | errorcode, | |
int | systemerror = 0 | |||
) | [protected] |
Sets the error codes.
void KResolver::setFamily | ( | int | families | ) |
Sets the allowed socket families.
- Parameters:
-
families the families that we want/accept
- See also:
- SocketFamilies for possible values
Definition at line 397 of file kresolver.cpp.
int KResolver::setFlags | ( | int | flags | ) |
Sets the flags.
- Parameters:
-
flags the new flags
- Returns:
- the old flags
Definition at line 385 of file kresolver.cpp.
void KResolver::setNodeName | ( | const QString & | nodename | ) |
Sets the nodename for the resolution.
Set the nodename to QString::null to unset it.
- Parameters:
-
nodename The nodename to be resolved.
Definition at line 348 of file kresolver.cpp.
void KResolver::setProtocol | ( | int | protonum, | |
const char * | name = 0L | |||
) |
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:
- the number and the name: both values will be stored internally; you may set the name to an empty value, if wanted
- the number only (name = NULL): the name will be searched in the protocols database
- the name only (number = 0): the number will be searched in the database
- neither name nor number: reset to default behaviour
- Parameters:
-
protonum the protocol number we want name the protocol name
Definition at line 417 of file kresolver.cpp.
void KResolver::setServiceName | ( | const QString & | service | ) |
Sets the service name to be resolved.
Set it to QString::null to unset it.
- Parameters:
-
service The service to be resolved.
Definition at line 360 of file kresolver.cpp.
void KResolver::setSocketType | ( | int | type | ) |
Sets the socket type we want.
The values for the type
parameter are the SOCK_* constants, defined in <sys/socket.h>. The most common values are:
- SOCK_STREAM streaming socket (= reliable, sequenced, connection-based)
- SOCK_DGRAM datagram socket (= unreliable, connectionless)
- SOCK_RAW raw socket, with direct access to the container protocol (such as IP)
- Parameters:
-
type the wanted socket type (SOCK_* constants). Set 0 to use the default.
Definition at line 407 of file kresolver.cpp.
bool KResolver::start | ( | ) |
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.
- Returns:
- true if this request was successfully queued for asynchronous resolution
Definition at line 438 of file kresolver.cpp.
int KResolver::status | ( | ) | const |
Retrieve the current status of this object.
- See also:
- StatusCodes for the possible status codes.
Definition at line 312 of file kresolver.cpp.
int KResolver::systemError | ( | ) | const |
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 324 of file kresolver.cpp.
void KResolver::virtual_hook | ( | int | id, | |
void * | data | |||
) | [protected, virtual] |
Definition at line 1039 of file kresolver.cpp.
bool KResolver::wait | ( | int | msec = 0 |
) |
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().
- Parameters:
-
msec the time to wait, in milliseconds or 0 to wait forever
- Returns:
- true if the resolution has finished processing, even when it failed or was canceled. False means the wait timed out and the resolution is still running.
Definition at line 457 of file kresolver.cpp.
The documentation for this class was generated from the following files: