The FreeRADIUS server $Id: 15bac2a4c627c01d1aa2047687b3418955ac7f00 $
Loading...
Searching...
No Matches
function.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: 767841b615062ab5e2821f1fd4f7d33b97f43f69 $
20 *
21 * @file unlang/function.h
22 * @brief Declarations for generic unlang functions.
23 *
24 * These are a useful alternative to module methods for library code.
25 * They're more light weight, and don't require instance data lookups
26 * to function.
27 *
28 * @copyright 2021 The FreeRADIUS server project
29 */
30
31#ifdef __cplusplus
32extern "C" {
33#endif
34
35#include <freeradius-devel/unlang/interpret.h>
36#include <freeradius-devel/server/rcode.h>
37#include <freeradius-devel/server/request.h>
38#include <freeradius-devel/server/signal.h>
39
40
41typedef enum {
42 UNLANG_FUNCTION_TYPE_WITH_RESULT, //!< Function with a result.
43 UNLANG_FUNCTION_TYPE_NO_RESULT, //!< Function without a result.
45
46/** A generic function pushed by a module or xlat to functions deeper in the C call stack to create resumption points
47 *
48 * @param[in] p_result The module return code and priority.
49 * @param[in] request The current request.
50 * @param[in,out] uctx Provided by whatever pushed the function. Is opaque to the
51 * interpreter, but should be usable by the function.
52 * All input (args) and output will be done using this structure.
53 * @return an #unlang_action_t.
54 */
55typedef unlang_action_t (*unlang_function_with_result_t)(unlang_result_t *p_result, request_t *request, void *uctx);
56
57/** A generic function pushed by a module or xlat to functions deeper in the C call stack to create resumption points
58 *
59 * @note Returning UNLANG_ACTION_FAIL has an identical effect to returning UNLANG_ACTION_CALCULATE_RESULT
60 * and will not be visible to the caller.
61 *
62 * @param[in] request The current request.
63 * @param[in,out] uctx Provided by whatever pushed the function. Is opaque to the
64 * interpreter, but should be usable by the function.
65 * All input (args) and output will be done using this structure.
66 * @return an #unlang_action_t.
67 */
68typedef unlang_action_t (*unlang_function_no_result_t)(request_t *request, void *uctx);
69
70/** Function to call if the request was signalled
71 *
72 * @param[in] request The current request.
73 * @param[in] action We're being signalled with.
74 * @param[in,out] uctx Provided by whatever pushed the function. Is opaque to the
75 * interpreter, but should be usable by the function.
76 * All input (args) and output will be done using this structure.
77 */
78typedef void (*unlang_function_signal_t)(request_t *request, fr_signal_t action, void *uctx);
79
80int unlang_function_clear(request_t *request) CC_HINT(warn_unused_result);
81
82/** Set a new signal function for an existing function frame
83 *
84 * The function frame being modified must be at the top of the stack.
85 *
86 * @param[in] _request The current request.
87 * @param[in] _signal The signal function to set.
88 * @param[in] _sigmask Signals to block.
89 * @return
90 * - 0 on success.
91 * - -1 on failure.
92 */
93#define unlang_function_signal_set(_request, _signal, _sigmask) \
94 _unlang_function_signal_set(_request, _signal, _sigmask, STRINGIFY(_signal))
95int _unlang_function_signal_set(request_t *request, unlang_function_signal_t signal, fr_signal_t sigmask, char const *name)
96 CC_HINT(warn_unused_result);
97
98/** Set a new repeat function for an existing function frame
99 *
100 * The function frame being modified must be at the top of the stack.
101 *
102 * @param[in] _request The current request.
103 * @param[in] _repeat the repeat function to set.
104 * @return
105 * - 0 on success.
106 * - -1 on failure.
107 */
108#define unlang_function_repeat_set(_request, _repeat) \
109 _Generic((&(_repeat)), \
110 unlang_function_with_result_t: _unlang_function_repeat_set(_request,\
111 (void *)(_repeat), \
112 STRINGIFY(_repeat), \
113 UNLANG_FUNCTION_TYPE_WITH_RESULT), \
114 unlang_function_no_result_t: _unlang_function_repeat_set(_request,\
115 (void *)(_repeat), \
116 STRINGIFY(_repeat), \
117 UNLANG_FUNCTION_TYPE_NO_RESULT) \
118 )
119int _unlang_function_repeat_set(request_t *request, void *repeat, char const *name, unlang_function_type_t type)
120 CC_HINT(warn_unused_result);
121
122/** Push a generic function onto the unlang stack that produces a result
123 *
124 * These can be pushed by any other type of unlang op to allow a submodule or function
125 * deeper in the C call stack to establish a new resumption point.
126 *
127 * @note If you're pushing a function onto the stack to resume execution in a module, you're probably
128 * doing it wrong. Use unlang_module_yield() instead, and change the process function for the
129 * module.
130 *
131 * @param[in] _result_p Where to write the result.
132 * @param[in] _request The current request.
133 * @param[in] _func to call going up the stack.
134 * @param[in] _repeat function to call going back down the stack (may be NULL).
135 * This may be the same as func.
136 * @param[in] _signal function to call if the request is signalled.
137 * @param[in] _sigmask Signals to block.
138 * @param[in] _top_frame Return out of the unlang interpreter when popping this frame.
139 * @param[in] _uctx to pass to func(s).
140 * @return
141 * - UNLANG_ACTION_PUSHED_CHILD on success.
142 * - UNLANG_ACTION_FAIL on failure.
143 */
144#define unlang_function_push_with_result(_result_p, _request, _func, _repeat, _signal, _sigmask, _top_frame, _uctx) \
145 _unlang_function_push_with_result(_result_p, _request, \
146 _func, STRINGIFY(_func), \
147 _repeat, STRINGIFY(_repeat), \
148 _signal, _sigmask, STRINGIFY(_signal), \
149 _top_frame, _uctx)
150
152 request_t *request,
153 unlang_function_with_result_t func, char const *func_name,
154 unlang_function_with_result_t repeat, char const *repeat_name,
155 unlang_function_signal_t signal, fr_signal_t sigmask, char const *signal_name,
156 bool top_frame, void *uctx) CC_HINT(warn_unused_result);
157
158/** Push a generic function onto the unlang stack
159 *
160 * These can be pushed by any other type of unlang op to allow a submodule or function
161 * deeper in the C call stack to establish a new resumption point.
162 *
163 * @note If you're pushing a function onto the stack to resume execution in a module, you're probably
164 * doing it wrong. Use unlang_module_yield() instead, and change the process function for the
165 * module.
166 *
167 * @param[in] _request The current request.
168 * @param[in] _func to call going up the stack.
169 * @param[in] _repeat function to call going back down the stack (may be NULL).
170 * This may be the same as func.
171 * @param[in] _signal function to call if the request is signalled.
172 * @param[in] _sigmask Signals to block.
173 * @param[in] _top_frame Return out of the unlang interpreter when popping this frame.
174 * @param[in] _uctx to pass to func(s).
175 * @return
176 * - UNLANG_ACTION_PUSHED_CHILD on success.
177 * - UNLANG_ACTION_FAIL on failure.
178 */
179#define unlang_function_push(_request, _func, _repeat, _signal, _sigmask, _top_frame, _uctx) \
180 _unlang_function_push_no_result(_request, \
181 _func, STRINGIFY(_func), \
182 _repeat, STRINGIFY(_repeat), \
183 _signal, _sigmask, STRINGIFY(_signal), \
184 _top_frame, _uctx)
185
187 unlang_function_no_result_t func, char const *func_name,
188 unlang_function_no_result_t repeat, char const *repeat_name,
189 unlang_function_signal_t signal, fr_signal_t sigmask, char const *signal_name,
190 bool top_frame, void *uctx) CC_HINT(warn_unused_result);
191#ifdef __cplusplus
192}
193#endif
unlang_action_t
Returned by unlang_op_t calls, determine the next action of the interpreter.
Definition action.h:35
unlang_function_type_t
Definition function.h:41
@ UNLANG_FUNCTION_TYPE_NO_RESULT
Function without a result.
Definition function.h:43
@ UNLANG_FUNCTION_TYPE_WITH_RESULT
Function with a result.
Definition function.h:42
void(* unlang_function_signal_t)(request_t *request, fr_signal_t action, void *uctx)
Function to call if the request was signalled.
Definition function.h:78
int unlang_function_clear(request_t *request)
Clear pending repeat function calls, and remove the signal handler.
Definition function.c:310
unlang_action_t(* unlang_function_no_result_t)(request_t *request, void *uctx)
A generic function pushed by a module or xlat to functions deeper in the C call stack to create resum...
Definition function.h:68
int _unlang_function_repeat_set(request_t *request, void *repeat, char const *name, unlang_function_type_t type)
Set a new repeat function for an existing function frame.
Definition function.c:383
unlang_action_t _unlang_function_push_with_result(unlang_result_t *p_result, request_t *request, unlang_function_with_result_t func, char const *func_name, unlang_function_with_result_t repeat, char const *repeat_name, unlang_function_signal_t signal, fr_signal_t sigmask, char const *signal_name, bool top_frame, void *uctx)
Push a generic function onto the unlang stack with a result.
Definition function.c:488
int _unlang_function_signal_set(request_t *request, unlang_function_signal_t signal, fr_signal_t sigmask, char const *name)
Set a new signal function for an existing function frame.
Definition function.c:344
unlang_action_t _unlang_function_push_no_result(request_t *request, unlang_function_no_result_t func, char const *func_name, unlang_function_no_result_t repeat, char const *repeat_name, unlang_function_signal_t signal, fr_signal_t sigmask, char const *signal_name, bool top_frame, void *uctx)
Push a generic function onto the unlang stack.
Definition function.c:539
unlang_action_t(* unlang_function_with_result_t)(unlang_result_t *p_result, request_t *request, void *uctx)
A generic function pushed by a module or xlat to functions deeper in the C call stack to create resum...
Definition function.h:55
static char const * name
fr_signal_t
Signals that can be generated/processed by request signal handlers.
Definition signal.h:38
fr_aka_sim_id_type_t type