add a bit of comments on internal functions.
authorLuigi Rizzo <rizzo@icir.org>
Mon, 23 Jul 2007 02:46:10 +0000 (02:46 +0000)
committerLuigi Rizzo <rizzo@icir.org>
Mon, 23 Jul 2007 02:46:10 +0000 (02:46 +0000)
git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@76458 65c4cc65-6c06-0410-ace0-fbb531ad65f3

channels/chan_sip.c

index 7e3c6ce..fe4c1bd 100644 (file)
@@ -1094,7 +1094,12 @@ static void dialoglist_unlock(void)
        ast_mutex_unlock(&dialoglock);
 }
 
-/*! \brief sip packet - raw format for outbound packets that are sent or scheduled for transmission */
+/*! \brief sip packet - raw format for outbound packets that are sent or scheduled for transmission
+ * Packets are linked in a list, whose head is in the struct sip_pvt they belong to.
+ * Each packet holds a reference to the parent struct sip_pvt.
+ * This structure is allocated in __sip_reliable_xmit() and only for packets that
+ * require retransmissions.
+ */
 struct sip_pkt {
        struct sip_pkt *next;                   /*!< Next packet in linked list */
        int retrans;                            /*!< Retransmission number */
@@ -4729,7 +4734,10 @@ static void make_our_tag(char *tagbuf, size_t len)
        snprintf(tagbuf, len, "as%08lx", ast_random());
 }
 
-/*! \brief Allocate SIP_PVT structure and set defaults */
+/*! \brief Allocate sip_pvt structure, set defaults and link in the container.
+ * Returns a reference to the object so whoever uses it later must
+ * remember to release the reference.
+ */
 static struct sip_pvt *sip_alloc(ast_string_field callid, struct sockaddr_in *sin,
                                 int useglobal_nat, const int intended_method)
 {
@@ -4862,8 +4870,11 @@ static struct sip_pvt *sip_alloc(ast_string_field callid, struct sockaddr_in *si
        return p;
 }
 
-/*! \brief Connect incoming SIP message to current dialog or create new dialog structure
-       Called by handle_request, sipsock_read */
+/*! \brief find or create a dialog structure for an incoming SIP message.
+ * Connect incoming SIP message to current dialog or create new dialog structure
+ * Returns a reference to the sip_pvt object, remember to give it back once done.
+ *     Called by handle_request, sipsock_read
+ */
 static struct sip_pvt *find_call(struct sip_request *req, struct sockaddr_in *sin, const int intended_method)
 {
        struct sip_pvt *p = NULL;
@@ -4973,7 +4984,7 @@ static struct sip_pvt *find_call(struct sip_request *req, struct sockaddr_in *si
                                ast_debug(4, "Failed allocating SIP dialog, sending 500 Server internal error and giving up\n");
                        }
                }
-               return p;
+               return p; /* can be NULL */
        } else if( sip_methods[intended_method].can_create == CAN_CREATE_DIALOG_UNSUPPORTED_METHOD) {
                /* A method we do not support, let's take it on the volley */
                transmit_response_using_temp(callid, sin, 1, intended_method, req, "501 Method Not Implemented");
@@ -5065,7 +5076,7 @@ static int sip_register(char *value, int lineno)
        reg->callid_valid = FALSE;
        reg->ocseq = INITIAL_CSEQ;
        ASTOBJ_CONTAINER_LINK(&regl, reg);      /* Add the new registry entry to the list */
-       registry_unref(reg);
+       registry_unref(reg);    /* release the reference given by ASTOBJ_INIT. The container has another reference */
        return 0;
 }
 
@@ -7821,7 +7832,12 @@ static char *regstate2str(enum sipregistrystate regstate)
        }
 }
 
-/*! \brief Update registration with SIP Proxy */
+/*! \brief Update registration with SIP Proxy.
+ * Called from the scheduler when the previous registration expires,
+ * so we don't have to cancel the pending event.
+ * We assume the reference so the sip_registry is valid, since it
+ * is stored in the scheduled event anyways.
+ */
 static int sip_reregister(void *data) 
 {
        /* if we are here, we know that we need to reregister. */
@@ -7853,7 +7869,12 @@ static int __sip_do_register(struct sip_registry *r)
        return res;
 }
 
-/*! \brief Registration timeout, register again */
+/*! \brief Registration timeout, register again
+ * Registered as a timeout handler during transmit_register(),
+ * to retransmit the packet if a reply does not come back.
+ * This is called by the scheduler so the event is not pending anymore when
+ * we are called.
+ */
 static int sip_reg_timeout(void *data)
 {
 
@@ -7867,6 +7888,10 @@ static int sip_reg_timeout(void *data)
                return 0;
 
        ast_log(LOG_NOTICE, "   -- Registration for '%s@%s' timed out, trying again (Attempt #%d)\n", r->username, r->hostname, r->regattempts); 
+       /* If the initial tranmission failed, we may not have an existing dialog,
+        * so it is possible that r->call == NULL.
+        * Otherwise destroy it, as we have a timeout so we don't want it.
+        */
        if (r->call) {
                /* Unlink us, destroy old call.  Locking is not relevant here because all this happens
                   in the single SIP manager thread. */
@@ -7897,7 +7922,9 @@ static int sip_reg_timeout(void *data)
        return 0;
 }
 
-/*! \brief Transmit register to SIP proxy or UA */
+/*! \brief Transmit register to SIP proxy or UA
+ * auth = NULL on the initial registration (from sip_reregister())
+ */
 static int transmit_register(struct sip_registry *r, int sipmethod, const char *auth, const char *authheader)
 {
        struct sip_request req;
@@ -9226,6 +9253,9 @@ static int get_rdnis(struct sip_pvt *p, struct sip_request *oreq)
 
 /*! \brief Find out who the call is for 
        We use the INVITE uri to find out
+       \return 0 on success (found a matching extension),
+       1 for pickup extension or overlap dialling support (if we support it),
+       -1 on error.
 */
 static int get_destination(struct sip_pvt *p, struct sip_request *oreq)
 {
@@ -9338,6 +9368,7 @@ static int get_destination(struct sip_pvt *p, struct sip_request *oreq)
        - Their tag is fromtag, our tag is to-tag
        - This means that in some transactions, totag needs to be their tag :-)
          depending upon the direction
+       Returns a reference, remember to release it when done XXX
 */
 static struct sip_pvt *get_sip_pvt_byid_locked(const char *callid, const char *totag, const char *fromtag) 
 {