refer.h File Reference

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

#include "asterisk/vector.h"
#include "asterisk/frame.h"

Include dependency graph for refer.h:

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

Go to the source code of this file.

Data Structures
struct	ast_refer_param
struct	ast_refer_params
struct	ast_refer_tech
	A refer technology. More...

Functions
struct ast_refer *	ast_refer_alloc (void)
	Allocate a refer. More...
struct ast_refer *	ast_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...
int	ast_refer_notify_transfer_request (struct ast_channel *originating_chan, const char *referred_by, const char *exten, const char *protocol_id, struct ast_channel *dest, struct ast_refer_params *params, enum ast_control_transfer state)
	Notify a transfer request. More...
struct ast_refer *	ast_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_iterator *	ast_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 124 of file refer.c.

{
    struct ast_refer *refer;
 
    if (!(refer = ao2_alloc_options(sizeof(*refer), refer_destructor, AO2_ALLOC_OPT_LOCK_NOLOCK))) {
        return NULL;
    }
 
    if (ast_string_field_init(refer, 128)) {
        ao2_ref(refer, -1);
        return NULL;
    }
 
    refer->vars = ao2_container_alloc_list(AO2_ALLOC_OPT_LOCK_MUTEX, 0,
        NULL, refer_data_cmp_fn);
    if (!refer->vars) {
        ao2_ref(refer, -1);
        return NULL;
    }
    refer->to_self = 0;
 
    return refer;
}

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

NULL

always.

Definition at line 154 of file refer.c.

{
    ao2_ref(refer, -1);
    return NULL;
}

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

refer

The refer to get the endpoint from

Returns

The endpoint associated with the refer

Return values

NULL	or empty string if the refer has no associated endpoint

Definition at line 246 of file refer.c.

{
    return refer->endpoint;
}

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

refer

The refer to get the soure from

Returns

The source of the refer

Return values

NULL	or empty string if the refer has no source

Definition at line 226 of file refer.c.

{
    return refer->from;
}

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

refer

The refer to get the "refer-to" value from

Returns

The "refer-to" value of the refer, encoded in UTF-8.

Definition at line 221 of file refer.c.

{
    return refer->refer_to;
}

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

refer

The refer to get the technology from

Returns

The technology of the refer

Return values

NULL	or empty string if the refer has no associated technology

Definition at line 241 of file refer.c.

{
    return refer->tech;
}

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

refer

The refer to get the destination from

Returns

The destination of the refer

Return values

NULL	or empty string if the refer has no destination

Definition at line 231 of file refer.c.

{
    return refer->to;
}

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

refer

The refer to get the destination from

Returns

The to_self value of the refer

Definition at line 236 of file refer.c.

{
    return refer->to_self;
}

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
name	Name of variable to get

Returns

The value associated with variable "name". NULL if variable not found.

Definition at line 317 of file refer.c.

{
    struct refer_data *data;
    const char *val = NULL;
 
    if (!(data = refer_data_find(refer->vars, name))) {
        return NULL;
    }
 
    val = data->value;
    ao2_ref(data, -1);
 
    return val;
}

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
name	Name of variable to get

Returns

The value associated with variable "name". NULL if variable not found.

Definition at line 269 of file refer.c.

{
    struct refer_data *data;
    char *val = NULL;
 
    if (!(data = ao2_find(refer->vars, name, OBJ_SEARCH_KEY | OBJ_UNLINK))) {
        return NULL;
    }
 
    val = ast_strdup(data->value);
    ao2_ref(data, -1);
 
    return val;
}

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_notify_transfer_request()

int ast_refer_notify_transfer_request	(	struct ast_channel *	originating_chan,
		const char *	referred_by,
		const char *	exten,
		const char *	protocol_id,
		struct ast_channel *	dest,
		struct ast_refer_params *	params,
		enum ast_control_transfer	state
	)

Notify a transfer request.

Parameters

originating_chan	The channel that received the transfer request
referred_by	Information about the requesting identity
exten	The extension for blind transfers
protocol_id	Technology specific replace indication
dest	The identified replace target for attended requests.
params	List of protocol specific params.
state	The state of the transfer

Definition at line 541 of file refer.c.

{
    RAII_VAR(struct ast_ari_transfer_message *, transfer_message, NULL, ao2_cleanup);
    RAII_VAR(struct stasis_message *, msg, NULL, ao2_cleanup);
    RAII_VAR(struct ast_bridge *, source_bridge, NULL, ao2_cleanup);
    RAII_VAR(struct ast_bridge *, dest_bridge, NULL, ao2_cleanup);
 
    transfer_message = ast_ari_transfer_message_create(source, referred_by, exten, protocol_id, dest, params, state);
    if (!transfer_message) {
        return -1;
    }
    source_bridge = ast_bridge_transfer_acquire_bridge(source);
    if (source_bridge) {
        RAII_VAR(struct ast_channel *, peer, NULL, ast_channel_cleanup);
 
        ast_bridge_lock(source_bridge);
        transfer_message->source_bridge = ast_bridge_get_snapshot(source_bridge);
        peer = ast_bridge_peer_nolock(source_bridge, source);
        if (peer) {
            ast_channel_lock(peer);
            transfer_message->source_peer = ao2_bump(ast_channel_snapshot(peer));
            ast_channel_unlock(peer);
        }
        ast_bridge_unlock(source_bridge);
    }
 
    if (dest) {
        dest_bridge = ast_bridge_transfer_acquire_bridge(dest);
        if (dest_bridge) {
            RAII_VAR(struct ast_channel *, peer, NULL, ast_channel_cleanup);
 
            ast_bridge_lock(dest_bridge);
            transfer_message->dest_bridge = ast_bridge_get_snapshot(dest_bridge);
            peer = ast_bridge_peer_nolock(dest_bridge, dest);
            if (peer) {
                ast_channel_lock(peer);
                transfer_message->dest_peer = ao2_bump(ast_channel_snapshot(peer));
                ast_channel_unlock(peer);
            }
            ast_bridge_unlock(dest_bridge);
        }
    }
 
    msg = stasis_message_create(ast_channel_transfer_request_type(), transfer_message);
    if (msg) {
        ast_channel_lock(source);
        stasis_publish(ast_channel_topic(source), msg);
        ast_channel_unlock(source);
    }
 
    return 0;
}

References ao2_bump, ao2_cleanup, ast_ari_transfer_message_create(), ast_bridge_get_snapshot(), ast_bridge_lock, ast_bridge_peer_nolock(), ast_bridge_transfer_acquire_bridge(), ast_bridge_unlock, ast_channel_cleanup, ast_channel_lock, ast_channel_snapshot(), ast_channel_topic(), ast_channel_transfer_request_type(), ast_channel_unlock, NULL, RAII_VAR, stasis_message_create(), and stasis_publish().

Referenced by ari_notify().

ast_refer_ref()

struct ast_refer * ast_refer_ref

(

struct ast_refer *

refer

)

Bump a refer's ref count.

Definition at line 148 of file refer.c.

{
    ao2_ref(refer, 1);
    return refer;
}

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

0	refer successfully queued to be sent out
non-zero	failure, refer not get sent out.

Definition at line 413 of file refer.c.

{
    char *tech_name = NULL;
    const struct ast_refer_tech *refer_tech;
    int res = -1;
 
    if (ast_strlen_zero(refer->to)) {
        ao2_ref(refer, -1);
        return -1;
    }
 
    tech_name = ast_strdupa(refer->to);
    tech_name = strsep(&tech_name, ":");
 
    ast_rwlock_rdlock(&refer_techs_lock);
    refer_tech = refer_find_by_tech_name(tech_name);
 
    if (!refer_tech) {
        ast_log(LOG_ERROR, "Unknown refer tech: %s\n", tech_name);
        ast_rwlock_unlock(&refer_techs_lock);
        ao2_ref(refer, -1);
        return -1;
    }
 
    ao2_lock(refer);
    res = refer_tech->refer_send(refer);
    ao2_unlock(refer);
 
    ast_rwlock_unlock(&refer_techs_lock);
 
    ao2_ref(refer, -1);
 
    return res;
}

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

0	success
-1	failure

Definition at line 210 of file refer.c.

{
    va_list ap;
 
    va_start(ap, fmt);
    ast_string_field_build_va(refer, endpoint, fmt, ap);
    va_end(ap);
 
    return 0;
}

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

0	success
-1	failure

Definition at line 171 of file refer.c.

{
    va_list ap;
 
    va_start(ap, fmt);
    ast_string_field_build_va(refer, from, fmt, ap);
    va_end(ap);
 
    return 0;
}

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

0	success
-1	failure

Definition at line 182 of file refer.c.

{
    va_list ap;
 
    va_start(ap, fmt);
    ast_string_field_build_va(refer, refer_to, fmt, ap);
    va_end(ap);
 
    return 0;
}

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

0	success
-1	failure

Definition at line 199 of file refer.c.

{
    va_list ap;
 
    va_start(ap, fmt);
    ast_string_field_build_va(refer, tech, fmt, ap);
    va_end(ap);
 
    return 0;
}

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

0	success
-1	failure

Definition at line 160 of file refer.c.

{
    va_list ap;
 
    va_start(ap, fmt);
    ast_string_field_build_va(refer, to, fmt, ap);
    va_end(ap);
 
    return 0;
}

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

0	success
-1	failure

Definition at line 193 of file refer.c.

{
    refer->to_self = val;
    return 0;
}

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
name	Name of variable to set
value	Value of variable to set

Return values

0	success
-1	failure

Definition at line 312 of file refer.c.

{
    return refer_set_var_full(refer, name, value);
}

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

0	success
non-zero	failure

Definition at line 448 of file refer.c.

{
    const struct ast_refer_tech *match;
 
    ast_rwlock_wrlock(&refer_techs_lock);
 
    match = refer_find_by_tech_name(tech->name);
    if (match) {
        ast_log(LOG_ERROR, "Refer technology already registered for '%s'\n",
                tech->name);
        ast_rwlock_unlock(&refer_techs_lock);
        return -1;
    }
 
    if (AST_VECTOR_APPEND(&refer_techs, tech)) {
        ast_log(LOG_ERROR, "Failed to register refer technology for '%s'\n",
                tech->name);
        ast_rwlock_unlock(&refer_techs_lock);
        return -1;
    }
    ast_verb(5, "Refer technology '%s' registered.\n", tech->name);
 
    ast_rwlock_unlock(&refer_techs_lock);
 
    return 0;
}

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

0	success
non-zero	failure

Definition at line 492 of file refer.c.

{
    int match;
 
    ast_rwlock_wrlock(&refer_techs_lock);
    match = AST_VECTOR_REMOVE_CMP_UNORDERED(&refer_techs, tech, refer_tech_cmp,
                                            AST_VECTOR_ELEM_CLEANUP_NOOP);
    ast_rwlock_unlock(&refer_techs_lock);
 
    if (match) {
        ast_log(LOG_ERROR, "No '%s' refer technology found.\n", tech->name);
        return -1;
    }
 
    ast_verb(5, "Refer technology '%s' unregistered.\n", tech->name);
 
    return 0;
}

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

iter	Iterator to be destroyed

Definition at line 378 of file refer.c.

{
    if (iter) {
        ao2_iterator_destroy(&iter->iter);
        ast_refer_var_unref_current(iter);
        ast_free(iter);
    }
}

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

refer

A refer whose variables are to be iterated over

Returns

An opaque pointer to the new iterator

Definition at line 337 of file refer.c.

{
    struct ast_refer_var_iterator *iter;
 
    iter = ast_calloc(1, sizeof(*iter));
    if (!iter) {
        return NULL;
    }
 
    iter->iter = ao2_iterator_init(refer->vars, 0);
 
    return iter;
}

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

iter	An iterator created with ast_refer_var_iterator_init
name	A pointer to the name result pointer
value	A 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

0	No more entries
1	Valid entry

Definition at line 351 of file refer.c.

{
    struct refer_data *data;
 
    if (!iter) {
        return 0;
    }
 
    data = ao2_iterator_next(&iter->iter);
    if (!data) {
        return 0;
    }
 
    *name = data->name;
    *value = data->value;
 
    iter->current_used = data;
 
    return 1;
}

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 372 of file refer.c.

{
    ao2_cleanup(iter->current_used);
    iter->current_used = NULL;
}

References ao2_cleanup, ast_refer_var_iterator::current_used, and NULL.

Referenced by ast_refer_var_iterator_destroy(), and vars_to_headers().