dialog API: Clarify documentation for DLGCB_FAILED

The DLGCB_FAILED callback is subject to the "200 OK" vs. "408 timeout"
SIP race condition during dialog establishment and developers should use
it with extra caution :)

(cherry picked from commit 1f2c8c4)

modules/dialog/dlg_cb.h

@@ -67,13 +67,16 @@ typedef int (*register_dlgcb_f)(struct dlg_cell* dlg, int cb_types,
 #define DLGCB_CREATED         (1<<1)
 
 /*
- * The dialog unequivocally failed to establish (a 3xx-6xx reply was received
- * and is being relayed upstream).  The reply is available, however any
- * changes performed on it will be ignored.
+ * The dialog apparently failed to establish (a 3xx-6xx reply was received
+ * and is being relayed upstream) and is now in the "terminated" state, with a
+ * small possibility to go *back* to a "confirmed" state if the reply was
+ * internally generated and is racing against a 200 OK from the actual callee!
+ *
+ * The reply is available, however any changes performed on it will be ignored.
  *
  * SIP signaling: initial INVITE and a 3xx-6xx reply
  * Registration:  per-dialog, "dlg" must be given
- * Trigger count: once per dialog
+ * Trigger count: 0 - 1 times per dialog
  */
 #define DLGCB_FAILED          (1<<2)
 
@@ -102,29 +105,34 @@ typedef int (*register_dlgcb_f)(struct dlg_cell* dlg, int cb_types,
 #define DLGCB_REQ_WITHIN      (1<<4)
 
 /*
- * The dialog's state has progressed to "terminated", either through a BYE
- * request generated by one of the participants or an internally-generated
- * dialog termination, due to several reasons:
+ * The dialog's state has unequivocally progressed to "terminated", either
+ * through a BYE request generated by one of the participants or an internally
+ * generated dialog termination, due to several reasons:
  *   - API-based termination (e.g. user ran out of credit)
  *   - MI-based termination
  *
  * SIP signaling: confirmed and acknowledged dialog, and a BYE or an internal
  *                termination (in the latter case, OpenSIPS will take
  *                care of generating proper BYEs for each participant)
  * Registration:  per-dialog, "dlg" must be given
- * Trigger count: once per dialog
+ * Trigger count: 0 - 1 times per dialog, exclusive with DLGCB_EXPIRED, and one
+ *                of these two will always be called for a dialog
  */
 #define DLGCB_TERMINATED      (1<<5)
 
 /*
- * The dialog's state has progressed to "terminated" strictly because the
+ * The dialog's state has unequivocally progressed to "terminated" because the
  * maximum timeout value ($DLG_timeout) has been reached.  OpenSIPS will take
  * care of generating proper BYEs for each participant.
  *
  * SIP signaling: confirmed and acknowledged dialog with exceeded max lifetime
  * Registration:  per-dialog, "dlg" must be given
- * Trigger count: once per dialog; if using replication sharing tags, this
- *                callback is ran only by the node that has the Active tag.
+ * Trigger count:
+ *                * 0 - 1 times per dialog, exclusive with DLGCB_TERMINATED,
+ *                  and one of these two will always be called for a dialog
+ *
+ *                * if using replication sharing tags, this callback is only
+ *                  ran by the node that has the Active tag.
  */
 #define DLGCB_EXPIRED         (1<<6)
 

modules/dialog/dlg_handlers.c

@@ -665,8 +665,10 @@ static void dlg_onreply(struct cell* t, int type, struct tmcb_params *param)
 		destroy_linkers(dlg);
 		remove_dlg_prof_table(dlg, 1);
 
-		/* dialog setup not completed (3456XX) */
+		/* dialog setup not completed (3456XX), but there is still a bit of
+		 * room to go *back* to 2XX if we're racing against a 200 OK! */
 		run_dlg_callbacks(DLGCB_FAILED, dlg, rpl, DLG_DIR_UPSTREAM, NULL, 0, 1);
+
 		/* do unref */
 		if (unref)
 			unref_dlg(dlg,unref);