diff options
Diffstat (limited to 'include/osmocom/mslookup/mslookup_client.h')
| -rw-r--r-- | include/osmocom/mslookup/mslookup_client.h | 132 |
1 files changed, 132 insertions, 0 deletions
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); |