1 files changed, 170 insertions, 0 deletions
diff --git a/include/asterisk/endpoints.h b/include/asterisk/endpoints.h
new file mode 100644
index 000000000..b0be1cf38
--- /dev/null
+++ b/include/asterisk/endpoints.h
@@ -0,0 +1,170 @@
+/*
+ * Asterisk -- An open source telephony toolkit.
+ *
+ * Copyright (C) 2013, Digium, Inc.
+ *
+ * David M. Lee, II <dlee@digium.com>
+ *
+ * See http://www.asterisk.org for more information about
+ * the Asterisk project. Please do not directly contact
+ * any of the maintainers of this project for assistance;
+ * the project provides a web site, mailing lists and IRC
+ * channels for your use.
+ *
+ * This program is free software, distributed under the terms of
+ * the GNU General Public License Version 2. See the LICENSE file
+ * at the top of the source tree.
+ */
+
+#ifndef _ASTERISK_ENDPOINTS_H
+#define _ASTERISK_ENDPOINTS_H
+
+/*! \file
+ *
+ * \brief 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 \a not a core concept within Asterisk iteself.
+ *
+ * This file defines \ref 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.
+ */
+
+#include "asterisk/json.h"
+
+/*!
+ * \brief Valid states for an endpoint.
+ * \since 12
+ */
+enum ast_endpoint_state {
+	/*! The endpoint state is not known. */
+	AST_ENDPOINT_UNKNOWN,
+	/*! The endpoint is not available. */
+	AST_ENDPOINT_OFFLINE,
+	/*! The endpoint is available. */
+	AST_ENDPOINT_ONLINE,
+};
+
+/*!
+ * \brief Returns a string representation of the given endpoint state.
+ *
+ * \param state Endpoint state.
+ * \return String representation of \a state.
+ * \return \c "?" if \a state isn't in \ref ast_endpoint_state.
+ */
+const char *ast_endpoint_state_to_string(enum ast_endpoint_state state);
+
+/*!
+ * \brief Opaque struct representing an endpoint.
+ *
+ * An endpoint is an external device/system that may offer/accept channels
+ * to/from Asterisk.
+ *
+ * \since 12
+ */
+struct ast_endpoint;
+
+/*!
+ * \brief Create an endpoint struct.
+ *
+ * The endpoint is created with a state of UNKNOWN and max_channels of -1
+ * (unlimited). While \ref ast_endpoint is AO2 managed, you have to
+ * shut it down with ast_endpoint_shutdown() to clean up references from
+ * subscriptions.
+ *
+ * \param tech Technology for this endpoint.
+ * \param resource Name of this endpoint.
+ * \return Newly created endpoint.
+ * \return \c NULL on error.
+ * \since 12
+ */
+struct ast_endpoint *ast_endpoint_create(const char *tech, const char *resource);
+
+/*!
+ * \brief Shutsdown an \ref ast_endpoint.
+ *
+ * \param endpoint Endpoint to shut down.
+ * \since 12
+ */
+void ast_endpoint_shutdown(struct ast_endpoint *endpoint);
+
+/*!
+ * \brief Gets the technology of the given endpoint.
+ *
+ * This is an immutable string describing the channel provider technology
+ * (SIP, IAX2, etc.).
+ *
+ * \param endpoint The endpoint.
+ * \return Tec of the endpoint.
+ * \return \c NULL if endpoint is \c NULL.
+ * \since 12
+ */
+const char *ast_endpoint_get_tech(const struct ast_endpoint *endpoint);
+
+/*!
+ * \brief Gets the resource name of the given endpoint.
+ *
+ * This is unique for the endpoint's technology, and immutable.
+ *
+ * \param endpoint The endpoint.
+ * \return Resource name of the endpoint.
+ * \return \c NULL if endpoint is \c NULL.
+ * \since 12
+ */
+const char *ast_endpoint_get_resource(const struct ast_endpoint *endpoint);
+
+/*!
+ * \brief Updates the state of the given endpoint.
+ *
+ * \param endpoint Endpoint to modify.
+ * \param state New state.
+ * \since 12
+ */
+void ast_endpoint_set_state(struct ast_endpoint *endpoint,
+	enum ast_endpoint_state state);
+
+/*!
+ * \brief Updates the maximum number of channels an endpoint supports.
+ *
+ * Set to -1 for unlimited channels.
+ *
+ * \param endpoint Endpoint to modify.
+ * \param max_channels Maximum number of concurrent channels this endpoint
+ *        supports.
+ */
+void ast_endpoint_set_max_channels(struct ast_endpoint *endpoint,
+	int max_channels);
+
+
+/*!
+ * \since 12
+ * \brief Adds a channel to the given endpoint.
+ *
+ * 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.
+ *
+ * \param endpoint
+ * \param chan Channel.
+ * \retval 0 on success.
+ * \retval Non-zero on error.
+ */
+int ast_endpoint_add_channel(struct ast_endpoint *endpoint,
+	struct ast_channel *chan);
+
+
+#endif /* _ASTERISK_ENDPOINTS_H */