/* SPDX-License-Identifier: GPL-2.0 */

/** \file write.h Writer API
 *
 * Writers are part of para_audiod(1), para_write(1) and para_play(1). They
 * represent data sinks which receive input via the buffer tree mechanism
 * from their parent buffer tree node and consume input data without
 * producing any output.
 *
 * An instance of a writer is described by struct \ref writer_node, whose
 * buffer tree node \ref writer_node::btrn is set up as a leaf node of the
 * buffer tree, see \ref buffer_tree.h.
 *
 * The alsa and the ao writer defined in \ref alsa_write.c and \ref ao_write.c
 * consume the data received from higher level buffer tree nodes by writing
 * data to an audio device, employing the alsa and ao low level libraries. The
 * file writer (see \ref file_write.c) writes data to an output file instead.
 *
 * The functions declared here are defined in \ref write_common.c.
 */

/**
 * Describes one running instance of a writer.
 *
 * A writer node corresponds to a buffer tree node and a task.
 */
struct writer_node {
	/** The ID of this writer. */
	int wid;
	/** Writer-specific data. */
	void *private_data;
	/** The parsed command line, merged with options given in the config file. */
	struct lls_parse_result *lpr;
	/** The buffer tree node associated with this writer node. */
	struct btr_node *btrn;
	/** The task of this writer node. */
	struct task *task;
	/** The minimal input queue size (size of one audio sample). */
	size_t min_iqs;
};

/**
 * Describes a data sink for audio streams.
 *
 * This structure contains the methods which have to be implemented by each
 * writer. Note that there is no open method. Writers generally need to defer
 * initialization until data is available and the stream parameters are known
 * (e.g., the sample rate and the number of channels). The writers obtain this
 * information from the other buffer tree nodes by calling \ref btr_exec_up().
 *
 * \sa struct \ref writer_node, struct \ref receiver, struct \ref filter.
 */
struct writer {
	/** Ask the scheduler to check whether data can be written. */
	void (*pre_monitor)(struct sched *s, void *context);
	/** Write audio data. */
	int (*post_monitor)(struct sched *s, void *context);
	/**
	 * Close one instance of the writer.
	 *
	 * This function should deallocate all resources, particularly the
	 * private data pointer. It is assumed to succeed.
	 */
	void (*close)(struct writer_node *);
};

/** \cond doxygen_ignore */
#define WRITE_CMD(_num) (lls_cmd(_num, write_cmd_suite))

#define WRITE_CMD_OPT_RESULT(_cmd, _opt, _lpr) \
	(lls_opt_result(LSG_WRITE_CMD_ ## _cmd ## _OPT_ ## _opt, _lpr))
#define WRITE_CMD_OPT_GIVEN(_cmd, _opt, _lpr) \
	(lls_opt_given(WRITE_CMD_OPT_RESULT(_cmd, _opt, _lpr)))
#define WRITE_CMD_OPT_UINT32_VAL(_cmd, _opt, _lpr) \
	(lls_uint32_val(0, WRITE_CMD_OPT_RESULT(_cmd, _opt, (_lpr))))
#define WRITE_CMD_OPT_STRING_VAL(_cmd, _opt, _lpr) \
	(lls_string_val(0, WRITE_CMD_OPT_RESULT(_cmd, _opt, (_lpr))))
/** \endcond */

int check_writer_arg_or_die(const char *wa, struct lls_parse_result **lprp);
const struct writer *writer_get(int wid);
const char *writer_name(int wid);
void register_writer_node(struct writer_node *wn, struct btr_node *parent,
		struct sched *s);
int get_btr_sample_rate(struct btr_node *btrn, int32_t *result);
int get_btr_channels(struct btr_node *btrn, int32_t *result);
int get_btr_sample_format(struct btr_node *btrn, int32_t *result);
void print_writer_helps(bool detailed);