Minor documentation fix

[senf.git] / Socket / Protocols / INet / INet6Address.hh

diff --git a/Socket/Protocols/INet/INet6Address.hh b/Socket/Protocols/INet/INet6Address.hh
index 48a2906..097022b 100644 (file)
--- a/Socket/Protocols/INet/INet6Address.hh
+++ b/Socket/Protocols/INet/INet6Address.hh
@@ -78,6 +78,15 @@ namespace senf {
 
         The INet6Address class is based on \c boost::array and is built as a fixed-size sequence of
         16 bytes.
+
+        \see CheckINet6Network Helper to check address against an arbitrary fixed network prefix
+        \ingroup addr_group
+
+        \implementation We awkwardly need to use static named constructors (<tt>from_</tt> members)
+            instead of ordinarily overloaded constructors for one simple reason: <tt>char *</tt>
+            doubles as string literal and as arbitrary data iterator. The iterator constructor can
+            therefore not be distinguished from initialization with a string literal. Therefore we
+            need to disambiguate using the named constructors.
      */
     class INet6Address
         : public boost::array<boost::uint8_t,16>,
@@ -96,6 +105,7 @@ namespace senf {
         static INet6Address const AllRouters;  ///< The 'all routers' link-local multicast address
 
         enum NoInit_t { noinit };
+        enum Resolve_t { ResolveINet6, ResolveINet4 };
 
         /** \brief Possible scope values
 
@@ -125,7 +135,7 @@ namespace senf {
                      boost::uint16_t a6=0u, boost::uint16_t a7=0u);
                                         ///< Construct an address constant
 
-        static INet6Address from_string(std::string const & s);
+        static INet6Address from_string(std::string const & s, Resolve_t resolve = ResolveINet6);
                                         ///< Convert string to address
                                         /**< This member will try to convert the given string into
                                              an IP address. from_string() supports all standard IP
@@ -135,9 +145,15 @@ namespace senf {
                                                  protocol like DNS or NIS
                                              \throws SyntaxException if the address cannot be
                                                  converted for some reason
-                                             \param[in] s Address literal or hostname */
-
-        static void from_string(std::string const & s, Callback const & cb);
+                                             \param[in] s Address literal or hostname 
+                                             \param[in] resolve If this is set to \c ResolveINet4,
+                                                 the call will additionally try to interpret \a s as
+                                                 an IpV4 address if no valid IpV6 address is
+                                                 found. The address will be returned as mapped IpV6
+                                                 address. */
+
+        static void from_string(std::string const & s, Callback const & cb, 
+                                Resolve_t resolve = ResolveINet6);
                                         ///< Convert string to address (async/non-blocking)
                                         /**< This member works like
                                              from_string(std::string const &). However unlike
@@ -149,6 +165,11 @@ namespace senf {
                                              On error, the address passed to \a cb will be empty.
                                              \param[in] s Address literal or hostname
                                              \param[in] cb Callback to pass the address to 
+                                             \param[in] resolve If this is set to \c ResolveINet4,
+                                                 the call will additionally try to interpret \a s as
+                                                 an IpV4 address if no valid IpV6 address is
+                                                 found. The address will be returned as mapped IpV6
+                                                 address.
                                              \fixme Implement */
 
         template <class InputIterator>