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 * Note: This callback is only fired when an AudioStreamCallback is set. 96 * If you use AudioStream::write() you have to evaluate the return codes of 97 * AudioStream::write() to notice errors in the stream. 98 * 99 * It is used with AudioStreamBuilder::setErrorCallback(). 100 */ 101 class AudioStreamErrorCallback { 102 public: 103 virtual ~AudioStreamErrorCallback() = default; 104 105 /** 106 * This will be called before other `onError` methods when an error occurs on a stream, 107 * such as when the stream is disconnected. 108 * 109 * It can be used to override and customize the normal error processing. 110 * Use of this method is considered an advanced technique. 111 * It might, for example, be used if an app want to use a high level lock when 112 * closing and reopening a stream. 113 * Or it might be used when an app want to signal a management thread that handles 114 * all of the stream state. 115 * 116 * If this method returns false it indicates that the stream has *not been stopped and closed 117 * by the application. In this case it will be stopped by Oboe in the following way: 118 * onErrorBeforeClose() will be called, then the stream will be closed and onErrorAfterClose() 119 * will be closed. 120 * 121 * If this method returns true it indicates that the stream *has* been stopped and closed 122 * by the application and Oboe will not do this. 123 * In that case, the app MUST stop() and close() the stream. 124 * 125 * This method will be called on a thread created by Oboe. 126 * 127 * @param audioStream pointer to the associated stream 128 * @param error 129 * @return true if the stream has been stopped and closed, false if not 130 */ onError(AudioStream *,Result)131 virtual bool onError(AudioStream* /* audioStream */, Result /* error */) { 132 return false; 133 } 134 135 /** 136 * This will be called when an error occurs on a stream, 137 * such as when the stream is disconnected, 138 * and if onError() returns false (indicating that the error has not already been handled). 139 * 140 * Note that this will be called on a thread created by Oboe. 141 * 142 * The underlying stream will already be stopped by Oboe but not yet closed. 143 * So the stream can be queried. 144 * 145 * Do not close or delete the stream in this method because it will be 146 * closed after this method returns. 147 * 148 * @param audioStream pointer to the associated stream 149 * @param error 150 */ onErrorBeforeClose(AudioStream *,Result)151 virtual void onErrorBeforeClose(AudioStream* /* audioStream */, Result /* error */) {} 152 153 /** 154 * This will be called when an error occurs on a stream, 155 * such as when the stream is disconnected, 156 * and if onError() returns false (indicating that the error has not already been handled). 157 * 158 * The underlying AAudio or OpenSL ES stream will already be stopped AND closed by Oboe. 159 * So the underlying stream cannot be referenced. 160 * But you can still query most parameters. 161 * 162 * This callback could be used to reopen a new stream on another device. 163 * 164 * @param audioStream pointer to the associated stream 165 * @param error 166 */ onErrorAfterClose(AudioStream *,Result)167 virtual void onErrorAfterClose(AudioStream* /* audioStream */, Result /* error */) {} 168 169 }; 170 171 /** 172 * AudioStreamCallback defines a callback interface for: 173 * 174 * 1) moving data to/from an audio stream using `onAudioReady` 175 * 2) being alerted when a stream has an error using `onError*` methods 176 * 177 * It is used with AudioStreamBuilder::setCallback(). 178 * 179 * It combines the interfaces defined by AudioStreamDataCallback and AudioStreamErrorCallback. 180 * This was the original callback object. We now recommend using the individual interfaces 181 * and using setDataCallback() and setErrorCallback(). 182 * 183 * @deprecated Use `AudioStreamDataCallback` and `AudioStreamErrorCallback` instead 184 */ 185 class AudioStreamCallback : public AudioStreamDataCallback, 186 public AudioStreamErrorCallback { 187 public: 188 virtual ~AudioStreamCallback() = default; 189 }; 190 191 } // namespace oboe 192 193 #endif //OBOE_STREAM_CALLBACK_H 194