Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/include/alsa/use-case.h @ 69:33d812a61356

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
planemo upload commit 2e9511a184a1ca667c7be0c6321a36dc4e3d116d
author jpayne
date Tue, 18 Mar 2025 17:55:14 -0400
parents
children
rev   line source
jpayne@69 1 /**
jpayne@69 2 * \file include/use-case.h
jpayne@69 3 * \brief use case interface for the ALSA driver
jpayne@69 4 * \author Liam Girdwood <lrg@slimlogic.co.uk>
jpayne@69 5 * \author Stefan Schmidt <stefan@slimlogic.co.uk>
jpayne@69 6 * \author Jaroslav Kysela <perex@perex.cz>
jpayne@69 7 * \author Justin Xu <justinx@slimlogic.co.uk>
jpayne@69 8 * \date 2008-2010
jpayne@69 9 */
jpayne@69 10 /*
jpayne@69 11 *
jpayne@69 12 * This library is free software; you can redistribute it and/or modify
jpayne@69 13 * it under the terms of the GNU Lesser General Public License as
jpayne@69 14 * published by the Free Software Foundation; either version 2.1 of
jpayne@69 15 * the License, or (at your option) any later version.
jpayne@69 16 *
jpayne@69 17 * This program is distributed in the hope that it will be useful,
jpayne@69 18 * but WITHOUT ANY WARRANTY; without even the implied warranty of
jpayne@69 19 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
jpayne@69 20 * GNU Lesser General Public License for more details.
jpayne@69 21 *
jpayne@69 22 * You should have received a copy of the GNU Lesser General Public
jpayne@69 23 * License along with this library; if not, write to the Free Software
jpayne@69 24 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
jpayne@69 25 *
jpayne@69 26 * Copyright (C) 2008-2010 SlimLogic Ltd
jpayne@69 27 * Copyright (C) 2010 Wolfson Microelectronics PLC
jpayne@69 28 * Copyright (C) 2010 Texas Instruments Inc.
jpayne@69 29 *
jpayne@69 30 * Support for the verb/device/modifier core logic and API,
jpayne@69 31 * command line tool and file parser was kindly sponsored by
jpayne@69 32 * Texas Instruments Inc.
jpayne@69 33 * Support for multiple active modifiers and devices,
jpayne@69 34 * transition sequences, multiple client access and user defined use
jpayne@69 35 * cases was kindly sponsored by Wolfson Microelectronics PLC.
jpayne@69 36 */
jpayne@69 37
jpayne@69 38 #ifndef __ALSA_USE_CASE_H
jpayne@69 39 #define __ALSA_USE_CASE_H
jpayne@69 40
jpayne@69 41 #ifdef __cplusplus
jpayne@69 42 extern "C" {
jpayne@69 43 #endif
jpayne@69 44
jpayne@69 45 #include <alsa/asoundlib.h>
jpayne@69 46
jpayne@69 47 /**
jpayne@69 48 * \defgroup ucm Use Case Interface
jpayne@69 49 * The ALSA Use Case manager interface.
jpayne@69 50 * See \ref Usecase page for more details.
jpayne@69 51 * \{
jpayne@69 52 */
jpayne@69 53
jpayne@69 54 /*! \page Usecase ALSA Use Case Interface
jpayne@69 55 *
jpayne@69 56 * The use case manager works by configuring the sound card ALSA kcontrols to
jpayne@69 57 * change the hardware digital and analog audio routing to match the requested
jpayne@69 58 * device use case. The use case manager kcontrol configurations are stored in
jpayne@69 59 * easy to modify text files.
jpayne@69 60 *
jpayne@69 61 * An audio use case can be defined by a verb and device parameter. The verb
jpayne@69 62 * describes the use case action i.e. a phone call, listening to music, recording
jpayne@69 63 * a conversation etc. The device describes the physical audio capture and playback
jpayne@69 64 * hardware i.e. headphones, phone handset, bluetooth headset, etc.
jpayne@69 65 *
jpayne@69 66 * It's intended clients will mostly only need to set the use case verb and
jpayne@69 67 * device for each system use case change (as the verb and device parameters
jpayne@69 68 * cover most audio use cases).
jpayne@69 69 *
jpayne@69 70 * However there are times when a use case has to be modified at runtime. e.g.
jpayne@69 71 *
jpayne@69 72 * + Incoming phone call when the device is playing music
jpayne@69 73 * + Recording sections of a phone call
jpayne@69 74 * + Playing tones during a call.
jpayne@69 75 *
jpayne@69 76 * In order to allow asynchronous runtime use case adaptations, we have a third
jpayne@69 77 * optional modifier parameter that can be used to further configure
jpayne@69 78 * the use case during live audio runtime.
jpayne@69 79 *
jpayne@69 80 * This interface allows clients to :-
jpayne@69 81 *
jpayne@69 82 * + Query the supported use case verbs, devices and modifiers for the machine.
jpayne@69 83 * + Set and Get use case verbs, devices and modifiers for the machine.
jpayne@69 84 * + Get the ALSA PCM playback and capture device PCMs for use case verb,
jpayne@69 85 * use case device and modifier.
jpayne@69 86 * + Get the TQ parameter for each use case verb, use case device and
jpayne@69 87 * modifier.
jpayne@69 88 * + Get the ALSA master playback and capture volume/switch kcontrols
jpayne@69 89 * or mixer elements for each use case.
jpayne@69 90 */
jpayne@69 91
jpayne@69 92
jpayne@69 93 /*
jpayne@69 94 * Use Case Verb.
jpayne@69 95 *
jpayne@69 96 * The use case verb is the main device audio action. e.g. the "HiFi" use
jpayne@69 97 * case verb will configure the audio hardware for HiFi Music playback
jpayne@69 98 * and capture.
jpayne@69 99 */
jpayne@69 100 #define SND_USE_CASE_VERB_INACTIVE "Inactive" /**< Inactive Verb */
jpayne@69 101 #define SND_USE_CASE_VERB_HIFI "HiFi" /**< HiFi Verb */
jpayne@69 102 #define SND_USE_CASE_VERB_HIFI_LOW_POWER "HiFi Low Power" /**< HiFi Low Power Verb */
jpayne@69 103 #define SND_USE_CASE_VERB_VOICE "Voice" /**< Voice Verb */
jpayne@69 104 #define SND_USE_CASE_VERB_VOICE_LOW_POWER "Voice Low Power" /**< Voice Low Power Verb */
jpayne@69 105 #define SND_USE_CASE_VERB_VOICECALL "Voice Call" /**< Voice Call Verb */
jpayne@69 106 #define SND_USE_CASE_VERB_IP_VOICECALL "Voice Call IP" /**< Voice Call IP Verb */
jpayne@69 107 #define SND_USE_CASE_VERB_ANALOG_RADIO "FM Analog Radio" /**< FM Analog Radio Verb */
jpayne@69 108 #define SND_USE_CASE_VERB_DIGITAL_RADIO "FM Digital Radio" /**< FM Digital Radio Verb */
jpayne@69 109 /* add new verbs to end of list */
jpayne@69 110
jpayne@69 111
jpayne@69 112 /*
jpayne@69 113 * Use Case Device.
jpayne@69 114 *
jpayne@69 115 * Physical system devices the render and capture audio. Devices can be OR'ed
jpayne@69 116 * together to support audio on simultaneous devices.
jpayne@69 117 *
jpayne@69 118 * If multiple devices with the same name exists, the number suffixes should
jpayne@69 119 * be added to these names like HDMI1,HDMI2,HDMI3 etc. No number gaps are
jpayne@69 120 * allowed. The names with numbers must be continuous. It is allowed to put
jpayne@69 121 * a whitespace between name and index (like 'Line 1') for the better
jpayne@69 122 * readability. The device names 'Line 1' and 'Line1' are equal for
jpayne@69 123 * this purpose.
jpayne@69 124 *
jpayne@69 125 * If EnableSequence/DisableSequence controls independent paths in the hardware
jpayne@69 126 * it is also recommended to split playback and capture UCM devices and use
jpayne@69 127 * the number suffixes. Example use case: Use the integrated microphone
jpayne@69 128 * in the laptop instead the microphone in headphones.
jpayne@69 129 *
jpayne@69 130 * The preference of the devices is determined by the priority value.
jpayne@69 131 */
jpayne@69 132 #define SND_USE_CASE_DEV_NONE "None" /**< None Device */
jpayne@69 133 #define SND_USE_CASE_DEV_SPEAKER "Speaker" /**< Speaker Device */
jpayne@69 134 #define SND_USE_CASE_DEV_LINE "Line" /**< Line Device */
jpayne@69 135 #define SND_USE_CASE_DEV_MIC "Mic" /**< Microphone Device */
jpayne@69 136 #define SND_USE_CASE_DEV_HEADPHONES "Headphones" /**< Headphones Device */
jpayne@69 137 #define SND_USE_CASE_DEV_HEADSET "Headset" /**< Headset Device */
jpayne@69 138 #define SND_USE_CASE_DEV_HANDSET "Handset" /**< Handset Device */
jpayne@69 139 #define SND_USE_CASE_DEV_BLUETOOTH "Bluetooth" /**< Bluetooth Device */
jpayne@69 140 #define SND_USE_CASE_DEV_EARPIECE "Earpiece" /**< Earpiece Device */
jpayne@69 141 #define SND_USE_CASE_DEV_SPDIF "SPDIF" /**< SPDIF Device */
jpayne@69 142 #define SND_USE_CASE_DEV_HDMI "HDMI" /**< HDMI Device */
jpayne@69 143 #define SND_USE_CASE_DEV_USB "USB" /**< USB Device (multifunctional) */
jpayne@69 144 /* add new devices to end of list */
jpayne@69 145
jpayne@69 146
jpayne@69 147 /*
jpayne@69 148 * Use Case Modifiers.
jpayne@69 149 *
jpayne@69 150 * The use case modifier allows runtime configuration changes to deal with
jpayne@69 151 * asynchronous events.
jpayne@69 152 *
jpayne@69 153 * If multiple modifiers with the same name exists, the number suffixes should
jpayne@69 154 * be added to these names like 'Echo Reference 1','Echo Reference 2' etc.
jpayne@69 155 * No number gaps are allowed. The names with numbers must be continuous.
jpayne@69 156 * It is allowed to put a whitespace between name and index for the better
jpayne@69 157 * readability. The modifier names 'Something 1' and 'Something1' are equal
jpayne@69 158 * for this purpose.
jpayne@69 159 *
jpayne@69 160 * e.g. to record a voice call :-
jpayne@69 161 * 1. Set verb to SND_USE_CASE_VERB_VOICECALL (for voice call)
jpayne@69 162 * 2. Set modifier SND_USE_CASE_MOD_CAPTURE_VOICE when capture required.
jpayne@69 163 * 3. Call snd_use_case_get("CapturePCM") to get ALSA source PCM name
jpayne@69 164 * with captured voice pcm data.
jpayne@69 165 *
jpayne@69 166 * e.g. to play a ring tone when listenin to MP3 Music :-
jpayne@69 167 * 1. Set verb to SND_USE_CASE_VERB_HIFI (for MP3 playback)
jpayne@69 168 * 2. Set modifier to SND_USE_CASE_MOD_PLAY_TONE when incoming call happens.
jpayne@69 169 * 3. Call snd_use_case_get("PlaybackPCM") to get ALSA PCM sink name for
jpayne@69 170 * ringtone pcm data.
jpayne@69 171 */
jpayne@69 172 #define SND_USE_CASE_MOD_CAPTURE_VOICE "Capture Voice" /**< Capture Voice Modifier */
jpayne@69 173 #define SND_USE_CASE_MOD_CAPTURE_MUSIC "Capture Music" /**< Capture Music Modifier */
jpayne@69 174 #define SND_USE_CASE_MOD_PLAY_MUSIC "Play Music" /**< Play Music Modifier */
jpayne@69 175 #define SND_USE_CASE_MOD_PLAY_VOICE "Play Voice" /**< Play Voice Modifier */
jpayne@69 176 #define SND_USE_CASE_MOD_PLAY_TONE "Play Tone" /**< Play Tone Modifier */
jpayne@69 177 #define SND_USE_CASE_MOD_ECHO_REF "Echo Reference" /**< Echo Reference Modifier */
jpayne@69 178 /* add new modifiers to end of list */
jpayne@69 179
jpayne@69 180
jpayne@69 181 /**
jpayne@69 182 * TQ - Tone Quality
jpayne@69 183 *
jpayne@69 184 * The interface allows clients to determine the audio TQ required for each
jpayne@69 185 * use case verb and modifier. It's intended as an optional hint to the
jpayne@69 186 * audio driver in order to lower power consumption.
jpayne@69 187 *
jpayne@69 188 */
jpayne@69 189 #define SND_USE_CASE_TQ_MUSIC "Music" /**< Music Tone Quality */
jpayne@69 190 #define SND_USE_CASE_TQ_VOICE "Voice" /**< Voice Tone Quality */
jpayne@69 191 #define SND_USE_CASE_TQ_TONES "Tones" /**< Tones Tone Quality */
jpayne@69 192
jpayne@69 193 /** use case container */
jpayne@69 194 typedef struct snd_use_case_mgr snd_use_case_mgr_t;
jpayne@69 195
jpayne@69 196 /**
jpayne@69 197 * \brief Create an identifier
jpayne@69 198 * \param fmt Format (sprintf like)
jpayne@69 199 * \param ... Optional arguments for sprintf like format
jpayne@69 200 * \return Allocated string identifier or NULL on error
jpayne@69 201 */
jpayne@69 202 char *snd_use_case_identifier(const char *fmt, ...);
jpayne@69 203
jpayne@69 204 /**
jpayne@69 205 * \brief Free a string list
jpayne@69 206 * \param list The string list to free
jpayne@69 207 * \param items Count of strings
jpayne@69 208 * \return Zero if success, otherwise a negative error code
jpayne@69 209 */
jpayne@69 210 int snd_use_case_free_list(const char *list[], int items);
jpayne@69 211
jpayne@69 212 /**
jpayne@69 213 * \brief Obtain a list of entries
jpayne@69 214 * \param uc_mgr Use case manager (may be NULL - card list)
jpayne@69 215 * \param identifier (may be NULL - card list)
jpayne@69 216 * \param list Returned allocated list
jpayne@69 217 * \return Number of list entries if success, otherwise a negative error code
jpayne@69 218 *
jpayne@69 219 * Defined identifiers:
jpayne@69 220 * - NULL - get card list
jpayne@69 221 * (in pair cardname+comment)
jpayne@69 222 * - _verbs - get verb list
jpayne@69 223 * (in pair verb+comment)
jpayne@69 224 * - _devices[/{verb}] - get list of supported devices
jpayne@69 225 * (in pair device+comment)
jpayne@69 226 * - _modifiers[/{verb}] - get list of supported modifiers
jpayne@69 227 * (in pair modifier+comment)
jpayne@69 228 * - TQ[/{verb}] - get list of TQ identifiers
jpayne@69 229 * - _enadevs - get list of enabled devices
jpayne@69 230 * - _enamods - get list of enabled modifiers
jpayne@69 231 *
jpayne@69 232 * - _identifiers/{modifier}|{device}[/{verb}] - list of value identifiers
jpayne@69 233 * - _supporteddevs/{modifier}|{device}[/{verb}] - list of supported devices
jpayne@69 234 * - _conflictingdevs/{modifier}|{device}[/{verb}] - list of conflicting devices
jpayne@69 235 *
jpayne@69 236 * Note that at most one of the supported/conflicting devs lists has
jpayne@69 237 * any entries, and when neither is present, all devices are supported.
jpayne@69 238 *
jpayne@69 239 */
jpayne@69 240 int snd_use_case_get_list(snd_use_case_mgr_t *uc_mgr,
jpayne@69 241 const char *identifier,
jpayne@69 242 const char **list[]);
jpayne@69 243
jpayne@69 244
jpayne@69 245 /**
jpayne@69 246 * \brief Get current - string
jpayne@69 247 * \param uc_mgr Use case manager
jpayne@69 248 * \param identifier
jpayne@69 249 * \param value Value pointer
jpayne@69 250 * \return Zero if success, otherwise a negative error code
jpayne@69 251 *
jpayne@69 252 * Note: The returned string is dynamically allocated, use free() to
jpayne@69 253 * deallocate this string. (Yes, the value parameter shouldn't be marked as
jpayne@69 254 * "const", but it's too late to fix it, sorry about that.)
jpayne@69 255 *
jpayne@69 256 * Known identifiers:
jpayne@69 257 * - NULL - return current card
jpayne@69 258 * - _verb - return current verb
jpayne@69 259 * - _file - return configuration file loaded for current card
jpayne@69 260 *
jpayne@69 261 * - [=]{NAME}[/[{modifier}|{/device}][/{verb}]]
jpayne@69 262 * - value identifier {NAME}
jpayne@69 263 * - Search starts at given modifier or device if any,
jpayne@69 264 * else at a verb
jpayne@69 265 * - Search starts at given verb if any,
jpayne@69 266 * else current verb
jpayne@69 267 * - Searches modifier/device, then verb, then defaults
jpayne@69 268 * - Specify a leading "=" to search only the exact
jpayne@69 269 * device/modifier/verb specified, and not search
jpayne@69 270 * through each object in turn.
jpayne@69 271 * - Examples:
jpayne@69 272 * - "PlaybackPCM/Play Music"
jpayne@69 273 * - "CapturePCM/SPDIF"
jpayne@69 274 * - From ValueDefaults only:
jpayne@69 275 * "=Variable"
jpayne@69 276 * - From current active verb:
jpayne@69 277 * "=Variable//"
jpayne@69 278 * - From verb "Verb":
jpayne@69 279 * "=Variable//Verb"
jpayne@69 280 * - From "Modifier" in current active verb:
jpayne@69 281 * "=Variable/Modifier/"
jpayne@69 282 * - From "Modifier" in "Verb":
jpayne@69 283 * "=Variable/Modifier/Verb"
jpayne@69 284 *
jpayne@69 285 * Recommended names for values:
jpayne@69 286 * - Linked
jpayne@69 287 * - value "True" or "1" (case insensitive)
jpayne@69 288 * - this is a linked UCM card
jpayne@69 289 * - don't use this UCM card, because the other UCM card refers devices
jpayne@69 290 * - valid only in the ValueDefaults section (query '=Linked')
jpayne@69 291 * - TQ
jpayne@69 292 * - Tone Quality
jpayne@69 293 * - Priority
jpayne@69 294 * - priority value (1-10000), higher value means higher priority
jpayne@69 295 * - valid only for verbs
jpayne@69 296 * - for devices - PlaybackPriority and CapturePriority
jpayne@69 297 * - PlaybackPCM
jpayne@69 298 * - full PCM playback device name
jpayne@69 299 * - PlaybackPCMIsDummy
jpayne@69 300 * - Valid values: "yes" and "no". If set to "yes", the PCM named by the
jpayne@69 301 * PlaybackPCM value is a dummy device, meaning that opening it enables
jpayne@69 302 * an audio path in the hardware, but writing to the PCM device has no
jpayne@69 303 * effect.
jpayne@69 304 * - CapturePCM
jpayne@69 305 * - full PCM capture device name
jpayne@69 306 * - CapturePCMIsDummy
jpayne@69 307 * - Valid values: "yes" and "no". If set to "yes", the PCM named by the
jpayne@69 308 * CapturePCM value is a dummy device, meaning that opening it enables
jpayne@69 309 * an audio path in the hardware, but reading from the PCM device has no
jpayne@69 310 * effect.
jpayne@69 311 * - PlaybackRate
jpayne@69 312 * - playback device sample rate
jpayne@69 313 * - PlaybackChannels
jpayne@69 314 * - playback device channel count
jpayne@69 315 * - PlaybackCTL
jpayne@69 316 * - playback control device name
jpayne@69 317 * - PlaybackVolume
jpayne@69 318 * - playback control volume identifier string
jpayne@69 319 * - can be parsed using snd_use_case_parse_ctl_elem_id()
jpayne@69 320 * - PlaybackSwitch
jpayne@69 321 * - playback control switch identifier string
jpayne@69 322 * - can be parsed using snd_use_case_parse_ctl_elem_id()
jpayne@69 323 * - PlaybackPriority
jpayne@69 324 * - priority value (1-10000), higher value means higher priority
jpayne@69 325 * - CaptureRate
jpayne@69 326 * - capture device sample rate
jpayne@69 327 * - CaptureChannels
jpayne@69 328 * - capture device channel count
jpayne@69 329 * - CaptureCTL
jpayne@69 330 * - capture control device name
jpayne@69 331 * - CaptureVolume
jpayne@69 332 * - capture control volume identifier string
jpayne@69 333 * - can be parsed using snd_use_case_parse_ctl_elem_id()
jpayne@69 334 * - CaptureSwitch
jpayne@69 335 * - capture control switch identifier string
jpayne@69 336 * - can be parsed using snd_use_case_parse_ctl_elem_id()
jpayne@69 337 * - CapturePriority
jpayne@69 338 * - priority value (1-10000), higher value means higher priority
jpayne@69 339 * - PlaybackMixer
jpayne@69 340 * - name of playback mixer
jpayne@69 341 * - PlaybackMixerElem
jpayne@69 342 * - mixer element playback identifier
jpayne@69 343 * - can be parsed using snd_use_case_parse_selem_id()
jpayne@69 344 * - PlaybackMasterElem
jpayne@69 345 * - mixer element playback identifier for the master control
jpayne@69 346 * - can be parsed using snd_use_case_parse_selem_id()
jpayne@69 347 * - PlaybackMasterType
jpayne@69 348 * - type of the master volume control
jpayne@69 349 * - Valid values: "soft" (software attenuation)
jpayne@69 350 * - CaptureMixer
jpayne@69 351 * - name of capture mixer
jpayne@69 352 * - CaptureMixerElem
jpayne@69 353 * - mixer element capture identifier
jpayne@69 354 * - can be parsed using snd_use_case_parse_selem_id()
jpayne@69 355 * - CaptureMasterElem
jpayne@69 356 * - mixer element playback identifier for the master control
jpayne@69 357 * - can be parsed using snd_use_case_parse_selem_id()
jpayne@69 358 * - CaptureMasterType
jpayne@69 359 * - type of the master volume control
jpayne@69 360 * - Valid values: "soft" (software attenuation)
jpayne@69 361 * - EDIDFile
jpayne@69 362 * - Path to EDID file for HDMI devices
jpayne@69 363 * - JackCTL
jpayne@69 364 * - jack control device name
jpayne@69 365 * - JackControl
jpayne@69 366 * - jack control identificator
jpayne@69 367 * - can be parsed using snd_use_case_parse_ctl_elem_id()
jpayne@69 368 * - UCM configuration files should contain both JackControl and JackDev
jpayne@69 369 * when possible, because applications are likely to support only one
jpayne@69 370 * or the other
jpayne@69 371 * - JackDev
jpayne@69 372 * - the input device id of the jack (if the full input device path is
jpayne@69 373 * /dev/input/by-id/foo, the JackDev value should be "foo")
jpayne@69 374 * - UCM configuration files should contain both JackControl and JackDev
jpayne@69 375 * when possible, because applications are likely to support only one
jpayne@69 376 * or the other
jpayne@69 377 * - JackHWMute
jpayne@69 378 * If this value is set, it indicates that when the jack is plugged
jpayne@69 379 * in, the hardware automatically mutes some other device(s). The
jpayne@69 380 * value is a space-separated list of device names. If the device
jpayne@69 381 * name contains space, it must be enclosed to ' or ", e.g.:
jpayne@69 382 * JackHWMute "'Dock Headphone' Headphone"
jpayne@69 383 * Note that JackHWMute should be used only when the hardware enforces
jpayne@69 384 * the automatic muting. If the hardware doesn't enforce any muting, it
jpayne@69 385 * may still be tempting to set JackHWMute to trick upper software layers
jpayne@69 386 * to e.g. automatically mute speakers when headphones are plugged in,
jpayne@69 387 * but that's application policy configuration that doesn't belong
jpayne@69 388 * to UCM configuration files.
jpayne@69 389 * - MinBufferLevel
jpayne@69 390 * - This is used on platform where reported buffer level is not accurate.
jpayne@69 391 * E.g. "512", which holds 512 samples in device buffer. Note: this will
jpayne@69 392 * increase latency.
jpayne@69 393 */
jpayne@69 394 int snd_use_case_get(snd_use_case_mgr_t *uc_mgr,
jpayne@69 395 const char *identifier,
jpayne@69 396 const char **value);
jpayne@69 397
jpayne@69 398 /**
jpayne@69 399 * \brief Get current - integer
jpayne@69 400 * \param uc_mgr Use case manager
jpayne@69 401 * \param identifier
jpayne@69 402 * \param value result
jpayne@69 403 * \return Zero if success, otherwise a negative error code
jpayne@69 404 *
jpayne@69 405 * Known identifiers:
jpayne@69 406 * - _devstatus/{device} - return status for given device
jpayne@69 407 * - _modstatus/{modifier} - return status for given modifier
jpayne@69 408 */
jpayne@69 409 int snd_use_case_geti(snd_use_case_mgr_t *uc_mgr,
jpayne@69 410 const char *identifier,
jpayne@69 411 long *value);
jpayne@69 412
jpayne@69 413 /**
jpayne@69 414 * \brief Set new
jpayne@69 415 * \param uc_mgr Use case manager
jpayne@69 416 * \param identifier
jpayne@69 417 * \param value Value
jpayne@69 418 * \return Zero if success, otherwise a negative error code
jpayne@69 419 *
jpayne@69 420 * Known identifiers:
jpayne@69 421 * - _boot - execute the boot sequence (value = NULL)
jpayne@69 422 * - _defaults - execute the 'defaults' sequence (value = NULL)
jpayne@69 423 * - _verb - set current verb = value
jpayne@69 424 * - _enadev - enable given device = value
jpayne@69 425 * - _disdev - disable given device = value
jpayne@69 426 * - _swdev/{old_device} - new_device = value
jpayne@69 427 * - disable old_device and then enable new_device
jpayne@69 428 * - if old_device is not enabled just return
jpayne@69 429 * - check transmit sequence firstly
jpayne@69 430 * - _enamod - enable given modifier = value
jpayne@69 431 * - _dismod - disable given modifier = value
jpayne@69 432 * - _swmod/{old_modifier} - new_modifier = value
jpayne@69 433 * - disable old_modifier and then enable new_modifier
jpayne@69 434 * - if old_modifier is not enabled just return
jpayne@69 435 * - check transmit sequence firstly
jpayne@69 436 */
jpayne@69 437 int snd_use_case_set(snd_use_case_mgr_t *uc_mgr,
jpayne@69 438 const char *identifier,
jpayne@69 439 const char *value);
jpayne@69 440
jpayne@69 441 /**
jpayne@69 442 * \brief Open and initialise use case core for sound card
jpayne@69 443 * \param uc_mgr Returned use case manager pointer
jpayne@69 444 * \param card_name Sound card name.
jpayne@69 445 * \return zero if success, otherwise a negative error code
jpayne@69 446 *
jpayne@69 447 * By default only first card is used when the driver card
jpayne@69 448 * name or long name is passed in the card_name argument.
jpayne@69 449 *
jpayne@69 450 * The "strict:" prefix in the card_name defines that
jpayne@69 451 * there is no driver name / long name matching. The straight
jpayne@69 452 * configuration is used.
jpayne@69 453 *
jpayne@69 454 * The "hw:" prefix in the card_name will load the configuration
jpayne@69 455 * for the ALSA card specified by the card index (value) or
jpayne@69 456 * the card string identificator.
jpayne@69 457 *
jpayne@69 458 * The sound card might be also composed from several physical
jpayne@69 459 * sound cards (for the default and strict card_name).
jpayne@69 460 * The application cannot expect that the device names will refer
jpayne@69 461 * only one ALSA sound card in this case.
jpayne@69 462 */
jpayne@69 463 int snd_use_case_mgr_open(snd_use_case_mgr_t **uc_mgr,
jpayne@69 464 const char *card_name);
jpayne@69 465
jpayne@69 466
jpayne@69 467 /**
jpayne@69 468 * \brief Reload and re-parse use case configuration files for sound card.
jpayne@69 469 * \param uc_mgr Use case manager
jpayne@69 470 * \return zero if success, otherwise a negative error code
jpayne@69 471 */
jpayne@69 472 int snd_use_case_mgr_reload(snd_use_case_mgr_t *uc_mgr);
jpayne@69 473
jpayne@69 474 /**
jpayne@69 475 * \brief Close use case manager
jpayne@69 476 * \param uc_mgr Use case manager
jpayne@69 477 * \return zero if success, otherwise a negative error code
jpayne@69 478 */
jpayne@69 479 int snd_use_case_mgr_close(snd_use_case_mgr_t *uc_mgr);
jpayne@69 480
jpayne@69 481 /**
jpayne@69 482 * \brief Reset use case manager verb, device, modifier to deafult settings.
jpayne@69 483 * \param uc_mgr Use case manager
jpayne@69 484 * \return zero if success, otherwise a negative error code
jpayne@69 485 */
jpayne@69 486 int snd_use_case_mgr_reset(snd_use_case_mgr_t *uc_mgr);
jpayne@69 487
jpayne@69 488 /*
jpayne@69 489 * helper functions
jpayne@69 490 */
jpayne@69 491
jpayne@69 492 /**
jpayne@69 493 * \brief Obtain a list of cards
jpayne@69 494 * \param list Returned allocated list
jpayne@69 495 * \return Number of list entries if success, otherwise a negative error code
jpayne@69 496 */
jpayne@69 497 static __inline__ int snd_use_case_card_list(const char **list[])
jpayne@69 498 {
jpayne@69 499 return snd_use_case_get_list(NULL, NULL, list);
jpayne@69 500 }
jpayne@69 501
jpayne@69 502 /**
jpayne@69 503 * \brief Obtain a list of verbs
jpayne@69 504 * \param uc_mgr Use case manager
jpayne@69 505 * \param list Returned list of verbs
jpayne@69 506 * \return Number of list entries if success, otherwise a negative error code
jpayne@69 507 */
jpayne@69 508 static __inline__ int snd_use_case_verb_list(snd_use_case_mgr_t *uc_mgr,
jpayne@69 509 const char **list[])
jpayne@69 510 {
jpayne@69 511 return snd_use_case_get_list(uc_mgr, "_verbs", list);
jpayne@69 512 }
jpayne@69 513
jpayne@69 514 /**
jpayne@69 515 * \brief Parse control element identifier
jpayne@69 516 * \param elem_id Element identifier
jpayne@69 517 * \param ucm_id Use case identifier
jpayne@69 518 * \param value String value to be parsed
jpayne@69 519 * \return Zero if success, otherwise a negative error code
jpayne@69 520 */
jpayne@69 521 int snd_use_case_parse_ctl_elem_id(snd_ctl_elem_id_t *dst,
jpayne@69 522 const char *ucm_id,
jpayne@69 523 const char *value);
jpayne@69 524
jpayne@69 525 /**
jpayne@69 526 * \brief Parse mixer element identifier
jpayne@69 527 * \param dst Simple mixer element identifier
jpayne@69 528 * \param ucm_id Use case identifier
jpayne@69 529 * \param value String value to be parsed
jpayne@69 530 * \return Zero if success, otherwise a negative error code
jpayne@69 531 */
jpayne@69 532 int snd_use_case_parse_selem_id(snd_mixer_selem_id_t *dst,
jpayne@69 533 const char *ucm_id,
jpayne@69 534 const char *value);
jpayne@69 535
jpayne@69 536 /**
jpayne@69 537 * \}
jpayne@69 538 */
jpayne@69 539
jpayne@69 540 #ifdef __cplusplus
jpayne@69 541 }
jpayne@69 542 #endif
jpayne@69 543
jpayne@69 544 #endif /* __ALSA_USE_CASE_H */