spa: Add a varlink client support library

spa/include/spa/support/varlink.h

@@ -0,0 +1,163 @@
+/* Simple Plugin API */
+/* SPDX-FileCopyrightText: Copyright © 2026 Arun Raghavan */
+/* SPDX-License-Identifier: MIT */
+
+#ifndef SPA_VARLINK_H
+#define SPA_VARLINK_H
+
+#include <spa/utils/hook.h>
+#include <spa/utils/json.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#ifndef SPA_API_VARLINK
+ #ifdef SPA_API_IMPL
+  #define SPA_API_VARLINK SPA_API_IMPL
+ #else
+  #define SPA_API_VARLINK static inline
+ #endif
+#endif
+
+/** \defgroup spa_varlink Varlink
+ * Varlink communication
+ */
+
+/**
+ * \addtogroup spa_varlink
+ * \{
+ */
+
+#define SPA_TYPE_INTERFACE_Varlink	SPA_TYPE_INFO_INTERFACE_BASE "Varlink"
+
+typedef void (*spa_varlink_reply_func_t) (void *data, const char *params,
+		const char *error, size_t len, bool continues);
+
+struct spa_varlink_client_events {
+#define SPA_VERSION_VARLINK_CLIENT_EVENTS 0
+	uint32_t version;
+
+	/** The client was destroyed. */
+	void (*destroy) (void *data);
+
+	/** The client was disconnected. */
+	void (*disconnect) (void *data);
+};
+
+struct spa_varlink_client {
+#define SPA_VERSION_VARLINK_CLIENT 0
+	uint32_t version;
+
+	/** Add a listener fo events */
+	void (*add_listener) (void *object, struct spa_hook *listener,
+			const struct spa_varlink_client_events *events,
+			void *data);
+
+        /** Call a single- or no-reply method on a varlink client.
+         *
+         * \param method Fully qualified (`interface.Method`) method name to
+         *		 call.
+         * \param params Method parameters as a string (must be a valid JSON
+         *		 object).
+         * \param oneway Signal that the server should not send a reply.
+         * \param more Expect multiple replies from the server for this method
+	 *	       call.
+	 * \param cb Callback to invok when a reply to this call arrives.
+	 * \param userdata Userdata to supply to the callback.
+         * \return 0 on success, or a negative error code on failure.
+         */
+        int (*call) (void *object, const char *method, const char *params,
+			bool oneway, bool more, spa_varlink_reply_func_t cb,
+			void *userdata);
+
+        /** Call a single-reply method and block until a reply is received.
+         *
+         * \param method Fully qualified (`interface.Method`) method name to
+         *		 call.
+         * \param params Method parameters as a string (must be a valid JSON
+         *		 object).
+         * \param reply The reply string. The caller is responsible for freeing
+         *		this data with `free()`
+         * \return 0 on success, or a negative error code on failure.
+         */
+        int (*call_sync) (void *object, const char *method, const char *params,
+			char **reply);
+
+	/** Destroy a varlink client.
+	 *
+	 * \param client The client to destroy
+	 */
+	void (*destroy) (void *object);
+};
+
+/** \copydoc spa_varlink_client_methods.add_listener
+ * \sa spa_varlink_client_methods.add_listener */
+SPA_API_VARLINK void
+spa_varlink_client_add_listener(struct spa_varlink_client *client,
+		struct spa_hook *listener,
+		const struct spa_varlink_client_events *events,
+		void *data)
+{
+	spa_api_func_v(client, add_listener, 0, listener, events, data);
+}
+
+/** \copydoc spa_varlink_client_methods.call
+ * \sa spa_varlink_client_methods.call */
+SPA_API_VARLINK int
+spa_varlink_client_call(struct spa_varlink_client *client, const char *method,
+		const char *params, bool oneway, bool more,
+		spa_varlink_reply_func_t cb, void *userdata)
+{
+	return spa_api_func_r(int, -EINVAL, client, call, 0, method, params,
+			oneway, more, cb, userdata);
+}
+
+/** \copydoc spa_varlink_client_methods.call_sync
+ * \sa spa_varlink_client_methods.call_sync */
+SPA_API_VARLINK int
+spa_varlink_client_call_sync(struct spa_varlink_client *client, const char *method,
+		const char *params, char **reply)
+{
+	return spa_api_func_r(int, -EINVAL, client, call_sync, 0, method,
+			params, reply);
+}
+
+/** \copydoc spa_varlink_client_methods.destroy
+ * \sa spa_varlink_client_methods.destroy */
+SPA_API_VARLINK void
+spa_varlink_client_destroy(struct spa_varlink_client *client)
+{
+	spa_api_func_v(client, destroy, 0);
+}
+
+#define SPA_VERSION_VARLINK	0
+struct spa_varlink { struct spa_interface iface; };
+
+struct spa_varlink_methods {
+#define SPA_VERSION_VARLINK_METHODS 0
+	uint32_t version;
+
+	/**
+	 * Connect to a varlink service.
+	 *
+	 * \param path Path to connect to, for example `unix:/path/to/socket`
+	 * \return A `spa_varlink_client` on success, NULL on failure.
+	 */
+	struct spa_varlink_client * (*connect) (void *object, const char *path);
+};
+
+/** \copydoc spa_varlink_methods.connect
+ * \sa spa_varlink_methods.connect */
+SPA_API_VARLINK void *
+spa_varlink_connect(struct spa_varlink *varlink, const char *path)
+{
+	return spa_api_method_r(struct spa_varlink_client *, NULL, spa_varlink,
+			&varlink->iface, connect, 0, path);
+}
+
+#ifdef __cplusplus
+} /* extern "C" */
+#endif
+
+#endif /* SPA_VARLINK_H */

spa/include/spa/utils/names.h

@@ -25,6 +25,7 @@ extern "C" {
 #define SPA_NAME_SUPPORT_LOOP		"support.loop"			/**< A Loop/LoopControl/LoopUtils
 									  *  interface */
 #define SPA_NAME_SUPPORT_SYSTEM		"support.system"		/**< A System interface */
+#define SPA_NAME_SUPPORT_VARLINK	"support.varlink"		/**< A Varlink interface */
 
 #define SPA_NAME_SUPPORT_NODE_DRIVER	"support.node.driver"		/**< A dummy driver node */