Changeset 1379 for pjproject/trunk/pjmedia/include/pjmedia/sdp_neg.h

Timestamp:

Jun 20, 2007 10:03:46 AM (17 years ago)

Author:

bennylp

Message:

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

File:

• pjproject/trunk/pjmedia/include/pjmedia/sdp_neg.h (modified) (3 diffs)

pjproject/trunk/pjmedia/include/pjmedia/sdp_neg.h

@@ -51 +51 @@
  *     create_w_local_offer()  +-------------+  send_local_offer()
  *     ----------------------->| LOCAL_OFFER |<-----------------------
- *    |                        +-------------+                        |
- *    |                               |                               |
- *    |           set_remote_answer() |                               |
- *    |                               V                               |
- * +--+---+                     +-----------+     negotiate()     +------+
+ *    |                        +-------------+______                  |
+ *    |                               |             \______ cancel()  |
+ *    |           set_remote_answer() |                    \______    |
+ *    |                               V                            \  |
+ * +--+---+                     +-----------+     negotiate()     +-~----+
  * | NULL |                     | WAIT_NEGO |-------------------->| DONE |
  * +------+                     +-----------+                     +------+
@@ -173 +173 @@
  * 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
@@ -599 +622 @@
 
 /**
+ * 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.