1 /* Copyright (c) 2013 The Chromium OS Authors. All rights reserved. 2 * Use of this source code is governed by a BSD-style license that can be 3 * found in the LICENSE file. 4 */ 5 6 #ifndef _CRAS_ALERT_H 7 #define _CRAS_ALERT_H 8 9 #ifdef __cplusplus 10 extern "C" { 11 #endif 12 13 /* The alert facility provides a way to signal the clients when a system state 14 * changes. 15 * 16 * First the clients registers callbacks to an alert. Each time the system state 17 * changes, we mark the associated alert as "pending". At the end of the event 18 * loop, we invoke the callbacks for the pending alerts. 19 * 20 * We do this delayed callback to collapses multiple callbacks into one (for 21 * example, if there are multiple nodes added at the same time, we will only 22 * fire the "nodes changed" signal once). 23 * 24 * There is an optional "prepare" function which can be provided when creating 25 * an alert. It is called before we invoke the callbacks. This gives the owner 26 * of each alert a chance to update the system to a consistent state before 27 * signalling the clients. 28 * 29 * The alert functions should only be used from the main thread. 30 */ 31 32 struct cras_alert; 33 34 /* Callback functions to be notified when settings change. arg is a user 35 * provided argument that will be passed back, data is extra info about the 36 * signal if available. 37 */ 38 typedef void (*cras_alert_cb)(void *arg, void *data); 39 typedef void (*cras_alert_prepare)(struct cras_alert *alert); 40 41 /* Flags for alerts. */ 42 enum CRAS_ALERT_FLAGS { 43 /* By default, alerts will only keep the last copy of the data 44 * specified in cras_alert_pending_data as an optimization - then 45 * the callback is executed once with the latest value, rather than 46 * for every value. In some cases, it is important to send the data 47 * with every change. Use this flag to enable that behavior. */ 48 CRAS_ALERT_FLAG_KEEP_ALL_DATA = 1 << 0, 49 }; 50 51 /* Creates an alert. 52 * Args: 53 * prepare - A function which will be called before calling the callbacks. 54 * The prepare function should update the system state in the shared 55 * memory to be consistent. It can be NULL if not needed. 56 * flags - 0 for defauts, or ORed values from enum CRAS_ALERT_FLAGS. 57 * Returns: 58 * A pointer to the alert, NULL if out of memory. 59 */ 60 struct cras_alert *cras_alert_create(cras_alert_prepare prepare, 61 unsigned int flags); 62 63 /* Adds a callback to the alert. 64 * Args: 65 * alert - A pointer to the alert. 66 * cb - The callback. 67 * arg - will be passed to the callback when it is called. 68 * Returns: 69 * 0 on success or negative error code on failure. 70 */ 71 int cras_alert_add_callback(struct cras_alert *alert, cras_alert_cb cb, 72 void *arg); 73 74 /* Removes a callback from the alert. It removes the callback if cb and arg 75 * match a previously registered entry. 76 * Args: 77 * alert - A pointer to the alert. 78 * cb - The callback. 79 * arg - will be passed to the callback when it is called. 80 * Returns: 81 * 0 on success or negative error code on failure. 82 */ 83 int cras_alert_rm_callback(struct cras_alert *alert, cras_alert_cb cb, 84 void *arg); 85 86 /* Marks an alert as pending. We don't call the callbacks immediately when an 87 * alert becomes pending, but will do that when 88 * cras_alert_process_all_pending_alerts() is called. 89 * Args: 90 * alert - A pointer to the alert. 91 */ 92 void cras_alert_pending(struct cras_alert *alert); 93 94 /* Marks an alert as pending. We don't call the callbacks immediately when an 95 * alert becomes pending, but will do that when 96 * cras_alert_process_all_pending_alerts() is called. 97 * By default only the last data value supplied here is provided as an 98 * argument to the callback. To have the callback executed with every 99 * data value, call cras_alert_keep_all_data() (see above). 100 * Args: 101 * alert - A pointer to the alert. 102 * data - A pointer to data that is copied and passed to the callback. 103 * data_size - Size of the data. 104 */ 105 void cras_alert_pending_data(struct cras_alert *alert, void *data, 106 size_t data_size); 107 108 /* Processes all alerts that are pending. 109 * 110 * For all pending alerts, its prepare function will be called, then the 111 * callbacks will be called. If any alert becomes pending during the callbacks, 112 * the process will start again until no alert is pending. 113 */ 114 void cras_alert_process_all_pending_alerts(); 115 116 /* Frees the resources used by an alert. 117 * Args: 118 * alert - A pointer to the alert. 119 */ 120 void cras_alert_destroy(struct cras_alert *alert); 121 122 /* Frees the resources used by all alerts in the system. */ 123 void cras_alert_destroy_all(); 124 125 #ifdef __cplusplus 126 } /* extern "C" */ 127 #endif 128 129 #endif /* _CRAS_ALERT_H */ 130