Adding doxygen comments to missing parts, moving some #define

...trying to get my head around the thoughts behind the TCP/TLS stuff
and figure out what needs to be done to make it useful...


git-svn-id: http://svn.digium.com/svn/asterisk/trunk@128290 f38db490-d61c-443f-a65b-d21fe96a405b

1 files changed, 27 insertions, 10 deletions

diff --git a/channels/chan_sip.c b/channels/chan_sip.c
index ae45b1205..9636e174a 100644
--- a/channels/chan_sip.c
+++ b/channels/chan_sip.c
@@ -1372,6 +1372,10 @@ struct sip_pvt {
  */
 struct ao2_container *dialogs;
 
+#define sip_pvt_lock(x) ao2_lock(x)
+#define sip_pvt_trylock(x) ao2_trylock(x)
+#define sip_pvt_unlock(x) ao2_unlock(x)
+
 /*!
  * when we create or delete references, make sure to use these
  * functions so we keep track of the refcounts.
@@ -1768,8 +1772,8 @@ static struct sockaddr_in stunaddr;		/*!< stun server address */
  */
 static struct ast_ha *localaddr;		/*!< List of local networks, on the same side of NAT as this Asterisk */
 
-static int ourport_tcp;
-static int ourport_tls;
+static int ourport_tcp;				/*!< The port used for TCP connections */
+static int ourport_tls;				/*!< The port used for TCP/TLS connections */
 static struct sockaddr_in debugaddr;
 
 static struct ast_config *notify_types;		/*!< The list of manual NOTIFY types we know how to send */
@@ -2069,6 +2073,10 @@ static int get_destination(struct sip_pvt *p, struct sip_request *oreq);
 static int get_msg_text(char *buf, int len, struct sip_request *req, int addnewline);
 static int transmit_state_notify(struct sip_pvt *p, int state, int full, int timeout);
 
+/*-- TCP connection handling ---*/
+static void *_sip_tcp_helper_thread(struct sip_pvt *pvt, struct ast_tcptls_session_instance *ser);
+static void *sip_tcp_worker_fn(void *);
+
 /*--- Constructing requests and responses */
 static void initialize_initreq(struct sip_pvt *p, struct sip_request *req);
 static int init_req(struct sip_request *req, int sipmethod, const char *recip);
@@ -2188,11 +2196,14 @@ static const struct ast_channel_tech sip_tech = {
  */
 static struct ast_channel_tech sip_tech_info;
 
-static void *sip_tcp_worker_fn(void *);
 
+/*! \brief Working TLS connection configuration */
 static struct ast_tls_config sip_tls_cfg;
+
+/*! \brief Default TLS connection configuration */
 static struct ast_tls_config default_tls_cfg;
 
+/*! \brief The TCP server definition */
 static struct server_args sip_tcp_desc = {
 	.accept_fd = -1,
 	.master = AST_PTHREADT_NULL,
@@ -2203,6 +2214,7 @@ static struct server_args sip_tcp_desc = {
 	.worker_fn = sip_tcp_worker_fn,
 };
 
+/*! \brief The TCP/TLS server definition */
 static struct server_args sip_tls_desc = {
 	.accept_fd = -1,
 	.master = AST_PTHREADT_NULL,
@@ -2253,8 +2265,8 @@ static struct ast_rtp_protocol sip_rtp = {
 	.get_codec = sip_get_codec,
 };
 
-static void *_sip_tcp_helper_thread(struct sip_pvt *pvt, struct ast_tcptls_session_instance *ser);
 
+/*! \brief SIP TCP connection handler */
 static void *sip_tcp_worker_fn(void *data)
 {
 	struct ast_tcptls_session_instance *ser = data;
@@ -2262,7 +2274,7 @@ static void *sip_tcp_worker_fn(void *data)
 	return _sip_tcp_helper_thread(NULL, ser);
 }
 
-/*! \brief SIP TCP helper function */
+/*! \brief SIP TCP thread management function */
 static void *_sip_tcp_helper_thread(struct sip_pvt *pvt, struct ast_tcptls_session_instance *ser) 
 {
 	int res, cl;
@@ -2355,8 +2367,10 @@ cleanup2:
 	fclose(ser->f);
 	ser->f = NULL;
 	ser->fd = -1;
-	if (reqcpy.data)
+	if (reqcpy.data) {
 		ast_free(reqcpy.data);
+	}
+
 	if (req.data) {
 		ast_free(req.data);
 		req.data = NULL;
@@ -2369,9 +2383,6 @@ cleanup2:
 	return NULL;
 }
 
-#define sip_pvt_lock(x) ao2_lock(x)
-#define sip_pvt_trylock(x) ao2_trylock(x)
-#define sip_pvt_unlock(x) ao2_unlock(x)
 
 /*!
  * helper functions to unreference various types of objects.
@@ -4286,6 +4297,9 @@ static int create_addr(struct sip_pvt *dialog, const char *opeer, struct sockadd
 
 		/* Let's see if we can find the host in DNS. First try DNS SRV records,
 		   then hostname lookup */
+		/*! \todo Fix this function. When we ask SRC, we should check all transports 
+			  In the future, we should first check NAPTR to find out transport preference
+		 */
 		hostn = peername;
 		portno = port ? atoi(port) : (dialog->socket.type & SIP_TRANSPORT_TLS) ? STANDARD_TLS_PORT : STANDARD_SIP_PORT;
 		if (global_srvlookup) {
@@ -10281,7 +10295,10 @@ static enum parse_register_result parse_register_contact(struct sip_pvt *pvt, st
 		ast_sched_add(sched, (expiry + 10) * 1000, expire_register, peer);
 	pvt->expiry = expiry;
 	snprintf(data, sizeof(data), "%s:%d:%d:%s:%s", ast_inet_ntoa(peer->addr.sin_addr), ntohs(peer->addr.sin_port), expiry, peer->username, peer->fullcontact);
-	/* Saving TCP connections is useless, we won't be able to reconnect */
+	/* Saving TCP connections is useless, we won't be able to reconnect 
+		XXX WHY???? XXX
+		\todo check this
+	*/
 	if (!peer->rt_fromcontact && (peer->socket.type & SIP_TRANSPORT_UDP)) 
 		ast_db_put("SIP/Registry", peer->name, data);
 	manager_event(EVENT_FLAG_SYSTEM, "PeerStatus", "ChannelType: SIP\r\nPeer: SIP/%s\r\nPeerStatus: Registered\r\nAddress: %s\r\nPort: %d\r\n", peer->name,  ast_inet_ntoa(peer->addr.sin_addr), ntohs(peer->addr.sin_port));