text: /* 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_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);
  
  /* Callback for handling server error. DEPRECATED
   *
   * Deprecated by cras_server_connection_status_cb_t: use that instead.
   * This is equivalent to CRAS_CONN_STATUS_FAILED.
   *
   * This callback is executed rarely: only when the connection to the server has
   * already been interrupted and could not be re-established due to resource
   * allocation failure (memory or file-descriptors). The caller may attempt
   * to reestablish communication once those resources are available with
   * cras_client_connect_async(), or (blocking) cras_client_connect().
   *
   * Args:
   *    client - The client created with cras_client_create().
   *    user_arg - The argument defined in cras_client_set_server_errro_cb().
   */
  typedef void (*cras_server_error_cb_t)(struct cras_client *client,
  				       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);
  
  /*
   * 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);
  
  /* 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 error callback. DEPRECATED
   *
   * See cras_server_error_cb_t for more information about this callback.
   *
   * Args:
   *    client - The client from cras_client_create.
   *    err_cb - The callback function to register.
   *    user_arg - Pointer that will be passed to the callback.
   */
  void cras_client_set_server_error_cb(struct cras_client *client,
  				     cras_server_error_cb_t err_cb,
  				     void *user_arg);
  
  /* 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 *));
  
  /*
   * 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);
  
  /* Setup stream configuration parameters.
   * 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 for streams that do simultaneous input/output.
   *    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 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 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);
  
  /* 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_ */
  