pipewire/spa/include/spa/support/varlink.h

/* 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 */