kresolver.h

来自「konqueror3 embedded版本, KDE环境下的当家浏览器的嵌入式版」· C头文件 代码 · 共 946 行 · 第 1/2 页

   * find out what the current status is.
   *
   * @see errorString for getting a textual representation of
   * this error
   */
  int error() 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.
   */
  int systemError() const;

  /**
   * Returns the textual representation of the error in this object.
   */
  inline QString errorString() const
  { return errorString(error(), systemError()); }

  /**
   * Returns true if this object is currently running
   */
  bool isRunning() const;

  /**
   * The nodename to which the resolution was/is to be performed.
   */
  QString nodeName() const;

  /**
   * The service name to which the resolution was/is to be performed.
   */
  QString serviceName() const;

  /**
   * Sets the nodename for the resolution.
   *
   * Set the nodename to QString::null to unset it.
   * @param nodename		The nodename to be resolved.
   */
  void setNodeName(const QString& nodename);

  /**
   * Sets the service name to be resolved.
   *
   * Set it to QString::null to unset it.
   * @param service		The service to be resolved.
   */
  void setServiceName(const QString& service);

  /**
   * Sets both the host and the service names.
   *
   * Setting either value to QString::null will unset them.
   * @param node		The nodename
   * @param service		The service name
   */
  void setAddress(const QString& node, const QString& service);

  /**
   * Retrieves the flags set for the resolution.
   *
   * @see Flags for an explanation on what flags are possible
   */
  int flags() const;

  /**
   * Sets the flags.
   *
   * @param flags		the new flags
   * @return			the old flags
   * @see Flags for an explanation on the flags
   */
  int setFlags(int flags);

  /**
   * Sets the allowed socket families.
   *
   * @param families		the families that we want/accept
   * @see SocketFamilies for possible values
   */
  void setFamily(int families);

  /**
   * Sets the socket type we want.
   *
   * The values for the @p type parameter are the SOCK_*
   * constants, defined in <sys/socket.h>. The most common
   * values are:
   *  @li SOCK_STREAM		streaming socket (= reliable, sequenced,
   *				connection-based)
   *  @li SOCK_DGRAM		datagram socket (= unreliable, connectionless)
   *  @li SOCK_RAW		raw socket, with direct access to the
   *				container protocol (such as IP)
   *
   * These three are the only values to which it is guaranteed that
   * resolution will work. Some systems may define other constants (such as
   * SOCK_RDM for reliable datagrams), but support is implementation-defined.
   * 
   * @param type		the wanted socket type (SOCK_* constants). Set
   *				0 to use the default.
   */
  void setSocketType(int type);

  /**
   * 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:
   * @li the number and the name: both values will be stored internally; you
   *		may set the name to an empty value, if wanted
   * @li the number only (name = NULL): the name will be searched in the 
   *		protocols database
   * @li the name only (number = 0): the number will be searched in the
   *		database
   * @li neither name nor number: reset to default behaviour
   *
   * @param protonum		the protocol number we want
   * @param name		the protocol name
   */
  void setProtocol(int protonum, const char *name = 0L);

  /**
   * 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 @ref finished might
   * be emitted before this function returns.
   *
   * @return true if this request was successfully queued for asynchronous
   *		resolution
   */
  bool start();

  /**
   * 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 @ref 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().
   *
   * @param msec		the time to wait, in milliseconds or 0 to
   *				wait forever
   * @return 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.
   */
  bool wait(int msec = 0);

  /**
   * 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.
   *
   * @param emitSignal	whether to emit the @ref finished signal or not
   */
  void cancel(bool emitSignal = true);

  /**
   * 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.
   *
   * @return the resolved data
   * @see status for information on finding out if the resolution was successful
   */
  KResolverResults results() const;

  /**
   * 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.
   */
  virtual bool event(QEvent*);

signals:
  // signals

  /**
   * This signal is emitted whenever the resolution is finished, one
   * way or another (success or failure). The @p 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.
   *
   * @param results		the resolved data; might be empty if the resolution
   *			failed
   * @see results for information on what the results are
   *
   * @note This signal is @b always delivered in the GUI event thread, even for
   *       resolutions that were started in secondary threads.
   */
  void finished(KResolverResults results);

private:
  void emitFinished();

public:
  // Static functions

  /**
   * Returns the string representation of this error code.
   *
   * @param errorcode	the error code. See @ref ErrorCodes.
   * @param syserror	the system error code associated.
   * @return		the string representation. This is already
   *			i18n'ed.
   */
  static QString errorString(int errorcode, int syserror = 0);

  /**
   * 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:
   *
   * \code
   *   KResolver qres(host, service);
   *   qres.setFlags(flags);
   *   qres.setFamily(families)
   *   qres.start();
   *   qres.wait();
   *   return qres.results();
   * \endcode
   *
   * @param host		the nodename to resolve
   * @param service		the service to resolve
   * @param flags		flags to be used
   * @param families		the families to be searched
   * @return a KResolverResults object containing the results
   * @see KResolverResults for information on how to obtain the error code
   */
  static KResolverResults resolve(const QString& host, const QString& service,
				 int flags = 0, int families = KResolver::InternetFamily);

  /**
   * 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
   * @ref finished signal to the given slot and starts the resolution
   * asynchronously. It is more or less equivalent to the following code:
   *
   * \b Note: this function may trigger the signal before it returns, so
   * your code must be prepared for this situation.
   *
   * \code
   *   KResolver* qres = new KResolver(host, service);
   *   QObject::connect(qres, SIGNAL(finished(KResolverResults)),
   *			  userObj, userSlot);
   *   qres->setFlags(flags);
   *   qres->setFamily(families);
   *   return qres->start();
   * \endcode
   *
   * You should use it like this in your code:
   * \code
   *   KResolver::resolveAsync(myObj, SLOT(mySlot(KResolverResults)), host, service);
   * \endcode
   *
   * @param userObj		the object whose slot @p userSlot we will connect
   * @param userSlot		the slot to which we'll connect
   * @param host		the nodename to resolve
   * @param service		the service to resolve
   * @param flags		flags to be used
   * @param families		families to be searcheed
   * @return true if the queueing was successful, false if not
   * @see KResolverResults for information on how to obtain the error code
   */
  static bool resolveAsync(QObject* userObj, const char *userSlot,
			   const QString& host, const QString& service,
			   int flags = 0, int families = KResolver::InternetFamily);

  /**
   * 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.
   *
   * @param unicodeDomain	the domain name to be encoded
   * @return the ACE-encoded suitable for DNS queries if successful, a null
   *	     QCString if failure.
   */
  static QCString domainToAscii(const QString& unicodeDomain);

  /**
   * Does the inverse of @ref 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 @ref domainToAscii will work.
   *
   * @param asciiDomain	the ACE-encoded domain name to be decoded
   * @return the Unicode representation of the given domain name
   * if successful, the original string if not
   * @note ACE = ASCII-Compatible Encoding, i.e., 7-bit
   */
  static QString domainToUnicode(const QCString& asciiDomain);

  /**
   * The same as above, but taking a QString argument.
   *
   * @param asciiDomain	the ACE-encoded domain name to be decoded
   * @return the Unicode representation of the given domain name
   * if successful, QString::null if not.
   */
  static QString domainToUnicode(const QString& asciiDomain);

  /**
   * 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.
   *
   * @param domain		a domain to be normalised
   * @return the normalised domain, or QString::null if the domain is
   * invalid.
   */
  static QString normalizeDomain(const QString& domain);

  /**
   * Resolves a protocol number to its names
   *
   * Note: the returned QStrList operates on deep-copies.
   *
   * @param protonum	the protocol number to be looked for
   * @return all the protocol names in a list. The first is the "proper"
   *		name.
   */
  static QStrList protocolName(int protonum);

  /**
   * Finds all aliases for a given protocol name
   *
   * @param protoname	the protocol name to be looked for
   * @return all the protocol names in a list. The first is the "proper"
   *		name.
   */
  static QStrList protocolName(const char *protoname);

  /**
   * Resolves a protocol name to its number
   *
   * @param protoname	the protocol name to be looked for
   * @return the protocol number or -1 if we couldn't locate it
   */
  static int protocolNumber(const char *protoname);

  /**
   * Resolves a service name to its port number
   *
   * @param servname		the service name to be looked for
   * @param protoname		the protocol it is associated with
   * @return the port number in host byte-order or -1 in case of error
   */
  static int servicePort(const char *servname, const char *protoname);

  /**
   * Finds all the aliases for a given service name
   *
   * Note: the returned QStrList operates on deep-copies.
   *
   * @param servname		the service alias to be looked for
   * @param protoname		the protocol it is associated with
   * @return all the service names in a list. The first is the "proper"
   *		name.
   */
  static QStrList serviceName(const char *servname, const char *protoname);

  /**
   * Resolves a port number to its names
   *
   * Note: the returned QStrList operates on deep copies.
   *
   * @param port		the port number, in host byte-order
   * @param protoname		the protocol it is associated with
   * @return all the service names in a list. The first is the "proper"
   *		name.
   */
  static QStrList serviceName(int port, const char *protoname);

  /**
   * Returns this machine's local hostname.
   *
   * @return this machine's local hostname
   * @since 3.5
   */
  static QString localHostName();

protected:

  /**
   * Sets the error codes
   */
  void setError(int errorcode, int systemerror = 0);

  virtual void virtual_hook( int id, void* data );
private:
  KResolverPrivate* d;
  friend class KResolverResults;
  friend class ::KNetwork::Internal::KResolverManager;
  
  static QStringList *idnDomains;
};

}				// namespace KNetwork

#endif