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