diff options
author | defanor <defanor@uberspace.net> | 2021-09-22 22:29:00 +0300 |
---|---|---|
committer | defanor <defanor@uberspace.net> | 2021-09-22 22:29:00 +0300 |
commit | 54cd916b857b0067223309466943011c1b2976fc (patch) | |
tree | d7a734d816f1a0ed5e9c6e0e7546fd88037d4129 | |
parent | 498e517c2f2fc22b40550f5d87596b5926b73f45 (diff) |
Update doxygen docs
-rw-r--r-- | src/rexmpp_dns.h | 51 | ||||
-rw-r--r-- | src/rexmpp_tls.h | 3 |
2 files changed, 50 insertions, 4 deletions
diff --git a/src/rexmpp_dns.h b/src/rexmpp_dns.h index 704cafb..6641238 100644 --- a/src/rexmpp_dns.h +++ b/src/rexmpp_dns.h @@ -1,9 +1,10 @@ /** @file rexmpp_dns.h - @brief DNS helper functions + @brief DNS resolution @author defanor <defanor@uberspace.net> @date 2020 @copyright MIT license. + */ @@ -15,6 +16,9 @@ #include "rexmpp.h" +/** + @brief DNS context. +*/ #if defined(USE_UNBOUND) #include <unbound.h> struct rexmpp_dns_ctx { @@ -42,12 +46,23 @@ struct rexmpp_dns_srv { typedef struct rexmpp_dns_srv rexmpp_dns_srv_t; +/** + @brief DNS query result. +*/ struct rexmpp_dns_result { + /** @brief NULL-terminated array of data pointers. They contain + ::rexmpp_dns_srv for SRV lookups, host addresses for A and AAAA + ones. */ void **data; + /** @brief An array of data structure lengths. */ int *len; + /** @brief Whether the result was retrieved securely (that is, + verified with DNSSEC). */ int secure; }; +typedef struct rexmpp_dns_result rexmpp_dns_result_t; + /** @brief Parses an SRV DNS RR's RDATA. @param[in] in SRV record's RDATA. @@ -58,21 +73,45 @@ struct rexmpp_dns_result { int rexmpp_parse_srv (char *in, int in_len, struct rexmpp_dns_srv *out); -typedef struct rexmpp_dns_result rexmpp_dns_result_t; - -/* struct rexmpp_dns_result *rexmpp_dns_result_init (int len); */ +/** + @brief Frees a ::rexmpp_dns_result structure and its members. + @param[in] result A pointer to a ::rexmpp_dns_result structure. +*/ void rexmpp_dns_result_free (rexmpp_dns_result_t *result); +/** + @brief Initializes a DNS resolver context. +*/ int rexmpp_dns_ctx_init (rexmpp_t *s); + +/** + @brief Cleans up the state that can be discarded between XMPP + connections, to be called from rexmpp_cleanup. +*/ void rexmpp_dns_ctx_cleanup (rexmpp_t *s); + +/** + @brief Deinitializes a DNS resolver context. +*/ void rexmpp_dns_ctx_deinit (rexmpp_t *s); + +/** + @brief Sets file descriptors to select/poll. +*/ int rexmpp_dns_fds (rexmpp_t *s, fd_set *read_fds, fd_set *write_fds); + +/** + @brief Reports timeouts. +*/ struct timeval * rexmpp_dns_timeout (rexmpp_t *s, struct timeval *max_tv, struct timeval *tv); typedef void (*dns_query_cb_t) (rexmpp_t *s, void *ptr, rexmpp_dns_result_t *result); +/** + @brief Initiates a query. +*/ int rexmpp_dns_resolve (rexmpp_t *s, const char *query, int rrtype, @@ -80,6 +119,10 @@ int rexmpp_dns_resolve (rexmpp_t *s, void* ptr, dns_query_cb_t callback); +/** + @brief Processes active queries, should be called based on the + reported timeouts and file descriptors. +*/ int rexmpp_dns_process (rexmpp_t *s, fd_set *read_fds, fd_set *write_fds); diff --git a/src/rexmpp_tls.h b/src/rexmpp_tls.h index 2d54d1e..21e61f3 100644 --- a/src/rexmpp_tls.h +++ b/src/rexmpp_tls.h @@ -33,6 +33,9 @@ enum rexmpp_tls_err { typedef enum rexmpp_tls_err rexmpp_tls_err_t; +/** + @brief TLS context. +*/ #if defined(USE_GNUTLS) #include <gnutls/gnutls.h> struct rexmpp_tls { |