1/*
2 * libjingle
3 * Copyright 2004--2010, Google Inc.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions are met:
7 *
8 *  1. Redistributions of source code must retain the above copyright notice,
9 *     this list of conditions and the following disclaimer.
10 *  2. Redistributions in binary form must reproduce the above copyright notice,
11 *     this list of conditions and the following disclaimer in the documentation
12 *     and/or other materials provided with the distribution.
13 *  3. The name of the author may not be used to endorse or promote products
14 *     derived from this software without specific prior written permission.
15 *
16 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED
17 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
18 * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
19 * EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
20 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
21 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
22 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
23 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
24 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
25 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26 */
27
28#ifndef TALK_SOUND_SOUNDSYSTEMINTERFACE_H_
29#define TALK_SOUND_SOUNDSYSTEMINTERFACE_H_
30
31#include <vector>
32
33#include "talk/base/constructormagic.h"
34
35namespace cricket {
36
37class SoundDeviceLocator;
38class SoundInputStreamInterface;
39class SoundOutputStreamInterface;
40
41// Interface for a platform's sound system.
42// Implementations must guarantee thread-safety for at least the following use
43// cases:
44// 1) Concurrent enumeration and opening of devices from different threads.
45// 2) Concurrent use of different Sound(Input|Output)StreamInterface
46// instances from different threads (but concurrent use of the _same_ one from
47// different threads need not be supported).
48class SoundSystemInterface {
49 public:
50  typedef std::vector<SoundDeviceLocator *> SoundDeviceLocatorList;
51
52  enum SampleFormat {
53    // Only one supported sample format at this time.
54    // The values here may be used in lookup tables, so they shouldn't change.
55    FORMAT_S16LE = 0,
56  };
57
58  enum Flags {
59    // Enable reporting the current stream latency in
60    // Sound(Input|Output)StreamInterface. See those classes for more details.
61    FLAG_REPORT_LATENCY = (1 << 0),
62  };
63
64  struct OpenParams {
65    // Format for the sound stream.
66    SampleFormat format;
67    // Sampling frequency in hertz.
68    unsigned int freq;
69    // Number of channels in the PCM stream.
70    unsigned int channels;
71    // Misc flags. Should be taken from the Flags enum above.
72    int flags;
73    // Desired latency, measured as number of bytes of sample data
74    int latency;
75  };
76
77  // Special values for the "latency" field of OpenParams.
78  // Use this one to say you don't care what the latency is. The sound system
79  // will optimize for other things instead.
80  static const int kNoLatencyRequirements = -1;
81  // Use this one to say that you want the sound system to pick an appropriate
82  // small latency value. The sound system may pick the minimum allowed one, or
83  // a slightly higher one in the event that the true minimum requires an
84  // undesirable trade-off.
85  static const int kLowLatency = 0;
86
87  // Max value for the volume parameters for Sound(Input|Output)StreamInterface.
88  static const int kMaxVolume = 255;
89  // Min value for the volume parameters for Sound(Input|Output)StreamInterface.
90  static const int kMinVolume = 0;
91
92  // Helper for clearing a locator list and deleting the entries.
93  static void ClearSoundDeviceLocatorList(SoundDeviceLocatorList *devices);
94
95  virtual ~SoundSystemInterface() {}
96
97  virtual bool Init() = 0;
98  virtual void Terminate() = 0;
99
100  // Enumerates the available devices. (Any pre-existing locators in the lists
101  // are deleted.)
102  virtual bool EnumeratePlaybackDevices(SoundDeviceLocatorList *devices) = 0;
103  virtual bool EnumerateCaptureDevices(SoundDeviceLocatorList *devices) = 0;
104
105  // Gets a special locator for the default device.
106  virtual bool GetDefaultPlaybackDevice(SoundDeviceLocator **device) = 0;
107  virtual bool GetDefaultCaptureDevice(SoundDeviceLocator **device) = 0;
108
109  // Opens the given device, or returns NULL on error.
110  virtual SoundOutputStreamInterface *OpenPlaybackDevice(
111      const SoundDeviceLocator *device,
112      const OpenParams &params) = 0;
113  virtual SoundInputStreamInterface *OpenCaptureDevice(
114      const SoundDeviceLocator *device,
115      const OpenParams &params) = 0;
116
117  // A human-readable name for this sound system.
118  virtual const char *GetName() const = 0;
119
120 protected:
121  SoundSystemInterface() {}
122
123 private:
124  DISALLOW_COPY_AND_ASSIGN(SoundSystemInterface);
125};
126
127}  // namespace cricket
128
129#endif  // TALK_SOUND_SOUNDSYSTEMINTERFACE_H_
130