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_endpointast_endpoint_create (const char *tech, const char *resource)
 Create an endpoint struct.
struct ast_endpointast_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.
const char * ast_endpoint_get_tech (const struct ast_endpoint *endpoint)
 Gets the technology of 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@digium.com>
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 iteself.

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

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.

00051                         {
00052    /*! The endpoint state is not known. */
00053    AST_ENDPOINT_UNKNOWN,
00054    /*! The endpoint is not available. */
00055    AST_ENDPOINT_OFFLINE,
00056    /*! The endpoint is available. */
00057    AST_ENDPOINT_ONLINE,
00058 };


Function Documentation

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 211 of file endpoints.c.

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_alloc_ap(), and AST_TEST_DEFINE().

00213 {
00214    ast_assert(chan != NULL);
00215    ast_assert(endpoint != NULL);
00216    ast_assert(!ast_strlen_zero(endpoint->resource));
00217 
00218    ast_channel_forward_endpoint(chan, endpoint);
00219 
00220    ao2_lock(endpoint);
00221    ast_str_container_add(endpoint->channel_ids, ast_channel_uniqueid(chan));
00222    ao2_unlock(endpoint);
00223 
00224    endpoint_publish_snapshot(endpoint);
00225 
00226    return 0;
00227 }

struct ast_endpoint* ast_endpoint_create ( const char *  tech,
const char *  resource 
) [read]

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.

NULL on error.

Since:
12

Definition at line 338 of file endpoints.c.

References ast_log, ast_strlen_zero, endpoint_internal_create(), LOG_ERROR, and NULL.

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

00339 {
00340    if (ast_strlen_zero(tech)) {
00341       ast_log(LOG_ERROR, "Endpoint tech cannot be empty\n");
00342       return NULL;
00343    }
00344 
00345    if (ast_strlen_zero(resource)) {
00346       ast_log(LOG_ERROR, "Endpoint resource cannot be empty\n");
00347       return NULL;
00348    }
00349 
00350    return endpoint_internal_create(tech, resource);
00351 }

struct ast_endpoint* ast_endpoint_find_by_id ( const char *  id  )  [read]

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.

NULL if not found.

Since:
12

Definition at line 129 of file endpoints.c.

References ao2_find, and OBJ_KEY.

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

00130 {
00131    struct ast_endpoint *endpoint = ao2_find(endpoints, id, OBJ_KEY);
00132 
00133    if (!endpoint) {
00134       endpoint = ao2_find(tech_endpoints, id, OBJ_KEY);
00135    }
00136 
00137    return endpoint;
00138 }

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.

NULL if endpoint is NULL.

Since:
12

Definition at line 410 of file endpoints.c.

References ast_endpoint::id, and NULL.

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

00411 {
00412    if (!endpoint) {
00413       return NULL;
00414    }
00415    return endpoint->id;
00416 }

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.

NULL if endpoint is NULL.

Since:
12

Definition at line 402 of file endpoints.c.

References NULL, and ast_endpoint::resource.

Referenced by ast_sip_get_endpoint_snapshot(), AST_TEST_DEFINE(), chan_pjsip_devicestate(), get_or_create_subscription(), get_subscription(), messaging_app_unsubscribe_endpoint(), persistent_endpoint_cmp(), persistent_endpoint_hash(), and persistent_endpoint_update_state().

00403 {
00404    if (!endpoint) {
00405       return NULL;
00406    }
00407    return endpoint->resource;
00408 }

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.

NULL if endpoint is NULL.

Since:
12

Definition at line 394 of file endpoints.c.

References NULL, and ast_endpoint::tech.

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

00395 {
00396    if (!endpoint) {
00397       return NULL;
00398    }
00399    return endpoint->tech;
00400 }

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 430 of file endpoints.c.

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

Referenced by AST_TEST_DEFINE().

00432 {
00433    ast_assert(endpoint != NULL);
00434    ast_assert(!ast_strlen_zero(endpoint->resource));
00435 
00436    ao2_lock(endpoint);
00437    endpoint->max_channels = max_channels;
00438    ao2_unlock(endpoint);
00439    endpoint_publish_snapshot(endpoint);
00440 }

void ast_endpoint_set_state ( struct ast_endpoint endpoint,
enum ast_endpoint_state  state 
)

void ast_endpoint_shutdown ( struct ast_endpoint endpoint  ) 

Shutsdown an ast_endpoint.

Parameters:
endpoint Endpoint to shut down.
Since:
12

Definition at line 369 of file endpoints.c.

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

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

00370 {
00371    RAII_VAR(struct stasis_message *, clear_msg, NULL, ao2_cleanup);
00372 
00373    if (endpoint == NULL) {
00374       return;
00375    }
00376 
00377    ao2_unlink(endpoints, endpoint);
00378    endpoint->tech_forward = stasis_forward_cancel(endpoint->tech_forward);
00379 
00380    clear_msg = create_endpoint_snapshot_message(endpoint);
00381    if (clear_msg) {
00382       RAII_VAR(struct stasis_message *, message, NULL, ao2_cleanup);
00383       message = stasis_cache_clear_create(clear_msg);
00384       if (message) {
00385          stasis_publish(ast_endpoint_topic(endpoint), message);
00386       }
00387    }
00388 
00389    /* Bump refcount to hold on to the router */
00390    ao2_ref(endpoint->router, +1);
00391    stasis_message_router_unsubscribe(endpoint->router);
00392 }

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.

"?" if state isn't in ast_endpoint_state.

Definition at line 156 of file endpoints.c.

References AST_ENDPOINT_OFFLINE, AST_ENDPOINT_ONLINE, and AST_ENDPOINT_UNKNOWN.

Referenced by ast_endpoint_snapshot_to_json().

00157 {
00158    switch (state) {
00159    case AST_ENDPOINT_UNKNOWN:
00160       return "unknown";
00161    case AST_ENDPOINT_OFFLINE:
00162       return "offline";
00163    case AST_ENDPOINT_ONLINE:
00164       return "online";
00165    }
00166    return "?";
00167 }


Generated on Thu Apr 16 06:30:51 2015 for Asterisk - The Open Source Telephony Project by  doxygen 1.5.6