Changeset 1598 for pjproject/trunk/pjsip/include/pjsip-ua/sip_inv.h

Timestamp:

Nov 25, 2007 4:40:07 AM (16 years ago)

Author:

bennylp

Message:

Ticket #416: Allow application to handle sending ACK manually

File:

• pjproject/trunk/pjsip/include/pjsip-ua/sip_inv.h (modified) (3 diffs)

pjproject/trunk/pjsip/include/pjsip-ua/sip_inv.h

@@ -191 +191 @@
     void (*on_media_update)(pjsip_inv_session *inv_ses, 
                             pj_status_t status);
+
+    /**
+     * This callback is called when the framework needs to send
+     * ACK request after it receives incoming  2xx response for 
+     * INVITE. It allows application to manually handle the 
+     * transmission of ACK request, which is required by some 3PCC
+     * scenarios. If this callback is not implemented, the framework
+     * will handle the ACK transmission automatically.
+     *
+     * When this callback is overridden, application may delay the
+     * sending of the ACK request (for example, when it needs to 
+     * wait for answer from the other call leg, in 3PCC scenarios). 
+     *
+     * Application creates the ACK request
+     *
+     * Once it has sent the ACK request, the framework will keep 
+     * this ACK request in the cache. Subsequent receipt of 2xx response
+     * will not cause this callback to be called, and instead automatic
+     * retransmission of this ACK request from the cache will be done
+     * by the framework.
+     *
+     * This callback is optional.
+     */
+    void (*on_send_ack)(pjsip_inv_session *inv, pjsip_rx_data *rdata);
 
 } pjsip_inv_callback;
@@ -588 +612 @@
 
 /**
+ * Create an ACK request. Normally ACK request transmission is handled
+ * by the framework. Application only needs to use this function if it
+ * handles the ACK transmission manually, by overriding \a on_send_ack()
+ * callback in #pjsip_inv_callback.
+ *
+ * Note that if the invite session has a pending offer to be answered 
+ * (for example when the last 2xx response to INVITE contains an offer), 
+ * application MUST have set the SDP answer with #pjsip_create_sdp_body()
+ * prior to creating the ACK request. In this case, the ACK request
+ * will be added with SDP message body.
+ *
+ * @param inv           The invite session.
+ * @param cseq          Mandatory argument to specify the CSeq of the
+ *                      ACK request. This value MUST match the value
+ *                      of the INVITE transaction to be acknowledged.
+ * @param p_tdata       Pointer to receive the ACK request message to
+ *                      be created.
+ *
+ * @return              PJ_SUCCESS if ACK request has been created.
+ */
+PJ_DECL(pj_status_t) pjsip_inv_create_ack(pjsip_inv_session *inv,
+                                          int cseq,
+                                          pjsip_tx_data **p_tdata);
+
+
+/**
  * Send request or response message in tdata. 
  *
@@ -603 +653 @@
 
 
-
 /**
  * Get the invite session for the dialog, if any.