Changeset 797 for pjproject/trunk/pjsip/include/pjsua-lib/pjsua.h

Timestamp:

Nov 11, 2006 4:16:04 PM (17 years ago)

Author:

bennylp

Message:

Attended call transfer implementation. The changes involves:

• Added support for SIP Replaces extension (RFC 3891)
• Added pjsua_call_xfer_replaces() to perform attended call transfer.
• PJSUA checks and process Replaces header in incoming calls
• Added pjsip_ua_find_dialog() API.
• Added pjsip_endpt_has_capability() API.
• Added pjsip_endpt_send_response2() API.
• etc.

File:

• pjproject/trunk/pjsip/include/pjsua-lib/pjsua.h (modified) (3 diffs)

pjproject/trunk/pjsip/include/pjsua-lib/pjsua.h

@@ -338 +338 @@
 
     /**
+     * Notify application about incoming INVITE with Replaces header.
+     * Application may reject the request by setting non-2xx code.
+     *
+     * @param call_id       The call ID to be replaced.
+     * @param rdata         The incoming INVITE request to replace the call.
+     * @param st_code       Status code to be set by application. Application
+     *                      should only return a final status (200-699).
+     * @param st_text       Optional status text to be set by application.
+     */
+    void (*on_call_replace_request)(pjsua_call_id call_id,
+                                    pjsip_rx_data *rdata,
+                                    int *st_code,
+                                    pj_str_t *st_text);
+
+    /**
+     * Notify application that an existing call has been replaced with
+     * a new call. This happens when PJSUA-API receives incoming INVITE
+     * request with Replaces header.
+     *
+     * After this callback is called, normally PJSUA-API will disconnect
+     * \a old_call_id and establish \a new_call_id.
+     *
+     * @param old_call_id   Existing call which to be replaced with the
+     *                      new call.
+     * @param new_call_id   The new call.
+     * @param rdata         The incoming INVITE with Replaces request.
+     */
+    void (*on_call_replaced)(pjsua_call_id old_call_id,
+                             pjsua_call_id new_call_id);
+
+
+    /**
      * Notify application when registration status has changed.
      * Application may then query the account info to get the
@@ -1753 +1785 @@
 
 /**
- * Initiate call transfer to the specified address.
- *
- * @param call_id       Call identification.
+ * Initiate call transfer to the specified address. This function will send
+ * REFER request to instruct remote call party to initiate a new INVITE
+ * session to the specified destination/target.
+ *
+ * @param call_id       The call id to be transfered.
  * @param dest          Address of new target to be contacted.
  * @param msg_data      Optional message components to be sent with
@@ -1765 +1799 @@
                                      const pj_str_t *dest,
                                      const pjsua_msg_data *msg_data);
+
+/**
+ * Flag to indicate that "Require: replaces" should not be put in the
+ * outgoing INVITE request caused by REFER request created by 
+ * #pjsua_call_xfer_replaces().
+ */
+#define PJSUA_XFER_NO_REQUIRE_REPLACES  1
+
+/**
+ * Initiate attended call transfer. This function will send REFER request
+ * to instruct remote call party to initiate new INVITE session to the URL
+ * of \a dest_call_id. The party at \a dest_call_id then should "replace"
+ * the call with us with the new call from the REFER recipient.
+ *
+ * @param call_id       The call id to be transfered.
+ * @param dest_call_id  The call id to be replaced.
+ * @param options       Application may specify PJSUA_XFER_NO_REQUIRE_REPLACES
+ *                      to suppress the inclusion of "Require: replaces" in
+ *                      the outgoing INVITE request created by the REFER
+ *                      request.
+ * @param msg_data      Optional message components to be sent with
+ *                      the request.
+ *
+ * @return              PJ_SUCCESS on success, or the appropriate error code.
+ */
+PJ_DECL(pj_status_t) pjsua_call_xfer_replaces(pjsua_call_id call_id, 
+                                              pjsua_call_id dest_call_id,
+                                              unsigned options,
+                                              const pjsua_msg_data *msg_data);
 
 /**