use-case.h

Go to the documentation of this file.

 
/*
 *
 *  This library is free software; you can redistribute it and/or modify
 *  it under the terms of the GNU Lesser General Public License as
 *  published by the Free Software Foundation; either version 2.1 of
 *  the License, or (at your option) any later version.
 *
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU Lesser General Public License for more details.
 *
 *  You should have received a copy of the GNU Lesser General Public
 *  License along with this library; if not, write to the Free Software
 *  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 *
 *  Copyright (C) 2008-2010 SlimLogic Ltd
 *  Copyright (C) 2010 Wolfson Microelectronics PLC
 *  Copyright (C) 2010 Texas Instruments Inc.
 *
 *  Support for the verb/device/modifier core logic and API,
 *  command line tool and file parser was kindly sponsored by
 *  Texas Instruments Inc.
 *  Support for multiple active modifiers and devices,
 *  transition sequences, multiple client access and user defined use
 *  cases was kindly sponsored by Wolfson Microelectronics PLC.
 */
 
#ifndef __ALSA_USE_CASE_H
#define __ALSA_USE_CASE_H
 
#ifdef __cplusplus
extern "C" {
#endif
 
#include <alsa/asoundlib.h>
 
/*
 * Use Case Verb.
 *
 * The use case verb is the main device audio action. e.g. the "HiFi" use
 * case verb will configure the audio hardware for HiFi Music playback
 * and capture.
 */
#define SND_USE_CASE_VERB_INACTIVE      "Inactive"      
#define SND_USE_CASE_VERB_HIFI          "HiFi"          
#define SND_USE_CASE_VERB_HIFI_LOW_POWER    "HiFi Low Power"    
#define SND_USE_CASE_VERB_VOICE         "Voice"         
#define SND_USE_CASE_VERB_VOICE_LOW_POWER   "Voice Low Power"   
#define SND_USE_CASE_VERB_VOICECALL     "Voice Call"        
#define SND_USE_CASE_VERB_IP_VOICECALL      "Voice Call IP"     
#define SND_USE_CASE_VERB_ANALOG_RADIO      "FM Analog Radio"   
#define SND_USE_CASE_VERB_DIGITAL_RADIO     "FM Digital Radio"  
/* add new verbs to end of list */
 
 
/*
 * Use Case Device.
 *
 * Physical system devices the render and capture audio. Devices can be OR'ed
 * together to support audio on simultaneous devices.
 *
 * If multiple devices with the same name exists, the number suffixes should
 * be added to these names like HDMI1,HDMI2,HDMI3 etc. No number gaps are
 * allowed. The names with numbers must be continuous. It is allowed to put
 * a whitespace between name and index (like 'Line 1') for the better
 * readability. The device names 'Line 1' and 'Line1' are equal for
 * this purpose.
 *
 * If EnableSequence/DisableSequence controls independent paths in the hardware
 * it is also recommended to split playback and capture UCM devices and use
 * the number suffixes. Example use case: Use the integrated microphone
 * in the laptop instead the microphone in headphones.
 *
 * The preference of the devices is determined by the priority value.
 */
#define SND_USE_CASE_DEV_NONE       "None"      
#define SND_USE_CASE_DEV_SPEAKER    "Speaker"   
#define SND_USE_CASE_DEV_LINE       "Line"      
#define SND_USE_CASE_DEV_MIC            "Mic"           
#define SND_USE_CASE_DEV_HEADPHONES "Headphones"    
#define SND_USE_CASE_DEV_HEADSET    "Headset"   
#define SND_USE_CASE_DEV_HANDSET    "Handset"   
#define SND_USE_CASE_DEV_BLUETOOTH  "Bluetooth" 
#define SND_USE_CASE_DEV_EARPIECE   "Earpiece"  
#define SND_USE_CASE_DEV_SPDIF      "SPDIF"     
#define SND_USE_CASE_DEV_HDMI       "HDMI"      
#define SND_USE_CASE_DEV_USB        "USB"       
#define SND_USE_CASE_DEV_DIRECT     "Direct"    
/* add new devices to end of list */
 
 
/*
 * Use Case Modifiers.
 *
 * The use case modifier allows runtime configuration changes to deal with
 * asynchronous events.
 *
 * If multiple modifiers with the same name exists, the number suffixes should
 * be added to these names like 'Echo Reference 1','Echo Reference 2' etc.
 * No number gaps are allowed. The names with numbers must be continuous.
 * It is allowed to put a whitespace between name and index for the better
 * readability. The modifier names 'Something 1' and 'Something1' are equal
 * for this purpose.
 *
 * e.g. to record a voice call :-
 *  1. Set verb to SND_USE_CASE_VERB_VOICECALL (for voice call)
 *  2. Set modifier SND_USE_CASE_MOD_CAPTURE_VOICE when capture required.
 *  3. Call snd_use_case_get("CapturePCM") to get ALSA source PCM name
 *     with captured voice pcm data.
 *
 * e.g. to play a ring tone when listenin to MP3 Music :-
 *  1. Set verb to SND_USE_CASE_VERB_HIFI (for MP3 playback)
 *  2. Set modifier to SND_USE_CASE_MOD_PLAY_TONE when incoming call happens.
 *  3. Call snd_use_case_get("PlaybackPCM") to get ALSA PCM sink name for
 *     ringtone pcm data.
 */
#define SND_USE_CASE_MOD_CAPTURE_VOICE      "Capture Voice"     
#define SND_USE_CASE_MOD_CAPTURE_MUSIC      "Capture Music"     
#define SND_USE_CASE_MOD_PLAY_MUSIC     "Play Music"        
#define SND_USE_CASE_MOD_PLAY_VOICE     "Play Voice"        
#define SND_USE_CASE_MOD_PLAY_TONE      "Play Tone"     
#define SND_USE_CASE_MOD_ECHO_REF       "Echo Reference"    
/* add new modifiers to end of list */
 
 
#define SND_USE_CASE_TQ_MUSIC       "Music"     
#define SND_USE_CASE_TQ_VOICE       "Voice"     
#define SND_USE_CASE_TQ_TONES       "Tones"     
typedef struct snd_use_case_mgr snd_use_case_mgr_t;
 
char *snd_use_case_identifier(const char *fmt, ...);
 
int snd_use_case_free_list(const char *list[], int items);
 
int snd_use_case_get_list(snd_use_case_mgr_t *uc_mgr,
                          const char *identifier,
                          const char **list[]);
 
 
int snd_use_case_get(snd_use_case_mgr_t *uc_mgr,
                     const char *identifier,
                     const char **value);
 
int snd_use_case_geti(snd_use_case_mgr_t *uc_mgr,
              const char *identifier,
              long *value);
 
int snd_use_case_set(snd_use_case_mgr_t *uc_mgr,
                     const char *identifier,
                     const char *value);
 
int snd_use_case_mgr_open(snd_use_case_mgr_t **uc_mgr,
                          const char *card_name);
 
 
int snd_use_case_mgr_reload(snd_use_case_mgr_t *uc_mgr);
 
int snd_use_case_mgr_close(snd_use_case_mgr_t *uc_mgr);
 
int snd_use_case_mgr_reset(snd_use_case_mgr_t *uc_mgr);
 
/*
 * helper functions
 */
 
static __inline__ int snd_use_case_card_list(const char **list[])
{
    return snd_use_case_get_list(NULL, NULL, list);
}
 
static __inline__ int snd_use_case_verb_list(snd_use_case_mgr_t *uc_mgr,
                     const char **list[])
{
    return snd_use_case_get_list(uc_mgr, "_verbs", list);
}
 
int snd_use_case_parse_ctl_elem_id(snd_ctl_elem_id_t *dst,
                   const char *ucm_id,
                   const char *value);
 
int snd_use_case_parse_selem_id(snd_mixer_selem_id_t *dst,
                const char *ucm_id,
                const char *value);
 
#ifdef __cplusplus
}
#endif
 
#endif /* __ALSA_USE_CASE_H */