Asterisk - The Open Source Telephony Project  GIT-master-a24979a
Enumerations | Functions
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. More...
 
struct ast_endpointast_endpoint_create (const char *tech, const char *resource)
 Create an endpoint struct. More...
 
struct ast_endpointast_endpoint_find_by_id (const char *id)
 Finds the endpoint with the given tech[/resource] id. More...
 
const char * ast_endpoint_get_id (const struct ast_endpoint *endpoint)
 Gets the tech/resource id of the given endpoint. More...
 
const char * ast_endpoint_get_resource (const struct ast_endpoint *endpoint)
 Gets the resource name of the given endpoint. More...
 
enum ast_endpoint_state ast_endpoint_get_state (const struct ast_endpoint *endpoint)
 Gets the state of the given endpoint. More...
 
const char * ast_endpoint_get_tech (const struct ast_endpoint *endpoint)
 Gets the technology of the given endpoint. More...
 
void ast_endpoint_set_max_channels (struct ast_endpoint *endpoint, int max_channels)
 Updates the maximum number of channels an endpoint supports. More...
 
void ast_endpoint_set_state (struct ast_endpoint *endpoint, enum ast_endpoint_state state)
 Updates the state of the given endpoint. More...
 
void ast_endpoint_shutdown (struct ast_endpoint *endpoint)
 Shutsdown an ast_endpoint. More...
 
const char * ast_endpoint_state_to_string (enum ast_endpoint_state state)
 Returns a string representation of the given endpoint state. More...
 

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

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.

51  {
52  /*! The endpoint state is not known. */
54  /*! The endpoint is not available. */
56  /*! The endpoint is available. */
58 };
@ AST_ENDPOINT_OFFLINE
Definition: endpoints.h:55
@ AST_ENDPOINT_ONLINE
Definition: endpoints.h:57
@ AST_ENDPOINT_UNKNOWN
Definition: endpoints.h:53

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
chanChannel.
Return values
0on success.
Non-zeroon error.

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

166 {
167  ast_assert(chan != NULL);
168  ast_assert(endpoint != NULL);
169  ast_assert(!ast_strlen_zero(endpoint->resource));
170 
171  ast_channel_forward_endpoint(chan, endpoint);
172 
173  ao2_lock(endpoint);
175  ao2_unlock(endpoint);
176 
177  endpoint_publish_snapshot(endpoint);
178 
179  return 0;
180 }
#define ao2_unlock(a)
Definition: astobj2.h:729
#define ao2_lock(a)
Definition: astobj2.h:717
const char * ast_channel_uniqueid(const struct ast_channel *chan)
int ast_channel_forward_endpoint(struct ast_channel *chan, struct ast_endpoint *endpoint)
Forward channel stasis messages to the given endpoint.
static void endpoint_publish_snapshot(struct ast_endpoint *endpoint)
#define NULL
Definition: resample.c:96
static force_inline int attribute_pure ast_strlen_zero(const char *s)
Definition: strings.h:65
int ast_str_container_add(struct ao2_container *str_container, const char *add)
Adds a string to a string container allocated by ast_str_container_alloc.
Definition: strings.c:206
struct ao2_container * channel_ids
const ast_string_field resource
#define ast_assert(a)
Definition: utils.h:734

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

◆ 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
techTechnology for this endpoint.
resourceName of this endpoint.
Returns
Newly created endpoint.
Return values
NULLon error.
Since
12

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

320 {
321  if (ast_strlen_zero(tech)) {
322  ast_log(LOG_ERROR, "Endpoint tech cannot be empty\n");
323  return NULL;
324  }
325 
326  if (ast_strlen_zero(resource)) {
327  ast_log(LOG_ERROR, "Endpoint resource cannot be empty\n");
328  return NULL;
329  }
330 
331  return endpoint_internal_create(tech, resource);
332 }
#define ast_log
Definition: astobj2.c:42
#define LOG_ERROR
static struct ast_endpoint * endpoint_internal_create(const char *tech, const char *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(), build_peer(), persistent_endpoint_find_or_create(), skinny_device_alloc(), 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
idTech[/resource] id to look for.
Returns
Associated endpoint.
Return values
NULLif not found.
Since
12

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

83 {
84  struct ast_endpoint *endpoint = ao2_find(endpoints, id, OBJ_KEY);
85 
86  if (!endpoint) {
87  endpoint = ao2_find(tech_endpoints, id, OBJ_KEY);
88  }
89 
90  return endpoint;
91 }
#define OBJ_KEY
Definition: astobj2.h:1151
#define ao2_find(container, arg, flags)
Definition: astobj2.h:1736
static struct ao2_container * tech_endpoints
static struct ao2_container * endpoints

References ao2_find, endpoints, OBJ_KEY, and tech_endpoints.

Referenced by ast_ari_endpoints_list_by_tech(), 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
endpointThe endpoint.
Returns
Tech/resource id of the endpoint.
Return values
NULLif endpoint is NULL.
Since
12

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

392 {
393  if (!endpoint) {
394  return NULL;
395  }
396  return endpoint->id;
397 }
const ast_string_field 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
endpointThe endpoint.
Returns
Resource name of the endpoint.
Return values
NULLif endpoint is NULL.
Since
12

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

384 {
385  if (!endpoint) {
386  return NULL;
387  }
388  return endpoint->resource;
389 }

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(), chan_pjsip_devicestate(), endpoint_deleted_observer(), get_or_create_subscription(), get_subscription(), messaging_app_unsubscribe_endpoint(), persistent_endpoint_cmp(), and persistent_endpoint_hash().

◆ 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
endpointThe endpoint.
Returns
state.
Return values
AST_ENDPOINT_UNKNOWNif endpoint is NULL.
Since
13.4

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

400 {
401  if (!endpoint) {
402  return AST_ENDPOINT_UNKNOWN;
403  }
404  return endpoint->state;
405 }
enum ast_endpoint_state 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
endpointThe endpoint.
Returns
Tec of the endpoint.
Return values
NULLif endpoint is NULL.
Since
12

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

376 {
377  if (!endpoint) {
378  return NULL;
379  }
380  return endpoint->tech;
381 }
const ast_string_field tech

References NULL, and ast_endpoint::tech.

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

◆ 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
endpointEndpoint to modify.
max_channelsMaximum number of concurrent channels this endpoint supports.

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

421 {
422  ast_assert(endpoint != NULL);
423  ast_assert(!ast_strlen_zero(endpoint->resource));
424 
425  ao2_lock(endpoint);
426  endpoint->max_channels = max_channels;
427  ao2_unlock(endpoint);
428  endpoint_publish_snapshot(endpoint);
429 }
int max_channels
Max channels for this endpoint. -1 means unlimited or unknown.

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

◆ 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
endpointEndpoint to modify.
stateNew state.
Since
12

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

409 {
410  ast_assert(endpoint != NULL);
411  ast_assert(!ast_strlen_zero(endpoint->resource));
412 
413  ao2_lock(endpoint);
414  endpoint->state = state;
415  ao2_unlock(endpoint);
416  endpoint_publish_snapshot(endpoint);
417 }
enum sip_cc_notify_state state
Definition: chan_sip.c:966

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

Referenced by __expire_registry(), __iax2_poke_noanswer(), ast_sip_persistent_endpoint_update_state(), AST_TEST_DEFINE(), expire_register(), handle_response_peerpoke(), persistent_endpoint_find_or_create(), sip_poke_noanswer(), skinny_register(), skinny_session_cleanup(), socket_process_helper(), unload_module(), update_registry(), and xmpp_client_change_state().

◆ ast_endpoint_shutdown()

void ast_endpoint_shutdown ( struct ast_endpoint endpoint)

Shutsdown an ast_endpoint.

Parameters
endpointEndpoint to shut down.
Since
12

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

351 {
352  RAII_VAR(struct stasis_message *, clear_msg, NULL, ao2_cleanup);
353 
354  if (endpoint == NULL) {
355  return;
356  }
357 
358  ao2_unlink(endpoints, endpoint);
359  endpoint->tech_forward = stasis_forward_cancel(endpoint->tech_forward);
360 
361  clear_msg = create_endpoint_snapshot_message(endpoint);
362  if (clear_msg) {
364  message = stasis_cache_clear_create(clear_msg);
365  if (message) {
367  }
368  }
369 
370  /* Bump refcount to hold on to the router */
371  ao2_ref(endpoint->router, +1);
373 }
#define ao2_cleanup(obj)
Definition: astobj2.h:1934
#define ao2_unlink(container, obj)
Remove an object from a container.
Definition: astobj2.h:1578
#define ao2_ref(o, delta)
Reference/unreference an object and return the old refcount.
Definition: astobj2.h:459
struct stasis_topic * ast_endpoint_topic(struct ast_endpoint *endpoint)
Returns the topic for a specific endpoint.
static struct stasis_message * create_endpoint_snapshot_message(struct ast_endpoint *endpoint)
struct stasis_message * stasis_cache_clear_create(struct stasis_message *message)
A message which instructs the caching topic to remove an entry from its cache.
Definition: stasis_cache.c:778
struct stasis_forward * stasis_forward_cancel(struct stasis_forward *forward)
Definition: stasis.c:1550
void stasis_publish(struct stasis_topic *topic, struct stasis_message *message)
Publish a message to a topic's subscribers.
Definition: stasis.c:1513
void stasis_message_router_unsubscribe(struct stasis_message_router *router)
Unsubscribe the router from the upstream topic.
struct stasis_forward * tech_forward
struct stasis_message_router * router
#define RAII_VAR(vartype, varname, initval, dtor)
Declare a variable that will call a destructor function when it goes out of scope.
Definition: utils.h:936

References ao2_cleanup, ao2_ref, ao2_unlink, ast_endpoint_topic(), create_endpoint_snapshot_message(), endpoints, 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().

◆ 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
stateEndpoint state.
Returns
String representation of state.
Return values
?if state isn't in ast_endpoint_state.

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

110 {
111  switch (state) {
113  return "unknown";
115  return "offline";
116  case AST_ENDPOINT_ONLINE:
117  return "online";
118  }
119  return "?";
120 }

References AST_ENDPOINT_OFFLINE, AST_ENDPOINT_ONLINE, and AST_ENDPOINT_UNKNOWN.

Referenced by ast_endpoint_snapshot_to_json().