include/hardware_legacy/AudioHardwareInterface.h

   1 /*
   2  * Copyright (C) 2007 The Android Open Source Project
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *      http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #ifndef ANDROID_AUDIO_HARDWARE_INTERFACE_H
  18 #define ANDROID_AUDIO_HARDWARE_INTERFACE_H
  19
  20 #include <stdint.h>
  21 #include <sys/types.h>
  22
  23 #include <utils/Errors.h>
  24 #include <utils/Vector.h>
  25 #include <utils/String16.h>
  26
  27 #include <media/IAudioFlinger.h>
  28 #include "media/AudioSystem.h"
  29
  30
  31 namespace android {
  32
  33 // ----------------------------------------------------------------------------
  34
  35 /**
  36  * AudioStreamOut is the abstraction interface for the audio output hardware.
  37  *
  38  * It provides information about various properties of the audio output hardware driver.
  39  */
  40 class AudioStreamOut {
  41 public:
  42     virtual             ~AudioStreamOut() = 0;
  43
  44     /** return audio sampling rate in hz - eg. 44100 */
  45     virtual uint32_t    sampleRate() const = 0;
  46
  47     /** returns size of output buffer - eg. 4800 */
  48     virtual size_t      bufferSize() const = 0;
  49
  50     /**
  51      * return number of output audio channels.
  52      * Acceptable values are 1 (mono) or 2 (stereo)
  53      */
  54     virtual int         channelCount() const = 0;
  55
  56     /**
  57      * return audio format in 8bit or 16bit PCM format -
  58      * eg. AudioSystem:PCM_16_BIT
  59      */
  60     virtual int         format() const = 0;
  61
  62     /**
  63      * return the frame size (number of bytes per sample).
  64      */
  65     uint32_t    frameSize() const { return channelCount()*((format()==AudioSystem::PCM_16_BIT)?sizeof(int16_t):sizeof(int8_t)); }
  66
  67     /**
  68      * return the audio hardware driver latency in milli seconds.
  69      */
  70     virtual uint32_t    latency() const = 0;
  71
  72     /**
  73      * Use this method in situations where audio mixing is done in the
  74      * hardware. This method serves as a direct interface with hardware,
  75      * allowing you to directly set the volume as apposed to via the framework.
  76      * This method might produce multiple PCM outputs or hardware accelerated
  77      * codecs, such as MP3 or AAC.
  78      */
  79     virtual status_t    setVolume(float volume) = 0;
  80
  81     /** write audio buffer to driver. Returns number of bytes written */
  82     virtual ssize_t     write(const void* buffer, size_t bytes) = 0;
  83
  84     /**
  85      * Put the audio hardware output into standby mode. Returns
  86      * status based on include/utils/Errors.h
  87      */
  88     virtual status_t    standby() = 0;
  89
  90     /** dump the state of the audio output device */
  91     virtual status_t dump(int fd, const Vector<String16>& args) = 0;
  92 };
  93
  94 /**
  95  * AudioStreamIn is the abstraction interface for the audio input hardware.
  96  *
  97  * It defines the various properties of the audio hardware input driver.
  98  */
  99 class AudioStreamIn {
 100 public:
 101     virtual             ~AudioStreamIn() = 0;
 102
 103     /** return the input buffer size allowed by audio driver */
 104     virtual size_t      bufferSize() const = 0;
 105
 106     /** return the number of audio input channels */
 107     virtual int         channelCount() const = 0;
 108
 109     /**
 110      * return audio format in 8bit or 16bit PCM format -
 111      * eg. AudioSystem:PCM_16_BIT
 112      */
 113     virtual int         format() const = 0;
 114
 115     /**
 116      * return the frame size (number of bytes per sample).
 117      */
 118     uint32_t    frameSize() const { return channelCount()*((format()==AudioSystem::PCM_16_BIT)?sizeof(int16_t):sizeof(int8_t)); }
 119
 120     /** set the input gain for the audio driver. This method is for
 121      *  for future use */
 122     virtual status_t    setGain(float gain) = 0;
 123
 124     /** read audio buffer in from audio driver */
 125     virtual ssize_t     read(void* buffer, ssize_t bytes) = 0;
 126
 127     /** dump the state of the audio input device */
 128     virtual status_t dump(int fd, const Vector<String16>& args) = 0;
 129
 130     /**
 131      * Put the audio hardware input into standby mode. Returns
 132      * status based on include/utils/Errors.h
 133      */
 134     virtual status_t    standby() = 0;
 135
 136 };
 137
 138 /**
 139  * AudioHardwareInterface.h defines the interface to the audio hardware abstraction layer.
 140  *
 141  * The interface supports setting and getting parameters, selecting audio routing
 142  * paths, and defining input and output streams.
 143  *
 144  * AudioFlinger initializes the audio hardware and immediately opens an output stream.
 145  * You can set Audio routing to output to handset, speaker, Bluetooth, or a headset.
 146  *
 147  * The audio input stream is initialized when AudioFlinger is called to carry out
 148  * a record operation.
 149  */
 150 class AudioHardwareInterface
 151 {
 152 public:
 153     virtual ~AudioHardwareInterface() {}
 154
 155     /**
 156      * check to see if the audio hardware interface has been initialized.
 157      * return status based on values defined in include/utils/Errors.h
 158      */
 159     virtual status_t    initCheck() = 0;
 160
 161     /** set the audio volume of a voice call. Range is between 0.0 and 1.0 */
 162     virtual status_t    setVoiceVolume(float volume) = 0;
 163
 164     /**
 165      * set the audio volume for all audio activities other than voice call.
 166      * Range between 0.0 and 1.0. If any value other than NO_ERROR is returned,
 167      * the software mixer will emulate this capability.
 168      */
 169     virtual status_t    setMasterVolume(float volume) = 0;
 170
 171     /**
 172      * Audio routing methods. Routes defined in include/hardware_legacy/AudioSystem.h.
 173      * Audio routes can be (ROUTE_EARPIECE | ROUTE_SPEAKER | ROUTE_BLUETOOTH
 174      *                    | ROUTE_HEADSET)
 175      *
 176      * setRouting sets the routes for a mode. This is called at startup. It is
 177      * also called when a new device is connected, such as a wired headset is
 178      * plugged in or a Bluetooth headset is paired.
 179      */
 180     virtual status_t    setRouting(int mode, uint32_t routes) = 0;
 181
 182     virtual status_t    getRouting(int mode, uint32_t* routes) = 0;
 183
 184     /**
 185      * setMode is called when the audio mode changes. NORMAL mode is for
 186      * standard audio playback, RINGTONE when a ringtone is playing, and IN_CALL
 187      * when a call is in progress.
 188      */
 189     virtual status_t    setMode(int mode) = 0;
 190     virtual status_t    getMode(int* mode) = 0;
 191
 192     // mic mute
 193     virtual status_t    setMicMute(bool state) = 0;
 194     virtual status_t    getMicMute(bool* state) = 0;
 195
 196     // Temporary interface, do not use
 197     // TODO: Replace with a more generic key:value get/set mechanism
 198     virtual status_t    setParameter(const char* key, const char* value) = 0;
 199
 200     // Returns audio input buffer size according to parameters passed or 0 if one of the
 201     // parameters is not supported
 202     virtual size_t    getInputBufferSize(uint32_t sampleRate, int format, int channelCount) = 0;
 203
 204     /** This method creates and opens the audio hardware output stream */
 205     virtual AudioStreamOut* openOutputStream(
 206                                 int format=0,
 207                                 int channelCount=0,
 208                                 uint32_t sampleRate=0,
 209                                 status_t *status=0) = 0;
 210
 211     /** This method creates and opens the audio hardware input stream */
 212     virtual AudioStreamIn* openInputStream(
 213                                 int inputSource,
 214                                 int format,
 215                                 int channelCount,
 216                                 uint32_t sampleRate,
 217                                 status_t *status,
 218                                 AudioSystem::audio_in_acoustics acoustics) = 0;
 219
 220     /**This method dumps the state of the audio hardware */
 221     virtual status_t dumpState(int fd, const Vector<String16>& args) = 0;
 222
 223     static AudioHardwareInterface* create();
 224
 225 protected:
 226     /**
 227      * doRouting actually initiates the routing. A call to setRouting
 228      * or setMode may result in a routing change. The generic logic calls
 229      * doRouting when required. If the device has any special requirements these
 230      * methods can be overriden.
 231      */
 232     virtual status_t    doRouting() = 0;
 233
 234     virtual status_t dump(int fd, const Vector<String16>& args) = 0;
 235 };
 236
 237 // ----------------------------------------------------------------------------
 238
 239 extern "C" AudioHardwareInterface* createAudioHardware(void);
 240
 241 }; // namespace android
 242
 243 #endif // ANDROID_AUDIO_HARDWARE_INTERFACE_H