From 4b8bbd4f2f3e5179ea7e93cbead14ac4a0751876 Mon Sep 17 00:00:00 2001 From: defanor Date: Sun, 1 Mar 2020 19:44:20 +0300 Subject: Annotate IQ-related things --- src/rexmpp.h | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/src/rexmpp.h b/src/rexmpp.h index c28b490..f36f438 100644 --- a/src/rexmpp.h +++ b/src/rexmpp.h @@ -18,13 +18,29 @@ typedef struct rexmpp rexmpp_t; + +/** + @brief An info/query callback function type. + @param[in,out] s A ::rexmpp structure. + @param[in] request A request that was made. + @param[in] response A response we have received. @c NULL if we are + giving up on this IQ. + + A callback must not free the request or the response, but merely + inspect those and react. +*/ typedef void (*rexmpp_iq_callback_t) (rexmpp_t *s, xmlNodePtr request, xmlNodePtr response); typedef struct rexmpp_iq rexmpp_iq_t; + +/** @brief A pending info/query request. */ struct rexmpp_iq { + /** @brief The sent request. */ xmlNodePtr request; + /** @brief A callback to call on reply. */ rexmpp_iq_callback_t cb; + /** @brief Next pending IQ. */ rexmpp_iq_t *next; }; @@ -290,6 +306,25 @@ rexmpp_err_t rexmpp_stop (rexmpp_t *s); */ rexmpp_err_t rexmpp_send (rexmpp_t *s, xmlNodePtr node); +/** + @brief Prepare and send a new info/query request. + @param[in,out] s ::rexmpp + @param[in] type + @param[in] to + @param[in] payload IQ payload, the library assumes ownership of it. + @param[in] cb A ::rexmpp_iq_callback_t function to call on reply + (or if we will give up on it), can be NULL. + + This function is specifically for IQs that should be tracked by the + library. If an application wants to track replies on its own, it + should use ::rexmpp_send. +*/ +void rexmpp_iq_new (rexmpp_t *s, + const char *type, + const char *to, + xmlNodePtr payload, + rexmpp_iq_callback_t cb); + struct timeval *rexmpp_timeout (rexmpp_t *s, struct timeval *max_tv, struct timeval *tv); int rexmpp_fds (rexmpp_t *s, fd_set *read_fds, fd_set *write_fds); -- cgit v1.2.3