ACE学习手记----ACE_INET_Addr类

ACE_INET_Addr类,在这个ACE_网络框架中,应该是比较重要的辅助类,该类主要封装了C SOCKET 的地址对象,通过外观封装的模式,把struct sockaddr_in封装在内。方便用户的操作。 

 

因此个人认为掌握此类的常用构造方法和常用的成员函数,并深刻的理解,对于后续的学习ACE或者开发ACE网络应用程序应该会起到很大的帮助。工欲用其器、必先利其器。就先让我们把ACE_INET_Addr对象深刻的牢记在心中吧。

  1. /* -*- C++ -*- */
  2. //=============================================================================
  3. /**
  4.  *  @file    INET_Addr.h
  5.  *
  6.  *  $Id: INET_Addr.h 78617 2007-06-27 20:40:19Z mesnier_p $
  7.  *
  8.  *  @author Douglas C. Schmidt 
  9.  */
  10. //=============================================================================
  11. #ifndef ACE_INET_ADDR_H
  12. #define ACE_INET_ADDR_H
  13. #include /**/ "ace/pre.h"
  14. #include "ace/Sock_Connect.h"
  15. #if !defined (ACE_LACKS_PRAGMA_ONCE)
  16. # pragma once
  17. #endif /* ACE_LACKS_PRAGMA_ONCE */
  18. #include "ace/Addr.h"
  19. #if defined(ACE_VXWORKS)
  20.    // Needed to get INET_ADDR_LEN
  21. #  include /**/ "inetLib.h"
  22. #endif /* ACE_VXWORKS */
  23. ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  24. /**
  25.  * @class ACE_INET_Addr
  26.  *
  27.  * @brief Defines a C++ wrapper facade for the Internet domain address
  28.  * family format.
  29.  */
  30. class ACE_Export ACE_INET_Addr : public ACE_Addr
  31. {
  32. public:
  33.   // = Initialization methods.
  34.   /// Default constructor.
  35.   /// 默认构造函数
  36.   ACE_INET_Addr (void);
  37.   /// Copy constructor.
  38.   /// 拷贝构造函数
  39.   ACE_INET_Addr (const ACE_INET_Addr &);
  40.   /// Creates an ACE_INET_Addr from a sockaddr_in structure.
  41.   /// 使用参数@addr 地址初始化ACE_INET_Addr对象。
  42.   /// 参数@len 为 @addr结构地址对象的长度,使用 sizeof(strcut sockaddr_in)
  43.   ACE_INET_Addr (const sockaddr_in *addr, int len);
  44.   /// Creates an ACE_INET_Addr from a  and the remote
  45.   /// . The port number is assumed to be in host byte order.
  46.   /// To set a port already in network byte order, please @see set().
  47.   /// Use address_family to select IPv6 (PF_INET6) vs. IPv4 (PF_INET).
  48.   /// 使用参数 @port_number 和 host_name 构造一个ACE_INET_Addr对象。
  49.   /// @port_number应该为主机字节序,构造函数需要把它转换了网络字节序。
  50.   /// 如果port_number为网络字节序,请使用 set成员函数或者set_port_number成员函数。
  51.   /// @address_family 用于指定ACE_INET_Addr的地址类型PF_INET(IPv4)或者PF_INET6(IPv6)
  52.   ACE_INET_Addr (u_short port_number,
  53.                  const char host_name[],
  54.                  int address_family = AF_UNSPEC);
  55.   /**
  56.    * Initializes an ACE_INET_Addr from the 
    , which can be
  57.    * "ip-number:port-number" (e.g., "tango.cs.wustl.edu:1234" or
  58.    * "128.252.166.57:1234").  If there is no ':' in the 
     it
  59.    * is assumed to be a port number, with the IP address being
  60.    * INADDR_ANY.
  61.    * 使用参数@address初始化一个ACE_INET_Addr对象。
  62.    * address的格式为 ip-number:port-number 或者 port-number.
  63.    * ip-number 可以为点分号的IP地址,也可是是域名地址。
  64.    * 如果参数@address没有提供 ip-number,只提供port-number时,地址被初始化为INADDR_ANY
  65.    * port-number 为主机字节序。
  66.    */
  67.   explicit ACE_INET_Addr (const char address[],
  68.                           int address_family = AF_UNSPEC);
  69.   /**
  70.    * Creates an ACE_INET_Addr from a  and an Internet
  71.    * .  This method assumes that  and 
  72.    * are in host byte order. If you have addressing information in
  73.    * network byte order, @see set().
  74.    * 使用主机字节序的@port_number 和 @ip_addr初始化一个ACE_INET_Addr对象。
  75.    * 如port_number或者 ip_addr为网络字节序时,请使用 set成员函数。
  76.    */
  77.   explicit ACE_INET_Addr (u_short port_number,
  78.                           ACE_UINT32 ip_addr = INADDR_ANY);
  79.   /// Uses  to create an ACE_INET_Addr from a
  80.   /// , the remote , and the .
  81.   /// 通过 getservbyname API获得port_name的端口,eg port_name="ftp"时,得到的端口是21.
  82.   ACE_INET_Addr (const char port_name[],
  83.                  const char host_name[],
  84.                  const char protocol[] = "tcp");
  85.   /**
  86.    * Uses  to create an ACE_INET_Addr from a
  87.    * , an Internet , and the .  This
  88.    * method assumes that  is in host byte order.
  89.    */
  90.   ACE_INET_Addr (const char port_name[],
  91.                  ACE_UINT32 ip_addr,
  92.                  const char protocol[] = "tcp");
  93. #if defined (ACE_HAS_WCHAR)
  94.   ACE_INET_Addr (u_short port_number,
  95.                  const wchar_t host_name[],
  96.                  int address_family = AF_UNSPEC);
  97.   explicit ACE_INET_Addr (const wchar_t address[],
  98.                           int address_family = AF_UNSPEC);
  99.   ACE_INET_Addr (const wchar_t port_name[],
  100.                  const wchar_t host_name[],
  101.                  const wchar_t protocol[] = ACE_TEXT_WIDE ("tcp"));
  102.   ACE_INET_Addr (const wchar_t port_name[],
  103.                  ACE_UINT32 ip_addr,
  104.                  const wchar_t protocol[] = ACE_TEXT_WIDE ("tcp"));
  105. #endif /* ACE_HAS_WCHAR */
  106.   /// Default dtor.
  107.   ~ACE_INET_Addr (void);
  108.   // = Direct initialization methods.
  109.   // = 直接初始化方法。当使用默认构造函数创建一个ACE_INET_Addr对象时,可以使用
  110.   // 下面的来设置一个ACE_INET_Addr对象的地址和端口。
  111.   // These methods are useful after the object has been constructed.
  112.   /// Initializes from another ACE_INET_Addr.
  113.   /// 使用一个已经存在的ACE_INET_Addr对象来初始化本对象。
  114.   int set (const ACE_INET_Addr &);
  115.   /**
  116.    * Initializes an ACE_INET_Addr from a  and the
  117.    * remote 
  118.    * 使用参数@port_number 和@host_name初始化 ACE_INET_Addr 对象。 
  119.    * If  is non-zero then  is
  120.    * converted into network byte order, otherwise it is assumed to be
  121.    * in network byte order already and are passed straight through.
  122.    * 如果参数@encode 为TRUE(非零),表示需要set函数内部进行网络字节序的转换,
  123.    * 也就是此时 port_number属于主机字节序的值。否则port_number就是已经是网络
  124.    * 字节序了,无需进行转换,直接赋值即可。
  125.    * address_family can be used to select IPv4/IPv6 if the OS has
  126.    * IPv6 capability (ACE_HAS_IPV6 is defined). To specify IPv6, use
  127.    * the value AF_INET6. To specify IPv4, use AF_INET.
  128.    * 参数@address_family 用于选定IPv4/IPv6的地址格式。使用AF_INET指定IPv4地址,
  129.    * AF_INET6指定IPv4地址格式。
  130.    */
  131.   int set (u_short port_number,
  132.            const char host_name[],
  133.            int encode = 1,
  134.            int address_family = AF_UNSPEC);
  135.   /**
  136.    * Initializes an ACE_INET_Addr from a @a port_number and an Internet
  137.    * @a ip_addr.  
  138.    * 使用参数@port_number 和参数 @ip_addr初始化 ACE_INET_Addr对象。
  139.    * If @a encode is non-zero then the port number and IP address
  140.    * are converted into network byte order, otherwise they are assumed to be
  141.    * in network byte order already and are passed straight through.
  142.    * 如果参数@encode 为TRUE(非零)时,表面 @port_number、@ip_addr 为主机字节序,
  143.    * set 函数内部需要把它们转换为网络字节序。否则它们为网络字节序,无需而外的转换
  144.    * 直接赋值。
  145.    * If  is non-zero and IPv6 support has been compiled in,
  146.    * then this address will be set to the IPv4-mapped IPv6 address of it.
  147.    */
  148.   int set (u_short port_number,
  149.            ACE_UINT32 ip_addr = INADDR_ANY,
  150.            int encode = 1,
  151.            int map = 0);
  152.   /// Uses  to initialize an ACE_INET_Addr from a
  153.   /// , the remote , and the .
  154.   int set (const char port_name[],
  155.            const char host_name[],
  156.            const char protocol[] = "tcp");
  157.   /**
  158.    * Uses  to initialize an ACE_INET_Addr from a
  159.    * , an , and the .  This assumes that
  160.    *  is already in network byte order.
  161.    */
  162.   int set (const char port_name[],
  163.            ACE_UINT32 ip_addr,
  164.            const char protocol[] = "tcp");
  165.   /**
  166.    * Initializes an ACE_INET_Addr from the @a addr, which can be
  167.    * "ip-number:port-number" (e.g., "tango.cs.wustl.edu:1234" or
  168.    * "128.252.166.57:1234").  If there is no ':' in the 
     it
  169.    * is assumed to be a port number, with the IP address being
  170.    * INADDR_ANY.
  171.    * 参数@addr格式为 %s:%d 或者 %d。
  172.    * %s为 IP地址或者域名, %d 为服务端口号。
  173.    * 也就是如果addr 数组中没有 冒号':' 时,此时地址被设置为 INADD_ANY,端口为@addr指定。
  174.    */
  175.   int set (const char addr[], int address_family = AF_UNSPEC);
  176.   /// Creates an ACE_INET_Addr from a sockaddr_in structure.
  177.   /// 使用 sockaddr_in 结构设置ACE_INET_Addr对象。
  178.   int set (const sockaddr_in *,
  179.            int len);
  180. #if defined (ACE_HAS_WCHAR)
  181.  /**
  182.  * 定义宽字符支持的接口。
  183.  */
  184.   int set (u_short port_number,
  185.            const wchar_t host_name[],
  186.            int encode = 1,
  187.            int address_family = AF_UNSPEC);
  188.   int set (const wchar_t port_name[],
  189.            const wchar_t host_name[],
  190.            const wchar_t protocol[] = ACE_TEXT_WIDE ("tcp"));
  191.   int set (const wchar_t port_name[],
  192.            ACE_UINT32 ip_addr,
  193.            const wchar_t protocol[] = ACE_TEXT_WIDE ("tcp"));
  194.   int set (const wchar_t addr[], int address_family = AF_UNSPEC);
  195. #endif /* ACE_HAS_WCHAR */
  196.   /// Return a pointer to the underlying network address.
  197.   /// 获得原始的网络地址指针,根据IPv4或者IPv6,可以得到一个 struct sockaddr地址的指针。
  198.   virtual void *get_addr (voidconst;
  199.   int get_addr_size(voidconst;
  200.   /// Set a pointer to the address.
  201.   virtual void set_addr (void *, int len);
  202.   /// Set a pointer to the address.
  203.   virtual void set_addr (void *, int len, int map);
  204.   /**
  205.    * Transform the current ACE_INET_Addr address into string format.
  206.    * If  is non-0 this produces "ip-number:port-number"
  207.    * (e.g., "128.252.166.57:1234"), whereas if  is 0
  208.    * this produces "ip-name:port-number" (e.g.,
  209.    * "tango.cs.wustl.edu:1234").  Returns -1 if the @a size of the
  210.    *  is too small, else 0.
  211.    * 把地址转换为字符串, 参数@ipaddr_format指定转换的格式,如果 
  212.    * @ipaddr_format为 TRUE(非零)时,转换为点分十进制的IP地址格式。否则
  213.    * 可能转换为域名的地址格式。
  214.    * @return 成功时返回 0,否则返回 -1,此时参数@buffer的长度太短。
  215.    *
  216.    */
  217.   virtual int addr_to_string (ACE_TCHAR buffer[],
  218.                               size_t size,
  219.                               int ipaddr_format = 1) const;
  220.   /**
  221.    * Initializes an ACE_INET_Addr from the @a address, which can be
  222.    * "ip-addr:port-number" (e.g., "tango.cs.wustl.edu:1234"),
  223.    * "ip-addr:port-name" (e.g., "tango.cs.wustl.edu:telnet"),
  224.    * "ip-number:port-number" (e.g., "128.252.166.57:1234"), or
  225.    * "ip-number:port-name" (e.g., "128.252.166.57:telnet").  If there
  226.    * is no ':' in the 
     it is assumed to be a port number,
  227.    * with the IP address being INADDR_ANY.
  228.    * 把字符串表示的地址格式转换为 ACE_INET_Addr对象的地址。
  229.    * 地址格式可以为 [{ip-addr|ip-number}:]{port-number|port-name}
  230.    * 如果地址格式没有包括冒号':'时,函数内部认为只是设置 port-number|port-name,
  231.    * 地址被设置为 INADDR_ANY
  232.    */
  233.   virtual int string_to_addr (const char address[],
  234.                               int address_family = AF_UNSPEC);
  235. #if defined (ACE_HAS_WCHAR)
  236.   /*
  237.   virtual int string_to_addr (const char address[]);
  238.   */
  239. #endif /* ACE_HAS_WCHAR */
  240.   /**
  241.    * Sets the port number without affecting the host name.  If
  242.    *  is enabled then  is converted into network
  243.    * byte order, otherwise it is assumed to be in network byte order
  244.    * already and are passed straight through.
  245.    * 设置ACE_INET_Addr对象的端口部分,不影响地址域。
  246.    * 参数@encode 的意思等同 set函数的@encode参数。
  247.    */
  248.   void set_port_number (u_short,
  249.                         int encode = 1);
  250.   /**
  251.    * Sets the address without affecting the port number.  If
  252.    *  is enabled then  is converted into network
  253.    * byte order, otherwise it is assumed to be in network byte order
  254.    * already and are passed straight through.  The size of the address
  255.    * is specified in the @a len parameter.
  256.    * If  is non-zero, IPv6 support has been compiled in, and
  257.    *  is an IPv4 address, then this address is set to the IPv4-mapped
  258.    * IPv6 address of it.
  259.    * 设置ACE_INET_Addr对象的地址部分,不改变地址对象的端口。
  260.    * 参数@enable与set函数的@encode一致。
  261.    * 参数@len指定 参数@ip_addr的长度。
  262.    * 参数@map 为 TRUE(非零)是,表示支持IPv6地址格式,否则为IPv4的地址。
  263.    */
  264.   int set_address (const char *ip_addr,
  265.                    int len,
  266.                    int encode = 1,
  267.                    int map = 0);
  268. #if (defined (__linux__) || defined (ACE_WIN32)) && defined (ACE_HAS_IPV6)
  269.   /**
  270.    * Sets the interface that should be used for this address. This only has
  271.    * an effect when the address is link local, otherwise it does nothing.
  272.    */
  273.   int set_interface (const char *intf_name);
  274. #endif /* (__linux__ || ACE_WIN32) && ACE_HAS_IPV6 */
  275.   /// Return the port number, converting it into host byte-order.
  276.   u_short get_port_number (voidconst;
  277.   /**
  278.    * Return the character representation of the name of the host,
  279.    * storing it in the  (which is assumed to be
  280.    *  bytes long).  This version is reentrant.  If
  281.    *  is greater than 0 then  will be
  282.    * NUL-terminated even if -1 is returned.
  283.    */
  284.   int get_host_name (char hostname[],
  285.                      size_t hostnamelen) const;
  286. #if defined (ACE_HAS_WCHAR)
  287.   int get_host_name (wchar_t hostname[],
  288.                      size_t hostnamelen) const;
  289. #endif /* ACE_HAS_WCHAR */
  290.   /**
  291.    * Return the character representation of the hostname.  This
  292.    * version is non-reentrant since it returns a pointer to a static
  293.    * data area.  You should therefore either (1) do a "deep copy" of
  294.    * the address returned by get_host_name(), e.g., using strdup() or
  295.    * (2) use the "reentrant" version of get_host_name() described
  296.    * above.
  297.    */
  298.   const char *get_host_name (voidconst;
  299.   /**
  300.    * Return the "dotted decimal" Internet address representation of
  301.    * the hostname storing it in the @a addr (which is assumed to be
  302.    *  bytes long).  This version is reentrant.
  303.    */
  304.   const char *get_host_addr (char *addr, int addr_size) const;
  305.   /**
  306.    * Return the "dotted decimal" Internet address representation of
  307.    * the hostname.  This version is non-reentrant since it returns a
  308.    * pointer to a static data area.  You should therefore either
  309.    * (1) do a "deep copy" of the address returned by get_host_addr(), e.g.,
  310.    * using strdup() or (2) use the "reentrant" version of
  311.    * get_host_addr() described above.
  312.    */
  313.   const char *get_host_addr (voidconst;
  314.   /// Return the 4-byte IP address, converting it into host byte
  315.   /// order.
  316.   ACE_UINT32 get_ip_address (voidconst;
  317.   /// Return @c true if the IP address is INADDR_ANY or IN6ADDR_ANY.
  318.   bool is_any (voidconst;
  319.   /// Return @c true if the IP address is IPv4/IPv6 loopback address.
  320.   bool is_loopback (voidconst;
  321.   /// Return @c true if the IP address is IPv4/IPv6 multicast address.
  322.   bool is_multicast (voidconst;
  323. #if defined (ACE_HAS_IPV6)
  324.   /// Return @c true if the IP address is IPv6 linklocal address.
  325.   bool is_linklocal (voidconst;
  326.   /// Return @c true if the IP address is IPv4-mapped IPv6 address.
  327.   bool is_ipv4_mapped_ipv6 (voidconst;
  328.   /// Return @c true if the IP address is IPv4-compatible IPv6 address.
  329.   bool is_ipv4_compat_ipv6 (voidconst;
  330. #endif /* ACE_HAS_IPV6 */
  331.   /**
  332.    * Returns @c true if @c this is less than @a rhs.  In this context,
  333.    * "less than" is defined in terms of IP address and TCP port
  334.    * number.  This operator makes it possible to use @c ACE_INET_Addrs
  335.    * in STL maps.
  336.    * 定义次函数,有何实际的应用吗?比较2个地址的大小有何实际意义?
  337.    * 
  338.    */
  339.   bool operator < (const ACE_INET_Addr &rhs) const;
  340.   /// Compare two addresses for equality.  The addresses are considered
  341.   /// equal if they contain the same IP address and port number.
  342.   /// 比较2个地址是否相等,包括地址部分和端口部分。
  343.   bool operator == (const ACE_INET_Addr &SAP) const;
  344.   /// Compare two addresses for inequality.
  345.   /// 比较2个地址是否不相等
  346.   bool operator != (const ACE_INET_Addr &SAP) const;
  347.   /// A variation of the equality operator, this method only compares the
  348.   /// IP address and ignores the port number.
  349.   /// 比较2个地址是否相等,只比较地址部分,忽略端口部分。
  350.   bool is_ip_equal (const ACE_INET_Addr &SAP) const;
  351.   /// Computes and returns hash value.
  352.   virtual u_long hash (voidconst;
  353.   /// Dump the state of an object.
  354.   void dump (voidconst;
  355.   /// Declare the dynamic allocation hooks.
  356.   ACE_ALLOC_HOOK_DECLARE;
  357. private:
  358.   /// Insure that @a hostname is properly null-terminated.
  359.   int get_host_name_i (char hostname[], size_t hostnamelen) const;
  360.   // Methods to gain access to the actual address of
  361.   // the underlying internet address structure.
  362.   void *ip_addr_pointer (voidconst;
  363.   int ip_addr_size (voidconst;
  364.   int determine_type (voidconst;
  365.   /// Initialize underlying inet_addr_ to default values
  366.   void reset (void);
  367.   /// Underlying representation.
  368.   /// This union uses the knowledge that the two structures share the
  369.   /// first member, sa_family (as all sockaddr structures do).
  370.   union
  371.   {
  372.     sockaddr_in  in4_;
  373. #if defined (ACE_HAS_IPV6)
  374.     sockaddr_in6 in6_;
  375. #endif /* ACE_HAS_IPV6 */
  376.   } inet_addr_;
  377. #if defined (ACE_VXWORKS)
  378.   char buf_[INET_ADDR_LEN];
  379. #endif
  380. };
  381. ACE_END_VERSIONED_NAMESPACE_DECL
  382. #if defined (__ACE_INLINE__)
  383. #include "ace/INET_Addr.inl"
  384. #endif /* __ACE_INLINE__ */
  385. #include /**/ "ace/post.h"
  386. #endif /* ACE_INET_ADDR_H */

总结:

1.在set、set_port_number、set_address中都提供了一个参数@encode,此参数在构造函数的参数中并没有提供。因为也意味着,使用任何一个构造函数来创建一个ACE_INET_Addr对象时,其地址和端口必须是主机字节序的。如果地址或者端口为网络字节序时,必须转换为主机字节序才可以使用构造函数。或者使用默认的构造函数,在通过set、set_port_number、set_address等成员函数,指定encode参数为FALSE(0)时,也可以直接把网络字节序的地址和端口设置给ACE_INET_Addr对象。如果地址和端口是2中不同的字节序,需要分别使用set_address和set_port_number进行设置,否则就可以使用set函数一次性设置地址和端口。

2.比较2个ACE_INET_Addr对象的相等性。 根据情况使用不同的成员函数。

  地址和端口都要相等时,使用 ==进行比较。

  只比较地址时,忽略端口时。使用 is_ip_equal 成员函数。

你可能感兴趣的:(ACE)