add libosmo-mslookup abstract client
mslookup is a key concept in Distributed GSM, which allows querying the current
location of a subscriber in a number of cooperating but independent core
network sites, by arbitrary service names and by MSISDN/IMSI.
Add the abstract mslookup client library. An actual lookup method (besides
mslookup_client_fake.c) is added in a subsequent patch.
For a detailed overview of this and upcoming patches, please see the elaborate
comment at the top of mslookup.c.
Add as separate library, libosmo-mslookup, to allow adding D-GSM capability to
arbitrary client programs.
osmo-hlr will be the only mslookup server implementation, added in a subsequent
patch.
osmo-hlr itself will also use this library and act as an mslookup client, when
requesting the home HLR for locally unknown IMSIs.
Related: OS#4237
Patch-by: osmith, nhofmeyr
Change-Id: I83487ab8aad1611eb02e997dafbcb8344da13df1
diff --git a/include/osmocom/mslookup/mslookup_client.h b/include/osmocom/mslookup/mslookup_client.h
new file mode 100644
index 0000000..cd0c21f
--- /dev/null
+++ b/include/osmocom/mslookup/mslookup_client.h
@@ -0,0 +1,132 @@
+/* Copyright 2019 by sysmocom s.f.m.c. GmbH <info@sysmocom.de>
+ *
+ * All Rights Reserved
+ *
+ * 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 <osmocom/core/linuxlist.h>
+#include <osmocom/core/timer.h>
+#include <osmocom/core/sockaddr_str.h>
+#include <osmocom/mslookup/mslookup.h>
+
+struct osmo_mslookup_client;
+struct osmo_mslookup_result;
+
+typedef void (*osmo_mslookup_cb_t)(struct osmo_mslookup_client *client,
+ uint32_t request_handle,
+ const struct osmo_mslookup_query *query,
+ const struct osmo_mslookup_result *result);
+
+/*! This handling information is passed along with a lookup request.
+ * It tells the osmo_mslookup_client layer how to handle responses received from various mslookup methods (at the time
+ * of writing only mDNS exists as a method, but the intention is to easily allow adding other methods in the future).
+ * This query handling info is not seen by the individual method implementations, to clarify that it is the
+ * osmo_mslookup_client layer that takes care of these details. */
+struct osmo_mslookup_query_handling {
+ /*! Wait at least this long before returning any results.
+ *
+ * If nonzero, result_cb will be called as soon as this delay has elapsed, either with the so far youngest age
+ * result, or with a "not found yet" result. After this delay has elapsed, receiving results will continue
+ * until result_timeout_milliseconds has elapsed.
+ *
+ * If zero, responses are fed to the result_cb right from the start, every time a younger aged result than
+ * before comes in.
+ *
+ * If a result with age == 0 is received, min_wait_milliseconds is ignored, the result is returned immediately
+ * and listening for responses ends.
+ *
+ * Rationale: If a subscriber has recently moved between sites, multiple results will arrive, and the youngest
+ * age wins. It can make sense to wait a minimum time for responses before determining the winning result.
+ *
+ * However, if no result or no valid result has arrived within a short period, the subscriber may be at a site
+ * that is far away or that is currently experiencing high latency. It is thus a good safety net to still
+ * receive results for an extended period of time.
+ *
+ * For some services, it is possible to establish links to every received result, and whichever link succeeds
+ * will be used (for example for SIP calls: first to pick up the call gets connected, the others are dropped
+ * silently).
+ */
+ uint32_t min_wait_milliseconds;
+
+ /*! Total time in milliseconds to listen for lookup responses.
+ *
+ * When this timeout elapses, osmo_mslookup_client_request_cancel() is called implicitly; Manually invoking
+ * osmo_mslookup_client_request_cancel() after result_timeout_milliseconds has elapsed is not necessary, but is
+ * still safe to do anyway.
+ *
+ * If zero, min_wait_milliseconds is also used as result_timeout_milliseconds; if that is also zero, a default
+ * timeout value is used.
+ *
+ * If result_timeout_milliseconds <= min_wait_milliseconds, then min_wait_milliseconds is used as
+ * result_timeout_milliseconds, i.e. the timeout triggers as soon as min_wait_milliseconds hits.
+ *
+ * osmo_mslookup_client_request_cancel() can be called any time to end the request.
+ */
+ uint32_t result_timeout_milliseconds;
+
+ /*! Invoked every time a result with a younger age than the previous result has arrived.
+ * To stop receiving results before result_timeout_milliseconds has elapsed, call
+ * osmo_mslookup_client_request_cancel().
+ */
+ osmo_mslookup_cb_t result_cb;
+};
+
+uint32_t osmo_mslookup_client_request(struct osmo_mslookup_client *client,
+ const struct osmo_mslookup_query *query,
+ const struct osmo_mslookup_query_handling *handling);
+
+void osmo_mslookup_client_request_cancel(struct osmo_mslookup_client *client, uint32_t request_handle);
+
+struct osmo_mslookup_client *osmo_mslookup_client_new(void *ctx);
+bool osmo_mslookup_client_active(struct osmo_mslookup_client *client);
+void osmo_mslookup_client_free(struct osmo_mslookup_client *client);
+
+/*! Describe a specific mslookup client method implementation. This struct is only useful for a lookup method
+ * implementation to add itself to an osmo_mslookup_client, see for example osmo_mslookup_client_add_mdns(). */
+struct osmo_mslookup_client_method {
+ struct llist_head entry;
+
+ /*! Human readable name of this lookup method. */
+ const char *name;
+
+ /*! Private data for the lookup method implementation. */
+ void *priv;
+
+ /*! Backpointer to the client this method is added to. */
+ struct osmo_mslookup_client *client;
+
+ /*! Launch a lookup query. Called from osmo_mslookup_client_request().
+ * The implementation returns results by calling osmo_mslookup_client_rx_result(). */
+ void (*request)(struct osmo_mslookup_client_method *method,
+ const struct osmo_mslookup_query *query,
+ uint32_t request_handle);
+ /*! End a lookup query. Called from osmo_mslookup_client_request_cancel(). It is guaranteed to be called
+ * exactly once per above request() invocation. (The API user is required to invoke
+ * osmo_mslookup_client_request_cancel() exactly once per osmo_mslookup_client_request().) */
+ void (*request_cleanup)(struct osmo_mslookup_client_method *method,
+ uint32_t request_handle);
+
+ /*! The mslookup_client is removing this method, clean up all open requests, lists and allocations. */
+ void (*destruct)(struct osmo_mslookup_client_method *method);
+};
+
+void osmo_mslookup_client_method_add(struct osmo_mslookup_client *client,
+ struct osmo_mslookup_client_method *method);
+bool osmo_mslookup_client_method_del(struct osmo_mslookup_client *client,
+ struct osmo_mslookup_client_method *method);
+void osmo_mslookup_client_rx_result(struct osmo_mslookup_client *client, uint32_t request_handle,
+ const struct osmo_mslookup_result *result);