More on ticket #399: a)send full offer on 200/OK response when re-INVITE does not have SDP, b) added on_create_offer() callback, c) handle some error cases

git-svn-id: http://svn.pjsip.org/repos/pjproject/trunk@1379 74dad513-b988-da41-8d7b-12977e46ad98

2 files changed, 60 insertions, 5 deletions

diff --git a/pjmedia/include/pjmedia/sdp_neg.h b/pjmedia/include/pjmedia/sdp_neg.h
index 3f8481da..bf75a3ac 100644
--- a/pjmedia/include/pjmedia/sdp_neg.h
+++ b/pjmedia/include/pjmedia/sdp_neg.h
@@ -50,11 +50,11 @@
  *                                              modify_local_offer()
  *     create_w_local_offer()  +-------------+  send_local_offer()
  *     ----------------------->| LOCAL_OFFER |<-----------------------
- *    |                        +-------------+                        |
- *    |                               |                               |
- *    |           set_remote_answer() |                               |
- *    |                               V                               |
- * +--+---+                     +-----------+     negotiate()     +------+
+ *    |                        +-------------+______                  |
+ *    |                               |             \______ cancel()  |
+ *    |           set_remote_answer() |                    \______    |
+ *    |                               V                            \  |
+ * +--+---+                     +-----------+     negotiate()     +-~----+
  * | NULL |                     | WAIT_NEGO |-------------------->| DONE |
  * +------+                     +-----------+                     +------+
  *    |                               A                               |
@@ -173,6 +173,29 @@
  * the negotiator state will move to PJMEDIA_SDP_NEG_STATE_DONE.
  * 
  *
+ * \subsection sdpneg_cancel_offer Cancelling an Offer
+ *
+ * In other case, after an offer is generated (negotiator state is in
+ * PJMEDIA_SDP_NEG_STATE_LOCAL_OFFER), the answer may not be received, and
+ * application wants the negotiator to reset itself to its previous state.
+ * Consider this example:
+ *
+ *  - media has been established, and negotiator state is
+ *    PJMEDIA_SDP_NEG_STATE_DONE.
+ *  - application generates a new offer for re-INVITE, so in this case
+ *    it would either call #pjmedia_sdp_neg_send_local_offer() or
+ *    #pjmedia_sdp_neg_modify_local_offer()
+ *  - the negotiator state moves to PJMEDIA_SDP_NEG_STATE_LOCAL_OFFER
+ *  - the re-INVITE was rejected with an error
+ *
+ * Since an answer is not received, it is necessary to reset the negotiator
+ * state back to PJMEDIA_SDP_NEG_STATE_DONE so that the negotiator can
+ * create or receive new offer.
+ *
+ * This can be accomplished by calling #pjmedia_sdp_neg_cancel_offer(),
+ * to reset the negotiator state back to PJMEDIA_SDP_NEG_STATE_DONE. In
+ * this case, both active local and active remote will not be modified.
+ *
  * \subsection sdpneg_create_answer Generating SDP Answer
  *
  * After remote offer has been set in the negotiator, application can 
@@ -598,6 +621,18 @@ PJ_DECL(pj_bool_t) pjmedia_sdp_neg_has_local_answer(pjmedia_sdp_neg *neg);
 
 
 /**
+ * Cancel previously sent offer, and move negotiator state back to
+ * previous stable state (PJMEDIA_SDP_NEG_STATE_DONE). The negotiator
+ * must be in PJMEDIA_SDP_NEG_STATE_LOCAL_OFFER state.
+ *
+ * @param neg		The negotiator.
+ *
+ * @return		PJ_SUCCESS or the appropriate error code.
+ */
+PJ_DECL(pj_status_t) pjmedia_sdp_neg_cancel_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
diff --git a/pjmedia/src/pjmedia/sdp_neg.c b/pjmedia/src/pjmedia/sdp_neg.c
index ecbba9eb..f24dc41e 100644
--- a/pjmedia/src/pjmedia/sdp_neg.c
+++ b/pjmedia/src/pjmedia/sdp_neg.c
@@ -985,6 +985,26 @@ static pj_status_t create_answer( pj_pool_t *pool,
     return has_active ? PJ_SUCCESS : status;
 }
 
+/* Cancel offer */
+PJ_DEF(pj_status_t) pjmedia_sdp_neg_cancel_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_LOCAL_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;
+    neg->has_remote_answer = PJ_FALSE;
+
+    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,