/* 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_NODE_H
#define SPA_NODE_H

#ifdef __cplusplus
extern "C" {
#endif

#include <spa/utils/defs.h>
#include <spa/utils/type.h>
#include <spa/utils/hook.h>
#include <spa/buffer/buffer.h>
#include <spa/node/event.h>
#include <spa/node/command.h>


/**
 * A spa_node is a component that can consume and produce buffers.
 */
#define SPA_TYPE_INTERFACE_Node		SPA_TYPE_INFO_INTERFACE_BASE "Node"

#define SPA_VERSION_NODE		0
struct spa_node { struct spa_interface iface; };

/**
 * Node information structure
 *
 * Contains the basic node information.
 */
struct spa_node_info {
	uint32_t max_input_ports;
	uint32_t max_output_ports;
#define SPA_NODE_CHANGE_MASK_FLAGS		(1u<<0)
#define SPA_NODE_CHANGE_MASK_PROPS		(1u<<1)
#define SPA_NODE_CHANGE_MASK_PARAMS		(1u<<2)
	uint64_t change_mask;

#define SPA_NODE_FLAG_RT			(1u<<0)	/**< node can do real-time processing */
#define SPA_NODE_FLAG_IN_DYNAMIC_PORTS		(1u<<1)	/**< input ports can be added/removed */
#define SPA_NODE_FLAG_OUT_DYNAMIC_PORTS		(1u<<2)	/**< output ports can be added/removed */
#define SPA_NODE_FLAG_IN_PORT_CONFIG		(1u<<3)	/**< input ports can be reconfigured with
							  *  PortConfig parameter */
#define SPA_NODE_FLAG_OUT_PORT_CONFIG		(1u<<4)	/**< output ports can be reconfigured with
							  *  PortConfig parameter */
#define SPA_NODE_FLAG_NEED_CONFIGURE		(1u<<5)	/**< node needs configuration before it can
							  *  be started. */
#define SPA_NODE_FLAG_ASYNC			(1u<<6)	/**< the process function might not
							  *  immediateley produce or consume data
							  *  but might offload the work to a worker
							  *  thread. */
	uint64_t flags;
	struct spa_dict *props;			/**< extra node properties */
	struct spa_param_info *params;		/**< parameter information */
	uint32_t n_params;			/**< number of items in \a params */
};

#define SPA_NODE_INFO_INIT()	(struct spa_node_info) { 0, }

/**
 * Port information structure
 *
 * Contains the basic port information.
 */
struct spa_port_info {
#define SPA_PORT_CHANGE_MASK_FLAGS		(1u<<0)
#define SPA_PORT_CHANGE_MASK_RATE		(1u<<1)
#define SPA_PORT_CHANGE_MASK_PROPS		(1u<<2)
#define SPA_PORT_CHANGE_MASK_PARAMS		(1u<<3)
	uint64_t change_mask;

#define SPA_PORT_FLAG_REMOVABLE			(1u<<0)	/**< port can be removed */
#define SPA_PORT_FLAG_OPTIONAL			(1u<<1)	/**< processing on port is optional */
#define SPA_PORT_FLAG_CAN_ALLOC_BUFFERS		(1u<<2)	/**< the port can allocate buffer data */
#define SPA_PORT_FLAG_IN_PLACE			(1u<<3)	/**< the port can process data in-place and
							 *   will need a writable input buffer */
#define SPA_PORT_FLAG_NO_REF			(1u<<4)	/**< the port does not keep a ref on the buffer.
							 *   This means the node will always completely
							 *   consume the input buffer and it will be
							 *   recycled after process. */
#define SPA_PORT_FLAG_LIVE			(1u<<5)	/**< output buffers from this port are
							 *   timestamped against a live clock. */
#define SPA_PORT_FLAG_PHYSICAL			(1u<<6)	/**< connects to some device */
#define SPA_PORT_FLAG_TERMINAL			(1u<<7)	/**< data was not created from this port
							 *   or will not be made available on another
							 *   port */
#define SPA_PORT_FLAG_DYNAMIC_DATA		(1u<<8)	/**< data pointer on buffers can be changed.
							 *   Only the buffer data marked as DYNAMIC
							 *   can be changed. */
	uint64_t flags;				/**< port flags */
	struct spa_fraction rate;		/**< rate of sequence numbers on port */
	const struct spa_dict *props;		/**< extra port properties */
	struct spa_param_info *params;		/**< parameter information */
	uint32_t n_params;			/**< number of items in \a params */
};

#define SPA_PORT_INFO_INIT()	(struct spa_port_info) { 0, }

#define SPA_RESULT_TYPE_NODE_ERROR	1
#define SPA_RESULT_TYPE_NODE_PARAMS	2

/** an error result */
struct spa_result_node_error {
	const char *message;
};

/** the result of enum_params or port_enum_params. */
struct spa_result_node_params {
	uint32_t id;		/**< id of parameter */
	uint32_t index;		/**< index of parameter */
	uint32_t next;		/**< next index of iteration */
	struct spa_pod *param;	/**< the result param */
};

#define SPA_NODE_EVENT_INFO		0
#define SPA_NODE_EVENT_PORT_INFO	1
#define SPA_NODE_EVENT_RESULT		2
#define SPA_NODE_EVENT_EVENT		3
#define SPA_NODE_EVENT_NUM		4

/** events from the spa_node.
 *
 * All event are called from the main thread and multiple
 * listeners can be registered for the events with
 * spa_node_add_listener().
 */
struct spa_node_events {
#define SPA_VERSION_NODE_EVENTS	0
	uint32_t version;	/**< version of this structure */

	/** Emitted when info changes */
	void (*info) (void *data, const struct spa_node_info *info);

	/** Emitted when port info changes, NULL when port is removed */
	void (*port_info) (void *data,
			enum spa_direction direction, uint32_t port,
			const struct spa_port_info *info);

	/** notify a result.
	 *
	 * Some methods will trigger a result event with an optional
	 * result of the given type. Look at the documentation of the
	 * method to know when to expect a result event.
	 *
	 * The result event can be called synchronously, as an event
	 * called from inside the method itself, in which case the seq
	 * number passed to the method will be passed unchanged.
	 *
	 * The result event will be called asynchronously when the
	 * method returned an async return value. In this case, the seq
	 * number in the result will match the async return value of
	 * the method call. Users should match the seq number from
	 * request to the reply.
	 */
	void (*result) (void *data, int seq, int res,
			uint32_t type, const void *result);

	/**
	 * \param node a spa_node
	 * \param event the event that was emitted
	 *
	 * This will be called when an out-of-bound event is notified
	 * on \a node.
	 */
	void (*event) (void *data, const struct spa_event *event);
};

#define SPA_NODE_CALLBACK_READY		0
#define SPA_NODE_CALLBACK_REUSE_BUFFER	1
#define SPA_NODE_CALLBACK_XRUN		2
#define SPA_NODE_CALLBACK_NUM		3

/** Node callbacks
 *
 * Callbacks are called from the real-time data thread. Only
 * one callback structure can be set on an spa_node.
 */
struct spa_node_callbacks {
#define SPA_VERSION_NODE_CALLBACKS	0
	uint32_t version;
	/**
	 * \param node a spa_node
	 *
	 * The node is ready for processing.
	 *
	 * When this function is NULL, synchronous operation is requested
	 * on the ports.
	 */
	int (*ready) (void *data, int state);

	/**
	 * \param node a spa_node
	 * \param port_id an input port_id
	 * \param buffer_id the buffer id to be reused
	 *
	 * The node has a buffer that can be reused.
	 *
	 * When this function is NULL, the buffers to reuse will be set in
	 * the io area of the input ports.
	 */
	int (*reuse_buffer) (void *data,
			     uint32_t port_id,
			     uint32_t buffer_id);

	/**
	 * \param data user data
	 * \param trigger the timestamp in microseconds when the xrun happened
	 * \param delay the amount of microseconds of xrun.
	 * \param info an object with extra info (NULL for now)
	 *
	 * The node has encountered an over or underrun
	 *
	 * The info contains an object with more information
	 */
	int (*xrun) (void *data, uint64_t trigger, uint64_t delay,
			struct spa_pod *info);
};


/** flags that can be passed to set_param and port_set_param functions */
#define SPA_NODE_PARAM_FLAG_TEST_ONLY	(1 << 0)	/**< Just check if the param is accepted */
#define SPA_NODE_PARAM_FLAG_FIXATE	(1 << 1)	/**< Fixate the non-optional unset fields */
#define SPA_NODE_PARAM_FLAG_NEAREST	(1 << 2)	/**< Allow set fields to be rounded to the
							  *  nearest allowed field value. */

/** flags to pass to the use_buffers functions */
#define SPA_NODE_BUFFERS_FLAG_ALLOC	(1 << 0)	/**< Allocate memory for the buffers. This flag
							  *  is ignored when the port does not have the
							  *  SPA_PORT_FLAG_CAN_ALLOC_BUFFERS set. */


#define SPA_NODE_METHOD_ADD_LISTENER		0
#define SPA_NODE_METHOD_SET_CALLBACKS		1
#define SPA_NODE_METHOD_SYNC			2
#define SPA_NODE_METHOD_ENUM_PARAMS		3
#define SPA_NODE_METHOD_SET_PARAM		4
#define SPA_NODE_METHOD_SET_IO			5
#define SPA_NODE_METHOD_SEND_COMMAND		6
#define SPA_NODE_METHOD_ADD_PORT		7
#define SPA_NODE_METHOD_REMOVE_PORT		8
#define SPA_NODE_METHOD_PORT_ENUM_PARAMS	9
#define SPA_NODE_METHOD_PORT_SET_PARAM		10
#define SPA_NODE_METHOD_PORT_USE_BUFFERS	11
#define SPA_NODE_METHOD_PORT_SET_IO		12
#define SPA_NODE_METHOD_PORT_REUSE_BUFFER	13
#define SPA_NODE_METHOD_PROCESS			14
#define SPA_NODE_METHOD_NUM			15

/**
 * Node methods
 */
struct spa_node_methods {
	/* the version of the node methods. This can be used to expand this
	 * structure in the future */
#define SPA_VERSION_NODE_METHODS	0
	uint32_t version;

	/**
	 * Adds an event listener on \a node.
	 *
	 * Setting the events will trigger the info event and a
	 * port_info event for each managed port on the new
	 * listener.
	 *
	 * \param node a #spa_node
	 * \param listener a listener
	 * \param events a #struct spa_node_events
	 * \param data data passed as first argument in functions of \a events
	 * \return 0 on success
	 *	   < 0 errno on error
	 */
	int (*add_listener) (void *object,
			struct spa_hook *listener,
			const struct spa_node_events *events,
			void *data);
	/**
	 * Set callbacks to on \a node.
	 * if \a callbacks is NULL, the current callbacks are removed.
	 *
	 * This function must be called from the main thread.
	 *
	 * All callbacks are called from the data thread.
	 *
	 * \param node a spa_node
	 * \param callbacks callbacks to set
	 * \return 0 on success
	 *         -EINVAL when node is NULL
	 */
	int (*set_callbacks) (void *object,
			      const struct spa_node_callbacks *callbacks,
			      void *data);
	/**
	 * Perform a sync operation.
	 *
	 * This method will emit the result event with the given sequence
	 * number synchronously or with the returned async return value
	 * asynchronously.
	 *
	 * Because all methods are serialized in the node, this can be used
	 * to wait for completion of all previous method calls.
	 *
	 * \param seq a sequence number
	 * \return 0 on success
	 *         -EINVAL when node is NULL
	 *         an async result
	 */
	int (*sync) (void *object, int seq);

	/**
	 * Enumerate the parameters of a node.
	 *
	 * Parameters are identified with an \a id. Some parameters can have
	 * multiple values, see the documentation of the parameter id.
	 *
	 * Parameters can be filtered by passing a non-NULL \a filter.
	 *
	 * The function will emit the result event up to \a max times with
	 * the result value. The seq in the result will either be the \a seq
	 * number when executed synchronously or the async return value of
	 * this function when executed asynchronously.
	 *
	 * This function must be called from the main thread.
	 *
	 * \param node a \ref spa_node
	 * \param seq a sequence number to pass to the result event when
	 *	this method is executed synchronously.
	 * \param id the param id to enumerate
	 * \param start the index of enumeration, pass 0 for the first item
	 * \param max the maximum number of parameters to enumerate
	 * \param filter and optional filter to use
	 *
	 * \return 0 when no more items can be iterated.
	 *         -EINVAL when invalid arguments are given
	 *         -ENOENT the parameter \a id is unknown
	 *         -ENOTSUP when there are no parameters
	 *                 implemented on \a node
	 *         an async return value when the result event will be
	 *             emitted later.
	 */
	int (*enum_params) (void *object, int seq,
			    uint32_t id, uint32_t start, uint32_t max,
			    const struct spa_pod *filter);

	/**
	 * Set the configurable parameter in \a node.
	 *
	 * Usually, \a param will be obtained from enum_params and then
	 * modified but it is also possible to set another spa_pod
	 * as long as its keys and types match a supported object.
	 *
	 * Objects with property keys that are not known are ignored.
	 *
	 * This function must be called from the main thread.
	 *
	 * \param node a \ref spa_node
	 * \param id the parameter id to configure
	 * \param flags additional flags
	 * \param param the parameter to configure
	 *
	 * \return 0 on success
	 *         -EINVAL when node is NULL
	 *         -ENOTSUP when there are no parameters implemented on \a node
	 *         -ENOENT the parameter is unknown
	 */
	int (*set_param) (void *object,
			  uint32_t id, uint32_t flags,
			  const struct spa_pod *param);

	/**
	 * Configure the given memory area with \a id on \a node. This
	 * structure is allocated by the host and is used to exchange
	 * data and parameters with the node.
	 *
	 * Setting an \a io of NULL will disable the node io.
	 *
	 * This function must be called from the main thread.
	 *
	 * \param id the id of the io area, the available ids can be
	 *        enumerated with the node parameters.
	 * \param data a io area memory
	 * \param size the size of \a data
	 * \return 0 on success
	 *         -EINVAL when invalid input is given
	 *         -ENOENT when \a id is unknown
	 *         -ENOSPC when \a size is too small
	 */
	int (*set_io) (void *object,
		       uint32_t id, void *data, size_t size);

	/**
	 * Send a command to a node.
	 *
	 * Upon completion, a command might change the state of a node.
	 *
	 * This function must be called from the main thread.
	 *
	 * \param node a  spa_node
	 * \param command a spa_command
	 * \return 0 on success
	 *         -EINVAL when node or command is NULL
	 *         -ENOTSUP when this node can't process commands
	 *         -EINVAL \a command is an invalid command
	 */
	int (*send_command) (void *object, const struct spa_command *command);

	/**
	 * Make a new port with \a port_id. The caller should use the lowest unused
	 * port id for the given \a direction.
	 *
	 * Port ids should be between 0 and max_ports as obtained from the info
	 * event.
	 *
	 * This function must be called from the main thread.
	 *
	 * \param node a  spa_node
	 * \param direction a #enum spa_direction
	 * \param port_id an unused port id
	 * \param props extra properties
	 * \return 0 on success
	 *         -EINVAL when node is NULL
	 */
	int (*add_port) (void *object,
			enum spa_direction direction, uint32_t port_id,
			const struct spa_dict *props);

	/**
	 * Remove a port with \a port_id.
	 *
	 * \param node a  spa_node
	 * \param direction a #enum spa_direction
	 * \param port_id a port id
	 * \return 0 on success
	 *         -EINVAL when node is NULL or when port_id is unknown or
	 *		when the port can't be removed.
	 */
	int (*remove_port) (void *object,
			enum spa_direction direction, uint32_t port_id);

	/**
	 * Enumerate all possible parameters of \a id on \a port_id of \a node
	 * that are compatible with \a filter.
	 *
	 * The result parameters can be queried and modified and ultimately be used
	 * to call port_set_param.
	 *
	 * The function will emit the result event up to \a max times with
	 * the result value. The seq in the result event will either be the
	 * \a seq number when executed synchronously or the async return
	 * value of this function when executed asynchronously.
	 *
	 * This function must be called from the main thread.
	 *
	 * \param node a spa_node
	 * \param seq a sequence number to pass to the result event when
	 *	this method is executed synchronously.
	 * \param direction an spa_direction
	 * \param port_id the port to query
	 * \param id the parameter id to query
	 * \param start the first index to query, 0 to get the first item
	 * \param max the maximum number of params to query
	 * \param filter a parameter filter or NULL for no filter
	 *
	 * \return 0 when no more items can be iterated.
	 *         -EINVAL when invalid parameters are given
	 *         -ENOENT when \a id is unknown
	 *         an async return value when the result event will be
	 *             emitted later.
	 */
	int (*port_enum_params) (void *object, int seq,
				 enum spa_direction direction, uint32_t port_id,
				 uint32_t id, uint32_t start, uint32_t max,
				 const struct spa_pod *filter);
	/**
	 * Set a parameter on \a port_id of \a node.
	 *
	 * When \a param is NULL, the parameter will be unset.
	 *
	 * This function must be called from the main thread.
	 *
	 * \param node a #struct spa_node
	 * \param direction a #enum spa_direction
	 * \param port_id the port to configure
	 * \param id the parameter id to set
	 * \param flags optional flags
	 * \param param a #struct spa_pod with the parameter to set
	 * \return 0 on success
	 *         1 on success, the value of \a param might have been
	 *                changed depending on \a flags and the final value can be found by
	 *                doing port_enum_params.
	 *         -EINVAL when node is NULL or invalid arguments are given
	 *         -ESRCH when one of the mandatory param
	 *                 properties is not specified and SPA_NODE_PARAM_FLAG_FIXATE was
	 *                 not set in \a flags.
	 *         -ESRCH when the type or size of a property is not correct.
	 *         -ENOENT when the param id is not found
	 */
	int (*port_set_param) (void *object,
			       enum spa_direction direction,
			       uint32_t port_id,
			       uint32_t id, uint32_t flags,
			       const struct spa_pod *param);

	/**
	 * Tell the port to use the given buffers
	 *
	 * When \a flags contains SPA_NODE_BUFFERS_FLAG_ALLOC, the data
	 * in the buffers should point to an array of at least 1 data entry
	 * with the desired supported type that will be filled by this function.
	 *
	 * The port should also have a spa_io_buffers io area configured to exchange
	 * the buffers with the port.
	 *
	 * For an input port, all the buffers will remain dequeued.
	 * Once a buffer has been queued on a port in the spa_io_buffers,
	 * it should not be reused until the reuse_buffer callback is notified
	 * or when the buffer has been returned in the spa_io_buffers of
	 * the port.
	 *
	 * For output ports, all buffers will be queued in the port. When process
	 * returns SPA_STATUS_HAVE_DATA, buffers are available in one or more
	 * of the spa_io_buffers areas.
	 *
	 * When a buffer can be reused, port_reuse_buffer() should be called or the
	 * buffer_id should be placed in the spa_io_buffers area before calling
	 * process.
	 *
	 * Passing NULL as \a buffers will remove the reference that the port has
	 * on the buffers.
	 *
	 * When this function returns async, use the spa_node_sync operation to
	 * wait for completion.
	 *
	 * This function must be called from the main thread.
	 *
	 * \param object an object implementing the interface
	 * \param direction a port direction
	 * \param port_id a port id
	 * \param flags extra flags
	 * \param buffers an array of buffer pointers
	 * \param n_buffers number of elements in \a buffers
	 * \return 0 on success
	 */
	int (*port_use_buffers) (void *object,
				 enum spa_direction direction,
				 uint32_t port_id,
				 uint32_t flags,
				 struct spa_buffer **buffers,
				 uint32_t n_buffers);

	/**
	 * Configure the given memory area with \a id on \a port_id. This
	 * structure is allocated by the host and is used to exchange
	 * data and parameters with the port.
	 *
	 * Setting an \a io of NULL will disable the port io.
	 *
	 * This function must be called from the main thread.
	 *
	 * \param direction a spa_direction
	 * \param port_id a port id
	 * \param id the id of the io area, the available ids can be
	 *        enumerated with the port parameters.
	 * \param data a io area memory
	 * \param size the size of \a data
	 * \return 0 on success
	 *         -EINVAL when invalid input is given
	 *         -ENOENT when \a id is unknown
	 *         -ENOSPC when \a size is too small
	 */
	int (*port_set_io) (void *object,
			    enum spa_direction direction,
			    uint32_t port_id,
			    uint32_t id,
			    void *data, size_t size);

	/**
	 * Tell an output port to reuse a buffer.
	 *
	 * This function must be called from the data thread.
	 *
	 * \param node a spa_node
	 * \param port_id a port id
	 * \param buffer_id a buffer id to reuse
	 * \return 0 on success
	 *         -EINVAL when node is NULL
	 */
	int (*port_reuse_buffer) (void *object, uint32_t port_id, uint32_t buffer_id);

	/**
	 * Process the node
	 *
	 * This function must be called from the data thread.
	 *
	 * Output io areas with SPA_STATUS_NEED_DATA will recycle the
	 * buffers if any.
	 *
	 * Input areas with SPA_STATUS_HAVE_DATA are consumed if possible
	 * and the status is set to SPA_STATUS_NEED_DATA or SPA_STATUS_OK.
	 *
	 * When the node has new output buffers, the SPA_STATUS_HAVE_DATA
	 * bit will be set.
	 *
	 * When the node can accept new input in the next cycle, the
	 * SPA_STATUS_NEED_DATA bit will be set.
	 */
	int (*process) (void *object);
};

#define spa_node_method(o,method,version,...)				\
({									\
	int _res = -ENOTSUP;						\
	struct spa_node *_n = o;					\
	spa_interface_call_res(&_n->iface,				\
			struct spa_node_methods, _res,			\
			method, version, ##__VA_ARGS__);		\
	_res;								\
})

#define spa_node_add_listener(n,...)		spa_node_method(n, add_listener, 0, __VA_ARGS__)
#define spa_node_set_callbacks(n,...)		spa_node_method(n, set_callbacks, 0, __VA_ARGS__)
#define spa_node_sync(n,...)			spa_node_method(n, sync, 0, __VA_ARGS__)
#define spa_node_enum_params(n,...)		spa_node_method(n, enum_params, 0, __VA_ARGS__)
#define spa_node_set_param(n,...)		spa_node_method(n, set_param, 0, __VA_ARGS__)
#define spa_node_set_io(n,...)			spa_node_method(n, set_io, 0, __VA_ARGS__)
#define spa_node_send_command(n,...)		spa_node_method(n, send_command, 0, __VA_ARGS__)
#define spa_node_add_port(n,...)		spa_node_method(n, add_port, 0, __VA_ARGS__)
#define spa_node_remove_port(n,...)		spa_node_method(n, remove_port, 0, __VA_ARGS__)
#define spa_node_port_enum_params(n,...)	spa_node_method(n, port_enum_params, 0, __VA_ARGS__)
#define spa_node_port_set_param(n,...)		spa_node_method(n, port_set_param, 0, __VA_ARGS__)
#define spa_node_port_use_buffers(n,...)	spa_node_method(n, port_use_buffers, 0, __VA_ARGS__)
#define spa_node_port_set_io(n,...)		spa_node_method(n, port_set_io, 0, __VA_ARGS__)

#define spa_node_port_reuse_buffer(n,...)	spa_node_method(n, port_reuse_buffer, 0, __VA_ARGS__)
#define spa_node_process(n)			spa_node_method(n, process, 0)

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

#endif /* SPA_NODE_H */