From a8e575ac2236f4542a0979a8f0d6f88576b772e4 Mon Sep 17 00:00:00 2001 From: Andreas Schneider Date: Mon, 3 May 2010 20:29:54 +0200 Subject: tevent: Document the missing tevent async request callback functions. --- lib/tevent/tevent.h | 145 +++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 144 insertions(+), 1 deletion(-) (limited to 'lib/tevent/tevent.h') diff --git a/lib/tevent/tevent.h b/lib/tevent/tevent.h index 5aea1c3ed7..e928a99407 100644 --- a/lib/tevent/tevent.h +++ b/lib/tevent/tevent.h @@ -562,20 +562,73 @@ enum tevent_req_state { */ struct tevent_req; -typedef void (*tevent_req_fn)(struct tevent_req *); +/** + * @brief A tevent request callback function. + * + * @param[in] req The tevent async request which executed this callback. + */ +typedef void (*tevent_req_fn)(struct tevent_req *req); +/** + * @brief Set an async request callback. + * + * @param[in] req The async request to set the callback. + * + * @param[in] fn The callback function to set. + * + * @param[in] pvt A pointer to private data to pass to the async request + * callback. + */ void tevent_req_set_callback(struct tevent_req *req, tevent_req_fn fn, void *pvt); +#ifdef DOXYGEN +/** + * @brief Get the private data casted to the given type for a callback from + * a tevent request structure. + * + * @param[in] req The structure to get the callback data from. + * + * @param[in] type The type of the private callback data to get. + * + * @return The type casted private data set NULL if not set. + */ +void *tevent_req_callback_data(struct tevent_req *req, #type); +#else void *_tevent_req_callback_data(struct tevent_req *req); #define tevent_req_callback_data(_req, _type) \ talloc_get_type_abort(_tevent_req_callback_data(_req), _type) +#endif +#ifdef DOXYGEN +/** + * @brief Get the private data for a callback from a tevent request structure. + * + * @param[in] req The structure to get the callback data from. + * + * @param[in] req The structure to get the data from. + * + * @return The private data or NULL if not set. + */ +void *tevent_req_callback_data_void(struct tevent_req *req); +#else #define tevent_req_callback_data_void(_req) \ _tevent_req_callback_data(_req) +#endif +#ifdef DOXYGEN +/** + * @brief Get the private data from a tevent request structure. + * + * @param[in] req The structure to get the private data from. + * + * @return The private data or NULL if not set. + */ +void *tevent_req_data(struct tevent_req *req); +#else void *_tevent_req_data(struct tevent_req *req); #define tevent_req_data(_req, _type) \ talloc_get_type_abort(_tevent_req_data(_req), _type) +#endif typedef char *(*tevent_req_print_fn)(struct tevent_req *, TALLOC_CTX *); @@ -696,13 +749,35 @@ struct tevent_req *_tevent_req_create(TALLOC_CTX *mem_ctx, #_type, __location__) #endif +/** + * @brief Set a timeout for an async request. + * + * @param[in] req The request to set the timeout for. + * + * @param[in] ev The event context to use for the timer. + * + * @param[in] endtime The endtime of the request. + * + * @return True if succeeded, false if not. + */ bool tevent_req_set_endtime(struct tevent_req *req, struct tevent_context *ev, struct timeval endtime); +#ifdef DOXYGEN +/** + * @brief Call the notify callback of the given tevent request manually. + * + * @param[in] req The tevent request to call the notify function from. + * + * @see tevent_req_set_callback() + */ +void tevent_req_notify_callback(struct tevent_req *req); +#else void _tevent_req_notify_callback(struct tevent_req *req, const char *location); #define tevent_req_notify_callback(req) \ _tevent_req_notify_callback(req, __location__) +#endif #ifdef DOXYGEN /** @@ -853,6 +928,20 @@ bool tevent_req_is_in_progress(struct tevent_req *req); bool tevent_req_poll(struct tevent_req *req, struct tevent_context *ev); +/** + * @brief Get the tevent request and the actual error code you've set. + * + * @param[in] req The tevent request to get the error from. + * + * @param[out] state A pointer to store the tevent request error state. + * + * @param[out] error A pointer to store the error set by tevent_req_error(). + * + * @return True if the function could set error and state, false + * otherwise. + * + * @see tevent_req_error() + */ bool tevent_req_is_error(struct tevent_req *req, enum tevent_req_state *state, uint64_t *error); @@ -866,9 +955,63 @@ bool tevent_req_is_error(struct tevent_req *req, */ void tevent_req_received(struct tevent_req *req); +/** + * @brief Create a tevent subrequest at a given time. + * + * The idea is that always the same syntax for tevent requests. + * + * @param[in] mem_ctx The talloc memory context to use. + * + * @param[in] ev The event handle to setup the request. + * + * @param[in] wakeup_time The time to wakeup and execute the request. + * + * @return The new subrequest, NULL on error. + * + * Example: + * @code + * static my_callback_wakeup_done(tevent_req *req) + * { + * struct tevent_req *req = tevent_req_callback_data(subreq, + * struct tevent_req); + * bool ok; + * + * ok = tevent_wakeup_recv(subreq); + * TALLOC_FREE(subreq); + * if (!ok) { + * tevent_req_error(req, -1); + * return; + * } + * ... + * } + * @endcode + * + * @code + * subreq = tevent_wakeup_send(mem_ctx, ev, wakeup_time); + * if (tevent_req_nomem(subreq, req)) { + * return false; + * } + * tevent_set_callback(subreq, my_callback_wakeup_done, req); + * @endcode + * + * @see tevent_wakeup_recv() + */ struct tevent_req *tevent_wakeup_send(TALLOC_CTX *mem_ctx, struct tevent_context *ev, struct timeval wakeup_time); + +/** + * @brief Check if the wakeup has been correctly executed. + * + * This function needs to be called in the callback function set after calling + * tevent_wakeup_send(). + * + * @param[in] req The tevent request to check. + * + * @return True on success, false otherwise. + * + * @see tevent_wakeup_recv() + */ bool tevent_wakeup_recv(struct tevent_req *req); /* @} */ -- cgit