Asterisk - The Open Source Telephony Project GIT-master-0644429
refer.h
Go to the documentation of this file.
1/*
2 * Asterisk -- An open source telephony toolkit.
3 *
4 * Copyright (C) 2023, Commend International
5 *
6 * Maximilian Fridrich <m.fridrich@commend.com>
7 *
8 * See http://www.asterisk.org for more information about
9 * the Asterisk project. Please do not directly contact
10 * any of the maintainers of this project for assistance;
11 * the project provides a web site, mailing lists and IRC
12 * channels for your use.
13 *
14 * This program is free software, distributed under the terms of
15 * the GNU General Public License Version 2. See the LICENSE file
16 * at the top of the source tree.
17 */
18
19/*!
20 * \file
21 *
22 * \brief Out-of-call refer support
23 *
24 * \author Maximilian Fridrich <m.fridrich@commend.com>
25 *
26 * The purpose of this API is to provide support for refers that
27 * are not session based. The refers are passed into the Asterisk core
28 * to be routed through the dialplan or another interface and potentially
29 * sent back out through a refer technology that has been registered
30 * through this API.
31 */
32
33#ifndef __AST_REFER_H__
34#define __AST_REFER_H__
35
36#if defined(__cplusplus) || defined(c_plusplus)
37extern "C" {
38#endif
39
40/*!
41 * \brief A refer structure.
42 *
43 * This is an opaque type that represents a refer.
44 */
45struct ast_refer;
46
47/*!
48 * \brief A refer technology
49 *
50 * A refer technology is capable of transmitting text refers.
51 */
53 /*!
54 * \brief Name of this refer technology
55 *
56 * This is the name that comes at the beginning of a URI for refers
57 * that should be sent to this refer technology implementation.
58 * For example, refers sent to "pjsip:m.fridrich@commend.com" would be
59 * passed to the ast_refer_tech with a name of "pjsip".
60 */
61 const char * const name;
62 /*!
63 * \brief Send a refer.
64 *
65 * \param refer The refer to send
66 *
67 * The fields of the ast_refer are guaranteed not to change during the
68 * duration of this function call.
69 *
70 * \retval 0 success
71 * \retval non-zero failure
72 */
73 int (* const refer_send)(const struct ast_refer *refer);
74};
75
76/*!
77 * \brief Register a refer technology
78 *
79 * \retval 0 success
80 * \retval non-zero failure
81 */
83
84/*!
85 * \brief Unregister a refer technology.
86 *
87 * \retval 0 success
88 * \retval non-zero failure
89 */
91
92/*!
93 * \brief Allocate a refer.
94 *
95 * Allocate a refer for the purposes of passing it into the Asterisk core
96 * to be routed through the dialplan. This refer must be destroyed using
97 * ast_refer_destroy().
98 *
99 * \return A refer object. This function will return NULL if an allocation
100 * error occurs.
101 */
102struct ast_refer *ast_refer_alloc(void);
103
104/*!
105 * \brief Destroy an ast_refer
106 *
107 * \retval NULL always.
108 */
109struct ast_refer *ast_refer_destroy(struct ast_refer *refer);
110
111/*!
112 * \brief Bump a refer's ref count
113 */
114struct ast_refer *ast_refer_ref(struct ast_refer *refer);
115
116/*!
117 * \brief Set the 'to' URI of a refer
118 *
119 * \retval 0 success
120 * \retval -1 failure
121 */
122int __attribute__((format(printf, 2, 3)))
123 ast_refer_set_to(struct ast_refer *refer, const char *fmt, ...);
124
125/*!
126 * \brief Set the 'from' URI of a refer
127 *
128 * \retval 0 success
129 * \retval -1 failure
130 */
131int __attribute__((format(printf, 2, 3)))
132 ast_refer_set_from(struct ast_refer *refer, const char *fmt, ...);
133
134/*!
135 * \brief Set the 'refer_to' URI of a refer
136 *
137 * \retval 0 success
138 * \retval -1 failure
139 */
140int __attribute__((format(printf, 2, 3)))
141 ast_refer_set_refer_to(struct ast_refer *refer, const char *fmt, ...);
142
143/*!
144 * \brief Set the 'to_self' value of a refer
145 *
146 * \retval 0 success
147 * \retval -1 failure
148 */
149int ast_refer_set_to_self(struct ast_refer *refer, int val);
150
151/*!
152 * \brief Set the technology associated with this refer
153 *
154 * \retval 0 success
155 * \retval -1 failure
156 */
157int __attribute__((format(printf, 2, 3)))
158 ast_refer_set_tech(struct ast_refer *refer, const char *fmt, ...);
159
160/*!
161 * \brief Set the technology's endpoint associated with this refer
162 *
163 * \retval 0 success
164 * \retval -1 failure
165 */
166int __attribute__((format(printf, 2, 3)))
167 ast_refer_set_endpoint(struct ast_refer *refer, const char *fmt, ...);
168
169/*!
170 * \brief Set a variable on the refer being sent to a refer tech directly.
171 * \note Setting a variable that already exists overwrites the existing variable value
172 *
173 * \param refer
174 * \param name Name of variable to set
175 * \param value Value of variable to set
176 *
177 * \retval 0 success
178 * \retval -1 failure
179 */
180int ast_refer_set_var_outbound(struct ast_refer *refer, const char *name, const char *value);
181
182/*!
183 * \brief Get the specified variable on the refer and unlink it from the container of variables
184 * \note The return value must be freed by the caller.
185 *
186 * \param refer
187 * \param name Name of variable to get
188 *
189 * \return The value associated with variable "name". NULL if variable not found.
190 */
191char *ast_refer_get_var_and_unlink(struct ast_refer *refer, const char *name);
192
193/*!
194 * \brief Get the specified variable on the refer
195 * \note The return value is valid only as long as the ast_refer is valid. Hold a reference
196 * to the refer if you plan on storing the return value. It is possible to re-set the
197 * same refer var name (with ast_refer_set_var_outbound passing the variable name)
198 * while holding a pointer to the result of this function.
199 *
200 * \param refer
201 * \param name Name of variable to get
202 *
203 * \return The value associated with variable "name". NULL if variable not found.
204 */
205const char *ast_refer_get_var(struct ast_refer *refer, const char *name);
206
207/*!
208 * \brief Get the "refer-to" value of a refer.
209 * \note The return value is valid only as long as the ast_refer is valid. Hold a reference
210 * to the refer if you plan on storing the return value.
211 *
212 * \param refer The refer to get the "refer-to" value from
213 *
214 * \return The "refer-to" value of the refer, encoded in UTF-8.
215 */
216const char *ast_refer_get_refer_to(const struct ast_refer *refer);
217
218/*!
219 * \brief Retrieve the source of this refer
220 *
221 * \param refer The refer to get the soure from
222 *
223 * \return The source of the refer
224 * \retval NULL or empty string if the refer has no source
225 */
226const char *ast_refer_get_from(const struct ast_refer *refer);
227
228/*!
229 * \brief Retrieve the destination of this refer
230 *
231 * \param refer The refer to get the destination from
232 *
233 * \return The destination of the refer
234 * \retval NULL or empty string if the refer has no destination
235 */
236const char *ast_refer_get_to(const struct ast_refer *refer);
237
238/*!
239 * \brief Retrieve the "to_self" value of this refer
240 *
241 * \param refer The refer to get the destination from
242 *
243 * \return The to_self value of the refer
244 */
245int ast_refer_get_to_self(const struct ast_refer *refer);
246
247/*!
248 * \brief Retrieve the technology associated with this refer
249 *
250 * \param refer The refer to get the technology from
251 *
252 * \return The technology of the refer
253 * \retval NULL or empty string if the refer has no associated technology
254 */
255const char *ast_refer_get_tech(const struct ast_refer *refer);
256
257/*!
258 * \brief Retrieve the endpoint associated with this refer
259 *
260 * \param refer The refer to get the endpoint from
261 *
262 * \return The endpoint associated with the refer
263 * \retval NULL or empty string if the refer has no associated endpoint
264 */
265const char *ast_refer_get_endpoint(const struct ast_refer *refer);
266
267/*!
268 * \brief Send a refer directly to an endpoint.
269 *
270 * Regardless of the return value of this function, this function will take
271 * care of ensuring that the refer object is properly destroyed when needed.
272 *
273 * \retval 0 refer successfully queued to be sent out
274 * \retval non-zero failure, refer not get sent out.
275 */
276int ast_refer_send(struct ast_refer *refer);
277
278/*!
279 * \brief Opaque iterator for refer variables
280 */
282
283/*!
284 * \brief Create a new refer variable iterator
285 * \param refer A refer whose variables are to be iterated over
286 *
287 * \return An opaque pointer to the new iterator
288 */
290
291/*!
292 * \brief Get the next variable name and value
293 *
294 * \param iter An iterator created with ast_refer_var_iterator_init
295 * \param name A pointer to the name result pointer
296 * \param value A pointer to the value result pointer
297 *
298 * \note The refcount to iter->current_used must be decremented by the caller
299 * by calling ast_refer_var_unref_current.
300 *
301 * \retval 0 No more entries
302 * \retval 1 Valid entry
303 */
304int ast_refer_var_iterator_next(struct ast_refer_var_iterator *iter, const char **name, const char **value);
305
306/*!
307 * \brief Destroy a refer variable iterator
308 * \param iter Iterator to be destroyed
309 */
311
312/*!
313 * \brief Unref a refer var from inside an iterator loop
314 */
316
317/*!
318 * @}
319 */
320
321#if defined(__cplusplus) || defined(c_plusplus)
322}
323#endif
324
325#endif /* __AST_REFER_H__ */
static const char name[]
Definition: format_mp3.c:68
void ast_refer_var_unref_current(struct ast_refer_var_iterator *iter)
Unref a refer var from inside an iterator loop.
Definition: refer.c:370
int ast_refer_tech_unregister(const struct ast_refer_tech *tech)
Unregister a refer technology.
Definition: refer.c:490
const char * ast_refer_get_to(const struct ast_refer *refer)
Retrieve the destination of this refer.
Definition: refer.c:229
int ast_refer_var_iterator_next(struct ast_refer_var_iterator *iter, const char **name, const char **value)
Get the next variable name and value.
Definition: refer.c:349
struct ast_refer_var_iterator * ast_refer_var_iterator_init(const struct ast_refer *refer)
Create a new refer variable iterator.
Definition: refer.c:335
struct ast_refer * ast_refer_alloc(void)
Allocate a refer.
Definition: refer.c:122
const char * ast_refer_get_from(const struct ast_refer *refer)
Retrieve the source of this refer.
Definition: refer.c:224
const char * ast_refer_get_var(struct ast_refer *refer, const char *name)
Get the specified variable on the refer.
Definition: refer.c:315
int ast_refer_set_var_outbound(struct ast_refer *refer, const char *name, const char *value)
Set a variable on the refer being sent to a refer tech directly.
Definition: refer.c:310
const char * ast_refer_get_endpoint(const struct ast_refer *refer)
Retrieve the endpoint associated with this refer.
Definition: refer.c:244
char * ast_refer_get_var_and_unlink(struct ast_refer *refer, const char *name)
Get the specified variable on the refer and unlink it from the container of variables.
Definition: refer.c:267
int ast_refer_set_endpoint(struct ast_refer *refer, const char *fmt,...)
Set the technology's endpoint associated with this refer.
Definition: refer.c:208
int ast_refer_set_from(struct ast_refer *refer, const char *fmt,...)
Set the 'from' URI of a refer.
Definition: refer.c:169
struct ast_refer * ast_refer_destroy(struct ast_refer *refer)
Destroy an ast_refer.
Definition: refer.c:152
int ast_refer_set_refer_to(struct ast_refer *refer, const char *fmt,...)
Set the 'refer_to' URI of a refer.
Definition: refer.c:180
const char * ast_refer_get_refer_to(const struct ast_refer *refer)
Get the "refer-to" value of a refer.
Definition: refer.c:219
int ast_refer_set_tech(struct ast_refer *refer, const char *fmt,...)
Set the technology associated with this refer.
Definition: refer.c:197
int ast_refer_tech_register(const struct ast_refer_tech *tech)
Register a refer technology.
Definition: refer.c:446
int ast_refer_set_to_self(struct ast_refer *refer, int val)
Set the 'to_self' value of a refer.
Definition: refer.c:191
int ast_refer_send(struct ast_refer *refer)
Send a refer directly to an endpoint.
Definition: refer.c:411
struct ast_refer * ast_refer_ref(struct ast_refer *refer)
Bump a refer's ref count.
Definition: refer.c:146
int ast_refer_set_to(struct ast_refer *refer, const char *fmt,...)
Set the 'to' URI of a refer.
Definition: refer.c:158
int ast_refer_get_to_self(const struct ast_refer *refer)
Retrieve the "to_self" value of this refer.
Definition: refer.c:234
void ast_refer_var_iterator_destroy(struct ast_refer_var_iterator *iter)
Destroy a refer variable iterator.
Definition: refer.c:376
const char * ast_refer_get_tech(const struct ast_refer *refer)
Retrieve the technology associated with this refer.
Definition: refer.c:239
A refer technology.
Definition: refer.h:52
int(*const refer_send)(const struct ast_refer *refer)
Send a refer.
Definition: refer.h:73
const char *const name
Name of this refer technology.
Definition: refer.h:61
A refer.
Definition: refer.c:57
const ast_string_field tech
Definition: refer.c:69
Definition: ast_expr2.c:325
int value
Definition: syslog.c:37