Doxygen docs
authorOlle Johansson <oej@edvina.net>
Wed, 12 Apr 2006 20:32:40 +0000 (20:32 +0000)
committerOlle Johansson <oej@edvina.net>
Wed, 12 Apr 2006 20:32:40 +0000 (20:32 +0000)
git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@19542 65c4cc65-6c06-0410-ace0-fbb531ad65f3

channels/chan_sip.c

index ec51770..9241317 100644 (file)
  *
  * \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 */