INET_Addr.h

Go to the documentation of this file.
00001 /* -*- C++ -*- */
00002 
00003 //=============================================================================
00004 /**
00005  *  @file    INET_Addr.h
00006  *
00007  *  INET_Addr.h,v 4.58 2006/05/30 10:57:22 jwillemsen Exp
00008  *
00009  *  @author Douglas C. Schmidt <schmidt@cs.wustl.edu>
00010  */
00011 //=============================================================================
00012 
00013 #ifndef ACE_INET_ADDR_H
00014 #define ACE_INET_ADDR_H
00015 #include /**/ "ace/pre.h"
00016 
00017 #include "ace/Sock_Connect.h"
00018 
00019 #if !defined (ACE_LACKS_PRAGMA_ONCE)
00020 # pragma once
00021 #endif /* ACE_LACKS_PRAGMA_ONCE */
00022 
00023 #include "ace/Addr.h"
00024 
00025 #if defined(ACE_VXWORKS)
00026    // Needed to get INET_ADDR_LEN
00027 #  include /**/ "inetLib.h"
00028 #endif /* ACE_VXWORKS */
00029 
00030 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
00031 
00032 /**
00033  * @class ACE_INET_Addr
00034  *
00035  * @brief Defines a C++ wrapper facade for the Internet domain address
00036  * family format.
00037  */
00038 class ACE_Export ACE_INET_Addr : public ACE_Addr
00039 {
00040 public:
00041   // = Initialization methods.
00042 
00043   /// Default constructor.
00044   ACE_INET_Addr (void);
00045 
00046   /// Copy constructor.
00047   ACE_INET_Addr (const ACE_INET_Addr &);
00048 
00049   /// Creates an ACE_INET_Addr from a sockaddr_in structure.
00050   ACE_INET_Addr (const sockaddr_in *, int len);
00051 
00052   /// Creates an ACE_INET_Addr from a <port_number> and the remote
00053   /// <host_name>. The port number is assumed to be in host byte order.
00054   /// To set a port already in network byte order, please @see set().
00055   /// Use address_family to select IPv6 (PF_INET6) vs. IPv4 (PF_INET).
00056   ACE_INET_Addr (u_short port_number,
00057                  const char host_name[],
00058                  int address_family = AF_UNSPEC);
00059 
00060   /**
00061    * Initializes an ACE_INET_Addr from the <address>, which can be
00062    * "ip-number:port-number" (e.g., "tango.cs.wustl.edu:1234" or
00063    * "128.252.166.57:1234").  If there is no ':' in the <address> it
00064    * is assumed to be a port number, with the IP address being
00065    * INADDR_ANY.
00066    */
00067   explicit ACE_INET_Addr (const char address[]);
00068 
00069   /**
00070    * Creates an ACE_INET_Addr from a <port_number> and an Internet
00071    * <ip_addr>.  This method assumes that <port_number> and <ip_addr>
00072    * are in host byte order. If you have addressing information in
00073    * network byte order, @see set().
00074    */
00075   explicit ACE_INET_Addr (u_short port_number,
00076                           ACE_UINT32 ip_addr = INADDR_ANY);
00077 
00078   /// Uses <getservbyname> to create an ACE_INET_Addr from a
00079   /// <port_name>, the remote <host_name>, and the <protocol>.
00080   ACE_INET_Addr (const char port_name[],
00081                  const char host_name[],
00082                  const char protocol[] = "tcp");
00083 
00084   /**
00085    * Uses <getservbyname> to create an ACE_INET_Addr from a
00086    * <port_name>, an Internet <ip_addr>, and the <protocol>.  This
00087    * method assumes that <ip_addr> is in host byte order.
00088    */
00089   ACE_INET_Addr (const char port_name[],
00090                  ACE_UINT32 ip_addr,
00091                  const char protocol[] = "tcp");
00092 
00093 #if defined (ACE_HAS_WCHAR)
00094   ACE_INET_Addr (u_short port_number,
00095                  const wchar_t host_name[],
00096                  int address_family = AF_UNSPEC);
00097 
00098   explicit ACE_INET_Addr (const wchar_t address[]);
00099 
00100   ACE_INET_Addr (const wchar_t port_name[],
00101                  const wchar_t host_name[],
00102                  const wchar_t protocol[] = ACE_TEXT_WIDE ("tcp"));
00103 
00104   ACE_INET_Addr (const wchar_t port_name[],
00105                  ACE_UINT32 ip_addr,
00106                  const wchar_t protocol[] = ACE_TEXT_WIDE ("tcp"));
00107 #endif /* ACE_HAS_WCHAR */
00108 
00109   /// Default dtor.
00110   ~ACE_INET_Addr (void);
00111 
00112   // = Direct initialization methods.
00113 
00114   // These methods are useful after the object has been constructed.
00115 
00116   /// Initializes from another ACE_INET_Addr.
00117   int set (const ACE_INET_Addr &);
00118 
00119   /**
00120    * Initializes an ACE_INET_Addr from a <port_number> and the
00121    * remote <host_name>.  If <encode> is non-zero then <port_number> is
00122    * converted into network byte order, otherwise it is assumed to be
00123    * in network byte order already and are passed straight through.
00124    * address_family can be used to select IPv4/IPv6 if the OS has
00125    * IPv6 capability (ACE_HAS_IPV6 is defined). To specify IPv6, use
00126    * the value AF_INET6. To specify IPv4, use AF_INET.
00127    */
00128   int set (u_short port_number,
00129            const char host_name[],
00130            int encode = 1,
00131            int address_family = AF_UNSPEC);
00132 
00133   /**
00134    * Initializes an ACE_INET_Addr from a @a port_number and an Internet
00135    * @a ip_addr.  If @a encode is non-zero then the port number and IP address
00136    * are converted into network byte order, otherwise they are assumed to be
00137    * in network byte order already and are passed straight through.
00138    *
00139    * If <map> is non-zero and IPv6 support has been compiled in,
00140    * then this address will be set to the IPv4-mapped IPv6 address of it.
00141    */
00142   int set (u_short port_number,
00143            ACE_UINT32 ip_addr = INADDR_ANY,
00144            int encode = 1,
00145            int map = 0);
00146 
00147   /// Uses <getservbyname> to initialize an ACE_INET_Addr from a
00148   /// <port_name>, the remote <host_name>, and the <protocol>.
00149   int set (const char port_name[],
00150            const char host_name[],
00151            const char protocol[] = "tcp");
00152 
00153   /**
00154    * Uses <getservbyname> to initialize an ACE_INET_Addr from a
00155    * <port_name>, an <ip_addr>, and the <protocol>.  This assumes that
00156    * <ip_addr> is already in network byte order.
00157    */
00158   int set (const char port_name[],
00159            ACE_UINT32 ip_addr,
00160            const char protocol[] = "tcp");
00161 
00162   /**
00163    * Initializes an ACE_INET_Addr from the <addr>, which can be
00164    * "ip-number:port-number" (e.g., "tango.cs.wustl.edu:1234" or
00165    * "128.252.166.57:1234").  If there is no ':' in the <address> it
00166    * is assumed to be a port number, with the IP address being
00167    * INADDR_ANY.
00168    */
00169   int set (const char addr[]);
00170 
00171   /// Creates an ACE_INET_Addr from a sockaddr_in structure.
00172   int set (const sockaddr_in *,
00173            int len);
00174 
00175 #if defined (ACE_HAS_WCHAR)
00176   int set (u_short port_number,
00177            const wchar_t host_name[],
00178            int encode = 1,
00179            int address_family = AF_UNSPEC);
00180 
00181   int set (const wchar_t port_name[],
00182            const wchar_t host_name[],
00183            const wchar_t protocol[] = ACE_TEXT_WIDE ("tcp"));
00184 
00185   int set (const wchar_t port_name[],
00186            ACE_UINT32 ip_addr,
00187            const wchar_t protocol[] = ACE_TEXT_WIDE ("tcp"));
00188 
00189   int set (const wchar_t addr[]);
00190 #endif /* ACE_HAS_WCHAR */
00191 
00192   /// Return a pointer to the underlying network address.
00193   virtual void *get_addr (void) const;
00194   int get_addr_size(void) const;
00195 
00196   /// Set a pointer to the address.
00197   virtual void set_addr (void *, int len);
00198 
00199   /// Set a pointer to the address.
00200   virtual void set_addr (void *, int len, int map);
00201 
00202   /**
00203    * Transform the current ACE_INET_Addr address into string format.
00204    * If <ipaddr_format> is non-0 this produces "ip-number:port-number"
00205    * (e.g., "128.252.166.57:1234"), whereas if <ipaddr_format> is 0
00206    * this produces "ip-name:port-number" (e.g.,
00207    * "tango.cs.wustl.edu:1234").  Returns -1 if the <size> of the
00208    * <buffer> is too small, else 0.
00209    */
00210   virtual int addr_to_string (ACE_TCHAR buffer[],
00211                               size_t size,
00212                               int ipaddr_format = 1) const;
00213 
00214   /**
00215    * Initializes an ACE_INET_Addr from the @a address, which can be
00216    * "ip-addr:port-number" (e.g., "tango.cs.wustl.edu:1234"),
00217    * "ip-addr:port-name" (e.g., "tango.cs.wustl.edu:telnet"),
00218    * "ip-number:port-number" (e.g., "128.252.166.57:1234"), or
00219    * "ip-number:port-name" (e.g., "128.252.166.57:telnet").  If there
00220    * is no ':' in the <address> it is assumed to be a port number,
00221    * with the IP address being INADDR_ANY.
00222    */
00223   virtual int string_to_addr (const char address[]);
00224 
00225 #if defined (ACE_HAS_WCHAR)
00226   /*
00227   virtual int string_to_addr (const char address[]);
00228   */
00229 #endif /* ACE_HAS_WCHAR */
00230 
00231   /**
00232    * Sets the port number without affecting the host name.  If
00233    * <encode> is enabled then <port_number> is converted into network
00234    * byte order, otherwise it is assumed to be in network byte order
00235    * already and are passed straight through.
00236    */
00237   void set_port_number (u_short,
00238                         int encode = 1);
00239 
00240   /**
00241    * Sets the address without affecting the port number.  If
00242    * <encode> is enabled then <ip_addr> is converted into network
00243    * byte order, otherwise it is assumed to be in network byte order
00244    * already and are passed straight through.  The size of the address
00245    * is specified in the <len> parameter.
00246    * If <map> is non-zero, IPv6 support has been compiled in, and
00247    * <ip_addr> is an IPv4 address, then this address is set to the IPv4-mapped
00248    * IPv6 address of it.
00249    */
00250   int set_address (const char *ip_addr,
00251                    int len,
00252                    int encode = 1,
00253                    int map = 0);
00254 
00255 #if (defined (__linux__) || defined (ACE_WIN32)) && defined (ACE_HAS_IPV6)
00256   /**
00257    * Sets the interface that should be used for this address. This only has
00258    * an effect when the address is link local, otherwise it does nothing.
00259    */
00260   int set_interface (const char *intf_name);
00261 #endif /* (__linux__ || ACE_WIN32) && ACE_HAS_IPV6 */
00262 
00263   /// Return the port number, converting it into host byte-order.
00264   u_short get_port_number (void) const;
00265 
00266   /**
00267    * Return the character representation of the name of the host,
00268    * storing it in the <hostname> (which is assumed to be
00269    * <hostnamelen> bytes long).  This version is reentrant.  If
00270    * <hostnamelen> is greater than 0 then <hostname> will be
00271    * NUL-terminated even if -1 is returned.
00272    */
00273   int get_host_name (char hostname[],
00274                      size_t hostnamelen) const;
00275 
00276 #if defined (ACE_HAS_WCHAR)
00277   int get_host_name (wchar_t hostname[],
00278                      size_t hostnamelen) const;
00279 #endif /* ACE_HAS_WCHAR */
00280 
00281   /**
00282    * Return the character representation of the hostname (this version
00283    * is non-reentrant since it returns a pointer to a static data
00284    * area).
00285    */
00286   const char *get_host_name (void) const;
00287 
00288   /// Return the "dotted decimal" Internet address.
00289   const char *get_host_addr (void) const;
00290   const char *get_host_addr (char *dst, int size) const;
00291 
00292   /// Return the 4-byte IP address, converting it into host byte
00293   /// order.
00294   ACE_UINT32 get_ip_address (void) const;
00295 
00296   /// Return @c true if the IP address is INADDR_ANY or IN6ADDR_ANY.
00297   bool is_any (void) const;
00298 
00299   /// Return @c true if the IP address is IPv4/IPv6 loopback address.
00300   bool is_loopback (void) const;
00301 
00302 #if defined (ACE_HAS_IPV6)
00303   /// Return @c true if the IP address is IPv6 linklocal address.
00304   bool is_linklocal (void) const;
00305 
00306   /// Return @c true if the IP address is IPv4-mapped IPv6 address.
00307   bool is_ipv4_mapped_ipv6 (void) const;
00308 
00309   /// Return @c true if the IP address is IPv4-compatible IPv6 address.
00310   bool is_ipv4_compat_ipv6 (void) const;
00311 #endif /* ACE_HAS_IPV6 */
00312 
00313   /**
00314    * Returns @c true if @c this is less than @a rhs.  In this context,
00315    * "less than" is defined in terms of IP address and TCP port
00316    * number.  This operator makes it possible to use @c ACE_INET_Addrs
00317    * in STL maps.
00318    */
00319   bool operator < (const ACE_INET_Addr &rhs) const;
00320 
00321   /// Compare two addresses for equality.  The addresses are considered
00322   /// equal if they contain the same IP address and port number.
00323   bool operator == (const ACE_INET_Addr &SAP) const;
00324 
00325   /// Compare two addresses for inequality.
00326   bool operator != (const ACE_INET_Addr &SAP) const;
00327 
00328   /// Computes and returns hash value.
00329   virtual u_long hash (void) const;
00330 
00331   /// Dump the state of an object.
00332   void dump (void) const;
00333 
00334   /// Declare the dynamic allocation hooks.
00335   ACE_ALLOC_HOOK_DECLARE;
00336 
00337 private:
00338   /// Insure that @a hostname is properly null-terminated.
00339   int get_host_name_i (char hostname[], size_t hostnamelen) const;
00340 
00341   // Methods to gain access to the actual address of
00342   // the underlying internet address structure.
00343   void *ip_addr_pointer (void) const;
00344   int ip_addr_size (void) const;
00345   int determine_type (void) const;
00346 
00347   /// Initialize underlying inet_addr_ to default values
00348   void reset (void);
00349 
00350   /// Underlying representation.
00351   /// This union uses the knowledge that the two structures share the
00352   /// first member, sa_family (as all sockaddr structures do).
00353   union
00354   {
00355     sockaddr_in  in4_;
00356 #if defined (ACE_HAS_IPV6)
00357     sockaddr_in6 in6_;
00358 #endif /* ACE_HAS_IPV6 */
00359   } inet_addr_;
00360 
00361 #if defined (ACE_VXWORKS)
00362   char buf_[INET_ADDR_LEN];
00363 #endif
00364 };
00365 
00366 ACE_END_VERSIONED_NAMESPACE_DECL
00367 
00368 #if defined (__ACE_INLINE__)
00369 #include "ace/INET_Addr.inl"
00370 #endif /* __ACE_INLINE__ */
00371 
00372 #include /**/ "ace/post.h"
00373 #endif /* ACE_INET_ADDR_H */

Generated on Thu Nov 9 09:41:52 2006 for ACE by doxygen 1.3.6