Class to hold and manipulate IPv4, IPv6 and Sock Addresses.
This is primarily to reduce old c-style code and improve the success of Protocol Changes now and in the future. New code where written from the point this class is pushed up to Squid3 HEAD should be coded with this IPAddress class as the method of storing and transfering address/port information. Old code modified from the point of publication of this class should be updated to use it.
| MAX_IPSTRLEN | Length of char* array needed to hold an IP String representation. |
Default constructors, and destructor are defined. Not for explicit public use,
but listed here to indicate standard new, delete and local variable creation are all possible.
Special constructors and assignment operators to convert IPv4 arpa objects into IPAddress type.
This is primarily intended for use during the code conversion from pre-IPAddress squid code.
Special constructors and assignment operators to convert IPv6 inet6 objects into IPAddress type.
This is primarily intended for use during the code conversion from pre-IPAddress squid code.
NP: These methods are currently only available when compiler directive INET6 is defined.
Equality tests of two IPAddress objects. Checks whether the address and port portion of the two objects match.
Test functions defined for external code to determin which objects types can be retrieved (in_addr, in6_addr, etc) from the IPAddress object tested.
Special helper function for connections requiring an IPv4-only address. Makes any subsequent actions follow IPv4-only mode for this object. Returns false if the address failed conversion to IPv4.
Retrieve the Reverse-DNS lookup string (aka rDNS Hostname) for the IP address stored within.
Optional second parameter defines a format conversion type, to present the string in IPv4 or IPv6 rDNS format.
Helper functions to set and retrieve the port value of the full address held within. Value received by SetPort should be in Host-Bit-Order. Return result will be a Port number in Host-Bit-Order, or 0 if no Port available after the operation is complete.
Helper functions to set and test for the special-case IP addresses:
ANY_ADDR (0.0.0.0 or ::)
NO_ADDR (255.255.255.255 or ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff)
LOCALHOST (127.0.0.1 or ::1)
using a generic format-neutral method.
NOTE: SetLocalhost() will set ::1 in IPv6 builds, even if --with-ipv6-localhost is not used.
Special helper function to reset the object to its initial state as if the default constructor had just been used.
Helper functions to set and retrieve protocol-neutral socket structures needed by low-level Comm code.
GetAddrInfo() should receive a pointer preset to NULL. It dynamicaly initialises all objects needed.
Analogous to the system call getaddrinfo(), but it initiates defaults assuming TCP streaing socket most commonly
used by squid. When UDP details are needed, the caller is responsible to altering the addrinfo socket/protocol details.
It may also be called with an optional parameter forcing the protocol type to either IPv4 or IPv6, useful for
binding listeners on a specific protocol if they require it.
FreeAddrInfo() direct replacement of the system freeaddrinfo() call. It cleanly destructs dynamic objects
allocated by GetAddrInfo().
NOTE: Due to the location of dynamic allocations; calls to the system getaddrinfo() MUST be deallocated
with the system freeaddrinfo() and calls to IPAddress::GetAddrInfo() MUST be deallocated with IPAddress::FreeAddrInfo().
To ensure this the matchign FreeAddrInfo() should always be called within the same function that calls GetAddrInfo().
When the system updates the addrifno structure it should be assigned back to the IPAddress for passing around squid.
see addrinfo documentatinon for further usage of the structure.
Retrieve the string representation of the address contained within.
Places the resulting string into the buffer received and returns the buffer pointer or NULL on failure.
buf should be a buffer of at least MAX_IPSTRLEN length.
len parameter should be the available length of the char* buffer.
format is optional and specifies which family display format is to be used (IPv4 can be displayed as hybrid AF_INET6).
Default will be native numeric display for the IP type stored.
NtoA provides functional analog to the old IPv4 inet_ntoa() and new IPv6 inet_ntop(), providing just the address part as a string.
ToHostname provides similar ability but in IPv6 displays address with brackets for use in URI without port.
ToURL provides similar ability to ToHostname but adds :port to the output if stored port is non-zero.
Dumps the URL formatted string representation of the contents to a stream. Places the resulting string into the output stream received as address:port if both are available, or just address if port is not valid (zero). Applies Brackets around address part for IPv6.
These methods are made available for use during the conversion of pre-IPAddress code to the full use of this
object.
They have been made intentionally hard to use to restrict temptation, and have no guarantee of longevity.
Code performing low-level socket operations ( bind(), connect(, getsock*(), etc) should use GetAddrInfo() to retrieve
protocol-neutral details those functions require.
Names are pretty self-explanitory. They retrieve old arpa and inet structure representations of the IPAddress objects content ready to be passed on to client functions that have not yet been converted to accept IPAddress objects.
$Id: IPAddress.html,v 1.9 2007/08/23 06:28:36 amosjeffries Exp $