path: root/cras/src/libcras/cras_client.h

/* Copyright (c) 2012 The Chromium OS Authors. All rights reserved.
 * Use of this source code is governed by a BSD-style license that can be
 * found in the LICENSE file.
 *
 * This API creates multiple threads, one for control, and a thread per audio
 * stream. The control thread is used to receive messages and notifications
 * from the audio server, and manage the per-stream threads. API calls below
 * may send messages to the control thread, or directly to the server. It is
 * required that the control thread is running in order to support audio
 * streams and notifications from the server.
 *
 * The API has multiple initialization sequences, but some of those can block
 * while waiting for a response from the server.
 *
 * The following is the non-blocking API initialization sequence:
 *	cras_client_create()
 *      cras_client_set_connection_status_cb()                       (optional)
 *      cras_client_run_thread()
 *      cras_client_connect_async()
 *
 * The connection callback is executed asynchronously from the control thread
 * when the connection has been established. The connection callback should be
 * used to turn on or off interactions with any API call that communicates with
 * the audio server or starts/stops audio streams. The above is implemented by
 * cras_helper_create_connect_async().
 *
 * The following alternative (deprecated) initialization sequence can ensure
 * that the connection is established synchronously.
 *
 * Just connect to the server (no control thread):
 *      cras_client_create()
 *      cras_client_set_server_connection_cb()                       (optional)
 *   one of:
 *      cras_client_connect()                                  (blocks forever)
 *   or
 *      cras_client_connect_timeout()                      (blocks for timeout)
 *
 * For API calls below that require the control thread to be running:
 *      cras_client_run_thread();
 *      cras_client_connected_wait();                     (blocks up to 1 sec.)
 *
 * The above minus setting the connection callback is implemented within
 * cras_helper_create_connect().
 */

#ifndef CRAS_CLIENT_H_
#define CRAS_CLIENT_H_

#ifdef __cplusplus
extern "C" {
#endif

#include <stdbool.h>
#include <stdint.h>
#include <sys/select.h>

#include "cras_iodev_info.h"
#include "cras_types.h"
#include "cras_util.h"

struct cras_client;
struct cras_hotword_handle;
struct cras_stream_params;

/* Callback for audio received or transmitted.
 * Args (All pointer will be valid - except user_arg, that's up to the user):
 *    client: The client requesting service.
 *    stream_id - Unique identifier for the stream needing data read/written.
 *    samples - Read or write samples to/form here.
 *    frames - Maximum number of frames to read or write.
 *    sample_time - Playback time for the first sample read/written.
 *    user_arg - Value passed to add_stream;
 * Return:
 *    Returns the number of frames read or written on success, or a negative
 *    number if there is a stream-fatal error. Returns EOF when the end of the
 *    stream is reached.
 */
typedef int (*cras_playback_cb_t)(struct cras_client *client,
				  cras_stream_id_t stream_id, uint8_t *samples,
				  size_t frames,
				  const struct timespec *sample_time,
				  void *user_arg);

/* Callback for audio received and/or transmitted.
 * Args (All pointer will be valid - except user_arg, that's up to the user):
 *    client: The client requesting service.
 *    stream_id - Unique identifier for the stream needing data read/written.
 *    captured_samples - Read samples form here.
 *    playback_samples - Read or write samples to here.
 *    frames - Maximum number of frames to read or write.
 *    captured_time - Time the first sample was read.
 *    playback_time - Playback time for the first sample written.
 *    user_arg - Value passed to add_stream;
 * Return:
 *    Returns the number of frames read or written on success, or a negative
 *    number if there is a stream-fatal error. Returns EOF when the end of the
 *    stream is reached.
 */
typedef int (*cras_unified_cb_t)(struct cras_client *client,
				 cras_stream_id_t stream_id,
				 uint8_t *captured_samples,
				 uint8_t *playback_samples, unsigned int frames,
				 const struct timespec *captured_time,
				 const struct timespec *playback_time,
				 void *user_arg);

/* Callback for handling stream errors.
 * Args:
 *    client - The client created with cras_client_create().
 *    stream_id - The ID for this stream.
 *    error - The error code,
 *    user_arg - The argument defined in cras_client_*_params_create().
 */
typedef int (*cras_error_cb_t)(struct cras_client *client,
			       cras_stream_id_t stream_id, int error,
			       void *user_arg);

/* Server connection status. */
typedef enum cras_connection_status {
	CRAS_CONN_STATUS_FAILED,
	/* Resource allocation problem. Free resources, and retry the
	 * connection with cras_client_connect_async(), or (blocking)
	 * cras_client_connect(). Do not call cras_client_connect(),
	 * cras_client_connect_timeout(), or cras_client_destroy()
	 * from the callback. */
	CRAS_CONN_STATUS_DISCONNECTED,
	/* The control thread is attempting to reconnect to the
	 * server in the background. Any attempt to access the
	 * server will fail or block (see
	 * cras_client_set_server_message_blocking(). */
	CRAS_CONN_STATUS_CONNECTED,
	/* Connection is established. All state change callbacks
	 * have been re-registered, but audio streams must be
	 * restarted, and node state data must be updated. */
} cras_connection_status_t;

/* Callback for handling server connection status.
 *
 * See also cras_client_set_connection_status_cb(). Do not call
 * cras_client_connect(), cras_client_connect_timeout(), or
 * cras_client_destroy() from this callback.
 *
 * Args:
 *    client - The client created with cras_client_create().
 *    status - The status of the connection to the server.
 *    user_arg - The argument defined in
 *               cras_client_set_connection_status_cb().
 */
typedef void (*cras_connection_status_cb_t)(struct cras_client *client,
					    cras_connection_status_t status,
					    void *user_arg);

/* Callback for setting thread priority. */
typedef void (*cras_thread_priority_cb_t)(struct cras_client *client);

/* Callback for handling get hotword models reply. */
typedef void (*get_hotword_models_cb_t)(struct cras_client *client,
					const char *hotword_models);

/* Callback to wait for a hotword trigger. */
typedef void (*cras_hotword_trigger_cb_t)(struct cras_client *client,
					  struct cras_hotword_handle *handle,
					  void *user_data);

/* Callback for handling hotword errors. */
typedef int (*cras_hotword_error_cb_t)(struct cras_client *client,
				       struct cras_hotword_handle *handle,
				       int error, void *user_data);

/*
 * Client handling.
 */

/* Creates a new client.
 * Args:
 *    client - Filled with a pointer to the new client.
 * Returns:
 *    0 on success (*client is filled with a valid cras_client pointer).
 *    Negative error code on failure(*client will be NULL).
 */
int cras_client_create(struct cras_client **client);

/* Creates a new client with given connection type.
 * Args:
 *     client - Filled with a pointer to the new client.
 *     conn_type - enum CRAS_CONNECTION_TYPE
 *
 * Returns:
 *     0 on success (*client is filled with a valid cras_client pointer).
 *     Negative error code on failure(*client will be NULL).
 */
int cras_client_create_with_type(struct cras_client **client,
				 enum CRAS_CONNECTION_TYPE conn_type);

/* Destroys a client.
 * Args:
 *    client - returned from "cras_client_create".
 */
void cras_client_destroy(struct cras_client *client);

/* Connects a client to the running server.
 * Waits forever (until interrupted or connected).
 * Args:
 *    client - pointer returned from "cras_client_create".
 * Returns:
 *    0 on success, or a negative error code on failure (from errno.h).
 */
int cras_client_connect(struct cras_client *client);

/* Connects a client to the running server, retries until timeout.
 * Args:
 *    client - pointer returned from "cras_client_create".
 *    timeout_ms - timeout in milliseconds or negative to wait forever.
 * Returns:
 *    0 on success, or a negative error code on failure (from errno.h).
 */
int cras_client_connect_timeout(struct cras_client *client,
				unsigned int timeout_ms);

/* Begins running the client control thread.
 *
 * Required for stream operations and other operations noted below.
 *
 * Args:
 *    client - the client to start (from cras_client_create).
 * Returns:
 *    0 on success or if the thread is already running, -EINVAL if the client
 *    pointer is NULL, or the negative result of pthread_create().
 */
int cras_client_run_thread(struct cras_client *client);

/* Stops running a client.
 * This function is executed automatically by cras_client_destroy().
 * Args:
 *    client - the client to stop (from cras_client_create).
 * Returns:
 *    0 on success or if the thread was already stopped, -EINVAL if the client
 *    isn't valid.
 */
int cras_client_stop(struct cras_client *client);

/* Wait up to 1 second for the client thread to complete the server connection.
 *
 * After cras_client_run_thread() is executed, this function can be used to
 * ensure that the connection has been established with the server and ensure
 * that any information about the server is up to date. If
 * cras_client_run_thread() has not yet been executed, or cras_client_stop()
 * was executed and thread isn't running, then this function returns -EINVAL.
 *
 * Args:
 *    client - pointer returned from "cras_client_create".
 * Returns:
 *    0 on success, or a negative error code on failure (from errno.h).
 */
int cras_client_connected_wait(struct cras_client *client);

/* Ask the client control thread to connect to the audio server.
 *
 * After cras_client_run_thread() is executed, this function can be used
 * to ask the control thread to connect to the audio server asynchronously.
 * The callback set with cras_client_set_connection_status_cb() will be
 * executed when the connection is established.
 *
 * Args:
 *    client - The client from cras_client_create().
 * Returns:
 *    0 on success, or a negative error code on failure (from errno.h).
 *    -EINVAL if the client pointer is invalid or the control thread is
 *    not running.
 */
int cras_client_connect_async(struct cras_client *client);

/* Sets server connection status callback.
 *
 * See cras_connection_status_t for a description of the connection states
 * and appropriate user action.
 *
 * Args:
 *    client - The client from cras_client_create.
 *    connection_cb - The callback function to register.
 *    user_arg - Pointer that will be passed to the callback.
 */
void cras_client_set_connection_status_cb(
	struct cras_client *client, cras_connection_status_cb_t connection_cb,
	void *user_arg);

/* Sets callback for setting thread priority.
 * Args:
 *    client - The client from cras_client_create.
 *    cb - The thread priority callback.
 */
void cras_client_set_thread_priority_cb(struct cras_client *client,
					cras_thread_priority_cb_t cb);

/* Returns the current list of output devices.
 *
 * Requires that the connection to the server has been established.
 *
 * Data is copied and thus can become out of date. This call must be
 * re-executed to get updates.
 *
 * Args:
 *    client - The client from cras_client_create.
 *    devs - Array that will be filled with device info.
 *    nodes - Array that will be filled with node info.
 *    *num_devs - Maximum number of devices to put in the array.
 *    *num_nodes - Maximum number of nodes to put in the array.
 * Returns:
 *    0 on success, -EINVAL if the client isn't valid or isn't running.
 *    *num_devs is set to the actual number of devices info filled.
 *    *num_nodes is set to the actual number of nodes info filled.
 */
int cras_client_get_output_devices(const struct cras_client *client,
				   struct cras_iodev_info *devs,
				   struct cras_ionode_info *nodes,
				   size_t *num_devs, size_t *num_nodes);

/* Returns the current list of input devices.
 *
 * Requires that the connection to the server has been established.
 *
 * Data is copied and thus can become out of date. This call must be
 * re-executed to get updates.
 *
 * Args:
 *    client - The client from cras_client_create.
 *    devs - Array that will be filled with device info.
 *    nodes - Array that will be filled with node info.
 *    *num_devs - Maximum number of devices to put in the array.
 *    *num_nodes - Maximum number of nodes to put in the array.
 * Returns:
 *    0 on success, -EINVAL if the client isn't valid or isn't running.
 *    *num_devs is set to the actual number of devices info filled.
 *    *num_nodes is set to the actual number of nodes info filled.
 */
int cras_client_get_input_devices(const struct cras_client *client,
				  struct cras_iodev_info *devs,
				  struct cras_ionode_info *nodes,
				  size_t *num_devs, size_t *num_nodes);

/* Returns the current list of clients attached to the server.
 *
 * Requires that the connection to the server has been established.
 *
 * Data is copied and thus can become out of date. This call must be
 * re-executed to get updates.
 *
 * Args:
 *    client - This client (from cras_client_create).
 *    clients - Array that will be filled with a list of attached clients.
 *    max_clients - Maximum number of clients to put in the array.
 * Returns:
 *    The number of attached clients.  This may be more that max_clients passed
 *    in, this indicates that all of the clients wouldn't fit in the provided
 *    array.
 */
int cras_client_get_attached_clients(const struct cras_client *client,
				     struct cras_attached_client_info *clients,
				     size_t max_clients);

/* Find a node info with the matching node id.
 *
 * Requires that the connection to the server has been established.
 *
 * Data is copied and thus can become out of date. This call must be
 * re-executed to get updates.
 *
 * Args:
 *    client - This client (from cras_client_create).
 *    input - Non-zero for input nodes, zero for output nodes.
 *    node_id - The node id to look for.
 *    node_info - The information about the ionode will be returned here.
 * Returns:
 *    0 if successful, negative on error; -ENOENT if the node cannot be found.
 */
int cras_client_get_node_by_id(const struct cras_client *client, int input,
			       const cras_node_id_t node_id,
			       struct cras_ionode_info *node_info);

/* Checks if the output device with the given name is currently plugged in.
 *
 * For internal devices this checks that jack state, for USB devices this will
 * always be true if they are present. The name parameter can be the complete
 * name or any unique prefix of the name. If the name is not unique the first
 * matching name will be checked.
 *
 * Requires that the connection to the server has been established.
 *
 * Data is copied and thus can become out of date. This call must be
 * re-executed to get updates.
 *
 * Args:
 *    client - The client from cras_client_create.
 *    name - Name of the device to check.
 * Returns:
 *    1 if the device exists and is plugged, 0 otherwise.
 */
int cras_client_output_dev_plugged(const struct cras_client *client,
				   const char *name);

/* Set the value of an attribute of an ionode.
 *
 * Args:
 *    client - The client from cras_client_create.
 *    node_id - The id of the ionode.
 *    attr - the attribute we want to change.
 *    value - the value we want to set.
 * Returns:
 *    Returns 0 for success, negative on error (from errno.h).
 */
int cras_client_set_node_attr(struct cras_client *client,
			      cras_node_id_t node_id, enum ionode_attr attr,
			      int value);

/* Select the preferred node for playback/capture.
 *
 * Args:
 *    client - The client from cras_client_create.
 *    direction - The direction of the ionode.
 *    node_id - The id of the ionode. If node_id is the special value 0, then
 *        the preference is cleared and cras will choose automatically.
 */
int cras_client_select_node(struct cras_client *client,
			    enum CRAS_STREAM_DIRECTION direction,
			    cras_node_id_t node_id);

/* Adds an active node for playback/capture.
 *
 * Args:
 *    client - The client from cras_client_create.
 *    direction - The direction of the ionode.
 *    node_id - The id of the ionode. If there's no node matching given
 *        id, nothing will happen in CRAS.
 */
int cras_client_add_active_node(struct cras_client *client,
				enum CRAS_STREAM_DIRECTION direction,
				cras_node_id_t node_id);

/* Removes an active node for playback/capture.
 *
 * Args:
 *    client - The client from cras_client_create.
 *    direction - The direction of the ionode.
 *    node_id - The id of the ionode. If there's no node matching given
 *        id, nothing will happen in CRAS.
 */
int cras_client_rm_active_node(struct cras_client *client,
			       enum CRAS_STREAM_DIRECTION direction,
			       cras_node_id_t node_id);

/* Asks the server to reload dsp plugin configuration from the ini file.
 *
 * Args:
 *    client - The client from cras_client_create.
 * Returns:
 *    0 on success, -EINVAL if the client isn't valid or isn't running.
 */
int cras_client_reload_dsp(struct cras_client *client);

/* Asks the server to dump current dsp information to syslog.
 *
 * Args:
 *    client - The client from cras_client_create.
 * Returns:
 *    0 on success, -EINVAL if the client isn't valid or isn't running.
 */
int cras_client_dump_dsp_info(struct cras_client *client);

/* Asks the server to dump current audio thread information.
 *
 * Args:
 *    client - The client from cras_client_create.
 *    cb - A function to call when the data is received.
 * Returns:
 *    0 on success, -EINVAL if the client isn't valid or isn't running.
 */
int cras_client_update_audio_debug_info(struct cras_client *client,
					void (*cb)(struct cras_client *));

/* Asks the server to dump bluetooth debug information.
 * Args:
 *    client - The client from cras_client_create.
 *    cb - Function to call when debug info is ready.
 * Returns:
 *    0 on success, -EINVAL if the client isn't valid or isn't running.
 */
int cras_client_update_bt_debug_info(struct cras_client *client,
				     void (*cb)(struct cras_client *));

/* Gets read-only access to audio thread log. Should be called once before
   calling cras_client_read_atlog.
 * Args:
 *    client - The client from cras_client_create.
 *    atlog_access_cb - Function to call after getting atlog access.
 * Returns:
 *    0 on success, -EINVAL if the client or atlog_access_cb isn't valid.
 */
int cras_client_get_atlog_access(struct cras_client *client,
				 void (*atlog_access_cb)(struct cras_client *));

/* Reads continuous audio thread log into 'buf', starting from 'read_idx'-th log
 * till the latest. The number of missing logs within the range will be stored
 * in 'missing'. Requires calling cras_client_get_atlog_access() beforehand
 * to get access to audio thread log.
 * Args:
 *    client - The client from cras_client_create.
 *    read_idx - The log number to start reading with.
 *    missing - The pointer to store the number of missing logs.
 *    buf - The buffer to which continuous logs will be copied.
 * Returns:
 *    The number of logs copied. < 0 if failed to read audio thread log.
 */
int cras_client_read_atlog(struct cras_client *client, uint64_t *read_idx,
			   uint64_t *missing,
			   struct audio_thread_event_log *buf);

/* Asks the server to dump current audio thread snapshots.
 *
 * Args:
 *    client - The client from cras_client_create.
 *    cb - A function to call when the data is received.
 * Returns:
 *    0 on success, -EINVAL if the client isn't valid or isn't running.
 */
int cras_client_update_audio_thread_snapshots(struct cras_client *client,
					      void (*cb)(struct cras_client *));

/*
 * Stream handling.
 */

/* Setup stream configuration parameters.
 * Args:
 *    direction - playback(CRAS_STREAM_OUTPUT) or capture(CRAS_STREAM_INPUT).
 *    buffer_frames - total number of audio frames to buffer (dictates latency).
 *    cb_threshold - For playback, call back for more data when the buffer
 *        reaches this level. For capture, this is ignored (Audio callback will
 *        be called when buffer_frames have been captured).
 *    unused - No longer used.
 *    stream_type - media or talk (currently only support "default").
 *    flags - None currently used.
 *    user_data - Pointer that will be passed to the callback.
 *    aud_cb - Called when audio is needed(playback) or ready(capture). Allowed
 *        return EOF to indicate that the stream should terminate.
 *    err_cb - Called when there is an error with the stream.
 *    format - The format of the audio stream.  Specifies bits per sample,
 *        number of channels, and sample rate.
 */
struct cras_stream_params *cras_client_stream_params_create(
	enum CRAS_STREAM_DIRECTION direction, size_t buffer_frames,
	size_t cb_threshold, size_t unused, enum CRAS_STREAM_TYPE stream_type,
	uint32_t flags, void *user_data, cras_playback_cb_t aud_cb,
	cras_error_cb_t err_cb, struct cras_audio_format *format);

/* Functions to set the client type on given stream parameter.
 * Args:
 *    params - Stream configuration parameters.
 *    client_type - A client type.
 */
void cras_client_stream_params_set_client_type(
	struct cras_stream_params *params, enum CRAS_CLIENT_TYPE client_type);

/* Functions to enable or disable specific effect on given stream parameter.
 * Args:
 *    params - Stream configuration parameters.
 */
void cras_client_stream_params_enable_aec(struct cras_stream_params *params);
void cras_client_stream_params_disable_aec(struct cras_stream_params *params);
void cras_client_stream_params_enable_ns(struct cras_stream_params *params);
void cras_client_stream_params_disable_ns(struct cras_stream_params *params);
void cras_client_stream_params_enable_agc(struct cras_stream_params *params);
void cras_client_stream_params_disable_agc(struct cras_stream_params *params);
void cras_client_stream_params_enable_vad(struct cras_stream_params *params);
void cras_client_stream_params_disable_vad(struct cras_stream_params *params);

/* Function to setup client-provided shm to be used as the backing shm for the
 * samples area in the cras_audio_shm shared with cras.
 * Args:
 *    client_shm_fd - shm fd to use for samples shm area.
 *    client_shm_size - size of shm area backed by 'client_shm_fd'.
 */
void cras_client_stream_params_configure_client_shm(
	struct cras_stream_params *params, int client_shm_fd,
	size_t client_shm_size);

/* Setup stream configuration parameters. DEPRECATED.
 * TODO(crbug.com/972928): remove this
 * Use cras_client_stream_params_create instead.
 * Args:
 *    direction - playback(CRAS_STREAM_OUTPUT) or capture(CRAS_STREAM_INPUT) or
 *        loopback(CRAS_STREAM_POST_MIX_PRE_DSP).
 *    block_size - The number of frames per callback(dictates latency).
 *    stream_type - media or talk (currently only support "default").
 *    flags - None currently used.
 *    user_data - Pointer that will be passed to the callback.
 *    unified_cb - Called to request audio data or to notify the client when
 *                 captured audio is available. Though this is a unified_cb,
 *                 only one direction will be used for a stream, depending
 *                 on the 'direction' parameter.
 *    err_cb - Called when there is an error with the stream.
 *    format - The format of the audio stream.  Specifies bits per sample,
 *        number of channels, and sample rate.
 */
struct cras_stream_params *cras_client_unified_params_create(
	enum CRAS_STREAM_DIRECTION direction, unsigned int block_size,
	enum CRAS_STREAM_TYPE stream_type, uint32_t flags, void *user_data,
	cras_unified_cb_t unified_cb, cras_error_cb_t err_cb,
	struct cras_audio_format *format);

/* Destroy stream params created with cras_client_stream_params_create. */
void cras_client_stream_params_destroy(struct cras_stream_params *params);

/* Creates a new stream and return the stream id or < 0 on error.
 *
 * Requires execution of cras_client_run_thread(), and an active connection
 * to the audio server.
 *
 * Args:
 *    client - The client to add the stream to (from cras_client_create).
 *    stream_id_out - On success will be filled with the new stream id.
 *        Guaranteed to be set before any callbacks are made.
 *    config - The cras_stream_params struct specifying the parameters for the
 *        stream.
 * Returns:
 *    0 on success, negative error code on failure (from errno.h).
 */
int cras_client_add_stream(struct cras_client *client,
			   cras_stream_id_t *stream_id_out,
			   struct cras_stream_params *config);

/* Creates a pinned stream and return the stream id or < 0 on error.
 *
 * Requires execution of cras_client_run_thread(), and an active connection
 * to the audio server.
 *
 * Args:
 *    client - The client to add the stream to (from cras_client_create).
 *    dev_idx - Index of the device to attach the newly created stream.
 *    stream_id_out - On success will be filled with the new stream id.
 *        Guaranteed to be set before any callbacks are made.
 *    config - The cras_stream_params struct specifying the parameters for the
 *        stream.
 * Returns:
 *    0 on success, negative error code on failure (from errno.h).
 */
int cras_client_add_pinned_stream(struct cras_client *client, uint32_t dev_idx,
				  cras_stream_id_t *stream_id_out,
				  struct cras_stream_params *config);

/* Removes a currently playing/capturing stream.
 *
 * Requires execution of cras_client_run_thread().
 *
 * Args:
 *    client - Client to remove the stream (returned from cras_client_create).
 *    stream_id - ID returned from cras_client_add_stream to identify the stream
          to remove.
 * Returns:
 *    0 on success negative error code on failure (from errno.h).
 */
int cras_client_rm_stream(struct cras_client *client,
			  cras_stream_id_t stream_id);

/* Sets the volume scaling factor for the given stream.
 *
 * Requires execution of cras_client_run_thread().
 *
 * Args:
 *    client - Client owning the stream.
 *    stream_id - ID returned from cras_client_add_stream.
 *    volume_scaler - 0.0-1.0 the new value to scale this stream by.
 */
int cras_client_set_stream_volume(struct cras_client *client,
				  cras_stream_id_t stream_id,
				  float volume_scaler);

/*
 * System level functions.
 */

/* Sets the volume of the system.
 *
 * Volume here ranges from 0 to 100, and will be translated to dB based on the
 * output-specific volume curve.
 *
 * Args:
 *    client - The client from cras_client_create.
 *    volume - 0-100 the new volume index.
 * Returns:
 *    0 for success, -EPIPE if there is an I/O error talking to the server, or
 *    -EINVAL if 'client' is invalid.
 */
int cras_client_set_system_volume(struct cras_client *client, size_t volume);

/* Sets the capture gain of the system.
 *
 * Gain is specified in dBFS * 100.  For example 5dB of gain would be specified
 * with an argument of 500, while -10 would be specified with -1000.
 *
 * Args:
 *    client - The client from cras_client_create.
 *    gain - The gain in dBFS * 100.
 * Returns:
 *    0 for success, -EPIPE if there is an I/O error talking to the server, or
 *    -EINVAL if 'client' is invalid.
 */
int cras_client_set_system_capture_gain(struct cras_client *client, long gain);

/* Sets the mute state of the system.
 *
 * Args:
 *    client - The client from cras_client_create.
 *    mute - 0 is un-mute, 1 is muted.
 * Returns:
 *    0 for success, -EPIPE if there is an I/O error talking to the server, or
 *    -EINVAL if 'client' is invalid.
 */
int cras_client_set_system_mute(struct cras_client *client, int mute);

/* Sets the user mute state of the system.
 *
 * This is used for mutes caused by user interaction. Like the mute key.
 *
 * Args:
 *    client - The client from cras_client_create.
 *    mute - 0 is un-mute, 1 is muted.
 * Returns:
 *    0 for success, -EPIPE if there is an I/O error talking to the server, or
 *    -EINVAL if 'client' is invalid.
 */
int cras_client_set_user_mute(struct cras_client *client, int mute);

/* Sets the mute locked state of the system.
 *
 * Changing mute state is impossible when this flag is set to locked.
 *
 * Args:
 *    client - The client from cras_client_create.
 *    locked - 0 is un-locked, 1 is locked.
 * Returns:
 *    0 for success, -EPIPE if there is an I/O error talking to the server, or
 *    -EINVAL if 'client' is invalid.
 */
int cras_client_set_system_mute_locked(struct cras_client *client, int locked);

/* Sets the capture mute state of the system.
 *
 * Recordings will be muted when this is set.
 *
 * Args:
 *    client - The client from cras_client_create.
 *    mute - 0 is un-mute, 1 is muted.
 * Returns:
 *    0 for success, -EPIPE if there is an I/O error talking to the server, or
 *    -EINVAL if 'client' is invalid.
 */
int cras_client_set_system_capture_mute(struct cras_client *client, int mute);

/* Sets the capture mute locked state of the system.
 *
 * Changing mute state is impossible when this flag is set to locked.
 *
 * Args:
 *    client - The client from cras_client_create.
 *    locked - 0 is un-locked, 1 is locked.
 * Returns:
 *    0 for success, -EPIPE if there is an I/O error talking to the server, or
 *    -EINVAL if 'client' is invalid.
 */
int cras_client_set_system_capture_mute_locked(struct cras_client *client,
					       int locked);

/* Gets the current system volume.
 *
 * Requires that the connection to the server has been established.
 *
 * Args:
 *    client - The client from cras_client_create.
 * Returns:
 *    The current system volume between 0 and 100.
 */
size_t cras_client_get_system_volume(const struct cras_client *client);

/* Gets the current system capture gain.
 *
 * Requires that the connection to the server has been established.
 *
 * Args:
 *    client - The client from cras_client_create.
 * Returns:
 *    The current system capture volume in dB * 100.
 */
long cras_client_get_system_capture_gain(const struct cras_client *client);

/* Gets the current system mute state.
 *
 * Requires that the connection to the server has been established.
 *
 * Args:
 *    client - The client from cras_client_create.
 * Returns:
 *    0 if not muted, 1 if it is.
 */
int cras_client_get_system_muted(const struct cras_client *client);

/* Gets the current user mute state.
 *
 * Requires that the connection to the server has been established.
 *
 * Args:
 *    client - The client from cras_client_create.
 * Returns:
 *    0 if not muted, 1 if it is.
 */
int cras_client_get_user_muted(const struct cras_client *client);

/* Gets the current system capture mute state.
 *
 * Requires that the connection to the server has been established.
 *
 * Args:
 *    client - The client from cras_client_create.
 * Returns:
 *    0 if capture is not muted, 1 if it is.
 */
int cras_client_get_system_capture_muted(const struct cras_client *client);

/* Gets the current minimum system volume.
 * Args:
 *    client - The client from cras_client_create.
 * Returns:
 *    The minimum value for the current output device in dBFS * 100.  This is
 *    the level of attenuation at volume == 1.
 */
long cras_client_get_system_min_volume(const struct cras_client *client);

/* Gets the current maximum system volume.
 * Args:
 *    client - The client from cras_client_create.
 * Returns:
 *    The maximum value for the current output device in dBFS * 100.  This is
 *    the level of attenuation at volume == 100.
 */
long cras_client_get_system_max_volume(const struct cras_client *client);

/* Gets the current minimum system capture gain.
 *
 * Requires that the connection to the server has been established.
 *
 * Args:
 *    client - The client from cras_client_create.
 * Returns:
 *    The minimum capture gain for the current input device in dBFS * 100.
 */
long cras_client_get_system_min_capture_gain(const struct cras_client *client);

/* Gets the current maximum system capture gain.
 *
 * Requires that the connection to the server has been established.
 *
 * Args:
 *    client - The client from cras_client_create.
 * Returns:
 *    The maximum capture gain for the current input device in dBFS * 100.
 */
long cras_client_get_system_max_capture_gain(const struct cras_client *client);

/* Gets audio debug info.
 *
 * Requires that the connection to the server has been established.
 * Access to the resulting pointer is not thread-safe.
 *
 * Args:
 *    client - The client from cras_client_create.
 * Returns:
 *    A pointer to the debug info.  This info is only updated when requested by
 *    calling cras_client_update_audio_debug_info.
 */
const struct audio_debug_info *
cras_client_get_audio_debug_info(const struct cras_client *client);

/* Gets bluetooth debug info.
 *
 * Requires that the connection to the server has been established.
 *
 * Args:
 *    client - The client from cras_client_create.
 * Returns:
 *    A pointer to the debug info. This info is updated and requested by
 *    calling cras_client_update_bt_debug_info.
 */
const struct cras_bt_debug_info *
cras_client_get_bt_debug_info(const struct cras_client *client);

/* Gets audio thread snapshot buffer.
 *
 * Requires that the connection to the server has been established.
 * Access to the resulting pointer is not thread-safe.
 *
 * Args:
 *    client - The client from cras_client_create.
 * Returns:
 *    A pointer to the snapshot buffer.  This info is only updated when
 *    requested by calling cras_client_update_audio_thread_snapshots.
 */
const struct cras_audio_thread_snapshot_buffer *
cras_client_get_audio_thread_snapshot_buffer(const struct cras_client *client);

/* Gets the number of streams currently attached to the server.
 *
 * This is the total number of capture and playback streams. If the ts argument
 * is not null, then it will be filled with the last time audio was played or
 * recorded. ts will be set to the current time if streams are currently
 * active.
 *
 * Requires that the connection to the server has been established.
 *
 * Args:
 *    client - The client from cras_client_create.
 *    ts - Filled with the timestamp of the last stream.
 * Returns:
 *    The number of active streams.
 */
unsigned cras_client_get_num_active_streams(const struct cras_client *client,
					    struct timespec *ts);

/*
 * Utility functions.
 */

/* Returns the number of bytes in an audio frame for a stream.
 * Args:
 *    format - The format of the audio stream.  Specifies bits per sample,
 *        number of channels, and sample rate.
 * Returns:
 *   Positive number of bytes in a frame, or a negative error code if fmt is
 *   NULL.
 */
int cras_client_format_bytes_per_frame(struct cras_audio_format *fmt);

/* For playback streams, calculates the latency of the next sample written.
 * Only valid when called from the audio callback function for the stream
 * (aud_cb).
 * Args:
 *    sample_time - The sample time stamp passed in to aud_cb.
 *    delay - Out parameter will be filled with the latency.
 * Returns:
 *    0 on success, -EINVAL if delay is NULL.
 */
int cras_client_calc_playback_latency(const struct timespec *sample_time,
				      struct timespec *delay);

/* For capture returns the latency of the next frame to be read from the buffer
 * (based on when it was captured).  Only valid when called from the audio
 * callback function for the stream (aud_cb).
 * Args:
 *    sample_time - The sample time stamp passed in to aud_cb.
 *    delay - Out parameter will be filled with the latency.
 * Returns:
 *    0 on success, -EINVAL if delay is NULL.
 */
int cras_client_calc_capture_latency(const struct timespec *sample_time,
				     struct timespec *delay);

/* Set the volume of the given output node. Only for output nodes.
 *
 * Args:
 *    client - The client from cras_client_create.
 *    node_id - ID of the node.
 *    volume - New value for node volume.
 */
int cras_client_set_node_volume(struct cras_client *client,
				cras_node_id_t node_id, uint8_t volume);

/* Swap the left and right channel of the given node.
 *
 * Args:
 *    client - The client from cras_client_create.
 *    node_id - ID of the node.
 *    enable - 1 to enable swap mode, 0 to disable.
 */
int cras_client_swap_node_left_right(struct cras_client *client,
				     cras_node_id_t node_id, int enable);

/* Set the capture gain of the given input node.  Only for input nodes.
 *
 * Args:
 *    client - The client from cras_client_create.
 *    node_id - ID of the node.
 *    gain - New capture gain for the node.
 */
int cras_client_set_node_capture_gain(struct cras_client *client,
				      cras_node_id_t node_id, long gain);

/* Add a test iodev to the iodev list.
 *
 * Args:
 *    client - The client from cras_client_create.
 *    type - The type of test iodev, see cras_types.h
 */
int cras_client_add_test_iodev(struct cras_client *client,
			       enum TEST_IODEV_TYPE type);

/* Send a test command to a test iodev.
 *
 * Args:
 *    client - The client from cras_client_create.
 *    iodev_idx - The index of the test iodev.
 *    command - The command to send.
 *    data_len - Length of command data.
 *    data - Command data.
 */
int cras_client_test_iodev_command(struct cras_client *client,
				   unsigned int iodev_idx,
				   enum CRAS_TEST_IODEV_CMD command,
				   unsigned int data_len, const uint8_t *data);

/* Finds the first node of the given type.
 *
 * This is used for finding a special hotword node.
 *
 * Requires that the connection to the server has been established.
 *
 * Args:
 *    client - The client from cras_client_create.
 *    type - The type of device to find.
 *    direction - Search input or output devices.
 *    node_id - The found node on success.
 * Returns:
 *    0 on success, a negative error on failure.
 */
int cras_client_get_first_node_type_idx(const struct cras_client *client,
					enum CRAS_NODE_TYPE type,
					enum CRAS_STREAM_DIRECTION direction,
					cras_node_id_t *node_id);

/* Finds the first device that contains a node of the given type.
 *
 * This is used for finding a special hotword device.
 *
 * Requires that the connection to the server has been established.
 *
 * Args:
 *    client - The client from cras_client_create.
 *    type - The type of device to find.
 *    direction - Search input or output devices.
 * Returns the device index of a negative error on failure.
 */
int cras_client_get_first_dev_type_idx(const struct cras_client *client,
				       enum CRAS_NODE_TYPE type,
				       enum CRAS_STREAM_DIRECTION direction);

/* Sets the suspend state of audio playback and capture.
 *
 * Set this before putting the system into suspend.
 *
 * Args:
 *    client - The client from cras_client_create.
 *    suspend - Suspend the system if non-zero, otherwise resume.
 */
int cras_client_set_suspend(struct cras_client *client, int suspend);

/* Configures the global converter for output remixing.
 *
 * Args:
 *    client - The client from cras_client_create.
 *    num_channels - Number of output channels.
 *    coefficient - Float array representing |num_channels| * |num_channels|
 *        matrix. Channels of mixed PCM output will be remixed by
 *        multiplying this matrix.
 */
int cras_client_config_global_remix(struct cras_client *client,
				    unsigned num_channels, float *coefficient);

/* Gets the set of supported hotword language models on a node. The supported
 * models may differ on different nodes.
 *
 * Args:
 *    client - The client from cras_client_create.
 *    node_id - ID of a hotword input node (CRAS_NODE_TYPE_HOTWORD).
 *    cb - The function to be called when hotword models are ready.
 * Returns:
 *    0 on success.
 */
int cras_client_get_hotword_models(struct cras_client *client,
				   cras_node_id_t node_id,
				   get_hotword_models_cb_t cb);

/* Sets the hotword language model on a node. If there are existing streams on
 * the hotword input node when this function is called, they need to be closed
 * then re-opend for the model change to take effect.
 * Args:
 *    client - The client from cras_client_create.
 *    node_id - ID of a hotword input node (CRAS_NODE_TYPE_HOTWORD).
 *    model_name - Name of the model to use, e.g. "en_us".
 * Returns:
 *    0 on success.
 *    -EINVAL if client or node_id is invalid.
 *    -ENOENT if the specified model is not found.
 */
int cras_client_set_hotword_model(struct cras_client *client,
				  cras_node_id_t node_id,
				  const char *model_name);

/*
 * Creates a hotword stream and waits for the hotword to trigger.
 *
 * Args:
 *    client - The client to add the stream to (from cras_client_create).
 *    user_data - Pointer that will be passed to the callback.
 *    trigger_cb - Called when a hotword is triggered.
 *    err_cb - Called when there is an error with the stream.
 *    handle_out - On success will be filled with a cras_hotword_handle.
 * Returns:
 *    0 on success, negative error code on failure (from errno.h).
 */
int cras_client_enable_hotword_callback(
	struct cras_client *client, void *user_data,
	cras_hotword_trigger_cb_t trigger_cb, cras_hotword_error_cb_t err_cb,
	struct cras_hotword_handle **handle_out);

/*
 * Closes a hotword stream that was created by cras_client_wait_for_hotword.
 *
 * Args:
 *    client - Client to remove the stream (returned from cras_client_create).
 *    handle - cras_hotword_handle returned from cras_client_wait_for_hotword.
 * Returns:
 *    0 on success negative error code on failure (from errno.h).
 */
int cras_client_disable_hotword_callback(struct cras_client *client,
					 struct cras_hotword_handle *handle);

/* Starts or stops the aec dump task on server side.
 * Args:
 *    client - The client from cras_client_create.
 *    stream_id - The id of the input stream running with aec effect.
 *    start - True to start APM debugging, otherwise to stop it.
 *    fd - File descriptor of the file to store aec dump result.
 */
int cras_client_set_aec_dump(struct cras_client *client,
			     cras_stream_id_t stream_id, int start, int fd);
/*
 * Reloads the aec.ini config file on server side.
 */
int cras_client_reload_aec_config(struct cras_client *client);

/*
 * Returns if AEC is supported.
 */
int cras_client_get_aec_supported(struct cras_client *client);

/*
 * Returns the AEC group ID if available.
 */
int cras_client_get_aec_group_id(struct cras_client *client);

/*
 * Sets the flag to enable bluetooth wideband speech in server.
 */
int cras_client_set_bt_wbs_enabled(struct cras_client *client, bool enabled);

/* Set the context pointer for system state change callbacks.
 * Args:
 *    client - The client from cras_client_create.
 *    context - The context pointer passed to all callbacks.
 */
void cras_client_set_state_change_callback_context(struct cras_client *client,
						   void *context);

/* Output volume change callback.
 *
 * Args:
 *    context - Context pointer set with
 *              cras_client_set_state_change_callback_context().
 *    volume - The system output volume, ranging from 0 to 100.
 */
typedef void (*cras_client_output_volume_changed_callback)(void *context,
							   int32_t volume);

/* Output mute change callback.
 *
 * Args:
 *    context - Context pointer set with
 *              cras_client_set_state_change_callback_context().
 *    muted - Non-zero when the audio is muted, zero otherwise.
 *    user_muted - Non-zero when the audio has been muted by the
 *                 user, zero otherwise.
 *    mute_locked - Non-zero when the mute funcion is locked,
 *                  zero otherwise.
 */
typedef void (*cras_client_output_mute_changed_callback)(void *context,
							 int muted,
							 int user_muted,
							 int mute_locked);

/* Capture gain change callback.
 *
 * Args:
 *    context - Context pointer set with
 *              cras_client_set_state_change_callback_context().
 *    gain - The system capture gain, in centi-decibels.
 */
typedef void (*cras_client_capture_gain_changed_callback)(void *context,
							  int32_t gain);

/* Capture mute change callback.
 *
 * Args:
 *    context - Context pointer set with
 *              cras_client_set_state_change_callback_context().
 *    muted - Non-zero when the audio is muted, zero otherwise.
 *    mute_locked - Non-zero when the mute funcion is locked,
 *                  zero otherwise.
 */
typedef void (*cras_client_capture_mute_changed_callback)(void *context,
							  int muted,
							  int mute_locked);

/* Nodes change callback.
 *
 * Args:
 *    context - Context pointer set with
 *              cras_client_set_state_change_callback_context().
 */
typedef void (*cras_client_nodes_changed_callback)(void *context);

/* Active node change callback.
 *
 * Args:
 *    context - Context pointer set with
 *              cras_client_set_state_change_callback_context().
 *    direction - Indicates the direction of the selected node.
 *    node_id - The ID of the selected node. Special device ID values
 *              defined by CRAS_SPECIAL_DEVICE will be used when no other
 *              device or node is selected or between selections.
 */
typedef void (*cras_client_active_node_changed_callback)(
	void *context, enum CRAS_STREAM_DIRECTION direction,
	cras_node_id_t node_id);

/* Output node volume change callback.
 *
 * Args:
 *    context - Context pointer set with
 *              cras_client_set_state_change_callback_context().
 *    node_id - The ID of the output node.
 *    volume - The volume for this node with range 0 to 100.
 */
typedef void (*cras_client_output_node_volume_changed_callback)(
	void *context, cras_node_id_t node_id, int32_t volume);

/* Node left right swapped change callback.
 *
 * Args:
 *    context - Context pointer set with
 *              cras_client_set_state_change_callback_context().
 *    node_id - The ID of the node.
 *    swapped - Non-zero if the node is left-right swapped, zero otherwise.
 */
typedef void (*cras_client_node_left_right_swapped_changed_callback)(
	void *context, cras_node_id_t node_id, int swapped);

/* Input node gain change callback.
 * Args:
 *    context - Context pointer set with
 *              cras_client_set_state_change_callback_context().
 *    node_id - The ID of the input node.
 *    gain - The gain for this node in centi-decibels.
 */
typedef void (*cras_client_input_node_gain_changed_callback)(
	void *context, cras_node_id_t node_id, int32_t gain);

/* Number of active streams change callback.
 *
 * Args:
 *    context - Context pointer set with
 *              cras_client_set_state_change_callback_context().
 *    direction - Indicates the direction of the stream's node.
 *    num_active_streams - The number of active streams.
 */
typedef void (*cras_client_num_active_streams_changed_callback)(
	void *context, enum CRAS_STREAM_DIRECTION direction,
	uint32_t num_active_streams);

/* Set system state information callbacks.
 * NOTE: These callbacks are executed from the client control thread.
 * Each state change callback is given the context pointer set with
 * cras_client_set_state_change_callback_context(). The context pointer is
 * NULL by default.
 * Args:
 *    client - The client from cras_client_create.
 *    cb - The callback, or NULL to disable the call-back.
 * Returns:
 *    0 for success or negative errno error code on error.
 */
int cras_client_set_output_volume_changed_callback(
	struct cras_client *client,
	cras_client_output_volume_changed_callback cb);
int cras_client_set_output_mute_changed_callback(
	struct cras_client *client,
	cras_client_output_mute_changed_callback cb);
int cras_client_set_capture_gain_changed_callback(
	struct cras_client *client,
	cras_client_capture_gain_changed_callback cb);
int cras_client_set_capture_mute_changed_callback(
	struct cras_client *client,
	cras_client_capture_mute_changed_callback cb);
int cras_client_set_nodes_changed_callback(
	struct cras_client *client, cras_client_nodes_changed_callback cb);
int cras_client_set_active_node_changed_callback(
	struct cras_client *client,
	cras_client_active_node_changed_callback cb);
int cras_client_set_output_node_volume_changed_callback(
	struct cras_client *client,
	cras_client_output_node_volume_changed_callback cb);
int cras_client_set_node_left_right_swapped_changed_callback(
	struct cras_client *client,
	cras_client_node_left_right_swapped_changed_callback cb);
int cras_client_set_input_node_gain_changed_callback(
	struct cras_client *client,
	cras_client_input_node_gain_changed_callback cb);
int cras_client_set_num_active_streams_changed_callback(
	struct cras_client *client,
	cras_client_num_active_streams_changed_callback cb);
#ifdef __cplusplus
}
#endif

#endif /* CRAS_CLIENT_H_ */