Merge "netsock2: Add ast_sockaddr_resolve_first_af to netsock2 public API"

include/asterisk/netsock2.h

@@ -437,6 +437,44 @@ int ast_sockaddr_parse(struct ast_sockaddr *addr, const char *str, int flags);
 int ast_sockaddr_resolve(struct ast_sockaddr **addrs, const char *str,
 			 int flags, int family);
 
+/*!
+ * \since 16.0
+ *
+ * \brief
+ * Return the first entry from ast_sockaddr_resolve filtered by address family
+ *
+ * \details
+ * Parses a string containing a host name or an IPv4 or IPv6 address followed
+ * by an optional port (separated by a colon).  This function only returns the
+ * first address into the ast_sockaddr. Allowed formats for name are the following:
+ *
+ * hostname:port
+ * host.example.com:port
+ * a.b.c.d
+ * a.b.c.d:port
+ * a:b:c:...:d
+ * [a:b:c:...:d]
+ * [a:b:c:...:d]:port
+ *
+ * \param[out] addr The resulting ast_sockaddr
+ * \param name The string to parse
+ * \param flags If set to zero, a port MAY be present. If set to
+ * PARSE_PORT_IGNORE, a port MAY be present but will be ignored. If set to
+ * PARSE_PORT_REQUIRE, a port MUST be present. If set to PARSE_PORT_FORBID, a
+ * port MUST NOT be present.
+ *
+ * \param family Only addresses of the given family will be returned. Use 0 or
+ * AST_AF_UNSPEC to specify any address family.  Behavior is ultimately determined
+ * by getaddrinfo in how it orders return results.  First result is selected to
+ * be returned.
+ *
+ * \retval 0 Success
+ * \retval non-zero Failure
+ * \warning Using this function potentially means you have a faulty design.
+ */
+int ast_sockaddr_resolve_first_af(struct ast_sockaddr *addr,
+				      const char* name, int flag, int family);
+
 /*!
  * \brief
  * Apply a netmask to an address and store the result in a separate structure.