ksocketaddress.h

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

  KSocketAddress& operator =(const KSocketAddress& other);

  /**
   * Returns the socket address structure, to be passed down to
   * low level functions.
   *
   * Note that this function returns NULL for invalid or empty sockets,
   * so you may use to to test for validity.
   */
  const sockaddr* address() const;

  /**
   * Returns the socket address structure, to be passed down to
   * low level functions.
   *
   * Note that this function returns NULL for invalid or empty sockets,
   * so you may use to to test for validity.
   *
   * The returned value, if not NULL, is an internal buffer which is guaranteed
   * to be at least @ref length() bytes long.
   */
  sockaddr* address();

  /**
   * Sets the address to the given address.
   * The raw socket address is copied into this object.
   *
   * @param sa		the socket address structure
   * @param len		the socket address length
   */
  KSocketAddress& setAddress(const sockaddr *sa, Q_UINT16 len);

  /**
   * Returns the socket address structure, to be passed down to
   * low level functions.
   */
  inline operator const sockaddr*() const
  { return address(); }

  /**
   * Returns the length of this socket address structure.
   */
  Q_UINT16 length() const;

  /**
   * Sets the length of this socket structure.
   *
   * Use this function with care. It allows you to resize the internal
   * buffer to fit needs. This function should not be used except for handling
   * unknown socket address structures.
   *
   * Also note that this function may invalidate the socket if a known
   * family is set (Internet or Unix socket) and the new length would be
   * too small to hold the system's sockaddr_* structure. If unsure, reset
   * the family:
   *
   * \code
   *   KSocketAddress qsa;
   *   [...]
   *   qsa.setFamily(AF_UNSPEC).setLength(newlen);
   * \endcode
   *
   * @param len		the new length
   */
  KSocketAddress& setLength(Q_UINT16 len);

  /**
   * Returns the family of this address.
   * @return the family of this address, AF_UNSPEC if it's undefined
   */
  int family() const;

  /**
   * Sets the family of this object.
   *
   * Note: setting the family will probably invalidate any address data
   * contained in this object. Use this function with care.
   *
   * @param family	the new family to set
   */
  virtual KSocketAddress& setFamily(int family);

  /**
   * Returns the IANA family number of this address.
   * @return the IANA family number of this address (1 for AF_INET.
   *         2 for AF_INET6, otherwise 0)
   */
  inline int ianaFamily() const
  { return ianaFamily(family()); }
  
  /**
   * Returns true if this equals the other socket.
   *
   * Socket addresses are considered matching if and only if all data is the same.
   *
   * @param other	the other socket
   * @return true if both sockets are equal
   */
  bool operator ==(const KSocketAddress& other) const;

  /**
   * Returns the node name of this socket.
   *
   * In the case of Internet sockets, this is string representation of the IP address.
   * The default implementation returns QString::null.
   *
   * @return the node name, can be QString::null
   * @bug use KResolver to resolve unknown families
   */
  virtual QString nodeName() const;

  /**
   * Returns the service name for this socket.
   *
   * In the case of Internet sockets, this is the port number.
   * The default implementation returns QString::null.
   *
   * @return the service name, can be QString::null
   * @bug use KResolver to resolve unknown families
   */
  virtual QString serviceName() const;

  /**
   * Returns this socket address as a string suitable for
   * printing. Family, node and service are part of this address.
   *
   * @bug use KResolver to resolve unknown families
   */
  virtual QString toString() const;

  /**
   * Returns an object reference that can be used to manipulate this socket
   * as an Internet socket address. Both objects share the same data.
   */
  KInetSocketAddress& asInet();

  /**
   * Returns an object is equal to this object's data, but they don't share it.
   */
  KInetSocketAddress asInet() const;

  /**
   * Returns an object reference that can be used to manipulate this socket
   * as a Unix socket address. Both objects share the same data.
   */
  KUnixSocketAddress& asUnix();

  /**
   * Returns an object is equal to this object's data, but they don't share it.
   */
  KUnixSocketAddress asUnix() const;

protected:
  /// @internal
  /// private data
  KSocketAddressData *d;

  /// @internal
  /// extra constructor
  KSocketAddress(KSocketAddressData* d);

public:				// static
  /**
   * Returns the IANA family number of the given address family.
   * Returns 0 if there is no corresponding IANA family number.
   * @param af		the address family, in AF_* constants
   * @return the IANA family number of this address (1 for AF_INET.
   *         2 for AF_INET6, otherwise 0)
   */
  static int ianaFamily(int af);

  /**
   * Returns the address family of the given IANA family number.
   * @return the address family, AF_UNSPEC for unknown IANA family numbers
   */
  static int fromIanaFamily(int iana);
};


/** @class KInetSocketAddress ksocketaddress.h ksocketaddress.h
 *  @brief an Internet socket address
 *
 * An Inet (IPv4 or IPv6) socket address
 *
 * This is an IPv4 or IPv6 address of the Internet.
 *
 * @author Thiago Macieira <[e-mail]>
 */
class KDECORE_EXPORT KInetSocketAddress: public KSocketAddress
{
  friend class KSocketAddress;
public:
  /**
   * Public constructor. Creates an empty object.
   */
  KInetSocketAddress();

  /**
   * Creates an object from raw data.
   *
   * Note: if the socket address @p sa does not contain a valid Internet
   * socket (IPv4 or IPv6), this object will be empty.
   *
   * @param sa		the sockaddr structure
   * @param len		the structure's length
   */
  KInetSocketAddress(const sockaddr* sa, Q_UINT16 len);

  /**
   * Creates an object from an IP address and port.
   *
   * @param host	the IP address
   * @param port	the port number
   */
  KInetSocketAddress(const KIpAddress& host, Q_UINT16 port);

  /**
   * Copy constructor.
   *
   * Data is not shared.
   *
   * @param other	the other object
   */
  KInetSocketAddress(const KInetSocketAddress& other);

  /**
   * Copy constructor.
   *
   * If the other, generic socket address contains an Internet address,
   * it will be copied. Otherwise, this object will be empty.
   *
   * @param other	the other object
   */
  KInetSocketAddress(const KSocketAddress& other);

  /**
   * Destroys this object.
   */
  virtual ~KInetSocketAddress();

  /**
   * Copy operator.
   *
   * Copies the other object into this one.
   *
   * @param other	the other object
   */
  KInetSocketAddress& operator =(const KInetSocketAddress& other);

  /**
   * Cast operator to sockaddr_in.
   */
  inline operator const sockaddr_in*() const
  { return (const sockaddr_in*)address(); }

  /**
   * Cast operator to sockaddr_in6.
   */
  inline operator const sockaddr_in6*() const
  { return (const sockaddr_in6*)address(); }

  /**
   * Returns the IP version of the address this object holds.
   *
   * @return 4 or 6, if IPv4 or IPv6, respectively; 0 if this object is empty
   */
  int ipVersion() const;

  /**
   * Returns the IP address component.
   */
  KIpAddress ipAddress() const;

  /**
   * Sets the IP address to the given raw address.
   *
   * This call will preserve port numbers accross IP versions, but will lose
   * IPv6 specific data if the address is set to IPv4.
   *
   * @param addr	the address to set to
   * @return a reference to itself
   */
  KInetSocketAddress& setHost(const KIpAddress& addr);

  /**
   * Retrieves the port number stored in this object.
   *
   * @return a port number in the range 0 to 65535, inclusive. An empty or 
   * invalid object will have a port number of 0.
   */
  Q_UINT16 port() const;

  /**
   * Sets the port number. If this object is empty, this function will default to
   * creating an IPv4 address.
   *
   * @param port	the port number to set
   * @return a reference to itself
   */
  KInetSocketAddress& setPort(Q_UINT16 port);

  /**
   * Converts this object to an IPv4 socket address. It has no effect if the object
   * is already an IPv4 socket address.
   *
   * If this object is an IPv6 address, the port number is preserved. All other information
   * is lost.
   *
   * @return a reference to itself
   */
  KInetSocketAddress& makeIPv4();

  /**
   * Converts this object to an IPv6 socket address. It has no effect if the object
   * is already an IPv6 socket address.
   *
   * If this object is an IPv4 address, the port number is preserved.
   *
   * @return a reference to itself
   */
  KInetSocketAddress& makeIPv6();

  /**
   * Returns the flowinfo information from the IPv6 socket address.
   *
   * @return the flowinfo information or 0 if this object is empty or IPv4
   */
  Q_UINT32 flowinfo() const;

  /**
   * Sets the flowinfo information for an IPv6 socket address. If this is not
   * an IPv6 socket address, this function converts it to one. See makeIPv6.
   *
   * @param flowinfo		the flowinfo to set
   * @return a reference to itself
   */
  KInetSocketAddress& setFlowinfo(Q_UINT32 flowinfo);

  /**
   * Returns the scope id this IPv6 socket is bound to.
   *
   * @return the scope id, or 0 if this is not an IPv6 object
   */
  int scopeId() const;

  /**
   * Sets the scope id for this IPv6 object. If this is not an IPv6 socket
   * address, this function converts it to one. See makeIPv6
   *
   * @param scopeid		the scopeid to set
   * @return a reference to itself
   */
  KInetSocketAddress& setScopeId(int scopeid);

protected:
  /// @internal
  /// extra constructor
  KInetSocketAddress(KSocketAddressData* d);

private:
  void update();
};

/*
 * External definition
 */

/** @class KUnixSocketAddress ksocketaddress.h ksocketaddress.h
 *  @brief A Unix (local) socket address.
 *
 * This is a Unix socket address.
 *
 * Note that this class uses QStrings to represent filenames, which means
 * the proper encoding is used to translate into valid filesystem file names.
 *
 * @author Thiago Macieira <[e-mail]>
 */
class KDECORE_EXPORT KUnixSocketAddress: public KSocketAddress
{
  friend class KSocketAddress;
public:
  /**
   * Default constructor. Creates an empty object.
   */
  KUnixSocketAddress();

  /**
   * Creates this object with the given raw data. If
   * the sockaddr structure does not contain a Local namespace
   * (Unix) socket, this object will be created empty.
   *
   * @param sa		the socket address structure
   * @param len		the structure's length
   */
  KUnixSocketAddress(const sockaddr* sa, Q_UINT16 len);

  /**
   * Copy constructor. Creates a copy of the other object,
   * sharing the data explicitly.
   *
   * @param other	the other object
   */
  KUnixSocketAddress(const KUnixSocketAddress& other);

  /**
   * Constructs an object from the given pathname.
   */
  KUnixSocketAddress(const QString& pathname);

  /**
   * Destructor.
   */
  virtual ~KUnixSocketAddress();

  /**
   * Copy operator. Copies the contents of the other object into
   * this one. Data is explicitly shared.
   *
   * @param other		the other
   */
  KUnixSocketAddress& operator =(const KUnixSocketAddress& other);

  /**
   * Cast operator to sockaddr_un.
   */
  inline operator const sockaddr_un*() const
  { return (const sockaddr_un*)address(); }

  /**
   * Returns the pathname associated with this object. Will return
   * QString::null if this object is empty.
   */
  QString pathname() const;

  /**
   * Sets the pathname for the object.
   *
   * @return a reference to itself
   */
  KUnixSocketAddress& setPathname(const QString& path);

protected:
  /// @internal
  /// extra constructor
  KUnixSocketAddress(KSocketAddressData* d);
};

}				// namespace KNetwork

#endif