codec negotiation: add incoming_call_offer_prefs option

Add a new option, incoming_call_offer_pref, to res_pjsip endpoints that
specifies the preferred order of codecs after receiving an offer.

This patch does the following:

  Adds a new enumeration, ast_sip_call_codec_pref, used by the the new
configuration option that's added to the endpoint media structure.

  Adds a new ast_sip_session_caps structure that's set for each session media
object.

  Creates a new file, res_pjsip_session_caps that "implements" the new
structure and option, and is compiled into the res_pjsip_session library.

ASTERISK-28756 #close

Change-Id: I35e7a2a0c236cfb6bd9cdf89539f57a1ffefc76f

include/asterisk/res_pjsip.h

@@ -509,6 +509,24 @@ enum ast_sip_session_redirect {
 	AST_SIP_REDIRECT_URI_PJSIP,
 };
 
+/*!
+ * \brief Incoming/Outgoing call offer/answer joint codec preference.
+ */
+enum ast_sip_call_codec_pref {
+	/*! Prefer, and order by local values */
+	AST_SIP_CALL_CODEC_PREF_LOCAL,
+	/*! Prefer, and order by local values (intersection) */
+	AST_SIP_CALL_CODEC_PREF_LOCAL_LIMIT,
+	/*! Prefer, and order by local values (top/first only) */
+	AST_SIP_CALL_CODEC_PREF_LOCAL_SINGLE,
+	/*! Prefer, and order by remote values */
+	AST_SIP_CALL_CODEC_PREF_REMOTE,
+	/*! Prefer, and order by remote values (intersection) */
+	AST_SIP_CALL_CODEC_PREF_REMOTE_LIMIT,
+	/*! Prefer, and order by remote values (top/first only) */
+	AST_SIP_CALL_CODEC_PREF_REMOTE_SINGLE,
+};
+
 /*!
  * \brief Session timers options
  */
@@ -750,6 +768,8 @@ struct ast_sip_endpoint_media_configuration {
 	unsigned int bundle;
 	/*! Enable webrtc settings and defaults */
 	unsigned int webrtc;
+	/*! Codec preference for an incoming offer */
+	enum ast_sip_call_codec_pref incoming_call_offer_pref;
 };
 
 /*!

include/asterisk/res_pjsip_session.h

@@ -59,6 +59,7 @@ enum ast_sip_session_t38state {
 
 struct ast_sip_session_sdp_handler;
 struct ast_sip_session;
+struct ast_sip_session_caps;
 struct ast_sip_session_media;
 
 typedef struct ast_frame *(*ast_sip_session_media_read_cb)(struct ast_sip_session *session, struct ast_sip_session_media *session_media);
@@ -79,6 +80,8 @@ struct ast_sip_session_media {
 	struct ast_sip_session_sdp_handler *handler;
 	/*! \brief Holds SRTP information */
 	struct ast_sdp_srtp *srtp;
+	/*! \brief Media format capabilities */
+	struct ast_sip_session_caps *caps;
 	/*! \brief What type of encryption is in use on this stream */
 	enum ast_sip_session_media_encryption encryption;
 	/*! \brief The media transport in use for this stream */

include/asterisk/res_pjsip_session_caps.h

@@ -0,0 +1,82 @@
+/*
+ * Asterisk -- An open source telephony toolkit.
+ *
+ * Copyright (C) 2020, Sangoma Technologies Corporation
+ *
+ * Kevin Harwell <kharwell@sangoma.com>
+ *
+ * See http://www.asterisk.org for more information about
+ * the Asterisk project. Please do not directly contact
+ * any of the maintainers of this project for assistance;
+ * the project provides a web site, mailing lists and IRC
+ * channels for your use.
+ *
+ * This program is free software, distributed under the terms of
+ * the GNU General Public License Version 2. See the LICENSE file
+ * at the top of the source tree.
+ */
+#ifndef RES_PJSIP_SESSION_CAPS_H
+#define RES_PJSIP_SESSION_CAPS_H
+
+struct ast_format_cap;
+struct ast_sip_session;
+struct ast_sip_session_media;
+struct ast_sip_session_caps;
+
+/*!
+ * \brief Allocate a SIP session capabilities object.
+ * \since 18.0.0
+ *
+ * \retval An ao2 allocated SIP session capabilities object, or NULL on error
+ */
+struct ast_sip_session_caps *ast_sip_session_caps_alloc(void);
+
+/*!
+ * \brief Set the incoming call offer capabilities for a session.
+ * \since 18.0.0
+ *
+ * This will replace any capabilities already present.
+ *
+ * \param caps A session's capabilities object
+ * \param cap The capabilities to set it to
+ */
+void ast_sip_session_set_incoming_call_offer_cap(struct ast_sip_session_caps *caps,
+	struct ast_format_cap *cap);
+
+/*!
+ * \brief Get the incoming call offer capabilities.
+ * \since 18.0.0
+ *
+ * \note Returned objects reference is not incremented.
+ *
+ * \param caps A session's capabilities object
+ *
+ * \retval An incoming call offer capabilities object
+ */
+const struct ast_format_cap *ast_sip_session_get_incoming_call_offer_cap(
+	const struct ast_sip_session_caps *caps);
+
+/*!
+ * \brief Make the incoming call offer capabilities for a session.
+ * \since 18.0.0
+ *
+ * Creates and sets a list of joint capabilities between the given remote
+ * capabilities, and pre-configured ones. The resulting joint list is then
+ * stored, and 'owned' (reference held) by the session.
+ *
+ * If the incoming capabilities have been set elsewhere, this will not replace
+ * those. It will however, return a pointer to the current set.
+ *
+ * \note Returned object's reference is not incremented.
+ *
+ * \param session The session
+ * \param session_media An associated media session
+ * \param remote Capabilities of a device
+ *
+ * \retval A pointer to the incoming call offer capabilities
+ */
+const struct ast_format_cap *ast_sip_session_join_incoming_call_offer_cap(
+	const struct ast_sip_session *session, const struct ast_sip_session_media *session_media,
+	const struct ast_format_cap *remote);
+
+#endif /* RES_PJSIP_SESSION_CAPS_H */