[asterisk-commits] dlee: branch dlee/endpoints r387180 - in /team/dlee/endpoints: channels/ incl...

[SVN commits to the Asterisk project]

Author: dlee
Date: Wed May  1 14:46:26 2013
New Revision: 387180

URL: http://svnview.digium.com/svn/asterisk?view=rev&rev=387180
Log:
Endpoint docs

Modified:
    team/dlee/endpoints/channels/chan_sip.c
    team/dlee/endpoints/include/asterisk/endpoints.h
    team/dlee/endpoints/main/channel_internal_api.c

Modified: team/dlee/endpoints/channels/chan_sip.c
URL: http://svnview.digium.com/svn/asterisk/team/dlee/endpoints/channels/chan_sip.c?view=diff&rev=387180&r1=387179&r2=387180
==============================================================================
--- team/dlee/endpoints/channels/chan_sip.c (original)
+++ team/dlee/endpoints/channels/chan_sip.c Wed May  1 14:46:26 2013
@@ -8015,7 +8015,7 @@
 
 	if (i->relatedpeer) {
 		int r;
-		r = ast_channel_forward_endpoint(tmp, i->relatedpeer->endpoint);
+		r = ast_endpoint_add_channel(i->relatedpeer->endpoint, tmp);
 		if (r != 0) {
 			ast_channel_unref(tmp);
 			sip_pvt_lock(i);

Modified: team/dlee/endpoints/include/asterisk/endpoints.h
URL: http://svnview.digium.com/svn/asterisk/team/dlee/endpoints/include/asterisk/endpoints.h?view=diff&rev=387180&r1=387179&r2=387180
==============================================================================
--- team/dlee/endpoints/include/asterisk/endpoints.h (original)
+++ team/dlee/endpoints/include/asterisk/endpoints.h Wed May  1 14:46:26 2013
@@ -25,6 +25,16 @@
  *
  * \author David M. Lee, II <dlee at 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 updated the endpoint appropriately, and forwards all of
+ * the channel's events to the endpoint's topic.
  */
 
 #include "asterisk/json.h"
@@ -47,7 +57,7 @@
 /*!
  * \brief Opaque struct representing an endpoint.
  *
- * And an endpoint is an external device/system that may offer/accept channels
+ * An endpoint is an external device/system that may offer/accept channels
  * to/from Asterisk.
  *
  * \since 12
@@ -128,16 +138,21 @@
 
 /*!
  * \since 12
- * \brief Forward a channels messages to its endpoint's topic.
+ * \brief Adds a channel to the given endpoint.
  *
- * This forward is unsubscribed when the channel is disposed of.
+ * 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.
- * \param endpoint_topic Topic of the corresponding endpoint.
  * \retval 0 on success.
  * \retval Non-zero on error.
  */
-int ast_channel_forward_endpoint(struct ast_channel *chan,
-	struct ast_endpoint *endpoint);
+int ast_endpoint_add_channel(struct ast_endpoint *endpoint,
+	struct ast_channel *chan);
+
 
 #endif /* _ASTERISK_ENDPOINTS_H */

Modified: team/dlee/endpoints/main/channel_internal_api.c
URL: http://svnview.digium.com/svn/asterisk/team/dlee/endpoints/main/channel_internal_api.c?view=diff&rev=387180&r1=387179&r2=387180
==============================================================================
--- team/dlee/endpoints/main/channel_internal_api.c (original)
+++ team/dlee/endpoints/main/channel_internal_api.c Wed May  1 14:46:26 2013
@@ -1393,8 +1393,8 @@
 	return chan ? chan->topic : ast_channel_topic_all();
 }
 
-int ast_channel_forward_endpoint(struct ast_channel *chan,
-	struct ast_endpoint *endpoint)
+int ast_endpoint_add_channel(struct ast_endpoint *endpoint,
+	struct ast_channel *chan)
 {
 	ast_assert(chan != NULL);
 	ast_assert(endpoint != NULL);