Asterisk - The Open Source Telephony Project GIT-master-0644429
Data Structures | Functions
refer.h File Reference

Out-of-call refer support. More...

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  ast_refer_tech
 A refer technology. More...
 

Functions

struct ast_referast_refer_alloc (void)
 Allocate a refer. More...
 
struct ast_referast_refer_destroy (struct ast_refer *refer)
 Destroy an ast_refer. More...
 
const char * ast_refer_get_endpoint (const struct ast_refer *refer)
 Retrieve the endpoint associated with this refer. More...
 
const char * ast_refer_get_from (const struct ast_refer *refer)
 Retrieve the source of this refer. More...
 
const char * ast_refer_get_refer_to (const struct ast_refer *refer)
 Get the "refer-to" value of a refer. More...
 
const char * ast_refer_get_tech (const struct ast_refer *refer)
 Retrieve the technology associated with this refer. More...
 
const char * ast_refer_get_to (const struct ast_refer *refer)
 Retrieve the destination of this refer. More...
 
int ast_refer_get_to_self (const struct ast_refer *refer)
 Retrieve the "to_self" value of this refer. More...
 
const char * ast_refer_get_var (struct ast_refer *refer, const char *name)
 Get the specified variable on the refer. More...
 
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. More...
 
struct ast_referast_refer_ref (struct ast_refer *refer)
 Bump a refer's ref count. More...
 
int ast_refer_send (struct ast_refer *refer)
 Send a refer directly to an endpoint. More...
 
int ast_refer_set_endpoint (struct ast_refer *refer, const char *fmt,...)
 Set the technology's endpoint associated with this refer. More...
 
int ast_refer_set_from (struct ast_refer *refer, const char *fmt,...)
 Set the 'from' URI of a refer. More...
 
int ast_refer_set_refer_to (struct ast_refer *refer, const char *fmt,...)
 Set the 'refer_to' URI of a refer. More...
 
int ast_refer_set_tech (struct ast_refer *refer, const char *fmt,...)
 Set the technology associated with this refer. More...
 
int ast_refer_set_to (struct ast_refer *refer, const char *fmt,...)
 Set the 'to' URI of a refer. More...
 
int ast_refer_set_to_self (struct ast_refer *refer, int val)
 Set the 'to_self' value of a refer. More...
 
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. More...
 
int ast_refer_tech_register (const struct ast_refer_tech *tech)
 Register a refer technology. More...
 
int ast_refer_tech_unregister (const struct ast_refer_tech *tech)
 Unregister a refer technology. More...
 
void ast_refer_var_iterator_destroy (struct ast_refer_var_iterator *iter)
 Destroy a refer variable iterator. More...
 
struct ast_refer_var_iteratorast_refer_var_iterator_init (const struct ast_refer *refer)
 Create a new refer variable iterator. More...
 
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. More...
 
void ast_refer_var_unref_current (struct ast_refer_var_iterator *iter)
 Unref a refer var from inside an iterator loop. More...
 

Detailed Description

Out-of-call refer support.

Author
Maximilian Fridrich m.fri.nosp@m.dric.nosp@m.h@com.nosp@m.mend.nosp@m..com

The purpose of this API is to provide support for refers that are not session based. The refers are passed into the Asterisk core to be routed through the dialplan or another interface and potentially sent back out through a refer technology that has been registered through this API.

Definition in file refer.h.

Function Documentation

◆ ast_refer_alloc()

struct ast_refer * ast_refer_alloc ( void  )

Allocate a refer.

Allocate a refer for the purposes of passing it into the Asterisk core to be routed through the dialplan. This refer must be destroyed using ast_refer_destroy().

Returns
A refer object. This function will return NULL if an allocation error occurs.

Definition at line 122 of file refer.c.

123{
124 struct ast_refer *refer;
125
126 if (!(refer = ao2_alloc_options(sizeof(*refer), refer_destructor, AO2_ALLOC_OPT_LOCK_NOLOCK))) {
127 return NULL;
128 }
129
130 if (ast_string_field_init(refer, 128)) {
131 ao2_ref(refer, -1);
132 return NULL;
133 }
134
137 if (!refer->vars) {
138 ao2_ref(refer, -1);
139 return NULL;
140 }
141 refer->to_self = 0;
142
143 return refer;
144}
@ AO2_ALLOC_OPT_LOCK_NOLOCK
Definition: astobj2.h:367
@ AO2_ALLOC_OPT_LOCK_MUTEX
Definition: astobj2.h:363
#define ao2_ref(o, delta)
Reference/unreference an object and return the old refcount.
Definition: astobj2.h:459
#define ao2_alloc_options(data_size, destructor_fn, options)
Definition: astobj2.h:404
#define ao2_container_alloc_list(ao2_options, container_options, sort_fn, cmp_fn)
Allocate and initialize a list container.
Definition: astobj2.h:1327
static int refer_data_cmp_fn(void *obj, void *arg, int flags)
Definition: refer.c:82
static void refer_destructor(void *obj)
Definition: refer.c:114
#define NULL
Definition: resample.c:96
#define ast_string_field_init(x, size)
Initialize a field pool and fields.
Definition: stringfields.h:359
A refer.
Definition: refer.c:57
struct ao2_container * vars
Definition: refer.c:73
int to_self
Definition: refer.c:71

References AO2_ALLOC_OPT_LOCK_MUTEX, AO2_ALLOC_OPT_LOCK_NOLOCK, ao2_alloc_options, ao2_container_alloc_list, ao2_ref, ast_string_field_init, NULL, refer_data_cmp_fn(), refer_destructor(), ast_refer::to_self, and ast_refer::vars.

Referenced by send_refer().

◆ ast_refer_destroy()

struct ast_refer * ast_refer_destroy ( struct ast_refer refer)

Destroy an ast_refer.

Return values
NULLalways.

Definition at line 152 of file refer.c.

153{
154 ao2_ref(refer, -1);
155 return NULL;
156}

References ao2_ref, and NULL.

Referenced by refer_data_destroy(), and send_refer().

◆ ast_refer_get_endpoint()

const char * ast_refer_get_endpoint ( const struct ast_refer refer)

Retrieve the endpoint associated with this refer.

Parameters
referThe refer to get the endpoint from
Returns
The endpoint associated with the refer
Return values
NULLor empty string if the refer has no associated endpoint

Definition at line 244 of file refer.c.

245{
246 return refer->endpoint;
247}
const ast_string_field endpoint
Definition: refer.c:69

References ast_refer::endpoint.

◆ ast_refer_get_from()

const char * ast_refer_get_from ( const struct ast_refer refer)

Retrieve the source of this refer.

Parameters
referThe refer to get the soure from
Returns
The source of the refer
Return values
NULLor empty string if the refer has no source

Definition at line 224 of file refer.c.

225{
226 return refer->from;
227}
const ast_string_field from
Definition: refer.c:69

References ast_refer::from.

Referenced by refer_data_create().

◆ ast_refer_get_refer_to()

const char * ast_refer_get_refer_to ( const struct ast_refer refer)

Get the "refer-to" value of a refer.

Note
The return value is valid only as long as the ast_refer is valid. Hold a reference to the refer if you plan on storing the return value.
Parameters
referThe refer to get the "refer-to" value from
Returns
The "refer-to" value of the refer, encoded in UTF-8.

Definition at line 219 of file refer.c.

220{
221 return refer->refer_to;
222}
const ast_string_field refer_to
Definition: refer.c:69

References ast_refer::refer_to.

Referenced by refer_data_create().

◆ ast_refer_get_tech()

const char * ast_refer_get_tech ( const struct ast_refer refer)

Retrieve the technology associated with this refer.

Parameters
referThe refer to get the technology from
Returns
The technology of the refer
Return values
NULLor empty string if the refer has no associated technology

Definition at line 239 of file refer.c.

240{
241 return refer->tech;
242}
const ast_string_field tech
Definition: refer.c:69

References ast_refer::tech.

◆ ast_refer_get_to()

const char * ast_refer_get_to ( const struct ast_refer refer)

Retrieve the destination of this refer.

Parameters
referThe refer to get the destination from
Returns
The destination of the refer
Return values
NULLor empty string if the refer has no destination

Definition at line 229 of file refer.c.

230{
231 return refer->to;
232}
const ast_string_field to
Definition: refer.c:69

References ast_refer::to.

Referenced by refer_data_create(), and sip_refer_send().

◆ ast_refer_get_to_self()

int ast_refer_get_to_self ( const struct ast_refer refer)

Retrieve the "to_self" value of this refer.

Parameters
referThe refer to get the destination from
Returns
The to_self value of the refer

Definition at line 234 of file refer.c.

235{
236 return refer->to_self;
237}

References ast_refer::to_self.

Referenced by refer_data_create().

◆ ast_refer_get_var()

const char * ast_refer_get_var ( struct ast_refer refer,
const char *  name 
)

Get the specified variable on the refer.

Note
The return value is valid only as long as the ast_refer is valid. Hold a reference to the refer if you plan on storing the return value. It is possible to re-set the same refer var name (with ast_refer_set_var_outbound passing the variable name) while holding a pointer to the result of this function.
Parameters
refer
nameName of variable to get
Returns
The value associated with variable "name". NULL if variable not found.

Definition at line 315 of file refer.c.

316{
317 struct refer_data *data;
318 const char *val = NULL;
319
320 if (!(data = refer_data_find(refer->vars, name))) {
321 return NULL;
322 }
323
324 val = data->value;
325 ao2_ref(data, -1);
326
327 return val;
328}
static const char name[]
Definition: format_mp3.c:68
static struct refer_data * refer_data_find(struct ao2_container *vars, const char *name)
Definition: refer.c:262
char * value
Definition: refer.c:49
struct ast_refer * refer
Definition: ast_expr2.c:325

References ao2_ref, name, NULL, refer_data::refer, refer_data_find(), refer_data::value, and ast_refer::vars.

◆ ast_refer_get_var_and_unlink()

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.

Note
The return value must be freed by the caller.
Parameters
refer
nameName of variable to get
Returns
The value associated with variable "name". NULL if variable not found.

Definition at line 267 of file refer.c.

268{
269 struct refer_data *data;
270 char *val = NULL;
271
272 if (!(data = ao2_find(refer->vars, name, OBJ_SEARCH_KEY | OBJ_UNLINK))) {
273 return NULL;
274 }
275
276 val = ast_strdup(data->value);
277 ao2_ref(data, -1);
278
279 return val;
280}
#define ast_strdup(str)
A wrapper for strdup()
Definition: astmm.h:241
#define ao2_find(container, arg, flags)
Definition: astobj2.h:1736
@ OBJ_UNLINK
Definition: astobj2.h:1039
@ OBJ_SEARCH_KEY
The arg parameter is a search key, but is not an object.
Definition: astobj2.h:1101

References ao2_find, ao2_ref, ast_strdup, name, NULL, OBJ_SEARCH_KEY, OBJ_UNLINK, refer_data::refer, refer_data::value, and ast_refer::vars.

Referenced by refer_send().

◆ ast_refer_ref()

struct ast_refer * ast_refer_ref ( struct ast_refer refer)

Bump a refer's ref count.

Definition at line 146 of file refer.c.

147{
148 ao2_ref(refer, 1);
149 return refer;
150}

References ao2_ref.

Referenced by refer_data_create().

◆ ast_refer_send()

int ast_refer_send ( struct ast_refer refer)

Send a refer directly to an endpoint.

Regardless of the return value of this function, this function will take care of ensuring that the refer object is properly destroyed when needed.

Return values
0refer successfully queued to be sent out
non-zerofailure, refer not get sent out.

Definition at line 411 of file refer.c.

412{
413 char *tech_name = NULL;
414 const struct ast_refer_tech *refer_tech;
415 int res = -1;
416
417 if (ast_strlen_zero(refer->to)) {
418 ao2_ref(refer, -1);
419 return -1;
420 }
421
422 tech_name = ast_strdupa(refer->to);
423 tech_name = strsep(&tech_name, ":");
424
427
428 if (!refer_tech) {
429 ast_log(LOG_ERROR, "Unknown refer tech: %s\n", tech_name);
431 ao2_ref(refer, -1);
432 return -1;
433 }
434
435 ao2_lock(refer);
436 res = refer_tech->refer_send(refer);
437 ao2_unlock(refer);
438
440
441 ao2_ref(refer, -1);
442
443 return res;
444}
#define ast_strdupa(s)
duplicate a string in memory from the stack
Definition: astmm.h:298
#define ast_log
Definition: astobj2.c:42
#define ao2_unlock(a)
Definition: astobj2.h:729
#define ao2_lock(a)
Definition: astobj2.h:717
char * strsep(char **str, const char *delims)
#define LOG_ERROR
#define ast_rwlock_rdlock(a)
Definition: lock.h:235
#define ast_rwlock_unlock(a)
Definition: lock.h:234
static ast_rwlock_t refer_techs_lock
Lock for refer_techs vector.
Definition: refer.c:77
static const struct ast_refer_tech * refer_find_by_tech_name(const char *tech_name)
Definition: refer.c:396
static const struct ast_refer_tech refer_tech
static force_inline int attribute_pure ast_strlen_zero(const char *s)
Definition: strings.h:65
A refer technology.
Definition: refer.h:52
int(*const refer_send)(const struct ast_refer *refer)
Send a refer.
Definition: refer.h:73

References ao2_lock, ao2_ref, ao2_unlock, ast_log, ast_rwlock_rdlock, ast_rwlock_unlock, ast_strdupa, ast_strlen_zero(), LOG_ERROR, NULL, refer_find_by_tech_name(), ast_refer_tech::refer_send, refer_tech, refer_techs_lock, strsep(), and ast_refer::to.

Referenced by send_refer().

◆ ast_refer_set_endpoint()

int ast_refer_set_endpoint ( struct ast_refer refer,
const char *  fmt,
  ... 
)

Set the technology's endpoint associated with this refer.

Return values
0success
-1failure

Definition at line 208 of file refer.c.

209{
210 va_list ap;
211
212 va_start(ap, fmt);
213 ast_string_field_build_va(refer, endpoint, fmt, ap);
214 va_end(ap);
215
216 return 0;
217}
#define ast_string_field_build_va(x, field, fmt, args)
Set a field to a complex (built) value.
Definition: stringfields.h:591

References ast_string_field_build_va, and ast_refer::endpoint.

◆ ast_refer_set_from()

int ast_refer_set_from ( struct ast_refer refer,
const char *  fmt,
  ... 
)

Set the 'from' URI of a refer.

Return values
0success
-1failure

Definition at line 169 of file refer.c.

170{
171 va_list ap;
172
173 va_start(ap, fmt);
174 ast_string_field_build_va(refer, from, fmt, ap);
175 va_end(ap);
176
177 return 0;
178}

References ast_string_field_build_va, and ast_refer::from.

Referenced by send_refer().

◆ ast_refer_set_refer_to()

int ast_refer_set_refer_to ( struct ast_refer refer,
const char *  fmt,
  ... 
)

Set the 'refer_to' URI of a refer.

Return values
0success
-1failure

Definition at line 180 of file refer.c.

181{
182 va_list ap;
183
184 va_start(ap, fmt);
185 ast_string_field_build_va(refer, refer_to, fmt, ap);
186 va_end(ap);
187
188 return 0;
189}

References ast_string_field_build_va, and ast_refer::refer_to.

Referenced by send_refer().

◆ ast_refer_set_tech()

int ast_refer_set_tech ( struct ast_refer refer,
const char *  fmt,
  ... 
)

Set the technology associated with this refer.

Return values
0success
-1failure

Definition at line 197 of file refer.c.

198{
199 va_list ap;
200
201 va_start(ap, fmt);
202 ast_string_field_build_va(refer, tech, fmt, ap);
203 va_end(ap);
204
205 return 0;
206}

References ast_string_field_build_va, and ast_refer::tech.

◆ ast_refer_set_to()

int ast_refer_set_to ( struct ast_refer refer,
const char *  fmt,
  ... 
)

Set the 'to' URI of a refer.

Return values
0success
-1failure

Definition at line 158 of file refer.c.

159{
160 va_list ap;
161
162 va_start(ap, fmt);
163 ast_string_field_build_va(refer, to, fmt, ap);
164 va_end(ap);
165
166 return 0;
167}

References ast_string_field_build_va, and ast_refer::to.

Referenced by send_refer().

◆ ast_refer_set_to_self()

int ast_refer_set_to_self ( struct ast_refer refer,
int  val 
)

Set the 'to_self' value of a refer.

Return values
0success
-1failure

Definition at line 191 of file refer.c.

192{
193 refer->to_self = val;
194 return 0;
195}

References ast_refer::to_self.

Referenced by send_refer().

◆ ast_refer_set_var_outbound()

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.

Note
Setting a variable that already exists overwrites the existing variable value
Parameters
refer
nameName of variable to set
valueValue of variable to set
Return values
0success
-1failure

Definition at line 310 of file refer.c.

311{
312 return refer_set_var_full(refer, name, value);
313}
static int refer_set_var_full(struct ast_refer *refer, const char *name, const char *value)
Definition: refer.c:282
int value
Definition: syslog.c:37

References name, refer_data::refer, refer_set_var_full(), and value.

Referenced by send_refer().

◆ ast_refer_tech_register()

int ast_refer_tech_register ( const struct ast_refer_tech tech)

Register a refer technology.

Return values
0success
non-zerofailure

Definition at line 446 of file refer.c.

447{
448 const struct ast_refer_tech *match;
449
451
453 if (match) {
454 ast_log(LOG_ERROR, "Refer technology already registered for '%s'\n",
455 tech->name);
457 return -1;
458 }
459
460 if (AST_VECTOR_APPEND(&refer_techs, tech)) {
461 ast_log(LOG_ERROR, "Failed to register refer technology for '%s'\n",
462 tech->name);
464 return -1;
465 }
466 ast_verb(5, "Refer technology '%s' registered.\n", tech->name);
467
469
470 return 0;
471}
static int match(struct ast_sockaddr *addr, unsigned short callno, unsigned short dcallno, const struct chan_iax2_pvt *cur, int check_dcallno)
Definition: chan_iax2.c:2362
#define ast_verb(level,...)
#define ast_rwlock_wrlock(a)
Definition: lock.h:236
struct @381 refer_techs
Vector of refer technologies.
const char *const name
Name of this refer technology.
Definition: refer.h:61
#define AST_VECTOR_APPEND(vec, elem)
Append an element to a vector, growing the vector if needed.
Definition: vector.h:256

References ast_log, ast_rwlock_unlock, ast_rwlock_wrlock, AST_VECTOR_APPEND, ast_verb, LOG_ERROR, match(), ast_refer_tech::name, refer_find_by_tech_name(), refer_techs, and refer_techs_lock.

Referenced by load_module().

◆ ast_refer_tech_unregister()

int ast_refer_tech_unregister ( const struct ast_refer_tech tech)

Unregister a refer technology.

Return values
0success
non-zerofailure

Definition at line 490 of file refer.c.

491{
492 int match;
493
498
499 if (match) {
500 ast_log(LOG_ERROR, "No '%s' refer technology found.\n", tech->name);
501 return -1;
502 }
503
504 ast_verb(5, "Refer technology '%s' unregistered.\n", tech->name);
505
506 return 0;
507}
static int refer_tech_cmp(const struct ast_refer_tech *vec_elem, const struct ast_refer_tech *srch)
Comparison callback for ast_refer_tech vector removal.
Definition: refer.c:482
#define AST_VECTOR_ELEM_CLEANUP_NOOP(elem)
Vector element cleanup that does nothing.
Definition: vector.h:571
#define AST_VECTOR_REMOVE_CMP_UNORDERED(vec, value, cmp, cleanup)
Remove an element from a vector that matches the given comparison.
Definition: vector.h:488

References ast_log, ast_rwlock_unlock, ast_rwlock_wrlock, AST_VECTOR_ELEM_CLEANUP_NOOP, AST_VECTOR_REMOVE_CMP_UNORDERED, ast_verb, LOG_ERROR, match(), ast_refer_tech::name, refer_tech_cmp(), refer_techs, and refer_techs_lock.

Referenced by load_module().

◆ ast_refer_var_iterator_destroy()

void ast_refer_var_iterator_destroy ( struct ast_refer_var_iterator iter)

Destroy a refer variable iterator.

Parameters
iterIterator to be destroyed

Definition at line 376 of file refer.c.

377{
378 if (iter) {
381 ast_free(iter);
382 }
383}
#define ast_free(a)
Definition: astmm.h:180
void ao2_iterator_destroy(struct ao2_iterator *iter)
Destroy a container iterator.
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
struct ao2_iterator iter
Definition: refer.c:331

References ao2_iterator_destroy(), ast_free, ast_refer_var_unref_current(), and ast_refer_var_iterator::iter.

Referenced by vars_to_headers().

◆ ast_refer_var_iterator_init()

struct ast_refer_var_iterator * ast_refer_var_iterator_init ( const struct ast_refer refer)

Create a new refer variable iterator.

Parameters
referA refer whose variables are to be iterated over
Returns
An opaque pointer to the new iterator

Definition at line 335 of file refer.c.

336{
338
339 iter = ast_calloc(1, sizeof(*iter));
340 if (!iter) {
341 return NULL;
342 }
343
344 iter->iter = ao2_iterator_init(refer->vars, 0);
345
346 return iter;
347}
#define ast_calloc(num, len)
A wrapper for calloc()
Definition: astmm.h:202
struct ao2_iterator ao2_iterator_init(struct ao2_container *c, int flags) attribute_warn_unused_result
Create an iterator for a container.

References ao2_iterator_init(), ast_calloc, ast_refer_var_iterator::iter, NULL, and ast_refer::vars.

Referenced by vars_to_headers().

◆ ast_refer_var_iterator_next()

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.

Parameters
iterAn iterator created with ast_refer_var_iterator_init
nameA pointer to the name result pointer
valueA pointer to the value result pointer
Note
The refcount to iter->current_used must be decremented by the caller by calling ast_refer_var_unref_current.
Return values
0No more entries
1Valid entry

Definition at line 349 of file refer.c.

350{
351 struct refer_data *data;
352
353 if (!iter) {
354 return 0;
355 }
356
357 data = ao2_iterator_next(&iter->iter);
358 if (!data) {
359 return 0;
360 }
361
362 *name = data->name;
363 *value = data->value;
364
365 iter->current_used = data;
366
367 return 1;
368}
#define ao2_iterator_next(iter)
Definition: astobj2.h:1911
struct refer_data * current_used
Definition: refer.c:332
char * name
Definition: refer.c:47

References ao2_iterator_next, ast_refer_var_iterator::current_used, ast_refer_var_iterator::iter, name, refer_data::name, refer_data::value, and value.

Referenced by vars_to_headers().

◆ ast_refer_var_unref_current()

void ast_refer_var_unref_current ( struct ast_refer_var_iterator iter)

Unref a refer var from inside an iterator loop.

Definition at line 370 of file refer.c.

371{
373 iter->current_used = NULL;
374}
#define ao2_cleanup(obj)
Definition: astobj2.h:1934

References ao2_cleanup, ast_refer_var_iterator::current_used, and NULL.

Referenced by ast_refer_var_iterator_destroy(), and vars_to_headers().