Defer response for incoming SIP MESSAGE requests (#4598)

Author: wosrediinanatour

pjsip-apps/build/Samples.mak

@@ -48,8 +48,7 @@ SAMPLES := auddemo \
 	   vid_codec_test \
 	   vid_streamutil
 
-PJSUA2_SAMPLES := pjsua2_demo \
-		pjsua2_hello_reg
+PJSUA2_SAMPLES = pjsua2_demo pjsua2_hello_reg
 
 ifeq ($(EXCLUDE_APP),0)
 EXES := $(foreach file, $(SAMPLES), $(file)$(HOST_EXE))

pjsip/build/Makefile

@@ -161,7 +161,7 @@ export PJSUA2_LIB_LDFLAGS += $(PJSUA_LIB_LDLIB) \
 #
 export PJSUA2_TEST_SRCDIR = ../src/pjsua2-test
 export PJSUA2_TEST_OBJS += $(OS_OBJS) $(M_OBJS) $(CC_OBJS) $(HOST_OBJS) \
-			   main.o
+			   main.o instant_messaging.o
 export PJSUA2_TEST_CFLAGS += $(_CFLAGS) $(PJ_VIDEO_CFLAGS)
 export PJSUA2_TEST_CXXFLAGS = $(_CXXFLAGS) $(PJSUA2_LIB_CFLAGS) $(PJ_VIDEO_CFLAGS)
 export PJSUA2_TEST_LDFLAGS += $(PJ_LDXXFLAGS) $(PJ_LDXXLIBS) $(LDFLAGS)
@@ -170,7 +170,6 @@ export PJSUA2_TEST_EXE := pjsua2-test-$(TARGET_NAME)$(HOST_EXE)
 endif
 export CC_OUT CC AR RANLIB HOST_MV HOST_RM HOST_RMDIR HOST_MKDIR OBJEXT LD LDOUT 
 
-
 ###############################################################################
 # Defines for building test application
 #

pjsip/include/pjsua-lib/pjsua.h

@@ -4782,6 +4782,28 @@ typedef struct pjsua_acc_config
      */
     pj_bool_t        use_shared_auth;
 
+    /**
+    * Specify whether incoming SIP MESSAGE requests are responded
+    * automatically.
+    *
+    * If set to PJ_TRUE (automatic response), incoming MESSAGE requests
+    * will be responded to immediately with SIP 200 OK (legacy behavior).
+    *
+    * If set to PJ_FALSE, incoming MESSAGE requests will create UAS
+    * transactions supporting explicit responses and defering responses.
+    *
+    * The application may either respond immediately in the on_pager() or
+    * on_pager2() callbacks by using pjsua_acc_send_response(), or defer the
+    * response to later time. In the latter case, the application must clone the
+    * rx_data by calling pjsip_rx_data_clone() within on_pager() or on_pager2()
+    * callbacks. The cloned rx_data and the pointer to the transaction can then
+    * be used later for pjsua_acc_send_response().
+    *
+    * Default: PJ_TRUE (automatic response for backward compatibility)
+    */
+    pj_bool_t        auto_repond_sip_message;
+
+
 } pjsua_acc_config;
 
 
@@ -5116,6 +5138,34 @@ PJ_DECL(pj_status_t) pjsua_acc_get_config(pjsua_acc_id acc_id,
 PJ_DECL(pj_status_t) pjsua_acc_modify(pjsua_acc_id acc_id,
                                       const pjsua_acc_config *acc_cfg);
 
+/**
+ * Send response to incoming request (e.g. SIP MESSAGE) that was
+ * processed by a UAS transaction.
+ *
+ * This function can be used when the application wants to defer a
+ * response to an incoming request that was processed by 
+ * a UAS transaction.
+ *
+ * @param acc_id        The account that will send the response.
+ * @param rdata         The received request data.
+ * @param tsx           The UAS transaction that was created for the incoming
+ *                      request.
+ * @param st_code       Status code to be sent (e.g., 200 for OK, 400 for 
+ *                      Bad Request, etc.).
+ * @param st_text       Optional status text. If NULL, default status text for
+ *                      the status code will be used.
+ * @param msg_data      Optional headers etc. to be added to the outgoing
+ *                      response, or NULL if no custom header is desired.
+ *
+ * @return              PJ_SUCCESS on success, or the appropriate error code.
+ */
+PJ_DECL(pj_status_t) pjsua_acc_send_response(pjsua_acc_id acc_id,
+                                             pjsip_rx_data *rdata,
+                                             pjsip_transaction *tsx,
+                                             int st_code,
+                                             const pj_str_t *st_text,
+                                             const pjsua_msg_data *msg_data);
+
 /**
  * Send arbitrary out-of-dialog requests from an account, e.g. OPTIONS.
  * The application should use the call or presence API to create
@@ -5125,7 +5175,8 @@ PJ_DECL(pj_status_t) pjsua_acc_modify(pjsua_acc_id acc_id,
  * @param dest_uri      URI to be put into the To header (normally is the same
  *                      as the target URI).
  * @param method        The SIP method of the request.
- * @param options       This is for future use (currently only NULL is supported).
+ * @param options       This is for future use (currently only NULL is
+ *                      supported).
  * @param token         Arbitrary token (user data owned by the application)
  *                      to be passed back to the application in callback
  *                      on_acc_send_request().
@@ -7284,7 +7335,6 @@ PJ_DECL(pj_status_t) pjsua_im_typing(pjsua_acc_id acc_id,
                                      const pjsua_msg_data *msg_data);
 
 
-
 /**
  * @}
  */

pjsip/include/pjsua2/account.hpp

@@ -311,6 +311,17 @@ struct AccountSipConfig : public PersistentObject
      */
     bool        useSharedAuth;
 
+    /**
+     * Configure automatic SIP-MESSAGE processing behavior for this account.
+     * When set to true, incoming SIP MESSAGE requests will be responded to
+     * immediately with a 200 OK response (legacy behavior). When set to false,
+     * incoming SIP MESSAGE requests will create UAS transactions allowing for
+     * deferred responses, cf. Account::sendResponse() and DeferredResponse.
+     *
+     * Default: true (automatic response for backward compatibility)
+     */
+    bool        autoRespondSipMessage;
+
 public:
     /**
      * Read this object from a container node.
@@ -860,8 +871,6 @@ struct SendRequestParam
     SendRequestParam();
 };
 
-
-
 /**
  * SRTP crypto.
  */
@@ -1931,6 +1940,86 @@ class FindBuddyMatch
     virtual ~FindBuddyMatch() {}
 };
 
+/**
+ * This class is used to store the received parsed SIP MESSAGE request and
+ * its transaction for use in sendResponse().
+ */
+class DeferredResponse
+{
+    friend class Account;
+public:
+    /**
+     * Constructor that clones the rx_data and keeps a non-owning pointer
+     * to the transaction.
+     * @param param        The instant message parameters from the callback.
+     */
+    explicit
+    DeferredResponse(const OnInstantMessageParam& param) PJSUA2_THROW(Error);
+
+    /**
+     * Constructs an empty object. Must be assigned to before use.
+     */
+    DeferredResponse();
+
+     /**
+      * Copies the deferred response object by cloning the rx_data.
+      */
+    DeferredResponse(const DeferredResponse& deferredResponse)
+        PJSUA2_THROW(Error);
+
+    /**
+     * Copies the deferred response object by cloning the rx_data.
+     */
+    DeferredResponse& operator=(const DeferredResponse& deferredResponse)
+        PJSUA2_THROW(Error);
+
+    /**
+     * Moves the deferred response object.
+     */
+    DeferredResponse(DeferredResponse&& deferredResponse) noexcept;
+
+    /**
+     * Moves the deferred response object.
+     */
+    DeferredResponse& operator=(DeferredResponse&& deferredResponse) noexcept;
+
+    /**
+     * Destructor that frees possible cloned rx_data.
+     */
+    virtual ~DeferredResponse();
+
+private:
+    /**
+     * Non-owning pointer to the registered transaction.
+     */
+    pjsip_transaction* transaction;
+
+    /**
+     * Owning pointer to the cloned rx_data.
+     */
+    pjsip_rx_data* data = nullptr;
+};
+
+/**
+ * Parameters for Account::sendResponse().
+ */
+struct SendResponseParam
+{
+    /**
+     * Deferred response object, which is valid until the response is sent.
+     */
+    DeferredResponse deferredResponse;
+
+    /**
+     * Status code of the response.
+     */
+    int         code;
+
+    /**
+     * Optional reason phrase of the response.
+     */
+    string      reason;
+};
 
 /**
  * Account.
@@ -2052,6 +2141,19 @@ class Account
      */
     void sendRequest(const pj::SendRequestParam& prm) PJSUA2_THROW(Error);
 
+    /**
+     * Send response for incoming request that was deferred earlier
+     * using DeferredResponse object.
+     *
+     * @param prm                   The response's parameters.
+     * @param prm.deferredResponse  The deferred response object
+     *                              identifying the incoming request to
+     *                              respond to.
+     * @param prm.code              The status code of the response.
+     * @param prm.reason            Optional reason phrase of the response.
+     */
+    void sendResponse(const pj::SendResponseParam& prm) PJSUA2_THROW(Error);
+
     /**
      * Update registration or perform unregistration. Application normally
      * only needs to call this function if it wants to manually update the

pjsip/src/pjsua-lib/pjsua_acc.c

@@ -4751,3 +4751,55 @@ void pjsua_acc_end_ip_change(pjsua_acc *acc)
     }
     PJSUA_UNLOCK();
 }
+
+/*
+ * Send response to incoming SIP MESSAGE request.
+ */
+PJ_DEF(pj_status_t) pjsua_acc_send_response(pjsua_acc_id acc_id,
+                                            pjsip_rx_data *rdata,
+                                            pjsip_transaction *tsx,
+                                            int st_code,
+                                            const pj_str_t *st_text,
+                                            const pjsua_msg_data *msg_data)
+{
+    pjsip_tx_data *tdata = NULL;
+    pj_status_t status;
+
+    PJ_ASSERT_RETURN(rdata != NULL, PJ_EINVAL);
+    PJ_ASSERT_RETURN(st_code >= 200 && st_code < 700, PJ_EINVAL);
+    PJ_UNUSED_ARG(acc_id);
+
+    if (!tsx) {
+        PJ_LOG(1,(THIS_FILE, "UAS transaction not found for MESSAGE response"));
+        return PJ_ENOTFOUND;
+    }
+
+    PJ_ASSERT_RETURN(tsx->role == PJSIP_ROLE_UAS, PJ_EINVAL);
+    PJ_ASSERT_RETURN(pjsip_method_cmp(&tsx->method, &pjsip_message_method) == 0,
+                     PJ_EINVAL);
+
+    status = pjsip_endpt_create_response(pjsua_var.endpt, rdata,
+                                        st_code, st_text, &tdata);
+    if (status != PJ_SUCCESS) {
+        pjsua_perror(THIS_FILE, "Unable to create response", status);
+        return status;
+    }
+
+    if (msg_data) {
+        pjsip_hdr *hdr;
+        for (hdr = &msg_data->hdr_list; hdr && hdr != &msg_data->hdr_list;
+             hdr=hdr->next) {
+            pjsip_msg_add_hdr(tdata->msg, (pjsip_hdr*)pjsip_hdr_clone(
+                                                    tdata->pool, hdr));
+        }
+    }
+
+    status = pjsip_tsx_send_msg(tsx, tdata);
+    if (status != PJ_SUCCESS) {
+        pjsua_perror(THIS_FILE, "Unable to send response", status);
+        pjsip_tx_data_dec_ref(tdata);
+        return status;
+    }
+
+    return PJ_SUCCESS;
+}

pjsip/src/pjsua-lib/pjsua_core.c

@@ -398,6 +398,8 @@ PJ_DEF(void) pjsua_acc_config_default(pjsua_acc_config *cfg)
                                         PJSUA_CALL_UPDATE_VIA;
     cfg->enable_rtcp_xr = (PJMEDIA_HAS_RTCP_XR && PJMEDIA_STREAM_ENABLE_XR);
     cfg->use_shared_auth = PJ_FALSE;
+
+    cfg->auto_repond_sip_message = PJ_TRUE;
 }
 
 PJ_DEF(void) pjsua_buddy_config_default(pjsua_buddy_config *cfg)