net/base/ip_address_number.h

   1 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef NET_BASE_IP_ADDRESS_NUMBER_H_
   6 #define NET_BASE_IP_ADDRESS_NUMBER_H_
   7
   8 #include <string>
   9 #include <vector>
  10
  11 #include "base/basictypes.h"
  12 #include "base/strings/string_piece.h"
  13 #include "net/base/net_export.h"
  14
  15 namespace net {
  16
  17 // IPAddressNumber is used to represent an IP address's numeric value as an
  18 // array of bytes, from most significant to least significant. This is the
  19 // network byte ordering.
  20 //
  21 // IPv4 addresses will have length 4, whereas IPv6 address will have length 16.
  22 typedef std::vector<unsigned char>
  23     IPAddressNumber;  // This is also duplicated in net_util.h
  24 typedef std::vector<IPAddressNumber> IPAddressList;
  25
  26 static const size_t kIPv4AddressSize = 4;
  27 static const size_t kIPv6AddressSize = 16;
  28
  29 // Returns true if an IP address hostname is in a range reserved by the IANA.
  30 // Works with both IPv4 and IPv6 addresses, and only compares against a given
  31 // protocols's reserved ranges.
  32 NET_EXPORT bool IsIPAddressReserved(const IPAddressNumber& address);
  33
  34 // Returns the string representation of an IP address.
  35 // For example: "192.168.0.1" or "::1".
  36 NET_EXPORT std::string IPAddressToString(const uint8_t* address,
  37                                          size_t address_len);
  38
  39 // Returns the string representation of an IP address along with its port.
  40 // For example: "192.168.0.1:99" or "[::1]:80".
  41 NET_EXPORT std::string IPAddressToStringWithPort(const uint8_t* address,
  42                                                  size_t address_len,
  43                                                  uint16_t port);
  44
  45 // Same as IPAddressToString() but for an IPAddressNumber.
  46 NET_EXPORT std::string IPAddressToString(const IPAddressNumber& addr);
  47
  48 // Same as IPAddressToStringWithPort() but for an IPAddressNumber.
  49 NET_EXPORT std::string IPAddressToStringWithPort(const IPAddressNumber& addr,
  50                                                  uint16_t port);
  51
  52 // Returns the address as a sequence of bytes in network-byte-order.
  53 NET_EXPORT std::string IPAddressToPackedString(const IPAddressNumber& addr);
  54
  55 // Parses a URL-safe IP literal (see RFC 3986, Sec 3.2.2) to its numeric value.
  56 // Returns true on success, and fills |ip_number| with the numeric value
  57 NET_EXPORT bool ParseURLHostnameToNumber(const std::string& hostname,
  58                                          IPAddressNumber* ip_number);
  59
  60 // Parses an IP address literal (either IPv4 or IPv6) to its numeric value.
  61 // Returns true on success and fills |ip_number| with the numeric value.
  62 NET_EXPORT bool ParseIPLiteralToNumber(const base::StringPiece& ip_literal,
  63                                        IPAddressNumber* ip_number);
  64
  65 // Converts an IPv4 address to an IPv4-mapped IPv6 address.
  66 // For example 192.168.0.1 would be converted to ::ffff:192.168.0.1.
  67 NET_EXPORT_PRIVATE IPAddressNumber ConvertIPv4NumberToIPv6Number(
  68     const IPAddressNumber& ipv4_number);
  69
  70 // Returns true iff |address| is an IPv4-mapped IPv6 address.
  71 NET_EXPORT_PRIVATE bool IsIPv4Mapped(const IPAddressNumber& address);
  72
  73 // Converts an IPv4-mapped IPv6 address to IPv4 address. Should only be called
  74 // on IPv4-mapped IPv6 addresses.
  75 NET_EXPORT_PRIVATE IPAddressNumber ConvertIPv4MappedToIPv4(
  76     const IPAddressNumber& address);
  77
  78 // Parses an IP block specifier from CIDR notation to an
  79 // (IP address, prefix length) pair. Returns true on success and fills
  80 // |*ip_number| with the numeric value of the IP address and sets
  81 // |*prefix_length_in_bits| with the length of the prefix.
  82 //
  83 // CIDR notation literals can use either IPv4 or IPv6 literals. Some examples:
  84 //
  85 //    10.10.3.1/20
  86 //    a:b:c::/46
  87 //    ::1/128
  88 NET_EXPORT bool ParseCIDRBlock(const std::string& cidr_literal,
  89                                IPAddressNumber* ip_number,
  90                                size_t* prefix_length_in_bits);
  91
  92 // Compares an IP address to see if it falls within the specified IP block.
  93 // Returns true if it does, false otherwise.
  94 //
  95 // The IP block is given by (|ip_prefix|, |prefix_length_in_bits|) -- any
  96 // IP address whose |prefix_length_in_bits| most significant bits match
  97 // |ip_prefix| will be matched.
  98 //
  99 // In cases when an IPv4 address is being compared to an IPv6 address prefix
 100 // and vice versa, the IPv4 addresses will be converted to IPv4-mapped
 101 // (IPv6) addresses.
 102 NET_EXPORT_PRIVATE bool IPNumberMatchesPrefix(const IPAddressNumber& ip_number,
 103                                               const IPAddressNumber& ip_prefix,
 104                                               size_t prefix_length_in_bits);
 105
 106 // Returns number of matching initial bits between the addresses |a1| and |a2|.
 107 unsigned CommonPrefixLength(const IPAddressNumber& a1,
 108                             const IPAddressNumber& a2);
 109
 110 // Computes the number of leading 1-bits in |mask|.
 111 unsigned MaskPrefixLength(const IPAddressNumber& mask);
 112
 113 }  // namespace net
 114
 115 #endif  // NET_BASE_IP_ADDRESS_NUMBER_H_