ACE学习手记----ACE_INET_Addr类

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

 

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

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