/* Copyright (c) 2013 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.
 */

#ifndef _CRAS_ALERT_H
#define _CRAS_ALERT_H

#ifdef __cplusplus
extern "C" {
#endif

/* The alert facility provides a way to signal the clients when a system state
 * changes.
 *
 * First the clients registers callbacks to an alert. Each time the system state
 * changes, we mark the associated alert as "pending". At the end of the event
 * loop, we invoke the callbacks for the pending alerts.
 *
 * We do this delayed callback to collapses multiple callbacks into one (for
 * example, if there are multiple nodes added at the same time, we will only
 * fire the "nodes changed" signal once).
 *
 * There is an optional "prepare" function which can be provided when creating
 * an alert. It is called before we invoke the callbacks. This gives the owner
 * of each alert a chance to update the system to a consistent state before
 * signalling the clients.
 *
 * The alert functions should only be used from the main thread.
 */

struct cras_alert;

/* Callback functions to be notified when settings change. arg is a user
 * provided argument that will be passed back, data is extra info about the
 * signal if available.
 */
typedef void (*cras_alert_cb)(void *arg, void *data);
typedef void (*cras_alert_prepare)(struct cras_alert *alert);

/* Flags for alerts. */
enum CRAS_ALERT_FLAGS {
	/* By default, alerts will only keep the last copy of the data
	 * specified in cras_alert_pending_data as an optimization - then
	 * the callback is executed once with the latest value, rather than
	 * for every value. In some cases, it is important to send the data
	 * with every change. Use this flag to enable that behavior. */
	CRAS_ALERT_FLAG_KEEP_ALL_DATA = 1 << 0,
};

/* Creates an alert.
 * Args:
 *    prepare - A function which will be called before calling the callbacks.
 *        The prepare function should update the system state in the shared
 *        memory to be consistent. It can be NULL if not needed.
 *    flags - 0 for defauts, or ORed values from enum CRAS_ALERT_FLAGS.
 * Returns:
 *    A pointer to the alert, NULL if out of memory.
 */
struct cras_alert *cras_alert_create(cras_alert_prepare prepare,
				     unsigned int flags);

/* Adds a callback to the alert.
 * Args:
 *    alert - A pointer to the alert.
 *    cb - The callback.
 *    arg - will be passed to the callback when it is called.
 * Returns:
 *    0 on success or negative error code on failure.
 */
int cras_alert_add_callback(struct cras_alert *alert, cras_alert_cb cb,
			    void *arg);

/* Removes a callback from the alert. It removes the callback if cb and arg
 * match a previously registered entry.
 * Args:
 *    alert - A pointer to the alert.
 *    cb - The callback.
 *    arg - will be passed to the callback when it is called.
 * Returns:
 *    0 on success or negative error code on failure.
 */
int cras_alert_rm_callback(struct cras_alert *alert, cras_alert_cb cb,
			   void *arg);

/* Marks an alert as pending. We don't call the callbacks immediately when an
 * alert becomes pending, but will do that when
 * cras_alert_process_all_pending_alerts() is called.
 * Args:
 *    alert - A pointer to the alert.
 */
void cras_alert_pending(struct cras_alert *alert);

/* Marks an alert as pending. We don't call the callbacks immediately when an
 * alert becomes pending, but will do that when
 * cras_alert_process_all_pending_alerts() is called.
 * By default only the last data value supplied here is provided as an
 * argument to the callback. To have the callback executed with every
 * data value, call cras_alert_keep_all_data() (see above).
 * Args:
 *    alert - A pointer to the alert.
 *    data - A pointer to data that is copied and passed to the callback.
 *    data_size - Size of the data.
 */
void cras_alert_pending_data(struct cras_alert *alert,
			     void *data, size_t data_size);

/* Processes all alerts that are pending.
 *
 * For all pending alerts, its prepare function will be called, then the
 * callbacks will be called. If any alert becomes pending during the callbacks,
 * the process will start again until no alert is pending.
 */
void cras_alert_process_all_pending_alerts();

/* Frees the resources used by an alert.
 * Args:
 *    alert - A pointer to the alert.
 */
void cras_alert_destroy(struct cras_alert *alert);

/* Frees the resources used by all alerts in the system. */
void cras_alert_destroy_all();

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

#endif /* _CRAS_ALERT_H */