utils.h: Deprecate `ast_gethostbyname()`. (#79)

Deprecate `ast_gethostbyname()` in favor of `ast_sockaddr_resolve()` and
`ast_sockaddr_resolve_first_af()`. `ast_gethostbyname()` has not been
used by any in-tree code since 2021.

This function will be removed entirely in Asterisk 23.

Resolves: #78

UpgradeNote: ast_gethostbyname() has been deprecated and will be removed
in Asterisk 23. New code should use `ast_sockaddr_resolve()` and
`ast_sockaddr_resolve_first_af()`.

diff --git a/include/asterisk/utils.h b/include/asterisk/utils.h
index 3c06e834eba2ea440d95a9a17e7d0d7708d138aa..30913fc05d89ee7a8883bd6a07a46a737435d993 100644 (file)
--- a/include/asterisk/utils.h
+++ b/include/asterisk/utils.h
@@ -210,7 +210,12 @@ struct ast_hostent {
        char buf[1024];
 };
 
-/*! \brief Thread-safe gethostbyname function to use in Asterisk */
+/*!
+ * \brief Thread-safe gethostbyname function to use in Asterisk
+ *
+ * \deprecated Replaced by \c ast_sockaddr_resolve() and \c ast_sockaddr_resolve_first_af()
+ * \note To be removed in Asterisk 23.
+ */
 struct hostent *ast_gethostbyname(const char *host, struct ast_hostent *hp);
 
 /*! \brief Produces MD5 hash based on input string */