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

doc/CHANGES-staging/res_pjsip_incoming_call_offer_pref.txt

@@ -0,0 +1,53 @@
+Subject: res_pjsip
+Subject: res_pjsip_session
+Master-Only: True
+
+A new option, incoming_call_offer_pref, was added to res_pjsip endpoints that
+specifies the preferred order of codecs to use between those received in the
+offer, and those set in the configuration.
+
+Valid values include:
+  local - prefer and order by configuration (default).
+  local_single - prefer and order by configuration, but only choose 'top'
+                 most codec
+  remote - prefer and order by incoming sdp.
+  remote_single - prefer and order by incoming sdp, but only choose 'top' most
+                  most codec
+
+Example A:
+  [alice]
+  type=endpoint
+  incoming_call_offer_pref=local
+  allow=!all,opus,alaw,ulaw
+
+  Alice's incoming sdp=g722,ulaw,alaw
+  RESULT: alaw,ulaw
+
+Example B:
+  [alice]
+  type=endpoint
+  incoming_call_offer_pref=local_single
+  allow=!all,opus,alaw,ulaw
+
+  Alice's incoming sdp=g722,ulaw,alaw
+  RESULT: alaw
+
+Example C:
+  [alice]
+  type=endpoint
+  incoming_call_offer_pref=remote
+  allow=!all,opus,alaw,ulaw
+
+  Alice's incoming sdp=g722,ulaw,alaw
+  RESULT: ulaw,alaw
+
+Example D:
+  [alice]
+  type=endpoint
+  incoming_call_offer_pref=remote_single
+  allow=!all,opus,alaw,ulaw
+
+  Alice's incoming sdp=g722,ulaw,alaw
+  RESULT: ulaw
+
+