Doxygen docs

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

1 files changed, 49 insertions, 9 deletions

diff --git a/channels/chan_sip.c b/channels/chan_sip.c
index ec5177033..924131719 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 */