The FreeRADIUS server $Id: 15bac2a4c627c01d1aa2047687b3418955ac7f00 $
Loading...
Searching...
No Matches
module.h
Go to the documentation of this file.
1#pragma once
2/*
3 * This program is free software; you can redistribute it and/or modify
4 * it under the terms of the GNU General Public License as published by
5 * the Free Software Foundation; either version 2, or (at your option)
6 * any later version.
7 *
8 * This program is distributed in the hope that it will be useful,
9 * but WITHOUT ANY WARRANTY; without even the implied warranty of
10 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11 * GNU General Public License for more details.
12 *
13 * You should have received a copy of the GNU General Public License
14 * along with this program; if not, write to the Free Software Foundation,
15 * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
16 */
17
18/**
19 * $Id: bf4ddb3aa7fde6807d6c7f233c27f3ee739516bb $
20 *
21 * @file unlang/module.h
22 *
23 * @brief Functions to allow modules to push resumption frames onto the stack
24 * and inform the interpreter about the conditions they need to be
25 * resumed under (usually an I/O event or timer event).
26 *
27 * @copyright 2016-2019 The FreeRADIUS server project
28 */
29#ifdef __cplusplus
30extern "C" {
31#endif
32
33#include <freeradius-devel/server/module.h>
34#include <freeradius-devel/server/module_rlm.h>
35#include <freeradius-devel/server/rcode.h>
36#include <freeradius-devel/unlang/interpret.h>
37#include <freeradius-devel/unlang/subrequest.h>
38#include <freeradius-devel/unlang/tmpl.h>
39
40/** A callback when a retry happens
41 *
42 * Used when a module needs wait for an event.
43 * Typically the callback is set, and then the module returns unlang_module_yield().
44 *
45 * @note The callback is automatically removed on unlang_interpret_mark_runnable(), i.e. if an event
46 * on a registered FD occurs before the timeout event fires.
47 *
48 * @param[in] mctx calling context for the module.
49 * Contains global, thread-specific, and call-specific data for a module.
50 * @param[in] request the request.
51 * @param[in] retry retry status. "now" is in retry->updated
52 */
53typedef void (*unlang_module_retry_t)(module_ctx_t const *mctx, request_t *request, fr_retry_t const *retry);
54
55/** A callback when the FD is ready for reading
56 *
57 * Used when a module needs to read from an FD. Typically the callback is set, and then the
58 * module returns unlang_module_yield().
59 *
60 * @note The callback is automatically removed on unlang_interpret_mark_runnable(), so
61 *
62 * @param[in] mctx calling context for the module.
63 * Contains global, thread-specific, and call-specific data for a module.
64 * @param[in] request the current request.
65 * @param[in] fd the file descriptor.
66 */
67typedef void (*unlang_module_fd_event_t)(module_ctx_t const *mctx, request_t *request, int fd);
68
69/** A callback when the request gets a fr_signal_t.
70 *
71 * A module may call unlang_yeild(), but still need to do something on FR_SIGNAL_DUP. If so, it's
72 * set here.
73 *
74 * @note The callback is automatically removed on unlang_interpret_mark_runnable().
75 *
76 * @param[in] mctx calling context for the module.
77 * Contains global, thread-specific, and call-specific data for a module.
78 * @param[in] request The current request.
79 * @param[in] action which is signalling the request.
80 */
81typedef void (*unlang_module_signal_t)(module_ctx_t const *mctx, request_t *request, fr_signal_t action);
82
83int unlang_module_push(unlang_result_t *p_result, request_t *request,
84 module_instance_t *module_instance, module_method_t method, bool top_frame)
85 CC_HINT(warn_unused_result) CC_HINT(nonnull(2,3,4));
86
88
90 request_t *request, CONF_SECTION *subcs,
91 rlm_rcode_t default_rcode,
92 module_method_t resume,
93 unlang_module_signal_t signal, fr_signal_t sigmask, void *rctx);
94
95unlang_action_t unlang_module_yield_to_xlat(TALLOC_CTX *ctx, unlang_result_t *p_result, fr_value_box_list_t *out,
96 request_t *request, xlat_exp_head_t const *xlat,
97 module_method_t resume,
98 unlang_module_signal_t signal, fr_signal_t sigmask, void *rctx);
99
100unlang_action_t unlang_module_yield_to_tmpl(TALLOC_CTX *ctx, fr_value_box_list_t *out,
101 request_t *request, tmpl_t const *vpt,
103 module_method_t resume,
104 unlang_module_signal_t signal, fr_signal_t sigmask, void *rctx);
105
106void unlang_module_retry_now(module_ctx_t const *mctx, request_t *request) CC_HINT(nonnull);
107
109 unlang_module_signal_t signal, fr_signal_t sigmask, void *rctx,
110 fr_retry_config_t const *retry_cfg);
111
113 module_method_t resume,
114 unlang_module_signal_t signal, fr_signal_t sigmask, void *rctx);
115
116#ifdef __cplusplus
117}
118#endif
unlang_action_t
Returned by unlang_op_t calls, determine the next action of the interpreter.
Definition action.h:35
va_list args
Definition acutest.h:770
A section grouping multiple CONF_PAIR.
Definition cf_priv.h:101
Temporary structure to hold arguments for module calls.
Definition module_ctx.h:41
rlm_rcode_t
Return codes indicating the result of the module call.
Definition rcode.h:40
unlang_action_t(* module_method_t)(unlang_result_t *p_result, module_ctx_t const *mctx, request_t *request)
Module section callback.
Definition module.h:69
Module instance data.
Definition module.h:285
static fr_slen_t vpt
Definition tmpl.h:1269
fr_signal_t
Signals that can be generated/processed by request signal handlers.
Definition signal.h:38
int unlang_module_set_resume(request_t *request, module_method_t resume)
Change the resume function of a module.
Definition module.c:129
unlang_action_t unlang_module_yield_to_xlat(TALLOC_CTX *ctx, unlang_result_t *p_result, fr_value_box_list_t *out, request_t *request, xlat_exp_head_t const *xlat, module_method_t resume, unlang_module_signal_t signal, fr_signal_t sigmask, void *rctx)
Push a pre-compiled xlat and resumption state onto the stack for evaluation.
Definition module.c:180
void(* unlang_module_retry_t)(module_ctx_t const *mctx, request_t *request, fr_retry_t const *retry)
A callback when a retry happens.
Definition module.h:53
void(* unlang_module_fd_event_t)(module_ctx_t const *mctx, request_t *request, int fd)
A callback when the FD is ready for reading.
Definition module.h:67
void(* unlang_module_signal_t)(module_ctx_t const *mctx, request_t *request, fr_signal_t action)
A callback when the request gets a fr_signal_t.
Definition module.h:81
unlang_action_t unlang_module_yield_to_retry(request_t *request, module_method_t resume, unlang_module_retry_t retry_cb, unlang_module_signal_t signal, fr_signal_t sigmask, void *rctx, fr_retry_config_t const *retry_cfg)
Yield a request back to the interpreter, with retries.
Definition module.c:372
unlang_action_t unlang_module_yield(request_t *request, module_method_t resume, unlang_module_signal_t signal, fr_signal_t sigmask, void *rctx)
Yield a request back to the interpreter from within a module.
Definition module.c:434
int unlang_module_push(unlang_result_t *p_result, request_t *request, module_instance_t *module_instance, module_method_t method, bool top_frame)
Push a module or submodule onto the stack for evaluation.
Definition module.c:50
void unlang_module_retry_now(module_ctx_t const *mctx, request_t *request)
Run the retry handler.
Definition module.c:301
unlang_action_t unlang_module_yield_to_section(unlang_result_t *p_result, request_t *request, CONF_SECTION *subcs, rlm_rcode_t default_rcode, module_method_t resume, unlang_module_signal_t signal, fr_signal_t sigmask, void *rctx)
Definition module.c:249
unlang_action_t unlang_module_yield_to_tmpl(TALLOC_CTX *ctx, fr_value_box_list_t *out, request_t *request, tmpl_t const *vpt, unlang_tmpl_args_t *args, module_method_t resume, unlang_module_signal_t signal, fr_signal_t sigmask, void *rctx)
Push a pre-compiled tmpl and resumption state onto the stack for evaluation.
Definition module.c:229
Arguments for evaluating different types of tmpls.
Definition tmpl.h:48
int nonnull(2, 5))
static size_t char ** out
Definition value.h:1020