add libosmo-sdp [1/n] add fmtp.h, sdp_strings.h

Add new noinst-library libosmo-sdp.la.

It will be used by
- osmo-mgw
- libosmo-mgcp-client
- callers of libosmo-mgcp-client may use SDP message parsing (osmo-msc)

The API will, with upcoming patches:
- parse and compose SDP fmtp strings
- manage SDP codecs and codec lists (like 'AMR:octet-align=1#112')
- parse and compose entire SDP messages

In this patch: parse and compose SDP fmtp strings.

Add libosmo-sdp build fu.
Add sdp/fmtp.h and sdp/sdp_strings.h.
Add tests/sdp/sdp_fmtp_test.c.

Change-Id: I6128852f4d249e90319f43d6cd6ed0a9a2ed0430

Makefile.am

@@ -18,6 +18,7 @@ SUBDIRS = \
 
 pkgconfigdir = $(libdir)/pkgconfig
 pkgconfig_DATA = \
+	libosmo-sdp.pc \
 	libosmo-mgcp-client.pc \
 	$(NULL)
 

configure.ac

@@ -187,11 +187,14 @@ AM_CONFIG_HEADER(bscconfig.h)
 
 AC_OUTPUT(
     libosmo-mgcp-client.pc
+    libosmo-sdp.pc
     include/Makefile
     include/osmocom/Makefile
+    include/osmocom/sdp/Makefile
     include/osmocom/mgcp_client/Makefile
     include/osmocom/mgcp/Makefile
     src/Makefile
+    src/libosmo-sdp/Makefile
     src/libosmo-mgcp-client/Makefile
     src/libosmo-mgcp/Makefile
     src/osmo-mgw/Makefile
@@ -199,6 +202,7 @@ AC_OUTPUT(
     tests/atlocal
     tests/mgcp_client/Makefile
     tests/mgcp/Makefile
+    tests/sdp/Makefile
     doc/Makefile
     doc/examples/Makefile
     doc/manuals/Makefile

debian/control

@@ -36,6 +36,21 @@ Multi-Arch: same
 Depends: libosmo-mgcp-client14 (= ${binary:Version}), ${misc:Depends}
 Description: libosmo-mgcp-client: Osmocom's Media Gateway Control Protocol client utilities
 
+Package: libosmo-sdp1
+Section: libs
+Architecture: any
+Multi-Arch: same
+Pre-Depends: ${misc:Pre-Depends}
+Depends: ${misc:Depends}, ${shlibs:Depends}
+Description: libosmo-sdp: Osmocom's Session Description Protocol encoder and decoder
+
+Package: libosmo-sdp-dev
+Section: libdevel
+Architecture: any
+Multi-Arch: same
+Depends: libosmo-sdp1 (= ${binary:Version}), ${misc:Depends}
+Description: libosmo-sdp: Osmocom's Session Description Protocol encoder and decoder
+
 Package: osmo-mgw-doc
 Architecture: all
 Section: doc

debian/copyright

@@ -63,3 +63,22 @@ License:   GPL-3.0+
 Files:     osmoappdesc.py
 Copyright: 2013 Katerina Barone-Adesi <kat.obsc@gmail.com>
 License:   GPL-3.0+
+
+Files:     src/libosmo-sdp/* include/osmocom/sdp/*
+Copyright: 2024 by sysmocom s.f.m.c. GmbH <info@sysmocom.de>
+License:   GPL-3.0+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+ .
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU General Public License for more details.
+ .
+ You should have received a copy of the GNU General Public License
+ along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ .
+ On Debian systems, the complete text of the GNU General Public License
+ Version 3 can be found in `/usr/share/common-licenses/GPL-3'.

debian/libosmo-sdp-dev.install

@@ -0,0 +1,4 @@
+usr/include/osmocom/sdp
+usr/lib/*/libosmo-sdp.so
+usr/lib/*/libosmo-sdp.a
+usr/lib/*/pkgconfig/libosmo-sdp.pc

debian/libosmo-sdp1.install

@@ -0,0 +1 @@
+usr/lib/*/libosmo-sdp.so.*

include/Makefile.am

@@ -8,6 +8,8 @@ nobase_include_HEADERS = \
 	osmocom/mgcp_client/mgcp_client_endpoint_fsm.h \
 	osmocom/mgcp_client/mgcp_client_fsm.h \
 	osmocom/mgcp_client/mgcp_client_pool.h \
+	osmocom/sdp/fmtp.h \
+	osmocom/sdp/sdp_strings.h \
 	$(NULL)
 
 noinst_HEADERS = \

include/osmocom/Makefile.am

@@ -1,4 +1,5 @@
 SUBDIRS = \
+	sdp \
 	mgcp_client \
 	mgcp \
 	$(NULL)

include/osmocom/sdp/fmtp.h

@@ -0,0 +1,33 @@
+/* Public API for codec management in SDP messages: managing SDP fmtp strings. */
+/*
+ * (C) 2024 by sysmocom - s.f.m.c. GmbH <info@sysmocom.de>
+ * All Rights Reserved.
+ *
+ * Author: Neels Janosch Hofmeyr <nhofmeyr@sysmocom.de>
+ *
+ * SPDX-License-Identifier: GPL-2.0+
+ *
+ *  This program is free software; you can redistribute it and/or modify
+ *  it under the terms of the GNU General Public License as published by
+ *  the Free Software Foundation; either version 2 of the License, or
+ *  (at your option) any later version.
+ *
+ *  This program is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU General Public License for more details.
+ *
+ *  You should have received a copy of the GNU General Public License
+ *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ *
+ */
+#pragma once
+
+#include <stddef.h>
+#include <stdbool.h>
+#include <stdint.h>
+
+bool osmo_sdp_fmtp_get_val(char *val, size_t val_size, const char *fmtp, const char *option_name);
+int64_t osmo_sdp_fmtp_get_int(const char *fmtp, const char *option_name, int64_t default_value);
+
+bool osmo_sdp_fmtp_amr_is_octet_aligned(const char *fmtp);

include/osmocom/sdp/sdp_strings.h

@@ -0,0 +1,39 @@
+/* Central definition of string tokens used for parsing and composing SDP messages */
+#pragma once
+
+#define OSMO_SDP_STR_MEDIA "m"
+#define OSMO_SDP_STR_ATTRIB "a"
+#define OSMO_SDP_STR_TIME_ACTIVE "t"
+
+#define OSMO_SDP_STR_RTPMAP "rtpmap"
+#define OSMO_SDP_STR_FMTP "fmtp"
+#define OSMO_SDP_STR_PTIME "ptime"
+
+/*! "a=foo:" */
+#define OSMO_SDP_A_PREFIX(STR) OSMO_SDP_STR_ATTRIB "=" STR ":"
+
+/*! "a=fmtp:" */
+#define OSMO_SDP_STR_A_FMTP OSMO_SDP_A_PREFIX(OSMO_SDP_STR_FMTP)
+
+/* Media Direction Attributes "a=recvonly", "a=sendrecv", "a=sendonly", "a=inactive" RFC-8866 6.7. */
+#define OSMO_SDP_STR_RECVONLY "recvonly"
+#define OSMO_SDP_STR_SENDRECV "sendrecv"
+#define OSMO_SDP_STR_SENDONLY "sendonly"
+#define OSMO_SDP_STR_INACTIVE "inactive"
+
+/* AMR related tokens */
+
+#define OSMO_SDP_STR_AMR_OCTET_ALIGN "octet-align"
+
+/*! "octet-align=1" */
+#define OSMO_SDP_STR_AMR_OCTET_ALIGN_1  OSMO_SDP_STR_AMR_OCTET_ALIGN "=1"
+
+/*! "octet-align=0".
+ * According to spec [1], "octet-align=0" is identical to omitting 'octet-align' entirely. In Osmocom practice, whether
+ * or not "octet-align=0" is present can make a big difference for osmo-mgw versions 1.12 and older, which do not heed
+ * [1].
+ *
+ * spec [1]: RFC4867, see details in description of osmo_sdp_fmtp_amr_is_octet_aligned().
+ */
+#define OSMO_SDP_STR_AMR_OCTET_ALIGN_0  OSMO_SDP_STR_AMR_OCTET_ALIGN "=0"
+

libosmo-sdp.pc.in

@@ -0,0 +1,10 @@
+prefix=@prefix@
+exec_prefix=@exec_prefix@
+libdir=@libdir@
+includedir=@includedir@
+
+Name: Osmocom Session Description Protocol coding library
+Description: C Utility Library
+Version: @VERSION@
+Libs: -L${libdir} -losmo-sdp
+Cflags: -I${includedir}/

src/Makefile.am

@@ -15,6 +15,7 @@ AM_CFLAGS = \
 
 # Libraries
 SUBDIRS = \
+	libosmo-sdp \
 	libosmo-mgcp-client \
 	libosmo-mgcp \
 	$(NULL)

src/libosmo-sdp/Makefile.am

@@ -0,0 +1,34 @@
+AM_CPPFLAGS = \
+	$(all_includes) \
+	-I$(top_srcdir)/include \
+	-I$(top_builddir) \
+	$(NULL)
+
+AM_CFLAGS = \
+	-Wall \
+	$(LIBOSMOCORE_CFLAGS) \
+	$(TALLOC_CFLAGS) \
+	$(NULL)
+
+SDP_LIBVERSION=1:0:0
+
+# This is not at all related to the release version, but a range of supported
+# API versions. Read TODO_RELEASE in the source tree's root!
+lib_LTLIBRARIES = \
+	libosmo-sdp.la \
+	$(NULL)
+
+libosmo_sdp_la_SOURCES = \
+	fmtp.c \
+	$(NULL)
+
+libosmo_sdp_la_LDFLAGS = \
+	$(AM_LDFLAGS) \
+	-version-info $(SDP_LIBVERSION) \
+	-no-undefined \
+	-export-symbols-regex '^osmo_' \
+	$(NULL)
+
+libosmo_sdp_la_LIBADD = \
+	$(LIBOSMOCORE_LIBS) \
+	$(NULL)

src/libosmo-sdp/fmtp.c

@@ -0,0 +1,150 @@
+/*
+ * (C) 2023-2024 by sysmocom - s.f.m.c. GmbH <info@sysmocom.de>
+ * All Rights Reserved
+ *
+ * Author: Neels Hofmeyr
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation; either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ *
+ */
+#include <string.h>
+#include <ctype.h>
+#include <osmocom/core/utils.h>
+#include <osmocom/core/logging.h>
+
+#include <osmocom/sdp/sdp_strings.h>
+#include <osmocom/sdp/fmtp.h>
+
+/* End of current fmtp parameter. Return a pointer to the next ';' character, if present, or the terminating '\0'. */
+static const char *osmo_sdp_fmtp_end(const char *fmtp)
+{
+	if (!fmtp)
+		return NULL;
+	for (; *fmtp && *fmtp != ';'; fmtp++);
+	return fmtp;
+}
+
+/* Start of next fmtp parameter. Return a pointer to the first character of the next fmtp parameter's name, or the
+ * terminating '\0'. */
+static const char *osmo_sdp_fmtp_next(const char *fmtp)
+{
+	if (!fmtp)
+		return NULL;
+	fmtp = osmo_sdp_fmtp_end(fmtp);
+	for (; *fmtp && (*fmtp == ';' || isspace(*fmtp)); fmtp++);
+	return fmtp;
+}
+
+/*! Parse a given SDP fmtp value string, returning the value of a specific option, if present.
+ *
+ * Example:
+ *
+ *   const char *fmtp_vals = "octet-align=1;mode-set=0,2,4,7";
+ *
+ *   char mode_set_str[23];
+ *   if (osmo_sdp_fmtp_get_val(mode_set_str, sizeof(mode_set_str), fmtp_vals, "mode-set")) {
+ *           // option 'mode-set' is present, now mode_set_str == "0,2,4,7"
+ *           use_modeset(mode_set_str);
+ *   } else {
+ *           // if 'mode-set' were not present...
+ *           use_modeset(MY_DEFAULT_MODESET);
+ *   }
+ *
+ * \param[out] val  Buffer to write the option's value to.
+ * \param[in] val_size  Space available in val.
+ * \param[in] fmtp  fmtp value string to parse -- must not contain the "a=fmtp:N " prefix, only the value part.
+ * \param[in] option_name  Which fmtp option to get the value for.
+ * \return true when the option was found, false when it was not present.
+ */
+bool osmo_sdp_fmtp_get_val(char *val, size_t val_size, const char *fmtp, const char *option_name)
+{
+	const char *pos = fmtp;
+	const char *end;
+	int option_name_len = strlen(option_name);
+	for (; pos && *pos; pos = osmo_sdp_fmtp_next(pos)) {
+		if (!osmo_str_startswith(pos, option_name))
+			continue;
+		pos += option_name_len;
+		if (*pos != '=')
+			continue;
+		pos++;
+		break;
+	}
+
+	if (!pos || !*pos)
+		return false;
+
+	end = osmo_sdp_fmtp_end(pos);
+	OSMO_ASSERT(end);
+	if (val && val_size)
+		osmo_strlcpy(val, pos, OSMO_MIN(val_size, end - pos + 1));
+	return true;
+}
+
+/*! Parse a given SDP fmtp value string, returning the value of a specific integer option, if present.
+ *
+ * Example:
+ *
+ *   const char *fmtp_vals = "octet-align=1;mode-set=0,2,4,7";
+ *   bool oa = osmo_sdp_fmtp_get_int(fmtp_vals, OSMO_SDP_AMR_OCTET_ALIGN_NAME, 1);
+ *
+ * \param[in] fmtp  fmtp value string to parse -- must not contain the "a=fmtp:N " prefix, only the value part.
+ * \param[in] option_name  Which fmtp option to get the value for.
+ * \param[in] default_value  If option_name is not present or cannot be parsed as integer, return this instead.
+ * \return the integer value when the option was found and actually an integer, default_value otherwise.
+ */
+int64_t osmo_sdp_fmtp_get_int(const char *fmtp, const char *option_name, int64_t default_value)
+{
+	char val[128];
+	if (!osmo_sdp_fmtp_get_val(val, sizeof(val), fmtp, option_name))
+		return default_value;
+	if (!val[0])
+		return default_value;
+	int64_t i;
+	if (osmo_str_to_int64(&i, val, 10, INT64_MIN, INT64_MAX)) {
+		/* error parsing number */
+		return default_value;
+	}
+	return i;
+}
+
+/*! Return true if octet-align is present and set to 1 in the given AMR related fmtp value.
+ * Default to octet-align=0, i.e. bandwidth-efficient mode.
+ *
+ * See RFC4867 "RTP Payload Format for AMR and AMR-WB" sections "8.1. AMR Media Type Registration" and "8.2. AMR-WB
+ * Media Type Registration":
+ *
+ *    octet-align: Permissible values are 0 and 1.  If 1, octet-align
+ *                 operation SHALL be used.  If 0 or if not present,
+ *                 bandwidth-efficient operation is employed.
+ *
+ * https://tools.ietf.org/html/rfc4867
+ */
+bool osmo_sdp_fmtp_amr_is_octet_aligned(const char *fmtp)
+{
+	return osmo_sdp_fmtp_get_int(fmtp, OSMO_SDP_STR_AMR_OCTET_ALIGN, 0) == 1;
+}
+
+static void strip_whitespace(char *str)
+{
+	char *i = str;
+	char *o = str;
+	for (; *i; i++, o++) {
+		while (isspace(*i))
+			i++;
+		*o = *i;
+		if (!*i)
+			break;
+	}
+}

tests/Makefile.am

@@ -1,6 +1,7 @@
 SUBDIRS = \
 	mgcp_client \
 	mgcp \
+	sdp \
 	$(NULL)
 
 # The `:;' works around a Bash 3.2 bug when the output is not writeable.

tests/sdp/Makefile.am

@@ -0,0 +1,39 @@
+AM_CPPFLAGS = \
+	$(all_includes) \
+	-I$(top_srcdir)/include \
+	-I$(top_builddir)/include \
+	-I$(top_srcdir) \
+	$(NULL)
+
+AM_CFLAGS = \
+	-Wall \
+	-ggdb3 \
+	$(LIBOSMOCORE_CFLAGS) \
+	$(COVERAGE_CFLAGS) \
+	$(NULL)
+
+AM_LDFLAGS = \
+	$(LIBOSMOCORE_LIBS) \
+	$(COVERAGE_LDFLAGS) \
+	-no-install \
+	$(NULL)
+
+EXTRA_DIST = \
+	sdp_fmtp_test.ok \
+	sdp_fmtp_test.err \
+	$(NULL)
+
+check_PROGRAMS = \
+	sdp_fmtp_test \
+	$(NULL)
+
+sdp_fmtp_test_SOURCES = \
+	sdp_fmtp_test.c \
+	$(NULL)
+
+sdp_fmtp_test_LDADD = \
+	$(top_builddir)/src/libosmo-sdp/libosmo-sdp.la \
+	$(NULL)
+
+update_exp:
+	$(builddir)/sdp_fmtp_test >$(srcdir)/sdp_fmtp_test.ok 2>$(srcdir)/sdp_fmtp_test.err

tests/sdp/sdp_fmtp_test.c

@@ -0,0 +1,126 @@
+#include <inttypes.h>
+#include <osmocom/core/utils.h>
+#include <osmocom/core/application.h>
+#include <osmocom/core/logging.h>
+
+#include <osmocom/sdp/fmtp.h>
+
+struct get_val_test {
+	const char *fmtp_string;
+	const char *val_name;
+	bool expect_rc;
+	const char *expect_val;
+};
+
+const struct get_val_test get_val_tests[] = {
+	{
+		"foo=123;bar=success;baz=456", "foo",
+		true, "123"
+	},
+	{
+		"foo=123;bar=success;baz=456", "bar",
+		true, "success"
+	},
+	{
+		"foo=123;bar=success;baz=456", "baz",
+		true, "456"
+	},
+};
+
+void test_get_val(void)
+{
+	int i;
+	printf("\n--- %s()\n", __func__);
+
+	for (i = 0; i < ARRAY_SIZE(get_val_tests); i++) {
+		const struct get_val_test *t = &get_val_tests[i];
+		char val[128] = {};
+		bool rc = osmo_sdp_fmtp_get_val(val, sizeof(val), t->fmtp_string, t->val_name);
+		bool ok;
+		printf("osmo_sdp_fmtp_get_val('%s', '%s') rc=%s",
+		       t->fmtp_string, t->val_name,
+		       rc ? "true" : "false");
+		if (rc)
+			printf(" val='%s'", val);
+		ok = true;
+		if (rc != t->expect_rc) {
+			printf(" ERROR: expected rc=%s", t->expect_rc ? "true" : "false");
+			ok = false;
+		}
+		if (t->expect_val && strcmp(val, t->expect_val)) {
+			printf(" ERROR: expected val='%s'", t->expect_val);
+			ok = false;
+		}
+		if (ok)
+			printf(" ok");
+		printf("\n");
+	}
+	printf("\n--- %s() DONE\n", __func__);
+}
+
+struct get_int_test {
+	const char *fmtp_string;
+	const char *val_name;
+	int64_t defval;
+	int64_t expect_rc;
+};
+
+const struct get_int_test get_int_tests[] = {
+	{
+		"foo=123;bar=success;baz=456", "foo", -1,
+		123
+	},
+	{
+		"foo=123;bar=success;baz=456", "bar", -1,
+		-1
+	},
+	{
+		"foo=123;bar=success;baz=456", "baz", -1,
+		456
+	},
+};
+
+void test_get_int(void)
+{
+	int i;
+	printf("\n--- %s()\n", __func__);
+
+	for (i = 0; i < ARRAY_SIZE(get_int_tests); i++) {
+		const struct get_int_test *t = &get_int_tests[i];
+		int64_t rc = osmo_sdp_fmtp_get_int(t->fmtp_string, t->val_name, t->defval);
+		printf("osmo_sdp_fmtp_get_int('%s', '%s') rc=%"PRId64,
+		       t->fmtp_string, t->val_name, rc);
+		if (rc != t->expect_rc) {
+			printf(" ERROR: expected rc=%"PRId64, t->expect_rc);
+		}
+		else {
+			printf(" ok");
+		}
+		printf("\n");
+	}
+	printf("\n--- %s() DONE\n", __func__);
+}
+
+static const struct log_info_cat log_categories[] = {
+};
+
+const struct log_info log_info = {
+        .cat = log_categories,
+        .num_cat = ARRAY_SIZE(log_categories),
+};
+
+int main(void)
+{
+	void *ctx = talloc_named_const(NULL, 1, "sdp_fmtp_test");
+
+	osmo_init_logging2(ctx, &log_info);
+	log_set_print_filename2(osmo_stderr_target, LOG_FILENAME_NONE);
+	log_set_print_timestamp(osmo_stderr_target, 0);
+	log_set_use_color(osmo_stderr_target, 0);
+	log_set_print_category_hex(osmo_stderr_target, 0);
+	log_set_print_category(osmo_stderr_target, 1);
+
+	test_get_val();
+	test_get_int();
+	return 0;
+}

tests/sdp/sdp_fmtp_test.ok

@@ -0,0 +1,14 @@
+
+--- test_get_val()
+osmo_sdp_fmtp_get_val('foo=123;bar=success;baz=456', 'foo') rc=true val='123' ok
+osmo_sdp_fmtp_get_val('foo=123;bar=success;baz=456', 'bar') rc=true val='success' ok
+osmo_sdp_fmtp_get_val('foo=123;bar=success;baz=456', 'baz') rc=true val='456' ok
+
+--- test_get_val() DONE
+
+--- test_get_int()
+osmo_sdp_fmtp_get_int('foo=123;bar=success;baz=456', 'foo') rc=123 ok
+osmo_sdp_fmtp_get_int('foo=123;bar=success;baz=456', 'bar') rc=-1 ok
+osmo_sdp_fmtp_get_int('foo=123;bar=success;baz=456', 'baz') rc=456 ok
+
+--- test_get_int() DONE

tests/testsuite.at

@@ -13,3 +13,10 @@ AT_KEYWORDS([mgcp])
 cat $abs_srcdir/mgcp/mgcp_test.ok > expout
 AT_CHECK([$abs_top_builddir/tests/mgcp/mgcp_test], [], [expout], [ignore])
 AT_CLEANUP
+
+AT_SETUP([sdp_fmtp])
+AT_KEYWORDS([sdp_fmtp])
+cat $abs_srcdir/sdp/sdp_fmtp_test.ok > expout
+cat $abs_srcdir/sdp/sdp_fmtp_test.err > experr
+AT_CHECK([$abs_top_builddir/tests/sdp/sdp_fmtp_test], [], [expout], [experr])
+AT_CLEANUP