ACE/ace/INET_Addr.h

   1 /* -*- C++ -*- */
   2
   3 //=============================================================================
   4 /**
   5  *  @file    INET_Addr.h
   6  *
   7  *  @author Douglas C. Schmidt <d.schmidt@vanderbilt.edu>
   8  */
   9 //=============================================================================
  10
  11 #ifndef ACE_INET_ADDR_H
  12 #define ACE_INET_ADDR_H
  13 #include /**/ "ace/pre.h"
  14
  15 #include "ace/Sock_Connect.h"
  16
  17 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  18 # pragma once
  19 #endif /* ACE_LACKS_PRAGMA_ONCE */
  20
  21 #include "ace/Addr.h"
  22 #include <vector>
  23
  24 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  25
  26 /**
  27  * @class ACE_INET_Addr
  28  *
  29  * @brief Defines a C++ wrapper facade for the Internet domain address
  30  * family format.
  31  *
  32  * ACE_INET_Addr can hold all of the IP addresses assigned to a single name.
  33  * By default it refers only to the first, if there is more than one. The
  34  * next() method can make the others available in turn.
  35  */
  36 class ACE_Export ACE_INET_Addr : public ACE_Addr
  37 {
  38 public:
  39   /// Default constructor.
  40   ACE_INET_Addr (void);
  41
  42   /// Copy constructor.
  43   ACE_INET_Addr (const ACE_INET_Addr &);
  44
  45   /// Creates an ACE_INET_Addr from a sockaddr_in structure.
  46   ACE_INET_Addr (const sockaddr_in *addr, int len);
  47
  48   /// Creates an ACE_INET_Addr from a @a port_number and the remote
  49   /// @a host_name. The port number is assumed to be in host byte order.
  50   /// To set a port already in network byte order, please @see set().
  51   /// Use address_family to select IPv6 (PF_INET6) vs. IPv4 (PF_INET).
  52   ACE_INET_Addr (u_short port_number,
  53                  const char host_name[],
  54                  int address_family = AF_UNSPEC);
  55
  56   /**
  57    * Initializes an ACE_INET_Addr from the @a address, which can be
  58    * "ip-addr:port-number" (e.g., "tango.cs.wustl.edu:1234"),
  59    * "ip-addr:port-name" (e.g., "tango.cs.wustl.edu:telnet"),
  60    * "ip-number:port-number" (e.g., "128.252.166.57:1234"),
  61    * "ip-number:port-name" (e.g., "128.252.166.57:telnet"),
  62    * "[ipv6-number]:port-number (e.g, "[2001:db8::57]:1234") or
  63    * "[ipv6-number]:port-name (e.g, "[2001:db8::57]:telnet").
  64    * If there is no ':' in the @a address it is assumed to be a port number,
  65    * with the IP address being INADDR_ANY.
  66    */
  67   explicit ACE_INET_Addr (const char address[],
  68                           int address_family = AF_UNSPEC);
  69
  70   /**
  71    * Creates an ACE_INET_Addr from a @a port_number and an Internet
  72    * @a ip_addr.  This method assumes that @a port_number and @a ip_addr
  73    * are in host byte order. If you have addressing information in
  74    * network byte order, @see set().
  75    */
  76   explicit ACE_INET_Addr (u_short port_number,
  77                           ACE_UINT32 ip_addr = INADDR_ANY);
  78
  79   /// Uses getservbyname() to create an ACE_INET_Addr from a
  80   /// @a port_name, the remote @a host_name, and the @a protocol.
  81   ACE_INET_Addr (const char port_name[],
  82                  const char host_name[],
  83                  const char protocol[] = "tcp");
  84
  85   /**
  86    * Uses getservbyname() to create an ACE_INET_Addr from a
  87    * @a port_name, an Internet @a ip_addr, and the @a protocol.  This
  88    * method assumes that @a ip_addr 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
  94 #if defined (ACE_HAS_WCHAR)
  95   ACE_INET_Addr (u_short port_number,
  96                  const wchar_t host_name[],
  97                  int address_family = AF_UNSPEC);
  98
  99   explicit ACE_INET_Addr (const wchar_t address[],
 100                           int address_family = AF_UNSPEC);
 101
 102   ACE_INET_Addr (const wchar_t port_name[],
 103                  const wchar_t host_name[],
 104                  const wchar_t protocol[] = ACE_TEXT_WIDE ("tcp"));
 105
 106   ACE_INET_Addr (const wchar_t port_name[],
 107                  ACE_UINT32 ip_addr,
 108                  const wchar_t protocol[] = ACE_TEXT_WIDE ("tcp"));
 109 #endif /* ACE_HAS_WCHAR */
 110
 111   /// Default dtor.
 112   ~ACE_INET_Addr (void);
 113
 114   // = Direct initialization methods.
 115
 116   // These methods are useful after the object has been constructed.
 117
 118   /// Assignment. In a more well-ordered world, member-wise assignment would
 119   /// work fine. However, because of the class design feature that all of the
 120   /// acceptor/connector-type classes that can be used in the
 121   /// Acceptor-Connector framework take ACE_Addr objects instead of the
 122   /// addressing class matching the family in use. The mechanism used to
 123   /// enable this substitution to the more-appropriate class is
 124   /// ACE_sap_any_cast, which casts the ACE_Addr to the more-specific class.
 125   /// In this case, casting an ACE_Addr to ACE_INET_Addr then copying it.
 126   /// Since adding multiple address support to ACE_INET_Addr, that cast-copy
 127   /// operation ends up, in the member-wise case, copying a bogus vector
 128   /// and doing lots of random damage. Thus, this operator is used to make
 129   /// life ordered in this common scenario.
 130   ACE_INET_Addr & operator= (const ACE_INET_Addr &rhs);
 131
 132   /// Initializes from another ACE_INET_Addr.
 133   int set (const ACE_INET_Addr &);
 134
 135   /**
 136    * Initializes an ACE_INET_Addr from a @a port_number and the
 137    * remote @a host_name.  If @a encode is non-zero then @a port_number is
 138    * converted into network byte order, otherwise it is assumed to be
 139    * in network byte order already and are passed straight through.
 140    * address_family can be used to select IPv4/IPv6 if the OS has
 141    * IPv6 capability (ACE_HAS_IPV6 is defined). To specify IPv6, use
 142    * the value AF_INET6. To specify IPv4, use AF_INET.
 143    */
 144   int set (u_short port_number,
 145            const char host_name[],
 146            int encode = 1,
 147            int address_family = AF_UNSPEC);
 148
 149   /**
 150    * Initializes an ACE_INET_Addr from a @a port_number and an Internet
 151    * @a ip_addr.  If @a encode is non-zero then the port number and IP address
 152    * are converted into network byte order, otherwise they are assumed to be
 153    * in network byte order already and are passed straight through.
 154    *
 155    * If @a map is non-zero and IPv6 support has been compiled in,
 156    * then this address will be set to the IPv4-mapped IPv6 address of it.
 157    */
 158   int set (u_short port_number,
 159            ACE_UINT32 ip_addr = INADDR_ANY,
 160            int encode = 1,
 161            int map = 0);
 162
 163   /// Uses getservbyname() to initialize an ACE_INET_Addr from a
 164   /// @a port_name, the remote @a host_name, and the @a protocol.
 165   int set (const char port_name[],
 166            const char host_name[],
 167            const char protocol[] = "tcp");
 168
 169   /**
 170    * Uses getservbyname() to initialize an ACE_INET_Addr from a
 171    * @a port_name, an @a ip_addr, and the @a protocol.  This assumes that
 172    * @a ip_addr is already in network byte order.
 173    */
 174   int set (const char port_name[],
 175            ACE_UINT32 ip_addr,
 176            const char protocol[] = "tcp");
 177
 178   /**
 179    * Initializes an ACE_INET_Addr from the @a address, which can be
 180    * "ip-addr:port-number" (e.g., "tango.cs.wustl.edu:1234"),
 181    * "ip-addr:port-name" (e.g., "tango.cs.wustl.edu:telnet"),
 182    * "ip-number:port-number" (e.g., "128.252.166.57:1234"),
 183    * "ip-number:port-name" (e.g., "128.252.166.57:telnet"),
 184    * "[ipv6-number]:port-number (e.g, "[2001:db8::57]:1234") or
 185    * "[ipv6-number]:port-name (e.g, "[2001:db8::57]:telnet").
 186    * If there is no ':' in the @a address it is assumed to be a port number,
 187    * with the IP address being INADDR_ANY.
 188    */
 189   int set (const char addr[], int address_family = AF_UNSPEC);
 190
 191   /// Creates an ACE_INET_Addr from a sockaddr_in structure.
 192   int set (const sockaddr_in *,
 193            int len);
 194
 195 #if defined (ACE_HAS_WCHAR)
 196   int set (u_short port_number,
 197            const wchar_t host_name[],
 198            int encode = 1,
 199            int address_family = AF_UNSPEC);
 200
 201   int set (const wchar_t port_name[],
 202            const wchar_t host_name[],
 203            const wchar_t protocol[] = ACE_TEXT_WIDE ("tcp"));
 204
 205   int set (const wchar_t port_name[],
 206            ACE_UINT32 ip_addr,
 207            const wchar_t protocol[] = ACE_TEXT_WIDE ("tcp"));
 208
 209   int set (const wchar_t addr[], int address_family = AF_UNSPEC);
 210 #endif /* ACE_HAS_WCHAR */
 211
 212   /// Return a pointer to the underlying network address.
 213   virtual void *get_addr (void) const;
 214   int get_addr_size(void) const;
 215
 216   /// Set a pointer to the address.
 217   virtual void set_addr (const void *, int len);
 218
 219   /// Set a pointer to the address.
 220   virtual void set_addr (const void *, int len, int map);
 221
 222   /**
 223    * Transform the current ACE_INET_Addr address into string format.
 224    * If @a ipaddr_format is true this produces "ip-number:port-number"
 225    * (e.g., "128.252.166.57:1234" or "[2001:db8::57]:1234"), whereas
 226    * if @a ipaddr_format is false this produces "ip-name:port-number" (e.g.,
 227    * "tango.cs.wustl.edu:1234").  Returns -1 if the @a size of the
 228    * @a buffer is too small, else 0.
 229    */
 230   virtual int addr_to_string (ACE_TCHAR buffer[],
 231                               size_t size,
 232                               int ipaddr_format = 1) const;
 233
 234   /**
 235    * Initializes an ACE_INET_Addr from the @a address, which can be
 236    * "ip-addr:port-number" (e.g., "tango.cs.wustl.edu:1234"),
 237    * "ip-addr:port-name" (e.g., "tango.cs.wustl.edu:telnet"),
 238    * "ip-number:port-number" (e.g., "128.252.166.57:1234"),
 239    * "ip-number:port-name" (e.g., "128.252.166.57:telnet"),
 240    * "[ipv6-number]:port-number (e.g, "[2001:db8::57]:1234") or
 241    * "[ipv6-number]:port-name (e.g, "[2001:db8::57]:telnet").
 242    * If there is no ':' in the @a address it is assumed to be a port number,
 243    * with the IP address being INADDR_ANY.
 244    */
 245   virtual int string_to_addr (const char address[],
 246                               int address_family = AF_UNSPEC);
 247
 248 #if defined (ACE_HAS_WCHAR)
 249   /*
 250   virtual int string_to_addr (const char address[]);
 251   */
 252 #endif /* ACE_HAS_WCHAR */
 253
 254   /**
 255    * Sets the port number without affecting the host name.  If
 256    * @a encode is enabled then @a port_number is converted into network
 257    * byte order, otherwise it is assumed to be in network byte order
 258    * already and are passed straight through.
 259    */
 260   void set_port_number (u_short,
 261                         int encode = 1);
 262
 263   /**
 264    * Sets the address without affecting the port number.  If
 265    * @a encode is enabled then @a ip_addr is converted into network
 266    * byte order, otherwise it is assumed to be in network byte order
 267    * already and are passed straight through.  The size of the address
 268    * is specified in the @a len parameter.
 269    * If @a map is non-zero, IPv6 support has been compiled in, and
 270    * @a ip_addr is an IPv4 address, then this address is set to the IPv4-mapped
 271    * IPv6 address of it.
 272    */
 273   int set_address (const char *ip_addr,
 274                    int len,
 275                    int encode = 1,
 276                    int map = 0);
 277
 278 #if (defined (ACE_LINUX) || defined (ACE_WIN32)) && defined (ACE_HAS_IPV6)
 279   /**
 280    * Sets the interface that should be used for this address. This only has
 281    * an effect when the address is link local, otherwise it does nothing.
 282    */
 283   int set_interface (const char *intf_name);
 284 #endif /* (ACE_LINUX || ACE_WIN32) && ACE_HAS_IPV6 */
 285
 286   /// Return the port number, converting it into host byte-order.
 287   u_short get_port_number (void) const;
 288
 289   /**
 290    * Return the character representation of the name of the host,
 291    * storing it in the @a hostname (which is assumed to be
 292    * @a hostnamelen bytes long).  This version is reentrant.  If
 293    * @a hostnamelen is greater than 0 then @a hostname will be
 294    * NUL-terminated even if -1 is returned.
 295    */
 296   int get_host_name (char hostname[],
 297                      size_t hostnamelen) const;
 298
 299 #if defined (ACE_HAS_WCHAR)
 300   int get_host_name (wchar_t hostname[],
 301                      size_t hostnamelen) const;
 302 #endif /* ACE_HAS_WCHAR */
 303
 304   /**
 305    * Return the character representation of the hostname.  This
 306    * version is non-reentrant since it returns a pointer to a static
 307    * data area.  You should therefore either (1) do a "deep copy" of
 308    * the address returned by get_host_name(), e.g., using strdup() or
 309    * (2) use the "reentrant" version of get_host_name() described
 310    * above.
 311    */
 312   const char *get_host_name (void) const;
 313
 314   /**
 315    * Return the "dotted decimal" Internet address representation of
 316    * the hostname storing it in the @a addr (which is assumed to be
 317    * @a addr_size bytes long).  This version is reentrant.
 318    */
 319   const char *get_host_addr (char *addr, int addr_size) const;
 320
 321   /**
 322    * Return the "dotted decimal" Internet address representation of
 323    * the hostname.  This version is non-reentrant since it returns a
 324    * pointer to a static data area.  You should therefore either
 325    * (1) do a "deep copy" of the address returned by get_host_addr(), e.g.,
 326    * using strdup() or (2) use the "reentrant" version of
 327    * get_host_addr() described above.
 328    */
 329   const char *get_host_addr (void) const;
 330
 331   /// Return the 4-byte IP address, converting it into host byte
 332   /// order.
 333   ACE_UINT32 get_ip_address (void) const;
 334
 335   /// Return @c true if the IP address is INADDR_ANY or IN6ADDR_ANY.
 336   bool is_any (void) const;
 337
 338   /// Return @c true if the IP address is IPv4/IPv6 loopback address.
 339   bool is_loopback (void) const;
 340
 341   /// Return @c true if the IP address is IPv4/IPv6 multicast address.
 342   bool is_multicast (void) const;
 343
 344 #if defined (ACE_HAS_IPV6)
 345   /// Return @c true if the IP address is IPv6 linklocal address.
 346   bool is_linklocal (void) const;
 347
 348   /// Return @c true if the IP address is IPv6 sitelocal address.
 349   bool is_sitelocal (void) const;
 350
 351   /// Return @c true if the IP address is IPv4-mapped IPv6 address.
 352   bool is_ipv4_mapped_ipv6 (void) const;
 353
 354   /// Return @c true if the IP address is IPv4-compatible IPv6 address.
 355   bool is_ipv4_compat_ipv6 (void) const;
 356 #endif /* ACE_HAS_IPV6 */
 357
 358   /**
 359    * Returns @c true if @c this is less than @a rhs.  In this context,
 360    * "less than" is defined in terms of IP address and TCP port
 361    * number.  This operator makes it possible to use @c ACE_INET_Addrs
 362    * in STL maps.
 363    */
 364   bool operator < (const ACE_INET_Addr &rhs) const;
 365
 366   /// Compare two addresses for equality.  The addresses are considered
 367   /// equal if they contain the same IP address and port number.
 368   bool operator == (const ACE_INET_Addr &SAP) const;
 369
 370   /// Compare two addresses for inequality.
 371   bool operator != (const ACE_INET_Addr &SAP) const;
 372
 373   /// A variation of the equality operator, this method only compares the
 374   /// IP address and ignores the port number.
 375   bool is_ip_equal (const ACE_INET_Addr &SAP) const;
 376
 377   /// Computes and returns hash value.
 378   virtual u_long hash (void) const;
 379
 380   /// If there is another address to examine, move to it and return true;
 381   /// else return false.
 382   bool next (void);
 383
 384   /// Reset the set of address so they can be scanned again using next().
 385   void reset (void);
 386
 387   /// Dump the state of an object.
 388   void dump (void) const;
 389
 390   /// Declare the dynamic allocation hooks.
 391   ACE_ALLOC_HOOK_DECLARE;
 392
 393 private:
 394   /// Insure that @a hostname is properly null-terminated.
 395   int get_host_name_i (char hostname[], size_t hostnamelen) const;
 396
 397   // Methods to gain access to the actual address of
 398   // the underlying internet address structure.
 399   void *ip_addr_pointer (void) const;
 400   int ip_addr_size (void) const;
 401   int determine_type (void) const;
 402
 403   /// Initialize underlying inet_addr_ to default values
 404   void reset_i (void);
 405
 406   /// Underlying representation.
 407   /// This union uses the knowledge that the two structures share the
 408   /// first member, sa_family (as all sockaddr structures do).
 409   union ip46
 410   {
 411     sockaddr_in  in4_;
 412 #if defined (ACE_HAS_IPV6)
 413     sockaddr_in6 in6_;
 414 #endif /* ACE_HAS_IPV6 */
 415   } inet_addr_;
 416   // If there is more than one address assigned to a given name, this
 417   // holds all of them; one is always copied to inet_addr_.
 418   std::vector<union ip46> inet_addrs_;
 419   std::vector<union ip46>::iterator inet_addrs_iter_;
 420 };
 421
 422 ACE_END_VERSIONED_NAMESPACE_DECL
 423
 424 #if defined (__ACE_INLINE__)
 425 #include "ace/INET_Addr.inl"
 426 #endif /* __ACE_INLINE__ */
 427
 428 #include /**/ "ace/post.h"
 429 #endif /* ACE_INET_ADDR_H */