mgcp_client: Introduce mgcp_client_conf_alloc(), deprecate mgcp_client_conf_init()

So far, the users of the old non-pooled API were in charge of allocating
the struct mgcp_client_conf by themselves, then init them using
mgcp_client_conf_init(). This causes a major problem, since it makes it
difficult to extend the struct mgcp_client_conf structure to add new
features, which may happen frequently.

The MGW pool API doesn't have this problem, because the struct
mgcp_client_conf is allocated as parts/fields of private structs defined
in internal headers. Only pointers to it are used in public headers.
Since it still has to internally initialize the conf fields, we still
need the API to initialize it internally, and hence why is it marked as
DEPRECTED_OUTSIDE instead of DEPRECATED.

While some programs already moved to the new MGW pool infrastructure,
they still use the old APIs to accomodate for old config files in order
to be back-compatible, hence most users of libosmo-mgcp-client are
affected.

Introduce an API to allocate the conf struct internally, which, while
still breaking the ABI, allows for a more relaxed update path where it's
possible to extend the struct mgcp_client_conf at the end.

Eventually the non pooled API should be gone and the struct
mgcp_client_conf can then be moved to a private header, but for now
let's add this small feature to avoid major ABI breakage.

Change-Id: Iba0853ed099a32cf1dde78c17e1b34343db41cfc

TODO-RELEASE

@@ -24,3 +24,5 @@
 # If any interfaces have been removed or changed since the last public release, a=0.
 #
 #library		what		description / commit summary line
+libosmo-mgcp-client     NEW API         mgcp_client_conf_alloc()
+libosmo-mgcp-client     DEPRECATED      mgcp_client_conf_init()

configure.ac

@@ -52,7 +52,8 @@ PKG_CHECK_MODULES(LIBOSMONETIF, libosmo-netif >= 1.3.0)
 PKG_CHECK_MODULES(LIBOSMOABIS, libosmoabis >= 1.4.0)
 PKG_CHECK_MODULES(LIBOSMOTRAU, libosmotrau >= 1.4.0)
 
-CFLAGS="$CFLAGS -pthread"
+CFLAGS="$CFLAGS -DBUILDING_LIBOSMOMGCPCLIENT -pthread"
+CPPFLAGS="$CPPFLAGS -DBUILDING_LIBOSMOMGCPCLIENT -pthread"
 LDFLAGS="$LDFLAGS -pthread"
 
 AC_ARG_ENABLE(sanitize,

include/Makefile.am

@@ -3,6 +3,7 @@ SUBDIRS = \
 	$(NULL)
 
 nobase_include_HEADERS = \
+	osmocom/mgcp_client/defs.h \
 	osmocom/mgcp_client/mgcp_client.h \
 	osmocom/mgcp_client/mgcp_client_endpoint_fsm.h \
 	osmocom/mgcp_client/mgcp_client_fsm.h \

include/osmocom/mgcp_client/defs.h

@@ -0,0 +1,7 @@
+#include <osmocom/core/defs.h>
+
+#if BUILDING_LIBOSMOMGCPCLIENT
+# define OSMO_DEPRECATED_OUTSIDE_LIBOSMOMGCPCLIENT(text)
+#else
+# define OSMO_DEPRECATED_OUTSIDE_LIBOSMOMGCPCLIENT(text) OSMO_DEPRECATED(text)
+#endif

include/osmocom/mgcp_client/mgcp_client.h

@@ -3,6 +3,7 @@
 #include <stdint.h>
 #include <arpa/inet.h>
 
+#include <osmocom/mgcp_client/defs.h>
 #include <osmocom/mgcp_client/mgcp_common.h>
 
 /* See also: RFC 3435, chapter 3.5 Transmission over UDP */
@@ -133,7 +134,8 @@ struct mgcp_msg {
 	struct mgcp_codec_param param;
 };
 
-void mgcp_client_conf_init(struct mgcp_client_conf *conf);
+struct mgcp_client_conf *mgcp_client_conf_alloc(void *ctx);
+void mgcp_client_conf_init(struct mgcp_client_conf *conf) OSMO_DEPRECATED_OUTSIDE_LIBOSMOMGCPCLIENT("use mgcp_client_conf_alloc() (or even better, switch to the mgcp_client_pool API!)");
 void mgcp_client_vty_init(void *talloc_ctx, int node, struct mgcp_client_conf *conf);
 int mgcp_client_config_write(struct vty *vty, const char *indent);
 struct mgcp_client_conf *mgcp_client_conf_actual(struct mgcp_client *mgcp);

src/libosmo-mgcp-client/mgcp_client.c

@@ -194,9 +194,7 @@ enum mgcp_codecs map_pt_to_codec(struct ptmap *ptmap, unsigned int ptmap_len,
 	return pt;
 }
 
-/*! Initialize MGCP client configuration struct with default values.
- *  \param[out] conf Client configuration.*/
-void mgcp_client_conf_init(struct mgcp_client_conf *conf)
+static void _mgcp_client_conf_init(struct mgcp_client_conf *conf)
 {
 	/* NULL and -1 default to MGCP_CLIENT_*_DEFAULT values */
 	*conf = (struct mgcp_client_conf){
@@ -209,6 +207,29 @@ void mgcp_client_conf_init(struct mgcp_client_conf *conf)
 	INIT_LLIST_HEAD(&conf->reset_epnames);
 }
 
+/*! Allocate and initialize MGCP client configuration struct with default values.
+ *  \param[in] ctx talloc context to use as a parent during allocation.
+ *
+ * The returned struct can be freed using talloc_free().
+ */
+struct mgcp_client_conf *mgcp_client_conf_alloc(void *ctx)
+{
+	struct mgcp_client_conf *conf = talloc(ctx, struct mgcp_client_conf);
+	_mgcp_client_conf_init(conf);
+	return conf;
+}
+
+/*! Initialize MGCP client configuration struct with default values.
+ *  \param[out] conf Client configuration.
+ *
+ * This function is deprecated and should not be used, as it may break if size
+ * of struct mgcp_client_conf changes in the future!
+ */
+void mgcp_client_conf_init(struct mgcp_client_conf *conf)
+{
+	_mgcp_client_conf_init(conf);
+}
+
 static void mgcp_client_handle_response(struct mgcp_client *mgcp,
 					struct mgcp_response_pending *pending,
 					struct mgcp_response *response)

tests/mgcp_client/mgcp_client_test.c

@@ -73,7 +73,7 @@ static struct msgb *from_str(const char *str)
 	return msg;
 }
 
-static struct mgcp_client_conf conf;
+static struct mgcp_client_conf *conf;
 struct mgcp_client *mgcp = NULL;
 
 static int reply_to(mgcp_trans_id_t trans_id, int code, const char *comment,
@@ -162,7 +162,7 @@ void test_mgcp_msg(void)
 
 	if (mgcp)
 		talloc_free(mgcp);
-	mgcp = mgcp_client_init(ctx, &conf);
+	mgcp = mgcp_client_init(ctx, conf);
 
 	printf("\n");
 
@@ -339,7 +339,7 @@ void test_mgcp_client_cancel(void)
 
 	if (mgcp)
 		talloc_free(mgcp);
-	mgcp = mgcp_client_init(ctx, &conf);
+	mgcp = mgcp_client_init(ctx, conf);
 
 	msg = mgcp_msg_gen(mgcp, &mgcp_msg);
 	trans_id = mgcp_msg_trans_id(msg);
@@ -630,7 +630,7 @@ void test_mgcp_client_e1_epname(void)
 
 	if (mgcp)
 		talloc_free(mgcp);
-	mgcp = mgcp_client_init(ctx, &conf);
+	mgcp = mgcp_client_init(ctx, conf);
 
 	/* Valid endpoint names */
 	epname = (char *)mgcp_client_e1_epname(ctx, mgcp, 1, 15, 64, 0);
@@ -697,7 +697,7 @@ int main(int argc, char **argv)
 
 	log_set_category_filter(osmo_stderr_target, DLMGCP, 1, LOGL_DEBUG);
 
-	mgcp_client_conf_init(&conf);
+	conf = mgcp_client_conf_alloc(ctx);
 
 	test_mgcp_msg();
 	test_mgcp_client_cancel();