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

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

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.
 
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.
 

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

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.

References AO2_ALLOC_OPT_LOCK_MUTEX, AO2_ALLOC_OPT_LOCK_NOLOCK, ao2_container_alloc_list, ao2_ref, ast_string_field_init, and ast_refer::vars.

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 
136  NULL, refer_data_cmp_fn);
137  if (!refer->vars) {
138  ao2_ref(refer, -1);
139  return NULL;
140  }
141  refer->to_self = 0;
142 
143  return refer;
144 }
A refer.
Definition: refer.c:57
struct ao2_container * vars
Definition: refer.c:73
#define ao2_container_alloc_list(ao2_options, container_options, sort_fn, cmp_fn)
Allocate and initialize a list container.
Definition: astobj2.h:1327
#define ast_string_field_init(x, size)
Initialize a field pool and fields.
Definition: stringfields.h:359
#define ao2_ref(o, delta)
Reference/unreference an object and return the old refcount.
Definition: astobj2.h:459
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.

References ao2_ref.

153 {
154  ao2_ref(refer, -1);
155  return NULL;
156 }
#define ao2_ref(o, delta)
Reference/unreference an object and return the old refcount.
Definition: astobj2.h:459
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.

References ast_refer::endpoint.

245 {
246  return refer->endpoint;
247 }
const ast_string_field endpoint
Definition: refer.c:69
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.

References ast_refer::from.

225 {
226  return refer->from;
227 }
const ast_string_field from
Definition: refer.c:69
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.

References ast_refer::refer_to.

220 {
221  return refer->refer_to;
222 }
const ast_string_field refer_to
Definition: refer.c:69
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.

References ast_refer::tech.

240 {
241  return refer->tech;
242 }
const ast_string_field tech
Definition: refer.c:69
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.

References ast_refer::to.

230 {
231  return refer->to;
232 }
const ast_string_field to
Definition: refer.c:69
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 }
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.

References ao2_ref, and ast_refer::vars.

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 }
struct ao2_container * vars
Definition: refer.c:73
#define ao2_ref(o, delta)
Reference/unreference an object and return the old refcount.
Definition: astobj2.h:459
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.

References ao2_ref, ast_strdup, OBJ_SEARCH_KEY, OBJ_UNLINK, and ast_refer::vars.

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 }
The arg parameter is a search key, but is not an object.
Definition: astobj2.h:1101
struct ao2_container * vars
Definition: refer.c:73
#define ast_strdup(str)
A wrapper for strdup()
Definition: astmm.h:241
#define ao2_ref(o, delta)
Reference/unreference an object and return the old refcount.
Definition: astobj2.h:459
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.

References ao2_ref, ast_strdupa, ast_refer_tech::refer_send, and ast_refer::to.

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 
425  ast_rwlock_rdlock(&refer_techs_lock);
426  refer_tech = refer_find_by_tech_name(tech_name);
427 
428  if (!refer_tech) {
429  ast_log(LOG_ERROR, "Unknown refer tech: %s\n", tech_name);
430  ast_rwlock_unlock(&refer_techs_lock);
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 
439  ast_rwlock_unlock(&refer_techs_lock);
440 
441  ao2_ref(refer, -1);
442 
443  return res;
444 }
A refer technology.
Definition: refer.h:52
int(*const refer_send)(const struct ast_refer *refer)
Send a refer.
Definition: refer.h:73
#define ast_strdupa(s)
duplicate a string in memory from the stack
Definition: astmm.h:298
#define ao2_ref(o, delta)
Reference/unreference an object and return the old refcount.
Definition: astobj2.h:459
const ast_string_field to
Definition: refer.c:69
static ast_rwlock_t refer_techs_lock
Lock for refer_techs vector.
Definition: refer.c:77
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.

References ast_string_field_build_va, and ast_refer::endpoint.

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
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.

References ast_string_field_build_va, and ast_refer::from.

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 }
#define ast_string_field_build_va(x, field, fmt, args)
Set a field to a complex (built) value.
Definition: stringfields.h:591
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.

References ast_string_field_build_va, and ast_refer::refer_to.

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 }
#define ast_string_field_build_va(x, field, fmt, args)
Set a field to a complex (built) value.
Definition: stringfields.h:591
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.

References ast_string_field_build_va, and ast_refer::tech.

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 }
#define ast_string_field_build_va(x, field, fmt, args)
Set a field to a complex (built) value.
Definition: stringfields.h:591
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.

References ast_string_field_build_va, and ast_refer::to.

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 }
#define ast_string_field_build_va(x, field, fmt, args)
Set a field to a complex (built) value.
Definition: stringfields.h:591
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 }
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 }
const char *const name
Name of this refer technology.
Definition: refer.h:61
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.

References AST_VECTOR_APPEND, ast_refer_tech::name, and refer_techs.

447 {
448  const struct ast_refer_tech *match;
449 
450  ast_rwlock_wrlock(&refer_techs_lock);
451 
452  match = refer_find_by_tech_name(tech->name);
453  if (match) {
454  ast_log(LOG_ERROR, "Refer technology already registered for '%s'\n",
455  tech->name);
456  ast_rwlock_unlock(&refer_techs_lock);
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);
463  ast_rwlock_unlock(&refer_techs_lock);
464  return -1;
465  }
466  ast_verb(5, "Refer technology '%s' registered.\n", tech->name);
467 
468  ast_rwlock_unlock(&refer_techs_lock);
469 
470  return 0;
471 }
#define AST_VECTOR_APPEND(vec, elem)
Append an element to a vector, growing the vector if needed.
Definition: vector.h:256
A refer technology.
Definition: refer.h:52
struct @387 refer_techs
Vector of refer technologies.
const char *const name
Name of this refer technology.
Definition: refer.h:61
static ast_rwlock_t refer_techs_lock
Lock for refer_techs vector.
Definition: refer.c:77
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.

References AST_VECTOR_ELEM_CLEANUP_NOOP, AST_VECTOR_REMOVE_CMP_UNORDERED, ast_refer_tech::name, refer_tech_cmp(), and refer_techs.

491 {
492  int match;
493 
494  ast_rwlock_wrlock(&refer_techs_lock);
497  ast_rwlock_unlock(&refer_techs_lock);
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 }
#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
#define AST_VECTOR_ELEM_CLEANUP_NOOP(elem)
Vector element cleanup that does nothing.
Definition: vector.h:571
struct @387 refer_techs
Vector of refer technologies.
const char *const name
Name of this refer technology.
Definition: refer.h:61
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
static ast_rwlock_t refer_techs_lock
Lock for refer_techs vector.
Definition: refer.c:77
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.

References ao2_iterator_destroy(), and ast_refer_var_unref_current().

377 {
378  if (iter) {
379  ao2_iterator_destroy(&iter->iter);
381  ast_free(iter);
382  }
383 }
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 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.

References ao2_iterator_init(), ast_calloc, and ast_refer::vars.

336 {
337  struct ast_refer_var_iterator *iter;
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 }
struct ao2_container * vars
Definition: refer.c:73
#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.
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 }