Asterisk - The Open Source Telephony Project  21.4.1
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)
37 extern "C" {
38 #endif
39 
40 /*!
41  * \brief A refer structure.
42  *
43  * This is an opaque type that represents a refer.
44  */
45 struct 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  */
102 struct ast_refer *ast_refer_alloc(void);
103 
104 /*!
105  * \brief Destroy an ast_refer
106  *
107  * \retval NULL always.
108  */
109 struct ast_refer *ast_refer_destroy(struct ast_refer *refer);
110 
111 /*!
112  * \brief Bump a refer's ref count
113  */
114 struct 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  */
122 int __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  */
131 int __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  */
140 int __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  */
149 int 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  */
157 int __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  */
166 int __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  */
180 int 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  */
191 char *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  */
205 const 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  */
216 const 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  */
226 const 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  */
236 const 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  */
245 int 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  */
255 const 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  */
265 const 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  */
276 int 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  */
289 struct ast_refer_var_iterator *ast_refer_var_iterator_init(const struct ast_refer *refer);
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  */
304 int 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  */
310 void ast_refer_var_iterator_destroy(struct ast_refer_var_iterator *iter);
311 
312 /*!
313  * \brief Unref a refer var from inside an iterator loop
314  */
315 void ast_refer_var_unref_current(struct ast_refer_var_iterator *iter);
316 
317 /*!
318  * @}
319  */
320 
321 #if defined(__cplusplus) || defined(c_plusplus)
322 }
323 #endif
324 
325 #endif /* __AST_REFER_H__ */
const char * ast_refer_get_var(struct ast_refer *refer, const char *name)
Get the specified variable on the refer.
Definition: refer.c:315
const char * ast_refer_get_to(const struct ast_refer *refer)
Retrieve the destination of this refer.
Definition: refer.c:229
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
A refer.
Definition: refer.c:57
int ast_refer_set_to_self(struct ast_refer *refer, int val)
Set the 'to_self' value of a refer.
Definition: refer.c:191
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
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 * ast_refer_get_endpoint(const struct ast_refer *refer)
Retrieve the endpoint associated with this refer.
Definition: refer.c:244
int ast_refer_send(struct ast_refer *refer)
Send a refer directly to an endpoint.
Definition: refer.c:411
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
int ast_refer_tech_register(const struct ast_refer_tech *tech)
Register a refer technology.
Definition: refer.c:446
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
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
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_set_from(struct ast_refer *refer, const char *fmt,...)
Set the 'from' URI of a refer.
Definition: refer.c:169
void ast_refer_var_iterator_destroy(struct ast_refer_var_iterator *iter)
Destroy a refer variable iterator.
Definition: refer.c:376
int ast_refer_set_tech(struct ast_refer *refer, const char *fmt,...)
Set the technology associated with this refer.
Definition: refer.c:197
const char *const name
Name of this refer technology.
Definition: refer.h:61
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
int ast_refer_get_to_self(const struct ast_refer *refer)
Retrieve the "to_self" value of this refer.
Definition: refer.c:234
const ast_string_field tech
Definition: refer.c:69
const char * ast_refer_get_from(const struct ast_refer *refer)
Retrieve the source of this refer.
Definition: refer.c:224
struct ast_refer * ast_refer_destroy(struct ast_refer *refer)
Destroy an ast_refer.
Definition: refer.c:152
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_endpoint(struct ast_refer *refer, const char *fmt,...)
Set the technology's endpoint associated with this refer.
Definition: refer.c:208
int ast_refer_tech_unregister(const struct ast_refer_tech *tech)
Unregister a refer technology.
Definition: refer.c:490
const char * ast_refer_get_tech(const struct ast_refer *refer)
Retrieve the technology associated with this refer.
Definition: refer.c:239
struct ast_refer * ast_refer_alloc(void)
Allocate a refer.
Definition: refer.c:122