pipewire/spa/include/spa/support/plugin.h

/* Simple Plugin API
 *
 * Copyright © 2018 Wim Taymans
 *
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the "Software"),
 * to deal in the Software without restriction, including without limitation
 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
 * and/or sell copies of the Software, and to permit persons to whom the
 * Software is furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice (including the next
 * paragraph) shall be included in all copies or substantial portions of the
 * Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 * DEALINGS IN THE SOFTWARE.
 */

#ifndef SPA_PLUGIN_H
#define SPA_PLUGIN_H

#ifdef __cplusplus
extern "C" {
#endif

#include <spa/utils/defs.h>
#include <spa/utils/dict.h>

/**
 * \defgroup spa_handle Plugin Handle
 * SPA plugin handle and factory interfaces
 */

/**
 * \addtogroup spa_handle
 * \{
 */

struct spa_handle {
	/** Version of this struct */
#define SPA_VERSION_HANDLE	0
	uint32_t version;

	/**
	 * Get the interface provided by \a handle with \a type.
	 *
	 * \a interface is always a struct spa_interface but depending on
	 * \a type, the struct might contain other information.
	 *
	 * \param handle a spa_handle
	 * \param type the interface type
	 * \param interface result to hold the interface.
	 * \return 0 on success
	 *         -ENOTSUP when there are no interfaces
	 *         -EINVAL when handle or info is NULL
	 */
	int (*get_interface) (struct spa_handle *handle, const char *type, void **interface);
	/**
	 * Clean up the memory of \a handle. After this, \a handle should not be used
	 * anymore.
	 *
	 * \param handle a pointer to memory
	 * \return 0 on success
	 */
	int (*clear) (struct spa_handle *handle);
};

#define spa_handle_get_interface(h,...)	(h)->get_interface((h),__VA_ARGS__)
#define spa_handle_clear(h)		(h)->clear((h))

/**
 * This structure lists the information about available interfaces on
 * handles.
 */
struct spa_interface_info {
	const char *type;	/*< the type of the interface, can be
				 *  used to get the interface */
};

/**
 * Extra supporting infrastructure passed to the init() function of
 * a factory. It can be extra information or interfaces such as logging.
 */
struct spa_support {
	const char *type;	/*< the type of the support item */
	void *data;		/*< specific data for the item */
};

/** Find a support item of the given type */
static inline void *spa_support_find(const struct spa_support *support,
				     uint32_t n_support,
				     const char *type)
{
	uint32_t i;
	for (i = 0; i < n_support; i++) {
		if (strcmp(support[i].type, type) == 0)
			return support[i].data;
	}
	return NULL;
}

#define SPA_SUPPORT_INIT(type,data) ((struct spa_support) { (type), (data) })

struct spa_handle_factory {
	/** The version of this structure */
#define SPA_VERSION_HANDLE_FACTORY	1
	uint32_t version;
	/**
	 * The name of the factory contains a logical name that describes
	 * the function of the handle. Other plugins might contain an alternative
	 * implementation with the same name.
	 *
	 * See utils/names.h for the list of standard names.
	 *
	 * Examples include:
	 *
	 *  api.alsa.pcm.sink: an object to write PCM samples to an alsa PLAYBACK
	 *			device
	 *  api.v4l2.source: an object to read from a v4l2 source.
	 */
	const char *name;
	/**
	 * Extra information about the handles of this factory.
	 */
	const struct spa_dict *info;
	/**
	 * Get the size of handles from this factory.
	 *
	 * \param factory a spa_handle_factory
	 * \param params extra parameters that determine the size of the
	 * handle.
	 */
	size_t (*get_size) (const struct spa_handle_factory *factory,
			    const struct spa_dict *params);

	/**
	 * Initialize an instance of this factory. The caller should allocate
	 * memory at least size bytes and pass this as \a handle.
	 *
	 * \a support can optionally contain extra interfaces or data items that the
	 * plugin can use such as a logger.
	 *
	 * \param factory a spa_handle_factory
	 * \param handle a pointer to memory
	 * \param info extra handle specific information, usually obtained
	 *        from a spa_device. This can be used to configure the handle.
	 * \param support support items
	 * \param n_support number of elements in \a support
	 * \return 0 on success
	 *	   < 0 errno type error
	 */
	int (*init) (const struct spa_handle_factory *factory,
		     struct spa_handle *handle,
		     const struct spa_dict *info,
		     const struct spa_support *support,
		     uint32_t n_support);

	/**
	 * spa_handle_factory::enum_interface_info:
	 * \param factory: a #spa_handle_factory
	 * \param info: result to hold spa_interface_info.
	 * \param index: index to keep track of the enumeration, 0 for first item
	 *
	 * Enumerate the interface information for \a factory.
	 *
	 * \return 1 when an item is available
	 *	   0 when no more items are available
	 *	   < 0 errno type error
	 */
	int (*enum_interface_info) (const struct spa_handle_factory *factory,
				    const struct spa_interface_info **info,
				    uint32_t *index);
};

#define spa_handle_factory_get_size(h,...)		(h)->get_size((h),__VA_ARGS__)
#define spa_handle_factory_init(h,...)			(h)->init((h),__VA_ARGS__)
#define spa_handle_factory_enum_interface_info(h,...)	(h)->enum_interface_info((h),__VA_ARGS__)

/**
 * The function signature of the entry point in a plugin.
 *
 * \param factory a location to hold the factory result
 * \param index index to keep track of the enumeration
 * \return 1 on success
 *         0 when there are no more factories
 *         -EINVAL when factory is NULL
 */
typedef int (*spa_handle_factory_enum_func_t) (const struct spa_handle_factory **factory,
					       uint32_t *index);

#define SPA_HANDLE_FACTORY_ENUM_FUNC_NAME "spa_handle_factory_enum"

/**
 * The entry point in a plugin.
 *
 * \param factory a location to hold the factory result
 * \param index index to keep track of the enumeration
 * \return 1 on success
 *	   0 when no more items are available
 *	   < 0 errno type error
 */
int spa_handle_factory_enum(const struct spa_handle_factory **factory, uint32_t *index);



#define SPA_KEY_FACTORY_NAME		"factory.name"		/**< the name of a factory */
#define SPA_KEY_FACTORY_AUTHOR		"factory.author"	/**< a comma separated list of factory authors */
#define SPA_KEY_FACTORY_DESCRIPTION	"factory.description"	/**< description of a factory */
#define SPA_KEY_FACTORY_USAGE		"factory.usage"		/**< usage of a factory */

#define SPA_KEY_LIBRARY_NAME		"library.name"		/**< the name of a library. This is usually
								  *  the filename of the plugin without the
								  *  path or the plugin extension. */

/**
 * \}
 */

#ifdef __cplusplus
}  /* extern "C" */
#endif

#endif /* SPA_PLUGIN_H */