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_endpoint *	ast_endpoint_create (const char *tech, const char *resource)
	Create an endpoint struct. More...
struct ast_endpoint *	ast_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 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

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 164 of file main/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().

{
   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;
}

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.

NULL on error.

Since

12

Definition at line 319 of file main/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(), register_verify(), skinny_device_alloc(), and xmpp_client_alloc().

{
   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);
}

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.

NULL if not found.

Since

12

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

References ao2_find, and OBJ_KEY.

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

{
   struct ast_endpoint *endpoint = ao2_find(endpoints, id, OBJ_KEY);

   if (!endpoint) {
      endpoint = ao2_find(tech_endpoints, id, OBJ_KEY);
   }

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

NULL if endpoint is NULL.

Since

12

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

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

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

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.

NULL if endpoint is NULL.

Since

12

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

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

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

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.

AST_ENDPOINT_UNKNOWN if endpoint is NULL.

Since

13.4

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

References AST_ENDPOINT_UNKNOWN, and ast_endpoint::state.

Referenced by add_to_regcontext(), and ast_sip_persistent_endpoint_update_state().

{
   if (!endpoint) {
      return AST_ENDPOINT_UNKNOWN;
   }
   return endpoint->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.

NULL if endpoint is NULL.

Since

12

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

References NULL, and ast_endpoint::tech.

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

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

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 419 of file main/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().

{
   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);
}

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 407 of file main/endpoints.c.

References ao2_lock, ao2_unlock, ast_assert, ast_strlen_zero, endpoint_publish_snapshot(), NULL, ast_endpoint::resource, 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(), parse_register_contact(), persistent_endpoint_find_or_create(), register_verify(), sip_poke_noanswer(), skinny_register(), skinny_session_cleanup(), socket_process_helper(), unload_module(), update_registry(), and xmpp_client_change_state().

{
   ast_assert(endpoint != NULL);
   ast_assert(!ast_strlen_zero(endpoint->resource));

   ao2_lock(endpoint);
   endpoint->state = state;
   ao2_unlock(endpoint);
   endpoint_publish_snapshot(endpoint);
}

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 350 of file main/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().

{
   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);
      }
   }

   /* Bump refcount to hold on to the router */
   ao2_ref(endpoint->router, +1);
   stasis_message_router_unsubscribe(endpoint->router);
}

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.

"?" if state isn't in ast_endpoint_state.

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

References AST_ENDPOINT_OFFLINE, AST_ENDPOINT_ONLINE, and AST_ENDPOINT_UNKNOWN.

Referenced by ast_endpoint_snapshot_to_json().

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