yate学习--yateclass.h--class YATE_API SocketAddr : public GenObject

请声明出处：

SocketAddr，一个封装了IPv4和IPv6的网络地址类：

/**
 * Wrapper class to keep a socket address
 * 封装一个类用于保持套接字的地址
 * @short A socket address holder
 * @一个短的套接字持有者
 */
class YATE_API SocketAddr : public GenObject
{
public:
    /**
     * Known address families
     * 已知的地址簇
     */
    enum Family {
	Unknown = AF_UNSPEC,
	IPv4 = AF_INET,
	AfMax = AF_MAX,
	AfUnsupported = AfMax,
#ifdef AF_INET6
	IPv6 = AF_INET6,
#else
	IPv6 = AfUnsupported + 1,
#endif
#ifdef HAS_AF_UNIX
	Unix = AF_UNIX,
#else
	Unix = AfUnsupported + 2,
#endif
    };

    /**
     * Default constructor of an empty address
     * 默认构造函数的一个空的地址
     */
    inline SocketAddr()
	: m_address(0), m_length(0)
	{ }

    /**
     * Copy constructor
     * 拷贝的构造函数
     * @param value Address to copy
     * @参数value，要拷贝的地址
     */
    inline SocketAddr(const SocketAddr& value)
	: GenObject(),
	  m_address(0), m_length(0)
	{ assign(value.address(),value.length()); }

    /**
     * Constructor of a null address
     * 一个空地址的构造函数
     * @param family Family of the address to create
     * @参数family，创建一个地址族为Family 的地址
     */
    explicit SocketAddr(int family);

    /**
     * Constructor that stores a copy of an address
     * 存储地址的副本的构造函数
     * @param addr Pointer to the address to store
     * @参数addr,存储地址的指针
     * @param len Length of the stored address, zero to use default
     * @参数len,存储地址的长度，默认使用0
     */
    SocketAddr(const struct sockaddr* addr, socklen_t len = 0);

    /**
     * Destructor that frees and zeroes out everything
     * 析构函数释放和清零一切
     */
    virtual ~SocketAddr();

    /**
     * Assignment operator
     * 赋值运算符(=)重载
     * @param value Address to copy
     * @参数value，要拷贝的地址
     */
    inline SocketAddr& operator=(const SocketAddr& value)
	{ assign(value.address(),value.length()); return *this; }

    /**
     * Equality comparation operator
     * 相等比较操作符(==)重载
     * @param other Address to compare to
     * @参数other，要比较的地址
     * @return True if the addresses are equal
     * @返回True,如果地址是相等的
     */
    bool operator==(const SocketAddr& other) const;

    /**
     * Inequality comparation operator
     * 不相等比较操作符(==)重载
     * @param other Address to compare to
     * @参数other，要比较的地址
     * @return True if the addresses are different
     * @返回True,如果地址是不相等的
     */
    inline bool operator!=(const SocketAddr& other) const
	{ return !operator==(other); }

    /**
     * Clears up the address, frees the memory
     * 消除了地址,释放内存
     */
    void clear();

    /**
     * Assigns an empty address of a specific type
     * 分配一个特定类型的空地址
     * @param family Family of the address to create
     * @参数family，创建一个地址族为Family 的地址
     * @return True if the address family is supported
     * @返回True,如果地址family 被支持
     */
    bool assign(int family);

    /**
     * Assigns a new address
     * 分配一个新地址
     * @param addr Pointer to the address to store
     * @参数addr，存储地址的指针
     * @param len Length of the stored address, zero to use default
     * @参数len，存储地址的长度，默认使用0
     */
    void assign(const struct sockaddr* addr, socklen_t len = 0);

    /**
     * Attempt to guess a local address that will be used to reach a remote one
     * 试图去猜测为本地地址，这个地址用于到达远程
     * @param remote Remote address to reach
     * @参数remote，远程地址到达
     * @return True if guessed an address, false if failed
     * @返回True,如果猜到了一个地址,假如果失败了
     */
    bool local(const SocketAddr& remote);

    /**
     * Check if a non-null address is held
     * 检查是否非空地址
     * @return True if a valid address is held, false if null
     * @返回True,如果一个有效的地址，返回false，如果是空
     */
    inline bool valid() const
	{ return m_length && m_address; }

    /**
     * Check if a null address is held
     * 检查是空地址
     * @return True if a null address is held
     * @返回True，如果是一个空地址
     */
    inline bool null() const
	{ return !(m_length && m_address); }

    /**
     * Get the family of the stored address
     * 从存储的地址获取地址族family
     * @return Address family of the stored address or zero (AF_UNSPEC)
     * @返回存储的地址族family或者是0(AF_UNSPEC)
     */
    inline int family() const
	{ return m_address ? m_address->sa_family : 0; }

    /**
     * Retrieve address family name
     * 重新获得地址族family的名字
     * @return Address family name
     * @返回地址族family的名字
     */
    inline const char* familyName()
	{ return lookupFamily(family()); }

    /**
     * Retrieve the sin6_scope_id value of an IPv6 address
     * 重新获取一个IPv6 地址sin6_scope_id 的值
     * @return The requested value (it may be 0), 0 if not available
     * @返回被请求的值，为0 如果不可用
     */
    inline unsigned int scopeId() const
	{ return scopeId(address()); }

    /**
     * Set the sin6_scope_id value of an IPv6 address
     * 设置一个IPv6 地址的sin6_scope_id 的值
     * @param val Value to set
     * @参数val，设置的值
     * @return True on success, false if not available
     * @返回True 设置成功，false 如果不可用
     */
    inline bool scopeId(unsigned int val)
	{ return scopeId(address(),val); }

    /**
     * Get the host of this address
     * 获得地址对象里面的主机
     * @return Host name as String
     * @返回字符串的主机名字
     */
    inline const String& host() const
	{ return m_host; }

    /**
     * Get the host and port of this address
     * 获得地址对象里面的主机和端口
     * @return Address String (host:port)
     * @返回地址字符串(host:port)
     */
    inline const String& addr() const {
	    if (!m_addr)
		updateAddr();
	    return m_addr;
	}

    /**
     * Set the hostname of this address.
     * 设置地址对象的主机名字
     * Guess address family if not initialized
     * 猜测地址族family，如果没有初始化
     * @param name Host to set
     * @参数name，要设置的主机
     * @return True if new host set, false if name could not be parsed
     * @返回True 如果设置了新的主机，false 如果主机name不能被解析
     */
    virtual bool host(const String& name);

    /**
     * Get the port of the stored address (if supported)
     * 从存储的地址中获取端口
     * @return Port number of the socket address or zero
     * @返回套接字地址的端口号或者0
     */
    int port() const;

    /**
     * Set the port of the stored address (if supported)
     * 设置端口号到存储的地址
     * @param newport Port number to set in the socket address
     * @参数newport ，要设置到套接字地址的端口号
     * @return True if new port set, false if not supported
     * @返回True 如果新的端口被设置，false 如果不被支持
     */
    bool port(int newport);

    /**
     * Get the contained socket address
     * 获得包含的套接字地址
     * @return A pointer to the socket address
     * @返回套接字地址的指针
     */
    inline struct sockaddr* address() const
	{ return m_address; }

    /**
     * Get the length of the address
     * 获得地址的长度
     * @return Length of the stored address
     * @返回被存的地址长度
     */
    inline socklen_t length() const
	{ return m_length; }

    /**
     * Check if this address is empty or null
     * 检查地址是否为空或者null
     * @return True if the address is empty or '0.0.0.0' (IPv4) or '::' IPv6
     * @返回true，如果地址为空或者'0.0.0.0' 或者'::'
     */
    inline bool isNullAddr() const
	{ return isNullAddr(m_host,family()); }

    /**
     * Check if an address family is supported by the library
     * 检查地址族是否被库支持
     * @param family Family of the address to check
     * @参数family，要检查的地址族
     * @return True if the address family is supported
     * @返回true，如果地址族被支持
     */
    static bool supports(int family);

    /**
     * Retrieve the family of an address
     * 检索地址的族
     * @param addr The address to check
     * @参数addr，要检查的地址
     * @return Address family
     * @返回地址族
     */
    static int family(const String& addr);

    /**
     * Convert the host address to a String
     * 转换主机地址为字符串
     * @param buf Destination buffer
     * @参数buf，存放字符串的缓冲区
     * @param addr Socket address
     * @参数addr，套接字的地址
     * @return True on success, false if address family is not supported
     * @返回true，成功，false，地址族不是支持
     */
    static bool stringify(String& buf, struct sockaddr* addr);

    /**
     * Put a host address to a buffer
     * 输出主机地址到缓冲区
     * @param buf Destination buffer. It must be large enough to keep the address
     *  (4 bytes for IPv4, 16 bytes for IPv6)
     * @参数buf，目标缓冲区，地址必须足够大
     * @param host The host address
     * @参数host，主机地址
     * @param family Address family, set it to Unknown to detect
     * @参数family, 地址族，未检测到设置为Unknown
     * @return Address family, Unknown on failure
     * @返回地址族，失败为Unknown
     */
    static inline int unStringify(uint8_t* buf, const String& host,
	int family = Unknown) {
	    SocketAddr sa(family);
	    return sa.host(host) ? copyAddr(buf,sa.address()) : Unknown;
	}

    /**
     * Copy a host address to a buffer
     * 拷贝主机地址到缓冲区
     * @param buf Destination buffer. It must be large enough to keep the address
     *  (4 bytes for IPv4, 16 bytes for IPv6)
     * @参数buf，目标缓冲区，地址必须足够大
     * @param addr The host address
     * @参数host，主机地址
     * @return Address family, Unknown on failure
     * @返回地址族，失败为Unknown
     */
    static int copyAddr(uint8_t* buf, struct sockaddr* addr);

    /**
     * Retrieve the scope id value of an IPv6 address
     * 检索IPv6地址的范围id值
     * @param addr The address
     * @参数addr,检索地址
     * @return The requested value (it may be 0), 0 if not available
     * @返回检索的值，0 ，如果不可用
     */
    static inline unsigned int scopeId(struct sockaddr* addr) {
#ifdef AF_INET6
	    if (addr && addr->sa_family == AF_INET6)
		return ((struct sockaddr_in6*)addr)->sin6_scope_id;
#endif
	    return 0;
	}

    /**
     * Set the scope id value of an IPv6 address
     * 设置IPv6地址的返回id值
     * @param addr Address to set
     * @参数addr, 要设置的地址
     * @param val Value to set
     * @参数val，要设置的值
     * @return True on success, false if not available
     * @返回true，设置成功,false，如果不可用
     */
    static inline bool scopeId(struct sockaddr* addr, unsigned int val) {
#ifdef AF_INET6
	    if (addr && addr->sa_family == AF_INET6) {
		((struct sockaddr_in6*)addr)->sin6_scope_id = val;
		return true;
	    }
#endif
	    return false;
	}

    /**
     * Append an address to a buffer
     * 附加地址到缓冲区
     * @param buf Destination buffer
     * @参数buf，目标缓冲区
     * @param addr Address to append
     * @参数addr,要附加的地址
     * @param family Address family, set it to Unknown to detect
     * @参数family, 地址族，未检测到设置为Unknown
     * @return Buffer address
     * @返回地址的缓冲区
     */
    static String& appendAddr(String& buf, const String& addr, int family = Unknown);

    /**
     * Append an address to a buffer in the form addr:port
     * 添加地址到缓冲区从地址:端口
     * @param buf Destination buffer
     * @参数buf，目标缓冲区
     * @param addr Address to append
     * @参数addr，要添加的地址
     * @param port Port to append
     * @参数port，添加的端口
     * @param family Address family, set it to Unknown to detect
     * @参数family, 地址族，未检测到设置为Unknown
     * @return Buffer address
     * @返回地址的缓冲区
     */
    static inline String& appendTo(String& buf, const String& addr, int port,
	int family = Unknown) {
	    appendAddr(buf,addr,family) << ":" << port;
	    return buf;
	}

    /**
     * Append an address to a buffer in the form addr:port
     * 添加地址到缓冲区从地址:端口
     * @param addr Address to append
     * @参数addr，要添加的地址
     * @param port Port to append
     * @参数port，添加的端口
     * @param family Address family, set it to Unknown to detect
     * @参数family, 地址族，未检测到设置为Unknown
     * @return A String with concatenated address and port
     * @返回地址和端口级联的字符串
     */
    static inline String appendTo(const String& addr, int port, int family = Unknown) {
	    String buf;
	    appendTo(buf,addr,port,family);
	    return buf;
	}

    /**
     * Check if an address is empty or null
     * 检查地址是否为空或者null
     * @param addr Address to check
     * @参数addr,要核查的地址
     * @param family Address family, set it to Unknown to detect
     * @参数family, 地址族，未检测到设置为Unknown
     * @return True if the address is empty or '0.0.0.0' (IPv4) or '::' IPv6
     * @返回true，如果地址为空,或者0.0.0.0' (IPv4)，或者'::' IPv6
     */
    static bool isNullAddr(const String& addr, int family = Unknown);

    /**
     * Split an interface from address
     * 分割一个地址接口
     * An interface may be present in addr after a percent char (e.g. fe80::23%eth0)
     * 一个接口可能出现在addr百分之一char
     * It is safe call this method with the same destination and source string
     * 对于相同的目标和源字符串是安全的调用方法
     * @param buf Source buffer
     * @参数buf，源数据缓冲区
     * @param addr Destination buffer for address
     * @参数addr，地址的目标缓冲区
     * @param iface Optional pointer to be filled with interface name
     * @参数iface,接口名的指针
     */
    static void splitIface(const String& buf, String& addr, String* iface = 0);

    /**
     * Split an address into ip/port.
     * 分割地址为ip 和port
     * Handled formats: addr, addr:port, [addr], [addr]:port
     * 处理后的格式: addr,addr:port,[addr],[addr]:port
     * It is safe call this method with the same destination and source string
     * 对于相同的目标和源字符串是安全的调用方法
     * @param buf Source buffer
     * @参数buf，源数据缓冲区
     * @param addr Destination buffer for address
     * @参数addr，地址的目标缓冲区
     * @param port Destination port
     * @参数port, 分割后的端口
     * @param portPresent Set it to true if the port is always present after the last ':'.
     * @参数portPresent，设置为true，如果端口总是在最后一个':'后面
     *  This will handle IPv6 addresses without square brackets and port present
     *  处理IPv6的地址，没有方括号和端口
     *  (e.g. fe80::23:5060 will split into addr=fe80::23 and port=5060)
     */
    static void split(const String& buf, String& addr, int& port, bool portPresent = false);

    /**
     * Retrieve address family name
     * 检索地址族名
     * @param family Address family to retrieve
     * @参数family，要检索的地址族
     * @return Address family name
     * @返回地址族名
     */
    static inline const char* lookupFamily(int family)
	{ return lookup(family,s_familyName); }

    /**
     * Retrieve IPv4 null address
     * 检索IPv4 的空地址
     * @return IPv4 null address (0.0.0.0)
     * @返回IPv4 空地址(0.0.0.0)
     */
    static const String& ipv4NullAddr();

    /**
     * Retrieve IPv6 null address
     * 检索IPv6 的空地址
     * @return IPv6 null address (::)
     * @返回IPv6 空地址(::)
     */
    static const String& ipv6NullAddr();

    /**
     * Retrieve the family name dictionary
     * 从族名目录检索
     * @return Pointer to family name dictionary
     * @返回族名目录的指针
     */
    static const TokenDict* dictFamilyName();

protected:
    /**
     * Convert the host address to a String stored in m_host
     * 将主机地址转换成字符串存储在m_host中
     */
    virtual void stringify();

    /**
     * Store host:port in m_addr
     * 存储主机: 端口到m_addr
     */
    virtual void updateAddr() const;

    struct sockaddr* m_address;
    socklen_t m_length;
    String m_host;
    mutable String m_addr;

private:
    static const TokenDict s_familyName[];
};