From 975ddb8552c367675c82eedeeac2f0bcefb62292 Mon Sep 17 00:00:00 2001
From: Olle Johansson <oej@edvina.net>
Date: Wed, 12 Apr 2006 20:32:40 +0000
Subject: [PATCH] Doxygen docs
git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@19542 65c4cc65-6c06-0410-ace0-fbb531ad65f3
---
channels/chan_sip.c | 58 ++++++++++++++++++++++++++++++++++++++-------
1 file changed, 49 insertions(+), 9 deletions(-)
diff --git a/channels/chan_sip.c b/channels/chan_sip.c
index ec5177033d..924131719d 100644
--- a/channels/chan_sip.c
+++ b/channels/chan_sip.c
@@ -35,6 +35,48 @@
*
* \ingroup channel_drivers
*
+ * \par Overview of the handling of SIP sessions
+ * The SIP channel handles several types of SIP sessions, or dialogs,
+ * not all of them being "telephone calls".
+ * - Incoming calls that will be sent to the PBX core
+ * - Outgoing calls, generated by the PBX
+ * - SIP subscriptions and notifications of states and voicemail messages
+ * - SIP registrations, both inbound and outbound
+ * - SIP peer management (peerpoke, OPTIONS)
+ * - SIP text messages
+ *
+ * In the SIP channel, there's a list of active SIP dialogs, which includes
+ * all of these when they are active. "sip show channels" in the CLI will
+ * show most of these, excluding subscriptions which are shown by
+ * "sip show subscriptions"
+ *
+ * \par incoming packets
+ * Incoming packets are received in the monitoring thread, then handled by
+ * sipsock_read(). This function parses the packet and matches an existing
+ * dialog or starts a new SIP dialog.
+ *
+ * sipsock_read sends the packet to handle_request(), that parses a bit more.
+ * if it's a response to an outbound request, it's sent to handle_response().
+ * If it is a request, handle_request sends it to one of a list of functions
+ * depending on the request type - INVITE, OPTIONS, REFER, BYE, CANCEL etc
+ *
+ * A new INVITE is sent to handle_request_invite(), that will end up
+ * starting a new channel in the PBX, the new channel after that executing
+ * in a separate channel thread. This is an incoming "call".
+ * When the call is answered, either by a bridged channel or the PBX itself
+ * the sip_answer() function is called.
+ *
+ * The actual media - Video or Audio - is mostly handled by the RTP subsystem
+ * in rtp.c
+ *
+ * \par Outbound calls
+ * Outbound calls are set up by the PBX through the sip_request_call()
+ * function. After that, they are activated by sip_call().
+ *
+ * \par Hanging up
+ * The PBX issues a hangup on both incoming and outgoing calls through
+ * the sip_hangup() function
+ *
*/
@@ -495,11 +537,11 @@ struct sip_pkt;
/*! \brief Parameters to the transmit_invite function */
struct sip_invite_param {
const char *distinctive_ring; /*!< Distinctive ring header */
- int addsipheaders; /*!< Add extra SIP headers */
+ int addsipheaders; /*!< Add extra SIP headers */
const char *uri_options; /*!< URI options to add to the URI */
const char *vxml_url; /*!< VXML url for Cisco phones */
- char *auth; /*!< Authentication */
- char *authheader; /*!< Auth header */
+ char *auth; /*!< Authentication */
+ char *authheader; /*!< Auth header */
enum sip_auth_type auth_type; /*!< Authentication type */
};
@@ -511,8 +553,8 @@ struct sip_route {
/*! \brief Modes for SIP domain handling in the PBX */
enum domain_mode {
- SIP_DOMAIN_AUTO, /*!< This domain is auto-configured */
- SIP_DOMAIN_CONFIG, /*!< This domain is from configuration */
+ SIP_DOMAIN_AUTO, /*!< This domain is auto-configured */
+ SIP_DOMAIN_CONFIG, /*!< This domain is from configuration */
};
struct domain {
@@ -542,11 +584,9 @@ struct sip_auth {
struct sip_auth *next; /*!< Next auth structure in list */
};
-/*--- Various flags for the flags field in the pvt structure
- Peer only flags should be set in PAGE2 below
-*/
+/*--- Various flags for the flags field in the pvt structure */
#define SIP_ALREADYGONE (1 << 0) /*!< Whether or not we've already been destroyed by our peer */
-#define SIP_NEEDDESTROY (1 << 1) /*!< if we need to be destroyed */
+#define SIP_NEEDDESTROY (1 << 1) /*!< if we need to be destroyed by the monitor thread */
#define SIP_NOVIDEO (1 << 2) /*!< Didn't get video in invite, don't offer */
#define SIP_RINGING (1 << 3) /*!< Have sent 180 ringing */
#define SIP_PROGRESS_SENT (1 << 4) /*!< Have sent 183 message progress */
--
GitLab