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 #include <utils/String8.h>
  27
  28 #include <media/IAudioFlinger.h>
  29 #include "media/AudioSystem.h"
  30
  31
  32 namespace android {
  33
  34 // ----------------------------------------------------------------------------
  35
  36 /**
  37  * AudioStreamOut is the abstraction interface for the audio output hardware.
  38  *
  39  * It provides information about various properties of the audio output hardware driver.
  40  */
  41 class AudioStreamOut {
  42 public:
  43     virtual             ~AudioStreamOut() = 0;
  44
  45     /** return audio sampling rate in hz - eg. 44100 */
  46     virtual uint32_t    sampleRate() const = 0;
  47
  48     /** returns size of output buffer - eg. 4800 */
  49     virtual size_t      bufferSize() const = 0;
  50
  51     /**
  52      * returns the output channel nask
  53      */
  54     virtual uint32_t    channels() 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 AudioSystem::popCount(channels())*((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 left, float right) = 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     // set/get audio output parameters. The function accepts a list of parameters
  94     // key value pairs in the form: key1=value1;key2=value2;...
  95     // Some keys are reserved for standard parameters (See AudioParameter class).
  96     // If the implementation does not accept a parameter change while the output is
  97     // active but the parameter is acceptable otherwise, it must return INVALID_OPERATION.
  98     // The audio flinger will put the output in standby and then change the parameter value.
  99     virtual status_t    setParameters(const String8& keyValuePairs) = 0;
 100     virtual String8     getParameters(const String8& keys) = 0;
 101 };
 102
 103 /**
 104  * AudioStreamIn is the abstraction interface for the audio input hardware.
 105  *
 106  * It defines the various properties of the audio hardware input driver.
 107  */
 108 class AudioStreamIn {
 109 public:
 110     virtual             ~AudioStreamIn() = 0;
 111
 112     /** return audio sampling rate in hz - eg. 44100 */
 113     virtual uint32_t    sampleRate() const = 0;
 114
 115     /** return the input buffer size allowed by audio driver */
 116     virtual size_t      bufferSize() const = 0;
 117
 118     /** return input channel mask */
 119     virtual uint32_t    channels() const = 0;
 120
 121     /**
 122      * return audio format in 8bit or 16bit PCM format -
 123      * eg. AudioSystem:PCM_16_BIT
 124      */
 125     virtual int         format() const = 0;
 126
 127     /**
 128      * return the frame size (number of bytes per sample).
 129      */
 130     uint32_t    frameSize() const { return AudioSystem::popCount(channels())*((format()==AudioSystem::PCM_16_BIT)?sizeof(int16_t):sizeof(int8_t)); }
 131
 132     /** set the input gain for the audio driver. This method is for
 133      *  for future use */
 134     virtual status_t    setGain(float gain) = 0;
 135
 136     /** read audio buffer in from audio driver */
 137     virtual ssize_t     read(void* buffer, ssize_t bytes) = 0;
 138
 139     /** dump the state of the audio input device */
 140     virtual status_t dump(int fd, const Vector<String16>& args) = 0;
 141
 142     /**
 143      * Put the audio hardware input into standby mode. Returns
 144      * status based on include/utils/Errors.h
 145      */
 146     virtual status_t    standby() = 0;
 147
 148     // set/get audio input parameters. The function accepts a list of parameters
 149     // key value pairs in the form: key1=value1;key2=value2;...
 150     // Some keys are reserved for standard parameters (See AudioParameter class).
 151     // If the implementation does not accept a parameter change while the output is
 152     // active but the parameter is acceptable otherwise, it must return INVALID_OPERATION.
 153     // The audio flinger will put the input in standby and then change the parameter value.
 154     virtual status_t    setParameters(const String8& keyValuePairs) = 0;
 155     virtual String8     getParameters(const String8& keys) = 0;
 156 };
 157
 158 /**
 159  * AudioHardwareInterface.h defines the interface to the audio hardware abstraction layer.
 160  *
 161  * The interface supports setting and getting parameters, selecting audio routing
 162  * paths, and defining input and output streams.
 163  *
 164  * AudioFlinger initializes the audio hardware and immediately opens an output stream.
 165  * You can set Audio routing to output to handset, speaker, Bluetooth, or a headset.
 166  *
 167  * The audio input stream is initialized when AudioFlinger is called to carry out
 168  * a record operation.
 169  */
 170 class AudioHardwareInterface
 171 {
 172 public:
 173     virtual ~AudioHardwareInterface() {}
 174
 175     /**
 176      * check to see if the audio hardware interface has been initialized.
 177      * return status based on values defined in include/utils/Errors.h
 178      */
 179     virtual status_t    initCheck() = 0;
 180
 181     /** set the audio volume of a voice call. Range is between 0.0 and 1.0 */
 182     virtual status_t    setVoiceVolume(float volume) = 0;
 183
 184     /**
 185      * set the audio volume for all audio activities other than voice call.
 186      * Range between 0.0 and 1.0. If any value other than NO_ERROR is returned,
 187      * the software mixer will emulate this capability.
 188      */
 189     virtual status_t    setMasterVolume(float volume) = 0;
 190
 191     /**
 192      * setMode is called when the audio mode changes. NORMAL mode is for
 193      * standard audio playback, RINGTONE when a ringtone is playing, and IN_CALL
 194      * when a call is in progress.
 195      */
 196     virtual status_t    setMode(int mode) = 0;
 197
 198     // mic mute
 199     virtual status_t    setMicMute(bool state) = 0;
 200     virtual status_t    getMicMute(bool* state) = 0;
 201
 202     // set/get global audio parameters
 203     virtual status_t    setParameters(const String8& keyValuePairs) = 0;
 204     virtual String8     getParameters(const String8& keys) = 0;
 205
 206     // Returns audio input buffer size according to parameters passed or 0 if one of the
 207     // parameters is not supported
 208     virtual size_t    getInputBufferSize(uint32_t sampleRate, int format, int channelCount) = 0;
 209
 210     /** This method creates and opens the audio hardware output stream */
 211     virtual AudioStreamOut* openOutputStream(
 212                                 uint32_t devices,
 213                                 int *format=0,
 214                                 uint32_t *channels=0,
 215                                 uint32_t *sampleRate=0,
 216                                 status_t *status=0) = 0;
 217     virtual    void        closeOutputStream(AudioStreamOut* out) = 0;
 218     /** This method creates and opens the audio hardware input stream */
 219     virtual AudioStreamIn* openInputStream(
 220                                 uint32_t devices,
 221                                 int *format,
 222                                 uint32_t *channels,
 223                                 uint32_t *sampleRate,
 224                                 status_t *status,
 225                                 AudioSystem::audio_in_acoustics acoustics) = 0;
 226     virtual    void        closeInputStream(AudioStreamIn* in) = 0;
 227
 228     /**This method dumps the state of the audio hardware */
 229     virtual status_t dumpState(int fd, const Vector<String16>& args) = 0;
 230
 231     static AudioHardwareInterface* create();
 232
 233 protected:
 234
 235     virtual status_t dump(int fd, const Vector<String16>& args) = 0;
 236 };
 237
 238 // ----------------------------------------------------------------------------
 239
 240 extern "C" AudioHardwareInterface* createAudioHardware(void);
 241
 242 }; // namespace android
 243
 244 #endif // ANDROID_AUDIO_HARDWARE_INTERFACE_H