Changeset 43171 in vbox for trunk/include

Timestamp:

Sep 4, 2012 5:07:27 PM (13 years ago)

Author:

vboxsync

svn:sync-xref-src-repo-rev:

80557

Message:

Runtime: add IPv6 parsing/resolving functions (contributed by Oliver Loch)
ExtPacks/VNC: add IPv6 support (contributed by Oliver Loch)

Location:

trunk/include/iprt

Files:

• mangling.h (modified) (3 diffs)
• socket.h (modified) (2 diffs)
• string.h (modified) (2 diffs)

trunk/include/iprt/mangling.h

@@ -11 +11 @@
 
 /*
- * Copyright (C) 2011 Oracle Corporation
+ * Copyright (C) 2011-2012 Oracle Corporation
  *
  * This file is part of VirtualBox Open Source Edition (OSE), as
@@ -1197 +1197 @@
 # define RTSocketClose                                  RT_MANGLER(RTSocketClose)
 # define RTSocketFromNative                             RT_MANGLER(RTSocketFromNative)
+# define RTSocketGetAddrInfo                            RT_MANGLER(RTSocketGetAddrInfo)
 # define RTSocketGetLocalAddress                        RT_MANGLER(RTSocketGetLocalAddress)
 # define RTSocketGetPeerAddress                         RT_MANGLER(RTSocketGetPeerAddress)
@@ -1284 +1285 @@
 # define RTStrICmp                                      RT_MANGLER(RTStrICmp)
 # define RTStrIStr                                      RT_MANGLER(RTStrIStr)
+# define RTStrIsIpAddr4                                 RT_MANGLER(RTStrIsIpAddr4)
+# define RTStrIsIpAddr6                                 RT_MANGLER(RTStrIsIpAddr6)
 # define RTStrIsValidEncoding                           RT_MANGLER(RTStrIsValidEncoding)
 # define RTStrmClearError                               RT_MANGLER(RTStrmClearError)

trunk/include/iprt/socket.h

@@ -4 +4 @@
 
 /*
- * Copyright (C) 2006-2011 Oracle Corporation
+ * Copyright (C) 2006-2012 Oracle Corporation
  *
  * This file is part of VirtualBox Open Source Edition (OSE), as
@@ -126 +126 @@
  */
 RTDECL(int) RTSocketParseInetAddress(const char *pszAddress, unsigned uPort, PRTNETADDR pAddr);
+
+/**
+ * Gets the ip addresses of a hostname via getaddrinfo()
+ * Returns only the first result for the moment
+ * This will change with the upcoming IPv6 struct.
+ *
+ * @returns IPRT status code.
+ * @param   psz szString we want to lookup
+ * @param   pszResult - memory used to write the result to
+ * @param   resultSize - size of pszResult in bytes.
+ *                       Holds size of string of the returned
+ *                       address on out
+ * @param   pAddrType   Which address to lookup, valid values are:
+ *                      RTNETADDRTYPE_IPV4 -> lookup AF_INET
+ *                      RTNETADDRTYPE_IPV6 -> lookup AF_INET6
+ *                      RTNETADDRTYPE_INVALID,NULL,... -> lookup anything
+ */
+RTDECL(int) RTSocketGetAddrInfo(const char *psz, char *pszResult, size_t *resultSize, PRTNETADDRTYPE pAddrType);
 
 /**

trunk/include/iprt/string.h

@@ -4 +4 @@
 
 /*
- * Copyright (C) 2006-2010 Oracle Corporation
+ * Copyright (C) 2006-2012 Oracle Corporation
  *
  * This file is part of VirtualBox Open Source Edition (OSE), as
@@ -3860 +3860 @@
 /** @} */
 
+/** @defgroup rt_str_net    Network Address related String operations
+ * @ingroup grp_rt_str
+ * @{ */
+
+/** @page IPv6 Address Format
+ *
+ * IPv6 Addresses, their representation in text and other problems.
+ *
+ * The following is based on:
+ *
+ * - http://tools.ietf.org/html/rfc4291
+ * - http://tools.ietf.org/html/rfc5952
+ * - http://tools.ietf.org/html/rfc6052
+ *
+ *
+ * Before you start using those functions, you should have an idea of
+ * what you're dealing with, before you come and blame the functions...
+ *
+ * First of all, the address itself:
+ *
+ * An address is written like this: (READ THIS FINE MANUAL!)
+ *
+ * - 2001:db8:abc:def::1
+ *
+ * The characters between two colons are called a "hextet".
+ * Each hextet consists of four characters and each IPv6 address
+ * consists of a maximum of eight hextets. So a full blown address
+ * would look like this:
+ *
+ * - 1111:2222:3333:4444:5555:6666:7777:8888
+ *
+ * The allowed characters are "0123456789abcdef". They have to be
+ * lower case. Upper case is not allowed.
+ *
+ * *** Gaps and adress shortening
+ *
+ * If an address contains hextets that contain only "0"s, they
+ * can be shortened, like this:
+ *
+ * - 1111:2222:0000:0000:0000:0000:7777:8888 -> 1111:2222::7777:8888
+ *
+ * The double colon represents the hextets that have been shortened "::".
+ * The "::" will be called "gap" from now on.
+ *
+ * When shortening an address, there are some special rules that need to be applied:
+ *
+ * - Shorten always the longest group of hextets.
+ *
+ *   Let's say, you have this address: 2001:db8:0:0:0:1:0:0 then it has to be
+ *   shortened to "2001:db8::1:0:0". Shortening to "2001:db8:0:0:0:1::" would
+ *   return an error.
+ *
+ * - Two or more gaps the same size.
+ *
+ *   Let's say you have this address: 2001:db8:0:0:1:0:0:1. As you can see, there
+ *   are two gaps, both the size of two hextets. If you shorten the last two hextets,
+ *   you end up in pain, as the RFC forbids this, so the correct address is:
+ *   "2001:db8::1:0:0:1"
+ *
+ * It's important to note that an address can only be shortened ONE TIME!
+ * This is invalid: "2001:db8::1::1"
+ *
+ * *** The scope.
+ *
+ * Each address has a so called "scope" it is added to the end of the address,
+ * separated by a percent sign "%". If there is no scope at the end, it defaults
+ * to "0".
+ *
+ * So "2001:db8::1" is the same as "2001:db8::1%0".
+ *
+ * As in IPv6 all network interfaces can/should have the same address, the scope
+ * gives you the ability to choose on which interface the system should listen.
+ *
+ * AFAIK, the scope can be used with unicast as well as link local addresses, but
+ * it is mandatory with link local addresses (starting with fe80::).
+ *
+ * On Linux the default scope is the interface's name. On Windows it's just the index
+ * of the interface. Run "route print -6" in the shell, to see the interface's index
+ * on Winodows.
+ *
+ * All functions can deal with the scope, and DO NOT warn if you put garbage there.
+ *
+ * *** Port added to the IPv6 address
+ *
+ * There is only one way to add a port to an IPv6 address is to embed it in brackets:
+ *
+ * [2001:db8::1]:12345
+ *
+ * This gives you the address "2001:db8::1" and the port "12345".
+ *
+ * What also works, but is not recommended by rfc is to separate the port
+ * by a dot:
+ *
+ * 2001:db8::1.12345
+ *
+ * It even works with embedded IPv4 addresses.
+ *
+ * *** Special addresses and how they are written
+ *
+ * The following are notations to represent "special addresses".
+ *
+ * "::" IN6ADDR_ANY
+ * ":::123" IN6ADDR_ANY with port "123"
+ * "[::]:123" IN6ADDR_ANY with port "123"
+ * "[:::123]" -> NO. Not allowed and makes no sense
+ * "::1" -> address of the loopback device (127.0.0.1 in v4)
+ *
+ * On systems with dual sockets, one can use so called embedded IPv4 addresses:
+ *
+ * "::ffff:192.168.1.1" results in the IPv6 address "::ffff:c0a8:0101" as two octets
+ * of the IPv4 address will be converted to one hextet in the IPv6 address.
+ *
+ * The prefix of such addresses MUST BE "::ffff:", 10 bytes as zero and two bytes as 255.
+ *
+ * The so called IPv4-compatible IPv6 addresses are deprecated and no longer in use.
+ *
+ * *** Valid addresses and string
+ *
+ * If you use any of the IPv6 address functions, keep in mind, that those addresses
+ * are all returning "valid" even if the underlying system (e.g. VNC) doesn't like
+ * such strings.
+ *
+ * [2001:db8::1]
+ * [2001:db8::1]:12345
+ *
+ * and so on. So to make sure you only pass the underlying software a pure IPv6 address
+ * without any garbage, you should use the "outAddress" parameters to get a RFC compliant
+ * address returned.
+ *
+ * So after reading the above, you'll start using the functions and see a bool called
+ * "followRfc" which is true by default. This is what this bool does:
+ *
+ * The following addresses all represent the exact same address:
+ *
+ * 1 - 2001:db8::1
+ * 2 - 2001:db8:0::1
+ * 3 - 2001:0db8:0000:0000:0000:0000:0000:0001
+ * 4 - 2001:DB8::1
+ * 5 - [2001:db8::1]
+ * 6 - [2001:db8:0::1]
+ *
+ * According to RFC 5952, number two, three, four and six are invalid.
+ *
+ * #2 - because there is a single hextet that hasn't been shortened
+ *
+ * #3 - because there has nothing been shortened (hextets 3 to 7) and
+ *      there are leading zeros in at least one hextet ("0db8")
+ *
+ * #4 - all characters in an IPv6 address have to be lower case
+ *
+ * #6 - same as two but included in brackets
+ *
+ * If you follow RFC, the above addresses are not converted and an
+ * error is returned. If you turn RFC off, you will get the expected
+ * representation of the address.
+ *
+ * It's a nice way to convert "weird" addresses to rfc compliant addresses
+ *
+ */
+
+/**
+ * Takes a string and tests if it is a valid IPv6 representation
+ *
+ * @returns iprt status code.
+ * @param psz                  The string to test
+ * @param pszResultAddress     plain address, optional read "valid addresses
+ *                             and strings" above.
+ * @param resultAddressSize    size of pszResultAddress
+ * @param addressOnly          return only the plain address (no scope)
+ *                             Ignored, and will always return the if id
+ *
+ */
+RTDECL(int) RTStrIsIpAddr6(const char *psz, char *pszResultAddress, size_t resultAddressSize, bool addressOnly, bool followRfc);
+
+/**
+ * Takes a string and returns 0 if it is an IPv4 address
+ *
+ * @returns iprt status code
+ * @param pst              The string to test
+ */
+RTDECL(int) RTStrIsIpAddr4(const char *psz);
+
+/** @} */
+
 
 RT_C_DECLS_END