chan_pjsip: Add PJSIPHangup dialplan app and manager action

See UserNote below.

Exposed the existing Hangup AMI action in manager.c so we can use
all of it's channel search and AMI protocol handling without
duplicating that code in dialplan_functions.c.

Added a lookup function to res_pjsip.c that takes in the
string represenation of the pjsip_status_code enum and returns
the actual status code.  I.E.  ast_sip_str2rc("DECLINE") returns
603.  This allows the caller to specify PJSIPHangup(decline) in
the dialplan, just like Hangup(call_rejected).

Also extracted the XML documentation to its own file since it was
almost as large as the code itself.

UserNote: A new dialplan app PJSIPHangup and AMI action allows you
to hang up an unanswered incoming PJSIP call with a specific SIP
response code in the 400 -> 699 range.

(cherry picked from commit af7e89ebf8)

include/asterisk/manager.h

@@ -621,4 +621,45 @@ void ast_manager_publish_event(const char *type, int class_type, struct ast_json
  */
 struct stasis_message_router *ast_manager_get_message_router(void);
 
+/*!
+ * \brief Callback used by ast_manager_hangup_helper
+ *        that will actually hangup a channel
+ *
+ * \param chan The channel to hang up
+ * \param causecode Cause code to set on the channel
+ */
+typedef void (*manager_hangup_handler_t)(struct ast_channel *chan, int causecode);
+
+/*!
+ * \brief Callback used by ast_manager_hangup_helper
+ *        that will validate the cause code.
+
+ * \param channel_name Mostly for displaying log messages
+ * \param cause Cause code string
+ *
+ * \returns integer cause code
+ */
+typedef int (*manager_hangup_cause_validator_t)(const char *channel_name,
+	const char *cause);
+
+/*!
+ * \brief A manager helper function that hangs up a channel using a supplied
+ *        channel type specific hangup function and cause code validator
+ *
+ * This function handles the lookup of channel(s) and the AMI interaction
+ * but uses the supplied callbacks to actually perform the hangup.  It can be
+ * used to implement a custom AMI 'Hangup' action without having to duplicate
+ * all the code in the standard Hangup action.
+ *
+ * \param s Session
+ * \param m Message
+ * \param handler Function that actually performs the hangup
+ * \param cause_validator Function that validates the cause code
+ *
+ * \retval 0 on success.
+ * \retval non-zero on error.
+ */
+int ast_manager_hangup_helper(struct mansession *s, const struct message *m,
+	manager_hangup_handler_t handler, manager_hangup_cause_validator_t cause_validator);
+
 #endif /* _ASTERISK_MANAGER_H */

include/asterisk/res_pjsip.h

@@ -4212,5 +4212,17 @@ unsigned int ast_sip_get_all_codecs_on_empty_reinvite(void);
  */
 const int ast_sip_hangup_sip2cause(int cause);
 
+/*!
+ * \brief Convert name to SIP response code
+ *
+ * \param name SIP response code name matching one of the
+ *             enum names defined in "enum pjsip_status_code"
+ *             defined in sip_msg.h.  May be specified with or
+ *             without the PJSIP_SC_ prefix.
+ *
+ * \retval SIP response code
+ * \retval -1 if matching code not found
+ */
+int ast_sip_str2rc(const char *name);
 
 #endif /* _RES_PJSIP_H */