endpoints.h File Reference

Endpoint abstractions. More...

#include "asterisk/json.h"

Include dependency graph for endpoints.h:

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

Go to the source code of this file.

Enumerations
enum	ast_endpoint_state { AST_ENDPOINT_UNKNOWN , AST_ENDPOINT_OFFLINE , AST_ENDPOINT_ONLINE }
	Valid states for an endpoint. More...

Functions
int	ast_endpoint_add_channel (struct ast_endpoint *endpoint, struct ast_channel *chan)
	Adds a channel to the given endpoint.
struct ast_endpoint *	ast_endpoint_create (const char *tech, const char *resource)
	Create an endpoint struct.
struct ast_endpoint *	ast_endpoint_find_by_id (const char *id)
	Finds the endpoint with the given tech[/resource] id.
const char *	ast_endpoint_get_id (const struct ast_endpoint *endpoint)
	Gets the tech/resource id of the given endpoint.
const char *	ast_endpoint_get_resource (const struct ast_endpoint *endpoint)
	Gets the resource name of the given endpoint.
struct ast_endpoint_snapshot *	ast_endpoint_get_snapshot (struct ast_endpoint *endpoint)
	Gets the latest snapshot of the given endpoint.
enum ast_endpoint_state	ast_endpoint_get_state (const struct ast_endpoint *endpoint)
	Gets the state of the given endpoint.
const char *	ast_endpoint_get_tech (const struct ast_endpoint *endpoint)
	Gets the technology of the given endpoint.
int	ast_endpoint_remove_channel (struct ast_endpoint *endpoint, struct ast_channel *chan)
	Removes a channel from the given endpoint.
void	ast_endpoint_set_max_channels (struct ast_endpoint *endpoint, int max_channels)
	Updates the maximum number of channels an endpoint supports.
void	ast_endpoint_set_state (struct ast_endpoint *endpoint, enum ast_endpoint_state state)
	Updates the state of the given endpoint.
void	ast_endpoint_shutdown (struct ast_endpoint *endpoint)
	Shutsdown an ast_endpoint.
const char *	ast_endpoint_state_to_string (enum ast_endpoint_state state)
	Returns a string representation of the given endpoint state.

Detailed Description

Endpoint abstractions.

Author

David M. Lee, II dlee@.nosp@m.digi.nosp@m.um.co.nosp@m.m

Since

12

An endpoint is an external device/system that may offer/accept channels to/from Asterisk. While this is a very useful concept for end users, it is surprisingly not a core concept within Asterisk itself.

This file defines ast_endpoint as a seperate object, which channel drivers may use to expose their concept of an endpoint. As the channel driver creates channels, it can use ast_endpoint_add_channel() to associate channels to the endpoint. This updates the endpoint appropriately, and forwards all of the channel's events to the endpoint's topic.

In order to avoid excessive locking on the endpoint object itself, the mutable state is not accessible via getters. Instead, you can create a snapshot using ast_endpoint_snapshot_create() to get a consistent snapshot of the internal state.

Definition in file endpoints.h.

Enumeration Type Documentation

ast_endpoint_state

enum ast_endpoint_state

Valid states for an endpoint.

Since

12

Enumerator
AST_ENDPOINT_UNKNOWN	The endpoint state is not known.
AST_ENDPOINT_OFFLINE	The endpoint is not available.
AST_ENDPOINT_ONLINE	The endpoint is available.

Definition at line 51 of file endpoints.h.

                        {
    /*! The endpoint state is not known. */
    AST_ENDPOINT_UNKNOWN,
    /*! The endpoint is not available. */
    AST_ENDPOINT_OFFLINE,
    /*! The endpoint is available. */
    AST_ENDPOINT_ONLINE,
};

Function Documentation

ast_endpoint_add_channel()

int ast_endpoint_add_channel	(	struct ast_endpoint *	endpoint,
		struct ast_channel *	chan
	)

Adds a channel to the given endpoint.

Since

12

This updates the endpoint's statistics, as well as forwarding all of the channel's messages to the endpoint's topic.

The channel is automagically removed from the endpoint when it is disposed of.

Parameters

endpoint
chan	Channel.

Return values

0	on success.
Non-zero	on error.

Definition at line 165 of file main/endpoints.c.

{
    ast_assert(chan != NULL);
    ast_assert(endpoint != NULL);
    ast_assert(!ast_strlen_zero(endpoint->resource));
 
    ast_channel_forward_endpoint(chan, endpoint);
 
    ao2_lock(endpoint);
    ast_str_container_add(endpoint->channel_ids, ast_channel_uniqueid(chan));
    ao2_unlock(endpoint);
 
    endpoint_publish_snapshot(endpoint);
 
    return 0;
}

References ao2_lock, ao2_unlock, ast_assert, ast_channel_forward_endpoint(), ast_channel_uniqueid(), ast_str_container_add(), ast_strlen_zero(), ast_endpoint::channel_ids, endpoint_publish_snapshot(), NULL, and ast_endpoint::resource.

Referenced by ast_channel_endpoint_set(), and AST_TEST_DEFINE().

ast_endpoint_create()

struct ast_endpoint * ast_endpoint_create	(	const char *	tech,
		const char *	resource
	)

Create an endpoint struct.

The endpoint is created with a state of UNKNOWN and max_channels of -1 (unlimited). While ast_endpoint is AO2 managed, you have to shut it down with ast_endpoint_shutdown() to clean up references from subscriptions.

Parameters

tech	Technology for this endpoint.
resource	Name of this endpoint.

Returns

Newly created endpoint.

Return values

NULL

on error.

Since

12

Definition at line 289 of file main/endpoints.c.

{
    if (ast_strlen_zero(tech)) {
        ast_log(LOG_ERROR, "Endpoint tech cannot be empty\n");
        return NULL;
    }
 
    if (ast_strlen_zero(resource)) {
        ast_log(LOG_ERROR, "Endpoint resource cannot be empty\n");
        return NULL;
    }
 
    return endpoint_internal_create(tech, resource);
}

References ast_log, ast_strlen_zero(), endpoint_internal_create(), LOG_ERROR, NULL, ast_endpoint::resource, and ast_endpoint::tech.

Referenced by AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), build_peer(), persistent_endpoint_find_or_create(), and xmpp_client_alloc().

ast_endpoint_find_by_id()

struct ast_endpoint * ast_endpoint_find_by_id

(

const char *

id

)

Finds the endpoint with the given tech[/resource] id.

Endpoints are refcounted, so ao2_cleanup() when you're done.

Note

The resource portion of an ID is optional. If not provided, an aggregate endpoint for the entire technology is returned. These endpoints must not be modified, but can be subscribed to in order to receive updates for all endpoints of a given technology.

Parameters

id	Tech[/resource] id to look for.

Returns

Associated endpoint.

Return values

NULL	if not found.

Since

12

Definition at line 81 of file main/endpoints.c.

{
    struct ast_endpoint *endpoint = ao2_find(endpoints, id, OBJ_KEY);
 
    if (!endpoint) {
        endpoint = ao2_find(tech_endpoints, id, OBJ_KEY);
    }
 
    return endpoint;
}

References ao2_find, endpoints, OBJ_KEY, and tech_endpoints.

Referenced by ast_ari_endpoints_list_by_tech(), endpoint_find(), and messaging_app_unsubscribe_endpoint().

ast_endpoint_get_id()

const char * ast_endpoint_get_id

(

const struct ast_endpoint *

endpoint

)

Gets the tech/resource id of the given endpoint.

This is unique across all endpoints, and immutable.

Parameters

endpoint

The endpoint.

Returns

Tech/resource id of the endpoint.

Return values

NULL	if endpoint is NULL.

Since

12

Definition at line 358 of file main/endpoints.c.

{
    if (!endpoint) {
        return NULL;
    }
    return endpoint->id;
}

References ast_endpoint::id, and NULL.

Referenced by app_subscribe_endpoint(), forwards_create_endpoint(), get_or_create_subscription(), get_subscription(), messaging_app_subscribe_endpoint(), and messaging_app_unsubscribe_endpoint().

ast_endpoint_get_resource()

const char * ast_endpoint_get_resource

(

const struct ast_endpoint *

endpoint

)

Gets the resource name of the given endpoint.

This is unique for the endpoint's technology, and immutable.

Note

If the endpoint being queried is a technology aggregate endpoint, this will be an empty string.

Parameters

endpoint

The endpoint.

Returns

Resource name of the endpoint.

Return values

NULL	if endpoint is NULL.

Since

12

Definition at line 350 of file main/endpoints.c.

{
    if (!endpoint) {
        return NULL;
    }
    return endpoint->resource;
}

References NULL, and ast_endpoint::resource.

Referenced by add_to_regcontext(), ast_sip_get_endpoint_snapshot(), ast_sip_persistent_endpoint_publish_contact_state(), ast_sip_persistent_endpoint_update_state(), AST_TEST_DEFINE(), endpoint_deleted_observer(), get_or_create_subscription(), get_subscription(), messaging_app_unsubscribe_endpoint(), persistent_endpoint_cmp(), and persistent_endpoint_hash().

ast_endpoint_get_snapshot()

struct ast_endpoint_snapshot * ast_endpoint_get_snapshot

(

struct ast_endpoint *

endpoint

)

Gets the latest snapshot of the given endpoint.

Parameters

endpoint

The endpoint.

Returns

Latest snapshot of the endpoint.

Return values

NULL	if endpoint is NULL.

Since

20.19.0

22.9.0

23.3.0

Definition at line 374 of file main/endpoints.c.

{
    struct ast_endpoint_snapshot *snapshot;
 
    if (!endpoint) {
        return NULL;
    }
 
    ao2_lock(endpoint);
    snapshot = ao2_bump(endpoint->snapshot);
    ao2_unlock(endpoint);
 
    return snapshot;
}

References ao2_bump, ao2_lock, ao2_unlock, NULL, and ast_endpoint::snapshot.

Referenced by chan_pjsip_devicestate().

ast_endpoint_get_state()

enum ast_endpoint_state ast_endpoint_get_state

(

const struct ast_endpoint *

endpoint

)

Gets the state of the given endpoint.

Parameters

endpoint

The endpoint.

Returns

state.

Return values

AST_ENDPOINT_UNKNOWN

if endpoint is NULL.

Since

13.4

Definition at line 366 of file main/endpoints.c.

{
    if (!endpoint) {
        return AST_ENDPOINT_UNKNOWN;
    }
    return endpoint->state;
}

References AST_ENDPOINT_UNKNOWN, and ast_endpoint::state.

Referenced by add_to_regcontext(), and ast_sip_persistent_endpoint_update_state().

ast_endpoint_get_tech()

const char * ast_endpoint_get_tech

(

const struct ast_endpoint *

endpoint

)

Gets the technology of the given endpoint.

This is an immutable string describing the channel provider technology (SIP, IAX2, etc.).

Parameters

endpoint

The endpoint.

Returns

Tec of the endpoint.

Return values

NULL	if endpoint is NULL.

Since

12

Definition at line 342 of file main/endpoints.c.

{
    if (!endpoint) {
        return NULL;
    }
    return endpoint->tech;
}

References NULL, and ast_endpoint::tech.

Referenced by ast_sip_get_endpoint_snapshot(), AST_TEST_DEFINE(), and get_subscription().

ast_endpoint_remove_channel()

int ast_endpoint_remove_channel	(	struct ast_endpoint *	endpoint,
		struct ast_channel *	chan
	)

Removes a channel from the given endpoint.

Since

23.1.0

22.7.0

20.17.0

Parameters

endpoint
chan	Channel.

Return values

0	on success.
Non-zero	on error.

Definition at line 183 of file main/endpoints.c.

{
    ast_assert(chan != NULL);
    ast_assert(endpoint != NULL);
    ast_assert(!ast_strlen_zero(endpoint->resource));
 
    ao2_lock(endpoint);
    ast_str_container_remove(endpoint->channel_ids, ast_channel_uniqueid(chan));
    ao2_unlock(endpoint);
 
    endpoint_publish_snapshot(endpoint);
 
    return 0;
}

References ao2_lock, ao2_unlock, ast_assert, ast_channel_uniqueid(), ast_str_container_remove(), ast_strlen_zero(), ast_endpoint::channel_ids, endpoint_publish_snapshot(), NULL, and ast_endpoint::resource.

Referenced by ast_channel_endpoint_set(), and AST_TEST_DEFINE().

ast_endpoint_set_max_channels()

void ast_endpoint_set_max_channels	(	struct ast_endpoint *	endpoint,
		int	max_channels
	)

Updates the maximum number of channels an endpoint supports.

Set to -1 for unlimited channels.

Parameters

endpoint	Endpoint to modify.
max_channels	Maximum number of concurrent channels this endpoint supports.

Definition at line 401 of file main/endpoints.c.

{
    ast_assert(endpoint != NULL);
    ast_assert(!ast_strlen_zero(endpoint->resource));
 
    ao2_lock(endpoint);
    endpoint->max_channels = max_channels;
    ao2_unlock(endpoint);
    endpoint_publish_snapshot(endpoint);
}

References ao2_lock, ao2_unlock, ast_assert, ast_strlen_zero(), endpoint_publish_snapshot(), ast_endpoint_snapshot::max_channels, ast_endpoint::max_channels, NULL, and ast_endpoint::resource.

Referenced by AST_TEST_DEFINE(), and AST_TEST_DEFINE().

ast_endpoint_set_state()

void ast_endpoint_set_state	(	struct ast_endpoint *	endpoint,
		enum ast_endpoint_state	state
	)

Updates the state of the given endpoint.

Parameters

endpoint	Endpoint to modify.
state	New state.

Since

12

Definition at line 389 of file main/endpoints.c.

{
    ast_assert(endpoint != NULL);
    ast_assert(!ast_strlen_zero(endpoint->resource));
 
    ao2_lock(endpoint);
    endpoint->state = state;
    ao2_unlock(endpoint);
    endpoint_publish_snapshot(endpoint);
}

References ao2_lock, ao2_unlock, ast_assert, ast_strlen_zero(), endpoint_publish_snapshot(), NULL, ast_endpoint::resource, ast_endpoint_snapshot::state, and ast_endpoint::state.

Referenced by __expire_registry(), __iax2_poke_noanswer(), ast_sip_persistent_endpoint_update_state(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), persistent_endpoint_find_or_create(), socket_process_helper(), update_registry(), and xmpp_client_change_state().

ast_endpoint_shutdown()

void ast_endpoint_shutdown

(

struct ast_endpoint *

endpoint

)

Shutsdown an ast_endpoint.

Parameters

endpoint

Endpoint to shut down.

Since

12

Definition at line 320 of file main/endpoints.c.

{
    RAII_VAR(struct stasis_message *, clear_msg, NULL, ao2_cleanup);
 
    if (endpoint == NULL) {
        return;
    }
 
    ao2_unlink(endpoints, endpoint);
    endpoint->tech_forward = stasis_forward_cancel(endpoint->tech_forward);
 
    clear_msg = create_endpoint_snapshot_message(endpoint);
    if (clear_msg) {
        RAII_VAR(struct stasis_message *, message, NULL, ao2_cleanup);
        message = stasis_cache_clear_create(clear_msg);
        if (message) {
            stasis_publish(ast_endpoint_topic(endpoint), message);
        }
    }
    ao2_ref(endpoint, -1);
}

References ao2_cleanup, ao2_ref, ao2_unlink, ast_endpoint_topic(), create_endpoint_snapshot_message(), endpoints, NULL, RAII_VAR, stasis_cache_clear_create(), stasis_forward_cancel(), stasis_publish(), and ast_endpoint::tech_forward.

Referenced by AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), peer_destructor(), persistent_endpoint_destroy(), and xmpp_client_destructor().

ast_endpoint_state_to_string()

const char * ast_endpoint_state_to_string

(

enum ast_endpoint_state

state

)

Returns a string representation of the given endpoint state.

Parameters

state

Endpoint state.

Returns

String representation of state.

Return values

?	if state isn't in ast_endpoint_state.

Definition at line 108 of file main/endpoints.c.

{
    switch (state) {
    case AST_ENDPOINT_UNKNOWN:
        return "unknown";
    case AST_ENDPOINT_OFFLINE:
        return "offline";
    case AST_ENDPOINT_ONLINE:
        return "online";
    }
    return "?";
}

References AST_ENDPOINT_OFFLINE, AST_ENDPOINT_ONLINE, and AST_ENDPOINT_UNKNOWN.

Referenced by ast_endpoint_snapshot_to_json().