Ticket #817: sdp_neg_cancel_remote_offer_r2669.patch

pjmedia/include/pjmedia/sdp_neg.h

@@ -50 +50 @@
  *                                              
  *                                              modify_local_offer()
  *     create_w_local_offer()  +-------------+  send_local_offer()
- *     ----------------------->| LOCAL_OFFER |<-----------------------
+ *    /----------------------->| LOCAL_OFFER |<-----------------------\
  *    |                        +-------------+______                  |
- *    |                               |             \______ cancel()  |
- *    |           set_remote_answer() |                    \______    |
- *    |                               V                            \  |
+ *    |                               |             \_____________    |
+ *    |           set_remote_answer() |           cancel_offer()  \   |
+ *    |                               V                            v  |
  * +--+---+                     +-----------+     negotiate()     +-~----+
  * | NULL |                     | WAIT_NEGO |-------------------->| DONE |
  * +------+                     +-----------+                     +------+
- *    |                               A                               |
- *    |            set_local_answer() |                               |
- *    |                               |                               |
+ *    |                               A      ______________________^  |
+ *    |            set_local_answer() |     / cancel_remote_offer()   |
+ *    |                               |    /                          |
  *    |                        +--------------+   set_remote_offer()  |
- *     ----------------------->| REMOTE_OFFER |<----------------------
+ *    \----------------------->| REMOTE_OFFER |<----------------------/
  *     create_w_remote_offer() +--------------+
  *
  * </pre>
@@ -255 +255 @@
  * Regardless of the return status of the #pjmedia_sdp_neg_negotiate(), 
  * the negotiator state will move to PJMEDIA_SDP_NEG_STATE_DONE.
  *
+ * \subsection sdpneg_cancel_remote_offer Cancelling Remote Offer
+ * 
+ * In other scenarios, application may want to reset the negotiator state
+ * after it has set a remote offer. Consider the following scenario:
+ *  - media has been established, and negotiator state is
+ *    PJMEDIA_SDP_NEG_STATE_DONE.
+ *  - application receives a new offer in re-INVITE, so in this case
+ *    it would call #pjmedia_sdp_neg_set_remote_offer().
+ *  - the negotiator state moves to PJMEDIA_SDP_NEG_STATE_REMOTE_OFFER
+ *  - application rejects the re-INVITE request with non-successful
+ *    final response.
  *
+ * In this case, application can call #pjmedia_sdp_neg_cancel_remote_offer()
+ * to reset the negotiator state back to PJMEDIA_SDP_NEG_STATE_DONE.
  */
 
 #include <pjmedia/sdp.h>
@@ -634 +647 @@
 
 
 /**
+ * Cancel previously received remote offer, and move negotiator state back
+ * to previous stable state ((PJMEDIA_SDP_NEG_STATE_DONE). The negotiator
+ * must be in PJMEDIA_SDP_NEG_STATE_REMOTE_OFFER state.
+ *
+ * @param neg           The negotiator.
+ *
+ * @return              PJ_SUCCESS or the appropriate error code.
+ */
+PJ_DECL(pj_status_t) pjmedia_sdp_neg_cancel_remote_offer(pjmedia_sdp_neg *neg);
+
+
+/**
  * Negotiate local and remote answer. Before calling this function, the
  * SDP negotiator must be in PJMEDIA_SDP_NEG_STATE_WAIT_NEGO state.
  * After calling this function, the negotiator state will move to

pjmedia/src/pjmedia/sdp_neg.c

@@ -1346 +1346 @@
 }
 
 
+/* Cancel remote offer */
+PJ_DEF(pj_status_t) pjmedia_sdp_neg_cancel_remote_offer(pjmedia_sdp_neg *neg)
+{
+    PJ_ASSERT_RETURN(neg, PJ_EINVAL);
+
+    /* Must be in LOCAL_OFFER state. */
+    PJ_ASSERT_RETURN(neg->state == PJMEDIA_SDP_NEG_STATE_REMOTE_OFFER,
+                     PJMEDIA_SDPNEG_EINSTATE);
+
+    /* Reset state to done */
+    neg->state = PJMEDIA_SDP_NEG_STATE_DONE;
+
+    /* Clear temporary SDP */
+    neg->neg_local_sdp = neg->neg_remote_sdp = NULL;
+
+    return PJ_SUCCESS;
+}
+
+
 /* The best bit: SDP negotiation function! */
 PJ_DEF(pj_status_t) pjmedia_sdp_neg_negotiate( pj_pool_t *pool,
                                                pjmedia_sdp_neg *neg,