1 /* 2 * Copyright (C) 2016 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 OBOE_STREAM_CALLBACK_H 18 #define OBOE_STREAM_CALLBACK_H 19 20 #include "oboe/Definitions.h" 21 22 namespace oboe { 23 24 class AudioStream; 25 26 /** 27 * AudioStreamDataCallback defines a callback interface for 28 * moving data to/from an audio stream using `onAudioReady` 29 * 2) being alerted when a stream has an error using `onError*` methods 30 * 31 * It is used with AudioStreamBuilder::setDataCallback(). 32 */ 33 34 class AudioStreamDataCallback { 35 public: 36 virtual ~AudioStreamDataCallback() = default; 37 38 /** 39 * A buffer is ready for processing. 40 * 41 * For an output stream, this function should render and write numFrames of data 42 * in the stream's current data format to the audioData buffer. 43 * 44 * For an input stream, this function should read and process numFrames of data 45 * from the audioData buffer. 46 * 47 * The audio data is passed through the buffer. So do NOT call read() or 48 * write() on the stream that is making the callback. 49 * 50 * Note that numFrames can vary unless AudioStreamBuilder::setFramesPerCallback() 51 * is called. 52 * 53 * Also note that this callback function should be considered a "real-time" function. 54 * It must not do anything that could cause an unbounded delay because that can cause the 55 * audio to glitch or pop. 56 * 57 * These are things the function should NOT do: 58 * <ul> 59 * <li>allocate memory using, for example, malloc() or new</li> 60 * <li>any file operations such as opening, closing, reading or writing</li> 61 * <li>any network operations such as streaming</li> 62 * <li>use any mutexes or other synchronization primitives</li> 63 * <li>sleep</li> 64 * <li>oboeStream->stop(), pause(), flush() or close()</li> 65 * <li>oboeStream->read()</li> 66 * <li>oboeStream->write()</li> 67 * </ul> 68 * 69 * The following are OK to call from the data callback: 70 * <ul> 71 * <li>oboeStream->get*()</li> 72 * <li>oboe::convertToText()</li> 73 * <li>oboeStream->setBufferSizeInFrames()</li> 74 * </ul> 75 * 76 * If you need to move data, eg. MIDI commands, in or out of the callback function then 77 * we recommend the use of non-blocking techniques such as an atomic FIFO. 78 * 79 * @param audioStream pointer to the associated stream 80 * @param audioData buffer containing input data or a place to put output data 81 * @param numFrames number of frames to be processed 82 * @return DataCallbackResult::Continue or DataCallbackResult::Stop 83 */ 84 virtual DataCallbackResult onAudioReady( 85 AudioStream *audioStream, 86 void *audioData, 87 int32_t numFrames) = 0; 88 }; 89 90 /** 91 * AudioStreamErrorCallback defines a callback interface for 92 * being alerted when a stream has an error or is disconnected 93 * using `onError*` methods. 94 * 95 * It is used with AudioStreamBuilder::setErrorCallback(). 96 */ 97 class AudioStreamErrorCallback { 98 public: 99 virtual ~AudioStreamErrorCallback() = default; 100 101 /** 102 * This will be called before other `onError` methods when an error occurs on a stream, 103 * such as when the stream is disconnected. 104 * 105 * It can be used to override and customize the normal error processing. 106 * Use of this method is considered an advanced technique. 107 * It might, for example, be used if an app want to use a high level lock when 108 * closing and reopening a stream. 109 * Or it might be used when an app want to signal a management thread that handles 110 * all of the stream state. 111 * 112 * If this method returns false it indicates that the stream has *not been stopped and closed 113 * by the application. In this case it will be stopped by Oboe in the following way: 114 * onErrorBeforeClose() will be called, then the stream will be closed and onErrorAfterClose() 115 * will be closed. 116 * 117 * If this method returns true it indicates that the stream *has* been stopped and closed 118 * by the application and Oboe will not do this. 119 * In that case, the app MUST stop() and close() the stream. 120 * 121 * This method will be called on a thread created by Oboe. 122 * 123 * @param audioStream pointer to the associated stream 124 * @param error 125 * @return true if the stream has been stopped and closed, false if not 126 */ onError(AudioStream *,Result)127 virtual bool onError(AudioStream* /* audioStream */, Result /* error */) { 128 return false; 129 } 130 131 /** 132 * This will be called when an error occurs on a stream, 133 * such as when the stream is disconnected, 134 * and if onError() returns false (indicating that the error has not already been handled). 135 * 136 * Note that this will be called on a thread created by Oboe. 137 * 138 * The underlying stream will already be stopped by Oboe but not yet closed. 139 * So the stream can be queried. 140 * 141 * Do not close or delete the stream in this method because it will be 142 * closed after this method returns. 143 * 144 * @param audioStream pointer to the associated stream 145 * @param error 146 */ onErrorBeforeClose(AudioStream *,Result)147 virtual void onErrorBeforeClose(AudioStream* /* audioStream */, Result /* error */) {} 148 149 /** 150 * This will be called when an error occurs on a stream, 151 * such as when the stream is disconnected, 152 * and if onError() returns false (indicating that the error has not already been handled). 153 * 154 * The underlying AAudio or OpenSL ES stream will already be stopped AND closed by Oboe. 155 * So the underlying stream cannot be referenced. 156 * But you can still query most parameters. 157 * 158 * This callback could be used to reopen a new stream on another device. 159 * 160 * @param audioStream pointer to the associated stream 161 * @param error 162 */ onErrorAfterClose(AudioStream *,Result)163 virtual void onErrorAfterClose(AudioStream* /* audioStream */, Result /* error */) {} 164 165 }; 166 167 /** 168 * AudioStreamCallback defines a callback interface for: 169 * 170 * 1) moving data to/from an audio stream using `onAudioReady` 171 * 2) being alerted when a stream has an error using `onError*` methods 172 * 173 * It is used with AudioStreamBuilder::setCallback(). 174 * 175 * It combines the interfaces defined by AudioStreamDataCallback and AudioStreamErrorCallback. 176 * This was the original callback object. We now recommend using the individual interfaces 177 * and using setDataCallback() and setErrorCallback(). 178 * 179 * @deprecated Use `AudioStreamDataCallback` and `AudioStreamErrorCallback` instead 180 */ 181 class AudioStreamCallback : public AudioStreamDataCallback, 182 public AudioStreamErrorCallback { 183 public: 184 virtual ~AudioStreamCallback() = default; 185 }; 186 187 } // namespace oboe 188 189 #endif //OBOE_STREAM_CALLBACK_H 190