Merge "chan_sip: option 'notifyringing' change and doc fix"

channels/chan_sip.c

@@ -14655,7 +14655,7 @@ static void state_notify_build_xml(struct state_notify_data *data, int full, con
 
 	switch (data->state) {
 	case (AST_EXTENSION_RINGING | AST_EXTENSION_INUSE):
-		statestring = (sip_cfg.notifyringing) ? "early" : "confirmed";
+		statestring = (sip_cfg.notifyringing == NOTIFYRINGING_ENABLED) ? "early" : "confirmed";
 		local_state = NOTIFY_INUSE;
 		pidfstate = "busy";
 		pidfnote = "Ringing";
@@ -21193,7 +21193,7 @@ static char *sip_show_settings(struct ast_cli_entry *e, int cmd, struct ast_cli_
 	ast_cli(a->fd, "  Outbound reg. timeout:  %d secs\n", global_reg_timeout);
 	ast_cli(a->fd, "  Outbound reg. attempts: %d\n", global_regattempts_max);
 	ast_cli(a->fd, "  Outbound reg. retry 403:%d\n", global_reg_retry_403);
-	ast_cli(a->fd, "  Notify ringing state:   %s\n", AST_CLI_YESNO(sip_cfg.notifyringing));
+	ast_cli(a->fd, "  Notify ringing state:   %s%s\n", AST_CLI_YESNO(sip_cfg.notifyringing), sip_cfg.notifyringing == NOTIFYRINGING_NOTINUSE ? " (when not in use)" : "");
 	if (sip_cfg.notifyringing) {
 		ast_cli(a->fd, "    Include CID:          %s%s\n",
 				AST_CLI_YESNO(sip_cfg.notifycid),
@@ -31740,7 +31740,11 @@ static int reload_config(enum channelreloadreason reason)
 		} else if (!strcasecmp(v->name, "directrtpsetup")) {
 			sip_cfg.directrtpsetup = ast_true(v->value);
 		} else if (!strcasecmp(v->name, "notifyringing")) {
-			sip_cfg.notifyringing = ast_true(v->value);
+			if (!strcasecmp(v->value, "notinuse")) {
+				sip_cfg.notifyringing = NOTIFYRINGING_NOTINUSE;
+			} else {
+				sip_cfg.notifyringing = ast_true(v->value) ? NOTIFYRINGING_ENABLED : NOTIFYRINGING_DISABLED;
+			}
 		} else if (!strcasecmp(v->name, "notifyhold")) {
 			sip_cfg.notifyhold = ast_true(v->value);
 		} else if (!strcasecmp(v->name, "notifycid")) {

channels/sip/include/sip.h

@@ -211,7 +211,7 @@
 #define DEFAULT_ALLOW_EXT_DOM  TRUE    /*!< Allow external domains */
 #define DEFAULT_REALM          "asterisk" /*!< Realm for HTTP digest authentication */
 #define DEFAULT_DOMAINSASREALM FALSE    /*!< Use the domain option to guess the realm for registration and invite requests */
-#define DEFAULT_NOTIFYRINGING  TRUE     /*!< Notify devicestate system on ringing state */
+#define DEFAULT_NOTIFYRINGING  NOTIFYRINGING_ENABLED /*!< Notify devicestate system on ringing state */
 #define DEFAULT_NOTIFYCID      DISABLED	/*!< Include CID with ringing notifications */
 #define DEFAULT_PEDANTIC       TRUE     /*!< Follow SIP standards for dialog matching */
 #define DEFAULT_AUTOCREATEPEER AUTOPEERS_DISABLED    /*!< Don't create peers automagically */
@@ -622,6 +622,13 @@ enum sipmethod {
 	SIP_PING,       /*!< Not supported at all, no standard but still implemented out there */
 };
 
+/*! \brief Setting for the 'notifyringing' option, see sip.conf.sample for details. */
+enum notifyringing_setting {
+	NOTIFYRINGING_DISABLED = 0,
+	NOTIFYRINGING_ENABLED = 1,
+	NOTIFYRINGING_NOTINUSE = 2,
+};
+
 /*! \brief Settings for the 'notifycid' option, see sip.conf.sample for details. */
 enum notifycid_setting {
 	DISABLED       = 0,

configs/samples/sip.conf.sample

@@ -694,8 +694,12 @@ srvlookup=yes                   ; Enable DNS SRV lookups on outbound calls
 ;subscribecontext = default     ; Set a specific context for SUBSCRIBE requests
                                 ; Useful to limit subscriptions to local extensions
                                 ; Settable per peer/user also
-;notifyringing = no             ; Control whether subscriptions already INUSE get sent
-                                ; RINGING when another call is sent (default: yes)
+;notifyringing = no             ; Control when subscriptions get notified of ringing state.
+                                ; Specify 'no' to not send any ringing notifications.
+                                ; Specify 'yes' to always send ringing notifications (default).
+                                ; Specify 'notinuse' to only send ringing notifications for
+                                ; extensions that are not currently in use. This is useful as a
+                                ; visual indication of who is available to pick up an incoming call
 ;notifyhold = yes               ; Notify subscriptions on HOLD state (default: no)
                                 ; Turning on notifyringing and notifyhold will add a lot
                                 ; more database transactions if you are using realtime.