dep/ACE_wrappers/ace/INET_Addr.h

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