diff options
Diffstat (limited to 'platform/sysroot/usr/include/aaudio/AAudio.h')
| -rw-r--r-- | platform/sysroot/usr/include/aaudio/AAudio.h | 303 |
1 files changed, 214 insertions, 89 deletions
diff --git a/platform/sysroot/usr/include/aaudio/AAudio.h b/platform/sysroot/usr/include/aaudio/AAudio.h index 0c4a8f78b..7648c76f6 100644 --- a/platform/sysroot/usr/include/aaudio/AAudio.h +++ b/platform/sysroot/usr/include/aaudio/AAudio.h @@ -103,7 +103,23 @@ enum { * * Available since API level 31. */ - AAUDIO_FORMAT_PCM_I32 + AAUDIO_FORMAT_PCM_I32, + + /** + * This format is used for compressed audio wrapped in IEC61937 for HDMI + * or S/PDIF passthrough. + * + * Unlike PCM playback, the Android framework is not able to do format + * conversion for IEC61937. In that case, when IEC61937 is requested, sampling + * rate and channel count or channel mask must be specified. Otherwise, it may + * fail when opening the stream. Apps are able to get the correct configuration + * for the playback by calling + * <a href="/reference/android/media/AudioManager#getDevices(int)"> + * AudioManager#getDevices(int)</a>. + * + * Available since API level 34. + */ + AAUDIO_FORMAT_IEC61937 }; typedef int32_t aaudio_format_t; @@ -118,7 +134,11 @@ enum { * The call was successful. */ AAUDIO_OK, - AAUDIO_ERROR_BASE = -900, // TODO review + + /** + * Reserved. This should not be returned. + */ + AAUDIO_ERROR_BASE = -900, /** * The audio device was disconnected. This could occur, for example, when headphones @@ -134,6 +154,10 @@ enum { */ AAUDIO_ERROR_ILLEGAL_ARGUMENT, // reserved + + /** + * An internal error occurred. + */ AAUDIO_ERROR_INTERNAL = AAUDIO_ERROR_ILLEGAL_ARGUMENT + 2, /** @@ -142,7 +166,9 @@ enum { AAUDIO_ERROR_INVALID_STATE, // reserved // reserved - /* The server rejected the handle used to identify the stream. + + /** + * The server rejected the handle used to identify the stream. */ AAUDIO_ERROR_INVALID_HANDLE = AAUDIO_ERROR_INVALID_STATE + 3, // reserved @@ -158,6 +184,10 @@ enum { * or a timestamp is not available. */ AAUDIO_ERROR_UNAVAILABLE, + + /** + * Reserved. This should not be returned. + */ AAUDIO_ERROR_NO_FREE_HANDLES, /** @@ -175,6 +205,10 @@ enum { * An operation took longer than expected. */ AAUDIO_ERROR_TIMEOUT, + + /** + * A queue is full. This queue would be blocked. + */ AAUDIO_ERROR_WOULD_BLOCK, /** @@ -261,6 +295,7 @@ enum AAUDIO_STREAM_STATE_CLOSED, /** * The stream is disconnected from audio device. + * @deprecated */ AAUDIO_STREAM_STATE_DISCONNECTED }; @@ -741,7 +776,8 @@ typedef struct AAudioStreamBuilderStruct AAudioStreamBuilder; * * @return pointer to a text representation of an AAudio result code. */ -AAUDIO_API const char * AAudio_convertResultToText(aaudio_result_t returnCode) __INTRODUCED_IN(26); +AAUDIO_API const char * _Nonnull AAudio_convertResultToText(aaudio_result_t returnCode) + __INTRODUCED_IN(26); /** * The text is the ASCII symbol corresponding to the stream state, @@ -753,7 +789,7 @@ AAUDIO_API const char * AAudio_convertResultToText(aaudio_result_t returnCode) _ * * @return pointer to a text representation of an AAudio state. */ -AAUDIO_API const char * AAudio_convertStreamStateToText(aaudio_stream_state_t state) +AAUDIO_API const char * _Nonnull AAudio_convertStreamStateToText(aaudio_stream_state_t state) __INTRODUCED_IN(26); // ============================================================ @@ -774,8 +810,8 @@ AAUDIO_API const char * AAudio_convertStreamStateToText(aaudio_stream_state_t st * * Available since API level 26. */ -AAUDIO_API aaudio_result_t AAudio_createStreamBuilder(AAudioStreamBuilder** builder) - __INTRODUCED_IN(26); +AAUDIO_API aaudio_result_t AAudio_createStreamBuilder(AAudioStreamBuilder* _Nullable* _Nonnull + builder) __INTRODUCED_IN(26); /** * Request an audio device identified by an ID. @@ -797,7 +833,7 @@ AAUDIO_API aaudio_result_t AAudio_createStreamBuilder(AAudioStreamBuilder** buil * @param builder reference provided by AAudio_createStreamBuilder() * @param deviceId device identifier or {@link #AAUDIO_UNSPECIFIED} */ -AAUDIO_API void AAudioStreamBuilder_setDeviceId(AAudioStreamBuilder* builder, +AAUDIO_API void AAudioStreamBuilder_setDeviceId(AAudioStreamBuilder* _Nonnull builder, int32_t deviceId) __INTRODUCED_IN(26); /** @@ -817,8 +853,8 @@ AAUDIO_API void AAudioStreamBuilder_setDeviceId(AAudioStreamBuilder* builder, * @param builder reference provided by AAudio_createStreamBuilder() * @param packageName packageName of the calling app. */ -AAUDIO_API void AAudioStreamBuilder_setPackageName(AAudioStreamBuilder* builder, - const char * packageName) __INTRODUCED_IN(31); +AAUDIO_API void AAudioStreamBuilder_setPackageName(AAudioStreamBuilder* _Nonnull builder, + const char * _Nonnull packageName) __INTRODUCED_IN(31); /** * Declare the attribution tag of the context creating the stream. @@ -832,8 +868,8 @@ AAUDIO_API void AAudioStreamBuilder_setPackageName(AAudioStreamBuilder* builder, * @param builder reference provided by AAudio_createStreamBuilder() * @param attributionTag attributionTag of the calling context. */ -AAUDIO_API void AAudioStreamBuilder_setAttributionTag(AAudioStreamBuilder* builder, - const char * attributionTag) __INTRODUCED_IN(31); +AAUDIO_API void AAudioStreamBuilder_setAttributionTag(AAudioStreamBuilder* _Nonnull builder, + const char * _Nonnull attributionTag) __INTRODUCED_IN(31); /** * Request a sample rate in Hertz. @@ -851,7 +887,7 @@ AAUDIO_API void AAudioStreamBuilder_setAttributionTag(AAudioStreamBuilder* build * @param builder reference provided by AAudio_createStreamBuilder() * @param sampleRate frames per second. Common rates include 44100 and 48000 Hz. */ -AAUDIO_API void AAudioStreamBuilder_setSampleRate(AAudioStreamBuilder* builder, +AAUDIO_API void AAudioStreamBuilder_setSampleRate(AAudioStreamBuilder* _Nonnull builder, int32_t sampleRate) __INTRODUCED_IN(26); /** @@ -870,12 +906,18 @@ AAUDIO_API void AAudioStreamBuilder_setSampleRate(AAudioStreamBuilder* builder, * will be respected if both this function and {@link AAudioStreamBuilder_setChannelMask} are * called. * + * Note that if the channel count is two then it may get mixed to mono when the device only supports + * one channel. If the channel count is greater than two but the device's supported channel count is + * less than the requested value, the channels higher than the device channel will be dropped. If + * higher channels should be mixed or spatialized, use {@link AAudioStreamBuilder_setChannelMask} + * instead. + * * Available since API level 26. * * @param builder reference provided by AAudio_createStreamBuilder() * @param channelCount Number of channels desired. */ -AAUDIO_API void AAudioStreamBuilder_setChannelCount(AAudioStreamBuilder* builder, +AAUDIO_API void AAudioStreamBuilder_setChannelCount(AAudioStreamBuilder* _Nonnull builder, int32_t channelCount) __INTRODUCED_IN(26); /** @@ -888,7 +930,7 @@ AAUDIO_API void AAudioStreamBuilder_setChannelCount(AAudioStreamBuilder* builder * * @deprecated use {@link AAudioStreamBuilder_setChannelCount} */ -AAUDIO_API void AAudioStreamBuilder_setSamplesPerFrame(AAudioStreamBuilder* builder, +AAUDIO_API void AAudioStreamBuilder_setSamplesPerFrame(AAudioStreamBuilder* _Nonnull builder, int32_t samplesPerFrame) __INTRODUCED_IN(26); /** @@ -908,7 +950,7 @@ AAUDIO_API void AAudioStreamBuilder_setSamplesPerFrame(AAudioStreamBuilder* buil * @param format common formats are {@link #AAUDIO_FORMAT_PCM_FLOAT} and * {@link #AAUDIO_FORMAT_PCM_I16}. */ -AAUDIO_API void AAudioStreamBuilder_setFormat(AAudioStreamBuilder* builder, +AAUDIO_API void AAudioStreamBuilder_setFormat(AAudioStreamBuilder* _Nonnull builder, aaudio_format_t format) __INTRODUCED_IN(26); /** @@ -924,7 +966,7 @@ AAUDIO_API void AAudioStreamBuilder_setFormat(AAudioStreamBuilder* builder, * @param builder reference provided by AAudio_createStreamBuilder() * @param sharingMode {@link #AAUDIO_SHARING_MODE_SHARED} or {@link #AAUDIO_SHARING_MODE_EXCLUSIVE} */ -AAUDIO_API void AAudioStreamBuilder_setSharingMode(AAudioStreamBuilder* builder, +AAUDIO_API void AAudioStreamBuilder_setSharingMode(AAudioStreamBuilder* _Nonnull builder, aaudio_sharing_mode_t sharingMode) __INTRODUCED_IN(26); /** @@ -937,7 +979,7 @@ AAUDIO_API void AAudioStreamBuilder_setSharingMode(AAudioStreamBuilder* builder, * @param builder reference provided by AAudio_createStreamBuilder() * @param direction {@link #AAUDIO_DIRECTION_OUTPUT} or {@link #AAUDIO_DIRECTION_INPUT} */ -AAUDIO_API void AAudioStreamBuilder_setDirection(AAudioStreamBuilder* builder, +AAUDIO_API void AAudioStreamBuilder_setDirection(AAudioStreamBuilder* _Nonnull builder, aaudio_direction_t direction) __INTRODUCED_IN(26); /** @@ -951,8 +993,8 @@ AAUDIO_API void AAudioStreamBuilder_setDirection(AAudioStreamBuilder* builder, * @param builder reference provided by AAudio_createStreamBuilder() * @param numFrames the desired buffer capacity in frames or {@link #AAUDIO_UNSPECIFIED} */ -AAUDIO_API void AAudioStreamBuilder_setBufferCapacityInFrames(AAudioStreamBuilder* builder, - int32_t numFrames) __INTRODUCED_IN(26); +AAUDIO_API void AAudioStreamBuilder_setBufferCapacityInFrames( + AAudioStreamBuilder* _Nonnull builder, int32_t numFrames) __INTRODUCED_IN(26); /** * Set the requested performance mode. @@ -971,7 +1013,7 @@ AAUDIO_API void AAudioStreamBuilder_setBufferCapacityInFrames(AAudioStreamBuilde * @param builder reference provided by AAudio_createStreamBuilder() * @param mode the desired performance mode, eg. {@link #AAUDIO_PERFORMANCE_MODE_LOW_LATENCY} */ -AAUDIO_API void AAudioStreamBuilder_setPerformanceMode(AAudioStreamBuilder* builder, +AAUDIO_API void AAudioStreamBuilder_setPerformanceMode(AAudioStreamBuilder* _Nonnull builder, aaudio_performance_mode_t mode) __INTRODUCED_IN(26); /** @@ -988,7 +1030,7 @@ AAUDIO_API void AAudioStreamBuilder_setPerformanceMode(AAudioStreamBuilder* buil * @param builder reference provided by AAudio_createStreamBuilder() * @param usage the desired usage, eg. {@link #AAUDIO_USAGE_GAME} */ -AAUDIO_API void AAudioStreamBuilder_setUsage(AAudioStreamBuilder* builder, +AAUDIO_API void AAudioStreamBuilder_setUsage(AAudioStreamBuilder* _Nonnull builder, aaudio_usage_t usage) __INTRODUCED_IN(28); /** @@ -1005,7 +1047,7 @@ AAUDIO_API void AAudioStreamBuilder_setUsage(AAudioStreamBuilder* builder, * @param builder reference provided by AAudio_createStreamBuilder() * @param contentType the type of audio data, eg. {@link #AAUDIO_CONTENT_TYPE_SPEECH} */ -AAUDIO_API void AAudioStreamBuilder_setContentType(AAudioStreamBuilder* builder, +AAUDIO_API void AAudioStreamBuilder_setContentType(AAudioStreamBuilder* _Nonnull builder, aaudio_content_type_t contentType) __INTRODUCED_IN(28); /** @@ -1020,7 +1062,8 @@ AAUDIO_API void AAudioStreamBuilder_setContentType(AAudioStreamBuilder* builder, * @param spatializationBehavior the desired behavior with regards to spatialization, eg. * {@link #AAUDIO_SPATIALIZATION_BEHAVIOR_AUTO} */ -AAUDIO_API void AAudioStreamBuilder_setSpatializationBehavior(AAudioStreamBuilder* builder, +AAUDIO_API void AAudioStreamBuilder_setSpatializationBehavior( + AAudioStreamBuilder* _Nonnull builder, aaudio_spatialization_behavior_t spatializationBehavior) __INTRODUCED_IN(32); /** @@ -1036,7 +1079,7 @@ AAUDIO_API void AAudioStreamBuilder_setSpatializationBehavior(AAudioStreamBuilde * @param isSpatialized true if the content is already processed for binaural or transaural spatial * rendering, false otherwise. */ -AAUDIO_API void AAudioStreamBuilder_setIsContentSpatialized(AAudioStreamBuilder* builder, +AAUDIO_API void AAudioStreamBuilder_setIsContentSpatialized(AAudioStreamBuilder* _Nonnull builder, bool isSpatialized) __INTRODUCED_IN(32); /** @@ -1056,7 +1099,7 @@ AAUDIO_API void AAudioStreamBuilder_setIsContentSpatialized(AAudioStreamBuilder* * @param builder reference provided by AAudio_createStreamBuilder() * @param inputPreset the desired configuration for recording */ -AAUDIO_API void AAudioStreamBuilder_setInputPreset(AAudioStreamBuilder* builder, +AAUDIO_API void AAudioStreamBuilder_setInputPreset(AAudioStreamBuilder* _Nonnull builder, aaudio_input_preset_t inputPreset) __INTRODUCED_IN(28); /** @@ -1074,7 +1117,7 @@ AAUDIO_API void AAudioStreamBuilder_setInputPreset(AAudioStreamBuilder* builder, * @param builder reference provided by AAudio_createStreamBuilder() * @param capturePolicy the desired level of opt-out from being captured. */ -AAUDIO_API void AAudioStreamBuilder_setAllowedCapturePolicy(AAudioStreamBuilder* builder, +AAUDIO_API void AAudioStreamBuilder_setAllowedCapturePolicy(AAudioStreamBuilder* _Nonnull builder, aaudio_allowed_capture_policy_t capturePolicy) __INTRODUCED_IN(29); /** Set the requested session ID. @@ -1104,7 +1147,7 @@ AAUDIO_API void AAudioStreamBuilder_setAllowedCapturePolicy(AAudioStreamBuilder* * @param builder reference provided by AAudio_createStreamBuilder() * @param sessionId an allocated sessionID or {@link #AAUDIO_SESSION_ID_ALLOCATE} */ -AAUDIO_API void AAudioStreamBuilder_setSessionId(AAudioStreamBuilder* builder, +AAUDIO_API void AAudioStreamBuilder_setSessionId(AAudioStreamBuilder* _Nonnull builder, aaudio_session_id_t sessionId) __INTRODUCED_IN(28); @@ -1126,7 +1169,7 @@ AAUDIO_API void AAudioStreamBuilder_setSessionId(AAudioStreamBuilder* builder, * @param privacySensitive true if capture from this stream must be marked as privacy sensitive, * false otherwise. */ -AAUDIO_API void AAudioStreamBuilder_setPrivacySensitive(AAudioStreamBuilder* builder, +AAUDIO_API void AAudioStreamBuilder_setPrivacySensitive(AAudioStreamBuilder* _Nonnull builder, bool privacySensitive) __INTRODUCED_IN(30); /** @@ -1157,7 +1200,10 @@ typedef int32_t aaudio_data_callback_result_t; * in the streams current data format to the audioData buffer. * * For an input stream, this function should read and process numFrames of data - * from the audioData buffer. + * from the audioData buffer. The data in the audioData buffer must not be modified + * directly. Instead, it should be copied to another buffer before doing any modification. + * In many cases, writing to the audioData buffer of an input stream will result in a + * native exception. * * The audio data is passed through the buffer. So do NOT call AAudioStream_read() or * AAudioStream_write() on the stream that is making the callback. @@ -1197,9 +1243,9 @@ typedef int32_t aaudio_data_callback_result_t; * @return AAUDIO_CALLBACK_RESULT_* */ typedef aaudio_data_callback_result_t (*AAudioStream_dataCallback)( - AAudioStream *stream, - void *userData, - void *audioData, + AAudioStream* _Nonnull stream, + void* _Nullable userData, + void* _Nonnull audioData, int32_t numFrames); /** @@ -1228,8 +1274,9 @@ typedef aaudio_data_callback_result_t (*AAudioStream_dataCallback)( * @param userData pointer to an application data structure that will be passed * to the callback functions. */ -AAUDIO_API void AAudioStreamBuilder_setDataCallback(AAudioStreamBuilder* builder, - AAudioStream_dataCallback callback, void *userData) __INTRODUCED_IN(26); +AAUDIO_API void AAudioStreamBuilder_setDataCallback(AAudioStreamBuilder* _Nonnull builder, + AAudioStream_dataCallback _Nullable callback, void* _Nullable userData) + __INTRODUCED_IN(26); /** * Set the requested data callback buffer size in frames. @@ -1256,8 +1303,8 @@ AAUDIO_API void AAudioStreamBuilder_setDataCallback(AAudioStreamBuilder* builder * @param builder reference provided by AAudio_createStreamBuilder() * @param numFrames the desired buffer size in frames or {@link #AAUDIO_UNSPECIFIED} */ -AAUDIO_API void AAudioStreamBuilder_setFramesPerDataCallback(AAudioStreamBuilder* builder, - int32_t numFrames) __INTRODUCED_IN(26); +AAUDIO_API void AAudioStreamBuilder_setFramesPerDataCallback(AAudioStreamBuilder* _Nonnull builder, + int32_t numFrames) __INTRODUCED_IN(26); /** * Prototype for the callback function that is passed to @@ -1284,8 +1331,8 @@ AAUDIO_API void AAudioStreamBuilder_setFramesPerDataCallback(AAudioStreamBuilder * @param error an AAUDIO_ERROR_* value. */ typedef void (*AAudioStream_errorCallback)( - AAudioStream *stream, - void *userData, + AAudioStream* _Nonnull stream, + void* _Nullable userData, aaudio_result_t error); /** @@ -1311,8 +1358,9 @@ typedef void (*AAudioStream_errorCallback)( * @param userData pointer to an application data structure that will be passed * to the callback functions. */ -AAUDIO_API void AAudioStreamBuilder_setErrorCallback(AAudioStreamBuilder* builder, - AAudioStream_errorCallback callback, void *userData) __INTRODUCED_IN(26); +AAUDIO_API void AAudioStreamBuilder_setErrorCallback(AAudioStreamBuilder* _Nonnull builder, + AAudioStream_errorCallback _Nullable callback, void* _Nullable userData) + __INTRODUCED_IN(26); /** * Open a stream based on the options in the StreamBuilder. @@ -1326,8 +1374,8 @@ AAUDIO_API void AAudioStreamBuilder_setErrorCallback(AAudioStreamBuilder* builde * @param stream pointer to a variable to receive the new stream reference * @return {@link #AAUDIO_OK} or a negative error. */ -AAUDIO_API aaudio_result_t AAudioStreamBuilder_openStream(AAudioStreamBuilder* builder, - AAudioStream** stream) __INTRODUCED_IN(26); +AAUDIO_API aaudio_result_t AAudioStreamBuilder_openStream(AAudioStreamBuilder* _Nonnull builder, + AAudioStream* _Nullable* _Nonnull stream) __INTRODUCED_IN(26); /** * Delete the resources associated with the StreamBuilder. @@ -1337,7 +1385,7 @@ AAUDIO_API aaudio_result_t AAudioStreamBuilder_openStream(AAudioStreamBuilder* * @param builder reference provided by AAudio_createStreamBuilder() * @return {@link #AAUDIO_OK} or a negative error. */ -AAUDIO_API aaudio_result_t AAudioStreamBuilder_delete(AAudioStreamBuilder* builder) +AAUDIO_API aaudio_result_t AAudioStreamBuilder_delete(AAudioStreamBuilder* _Nonnull builder) __INTRODUCED_IN(26); /** @@ -1363,7 +1411,7 @@ AAUDIO_API aaudio_result_t AAudioStreamBuilder_delete(AAudioStreamBuilder* buil * @param builder reference provided by AAudio_createStreamBuilder() * @param channelMask Audio channel mask desired. */ -AAUDIO_API void AAudioStreamBuilder_setChannelMask(AAudioStreamBuilder* builder, +AAUDIO_API void AAudioStreamBuilder_setChannelMask(AAudioStreamBuilder* _Nonnull builder, aaudio_channel_mask_t channelMask) __INTRODUCED_IN(32); // ============================================================ @@ -1392,7 +1440,8 @@ AAUDIO_API void AAudioStreamBuilder_setChannelMask(AAudioStreamBuilder* builder, * @param stream reference provided by AAudioStreamBuilder_openStream() * @return {@link #AAUDIO_OK} or a negative error. */ -AAUDIO_API aaudio_result_t AAudioStream_release(AAudioStream* stream) __INTRODUCED_IN(30); +AAUDIO_API aaudio_result_t AAudioStream_release(AAudioStream* _Nonnull stream) + __INTRODUCED_IN(30); /** * Delete the internal data structures associated with the stream created @@ -1405,7 +1454,7 @@ AAUDIO_API aaudio_result_t AAudioStream_release(AAudioStream* stream) __INTRODU * @param stream reference provided by AAudioStreamBuilder_openStream() * @return {@link #AAUDIO_OK} or a negative error. */ -AAUDIO_API aaudio_result_t AAudioStream_close(AAudioStream* stream) __INTRODUCED_IN(26); +AAUDIO_API aaudio_result_t AAudioStream_close(AAudioStream* _Nonnull stream) __INTRODUCED_IN(26); /** * Asynchronously request to start playing the stream. For output streams, one should @@ -1419,7 +1468,8 @@ AAUDIO_API aaudio_result_t AAudioStream_close(AAudioStream* stream) __INTRODUCE * @param stream reference provided by AAudioStreamBuilder_openStream() * @return {@link #AAUDIO_OK} or a negative error. */ -AAUDIO_API aaudio_result_t AAudioStream_requestStart(AAudioStream* stream) __INTRODUCED_IN(26); +AAUDIO_API aaudio_result_t AAudioStream_requestStart(AAudioStream* _Nonnull stream) + __INTRODUCED_IN(26); /** * Asynchronous request for the stream to pause. @@ -1436,12 +1486,16 @@ AAUDIO_API aaudio_result_t AAudioStream_requestStart(AAudioStream* stream) __IN * @param stream reference provided by AAudioStreamBuilder_openStream() * @return {@link #AAUDIO_OK} or a negative error. */ -AAUDIO_API aaudio_result_t AAudioStream_requestPause(AAudioStream* stream) __INTRODUCED_IN(26); +AAUDIO_API aaudio_result_t AAudioStream_requestPause(AAudioStream* _Nonnull stream) + __INTRODUCED_IN(26); /** * Asynchronous request for the stream to flush. * Flushing will discard any pending data. - * This call only works if the stream is pausing or paused. TODO review + * This call only works if the stream is OPEN, PAUSED, STOPPED, or FLUSHED. + * Calling this function when in other states, + * or calling from an AAudio callback function, + * will have no effect and an error will be returned. * Frame counters are not reset by a flush. They may be advanced. * After this call the state will be in {@link #AAUDIO_STREAM_STATE_FLUSHING} or * {@link #AAUDIO_STREAM_STATE_FLUSHED}. @@ -1453,7 +1507,8 @@ AAUDIO_API aaudio_result_t AAudioStream_requestPause(AAudioStream* stream) __IN * @param stream reference provided by AAudioStreamBuilder_openStream() * @return {@link #AAUDIO_OK} or a negative error. */ -AAUDIO_API aaudio_result_t AAudioStream_requestFlush(AAudioStream* stream) __INTRODUCED_IN(26); +AAUDIO_API aaudio_result_t AAudioStream_requestFlush(AAudioStream* _Nonnull stream) + __INTRODUCED_IN(26); /** * Asynchronous request for the stream to stop. @@ -1466,7 +1521,8 @@ AAUDIO_API aaudio_result_t AAudioStream_requestFlush(AAudioStream* stream) __IN * @param stream reference provided by AAudioStreamBuilder_openStream() * @return {@link #AAUDIO_OK} or a negative error. */ -AAUDIO_API aaudio_result_t AAudioStream_requestStop(AAudioStream* stream) __INTRODUCED_IN(26); +AAUDIO_API aaudio_result_t AAudioStream_requestStop(AAudioStream* _Nonnull stream) + __INTRODUCED_IN(26); /** * Query the current state of the client, eg. {@link #AAUDIO_STREAM_STATE_PAUSING} @@ -1480,7 +1536,8 @@ AAUDIO_API aaudio_result_t AAudioStream_requestStop(AAudioStream* stream) __INT * * @param stream reference provided by AAudioStreamBuilder_openStream() */ -AAUDIO_API aaudio_stream_state_t AAudioStream_getState(AAudioStream* stream) __INTRODUCED_IN(26); +AAUDIO_API aaudio_stream_state_t AAudioStream_getState(AAudioStream* _Nonnull stream) + __INTRODUCED_IN(26); /** * Wait until the current state no longer matches the input state. @@ -1506,8 +1563,8 @@ AAUDIO_API aaudio_stream_state_t AAudioStream_getState(AAudioStream* stream) __I * @param timeoutNanoseconds Maximum number of nanoseconds to wait for completion. * @return {@link #AAUDIO_OK} or a negative error. */ -AAUDIO_API aaudio_result_t AAudioStream_waitForStateChange(AAudioStream* stream, - aaudio_stream_state_t inputState, aaudio_stream_state_t *nextState, +AAUDIO_API aaudio_result_t AAudioStream_waitForStateChange(AAudioStream* _Nonnull stream, + aaudio_stream_state_t inputState, aaudio_stream_state_t* _Nullable nextState, int64_t timeoutNanoseconds) __INTRODUCED_IN(26); // ============================================================ @@ -1536,8 +1593,8 @@ AAUDIO_API aaudio_result_t AAudioStream_waitForStateChange(AAudioStream* stream, * @param timeoutNanoseconds Maximum number of nanoseconds to wait for completion. * @return The number of frames actually read or a negative error. */ -AAUDIO_API aaudio_result_t AAudioStream_read(AAudioStream* stream, - void *buffer, int32_t numFrames, int64_t timeoutNanoseconds) __INTRODUCED_IN(26); +AAUDIO_API aaudio_result_t AAudioStream_read(AAudioStream* _Nonnull stream, + void* _Nonnull buffer, int32_t numFrames, int64_t timeoutNanoseconds) __INTRODUCED_IN(26); /** * Write data to the stream. @@ -1561,8 +1618,9 @@ AAUDIO_API aaudio_result_t AAudioStream_read(AAudioStream* stream, * @param timeoutNanoseconds Maximum number of nanoseconds to wait for completion. * @return The number of frames actually written or a negative error. */ -AAUDIO_API aaudio_result_t AAudioStream_write(AAudioStream* stream, - const void *buffer, int32_t numFrames, int64_t timeoutNanoseconds) __INTRODUCED_IN(26); +AAUDIO_API aaudio_result_t AAudioStream_write(AAudioStream* _Nonnull stream, + const void* _Nonnull buffer, int32_t numFrames, int64_t timeoutNanoseconds) + __INTRODUCED_IN(26); // ============================================================ // Stream - queries @@ -1586,7 +1644,7 @@ AAUDIO_API aaudio_result_t AAudioStream_write(AAudioStream* stream, * @param numFrames requested number of frames that can be filled without blocking * @return actual buffer size in frames or a negative error */ -AAUDIO_API aaudio_result_t AAudioStream_setBufferSizeInFrames(AAudioStream* stream, +AAUDIO_API aaudio_result_t AAudioStream_setBufferSizeInFrames(AAudioStream* _Nonnull stream, int32_t numFrames) __INTRODUCED_IN(26); /** @@ -1597,7 +1655,8 @@ AAUDIO_API aaudio_result_t AAudioStream_setBufferSizeInFrames(AAudioStream* stre * @param stream reference provided by AAudioStreamBuilder_openStream() * @return buffer size in frames. */ -AAUDIO_API int32_t AAudioStream_getBufferSizeInFrames(AAudioStream* stream) __INTRODUCED_IN(26); +AAUDIO_API int32_t AAudioStream_getBufferSizeInFrames(AAudioStream* _Nonnull stream) + __INTRODUCED_IN(26); /** * Query the number of frames that the application should read or write at @@ -1614,7 +1673,8 @@ AAUDIO_API int32_t AAudioStream_getBufferSizeInFrames(AAudioStream* stream) __IN * @param stream reference provided by AAudioStreamBuilder_openStream() * @return burst size */ -AAUDIO_API int32_t AAudioStream_getFramesPerBurst(AAudioStream* stream) __INTRODUCED_IN(26); +AAUDIO_API int32_t AAudioStream_getFramesPerBurst(AAudioStream* _Nonnull stream) + __INTRODUCED_IN(26); /** * Query maximum buffer capacity in frames. @@ -1624,7 +1684,8 @@ AAUDIO_API int32_t AAudioStream_getFramesPerBurst(AAudioStream* stream) __INTROD * @param stream reference provided by AAudioStreamBuilder_openStream() * @return buffer capacity in frames */ -AAUDIO_API int32_t AAudioStream_getBufferCapacityInFrames(AAudioStream* stream) __INTRODUCED_IN(26); +AAUDIO_API int32_t AAudioStream_getBufferCapacityInFrames(AAudioStream* _Nonnull stream) + __INTRODUCED_IN(26); /** * Query the size of the buffer that will be passed to the dataProc callback @@ -1647,7 +1708,8 @@ AAUDIO_API int32_t AAudioStream_getBufferCapacityInFrames(AAudioStream* stream) * @param stream reference provided by AAudioStreamBuilder_openStream() * @return callback buffer size in frames or {@link #AAUDIO_UNSPECIFIED} */ -AAUDIO_API int32_t AAudioStream_getFramesPerDataCallback(AAudioStream* stream) __INTRODUCED_IN(26); +AAUDIO_API int32_t AAudioStream_getFramesPerDataCallback(AAudioStream* _Nonnull stream) + __INTRODUCED_IN(26); /** * An XRun is an Underrun or an Overrun. @@ -1666,15 +1728,31 @@ AAUDIO_API int32_t AAudioStream_getFramesPerDataCallback(AAudioStream* stream) _ * @param stream reference provided by AAudioStreamBuilder_openStream() * @return the underrun or overrun count */ -AAUDIO_API int32_t AAudioStream_getXRunCount(AAudioStream* stream) __INTRODUCED_IN(26); +AAUDIO_API int32_t AAudioStream_getXRunCount(AAudioStream* _Nonnull stream) __INTRODUCED_IN(26); /** * Available since API level 26. * * @param stream reference provided by AAudioStreamBuilder_openStream() - * @return actual sample rate + * @return actual sample rate of the stream + */ +AAUDIO_API int32_t AAudioStream_getSampleRate(AAudioStream* _Nonnull stream) __INTRODUCED_IN(26); + +/** + * There may be sample rate conversions in the Audio framework. + * The sample rate set in the stream builder may not be actual sample rate used in the hardware. + * + * This returns the sample rate used by the hardware in Hertz. + * + * If AAudioStreamBuilder_openStream() returned AAUDIO_OK, the result should always be valid. + * + * Available since API level 34. + * + * @param stream reference provided by AAudioStreamBuilder_openStream() + * @return actual sample rate of the underlying hardware */ -AAUDIO_API int32_t AAudioStream_getSampleRate(AAudioStream* stream) __INTRODUCED_IN(26); +AAUDIO_API int32_t AAudioStream_getHardwareSampleRate(AAudioStream* _Nonnull stream) + __INTRODUCED_IN(__ANDROID_API_U__); /** * A stream has one or more channels of data. @@ -1683,9 +1761,26 @@ AAUDIO_API int32_t AAudioStream_getSampleRate(AAudioStream* stream) __INTRODUCED * Available since API level 26. * * @param stream reference provided by AAudioStreamBuilder_openStream() - * @return actual number of channels + * @return actual number of channels of the stream + */ +AAUDIO_API int32_t AAudioStream_getChannelCount(AAudioStream* _Nonnull stream) __INTRODUCED_IN(26); + +/** + * There may be channel conversions in the Audio framework. + * The channel count or channel mask set in the stream builder may not be actual number of + * channels used in the hardware. + * + * This returns the channel count used by the hardware. + * + * If AAudioStreamBuilder_openStream() returned AAUDIO_OK, the result should always be valid. + * + * Available since API level 34. + * + * @param stream reference provided by AAudioStreamBuilder_openStream() + * @return actual number of channels of the underlying hardware */ -AAUDIO_API int32_t AAudioStream_getChannelCount(AAudioStream* stream) __INTRODUCED_IN(26); +AAUDIO_API int32_t AAudioStream_getHardwareChannelCount(AAudioStream* _Nonnull stream) + __INTRODUCED_IN(__ANDROID_API_U__); /** * Identical to AAudioStream_getChannelCount(). @@ -1695,7 +1790,8 @@ AAUDIO_API int32_t AAudioStream_getChannelCount(AAudioStream* stream) __INTRODUC * @param stream reference provided by AAudioStreamBuilder_openStream() * @return actual number of samples frame */ -AAUDIO_API int32_t AAudioStream_getSamplesPerFrame(AAudioStream* stream) __INTRODUCED_IN(26); +AAUDIO_API int32_t AAudioStream_getSamplesPerFrame(AAudioStream* _Nonnull stream) + __INTRODUCED_IN(26); /** * Available since API level 26. @@ -1703,15 +1799,39 @@ AAUDIO_API int32_t AAudioStream_getSamplesPerFrame(AAudioStream* stream) __INTRO * @param stream reference provided by AAudioStreamBuilder_openStream() * @return actual device ID */ -AAUDIO_API int32_t AAudioStream_getDeviceId(AAudioStream* stream) __INTRODUCED_IN(26); +AAUDIO_API int32_t AAudioStream_getDeviceId(AAudioStream* _Nonnull stream) __INTRODUCED_IN(26); /** * Available since API level 26. * * @param stream reference provided by AAudioStreamBuilder_openStream() - * @return actual data format + * @return actual data format of the stream */ -AAUDIO_API aaudio_format_t AAudioStream_getFormat(AAudioStream* stream) __INTRODUCED_IN(26); +AAUDIO_API aaudio_format_t AAudioStream_getFormat(AAudioStream* _Nonnull stream) + __INTRODUCED_IN(26); + +/** + * There may be data format conversions in the Audio framework. + * The data format set in the stream builder may not be actual format used in the hardware. + * + * This returns the audio format used by the hardware. + * + * If AAudioStreamBuilder_openStream() returned AAUDIO_OK, this should always return an + * aaudio_format_t. + * + * AUDIO_FORMAT_PCM_8_24_BIT is currently not supported in AAudio, but the hardware may use it. + * If AUDIO_FORMAT_PCM_8_24_BIT is used by the hardware, return AAUDIO_FORMAT_PCM_I24_PACKED. + * + * If any other format used by the hardware is not supported by AAudio, this will return + * AAUDIO_FORMAT_INVALID. + * + * Available since API level 34. + * + * @param stream reference provided by AAudioStreamBuilder_openStream() + * @return actual data format of the underlying hardware. + */ +AAUDIO_API aaudio_format_t AAudioStream_getHardwareFormat(AAudioStream* _Nonnull stream) + __INTRODUCED_IN(__ANDROID_API_U__); /** * Provide actual sharing mode. @@ -1721,7 +1841,7 @@ AAUDIO_API aaudio_format_t AAudioStream_getFormat(AAudioStream* stream) __INTROD * @param stream reference provided by AAudioStreamBuilder_openStream() * @return actual sharing mode */ -AAUDIO_API aaudio_sharing_mode_t AAudioStream_getSharingMode(AAudioStream* stream) +AAUDIO_API aaudio_sharing_mode_t AAudioStream_getSharingMode(AAudioStream* _Nonnull stream) __INTRODUCED_IN(26); /** @@ -1731,7 +1851,7 @@ AAUDIO_API aaudio_sharing_mode_t AAudioStream_getSharingMode(AAudioStream* strea * * @param stream reference provided by AAudioStreamBuilder_openStream() */ -AAUDIO_API aaudio_performance_mode_t AAudioStream_getPerformanceMode(AAudioStream* stream) +AAUDIO_API aaudio_performance_mode_t AAudioStream_getPerformanceMode(AAudioStream* _Nonnull stream) __INTRODUCED_IN(26); /** @@ -1740,7 +1860,8 @@ AAUDIO_API aaudio_performance_mode_t AAudioStream_getPerformanceMode(AAudioStrea * @param stream reference provided by AAudioStreamBuilder_openStream() * @return direction */ -AAUDIO_API aaudio_direction_t AAudioStream_getDirection(AAudioStream* stream) __INTRODUCED_IN(26); +AAUDIO_API aaudio_direction_t AAudioStream_getDirection(AAudioStream* _Nonnull stream) + __INTRODUCED_IN(26); /** * Passes back the number of frames that have been written since the stream was created. @@ -1755,7 +1876,8 @@ AAUDIO_API aaudio_direction_t AAudioStream_getDirection(AAudioStream* stream) __ * @param stream reference provided by AAudioStreamBuilder_openStream() * @return frames written */ -AAUDIO_API int64_t AAudioStream_getFramesWritten(AAudioStream* stream) __INTRODUCED_IN(26); +AAUDIO_API int64_t AAudioStream_getFramesWritten(AAudioStream* _Nonnull stream) + __INTRODUCED_IN(26); /** * Passes back the number of frames that have been read since the stream was created. @@ -1770,7 +1892,7 @@ AAUDIO_API int64_t AAudioStream_getFramesWritten(AAudioStream* stream) __INTRODU * @param stream reference provided by AAudioStreamBuilder_openStream() * @return frames read */ -AAUDIO_API int64_t AAudioStream_getFramesRead(AAudioStream* stream) __INTRODUCED_IN(26); +AAUDIO_API int64_t AAudioStream_getFramesRead(AAudioStream* _Nonnull stream) __INTRODUCED_IN(26); /** * Passes back the session ID associated with this stream. @@ -1795,7 +1917,8 @@ AAUDIO_API int64_t AAudioStream_getFramesRead(AAudioStream* stream) __INTRODUCED * @param stream reference provided by AAudioStreamBuilder_openStream() * @return session ID or {@link #AAUDIO_SESSION_ID_NONE} */ -AAUDIO_API aaudio_session_id_t AAudioStream_getSessionId(AAudioStream* stream) __INTRODUCED_IN(28); +AAUDIO_API aaudio_session_id_t AAudioStream_getSessionId(AAudioStream* _Nonnull stream) + __INTRODUCED_IN(28); /** * Passes back the time at which a particular frame was presented. @@ -1821,8 +1944,9 @@ AAUDIO_API aaudio_session_id_t AAudioStream_getSessionId(AAudioStream* stream) _ * @param timeNanoseconds pointer to a variable to receive the time * @return {@link #AAUDIO_OK} or a negative error */ -AAUDIO_API aaudio_result_t AAudioStream_getTimestamp(AAudioStream* stream, - clockid_t clockid, int64_t *framePosition, int64_t *timeNanoseconds) __INTRODUCED_IN(26); +AAUDIO_API aaudio_result_t AAudioStream_getTimestamp(AAudioStream* _Nonnull stream, + clockid_t clockid, int64_t* _Nonnull framePosition, int64_t* _Nonnull timeNanoseconds) + __INTRODUCED_IN(26); /** * Return the use case for the stream. @@ -1832,7 +1956,7 @@ AAUDIO_API aaudio_result_t AAudioStream_getTimestamp(AAudioStream* stream, * @param stream reference provided by AAudioStreamBuilder_openStream() * @return frames read */ -AAUDIO_API aaudio_usage_t AAudioStream_getUsage(AAudioStream* stream) __INTRODUCED_IN(28); +AAUDIO_API aaudio_usage_t AAudioStream_getUsage(AAudioStream* _Nonnull stream) __INTRODUCED_IN(28); /** * Return the content type for the stream. @@ -1842,7 +1966,7 @@ AAUDIO_API aaudio_usage_t AAudioStream_getUsage(AAudioStream* stream) __INTRODUC * @param stream reference provided by AAudioStreamBuilder_openStream() * @return content type, for example {@link #AAUDIO_CONTENT_TYPE_MUSIC} */ -AAUDIO_API aaudio_content_type_t AAudioStream_getContentType(AAudioStream* stream) +AAUDIO_API aaudio_content_type_t AAudioStream_getContentType(AAudioStream* _Nonnull stream) __INTRODUCED_IN(28); /** @@ -1857,7 +1981,7 @@ AAUDIO_API aaudio_content_type_t AAudioStream_getContentType(AAudioStream* strea * @return spatialization behavior, for example {@link #AAUDIO_SPATIALIZATION_BEHAVIOR_AUTO} */ AAUDIO_API aaudio_spatialization_behavior_t AAudioStream_getSpatializationBehavior( - AAudioStream* stream) __INTRODUCED_IN(32); + AAudioStream* _Nonnull stream) __INTRODUCED_IN(32); /** * Return whether the content of the stream is spatialized. @@ -1867,7 +1991,8 @@ AAUDIO_API aaudio_spatialization_behavior_t AAudioStream_getSpatializationBehavi * @param stream reference provided by AAudioStreamBuilder_openStream() * @return true if the content is spatialized */ -AAUDIO_API bool AAudioStream_isContentSpatialized(AAudioStream* stream) __INTRODUCED_IN(32); +AAUDIO_API bool AAudioStream_isContentSpatialized(AAudioStream* _Nonnull stream) + __INTRODUCED_IN(32); /** @@ -1878,7 +2003,7 @@ AAUDIO_API bool AAudioStream_isContentSpatialized(AAudioStream* stream) __INTROD * @param stream reference provided by AAudioStreamBuilder_openStream() * @return input preset, for example {@link #AAUDIO_INPUT_PRESET_CAMCORDER} */ -AAUDIO_API aaudio_input_preset_t AAudioStream_getInputPreset(AAudioStream* stream) +AAUDIO_API aaudio_input_preset_t AAudioStream_getInputPreset(AAudioStream* _Nonnull stream) __INTRODUCED_IN(28); /** @@ -1891,7 +2016,7 @@ AAUDIO_API aaudio_input_preset_t AAudioStream_getInputPreset(AAudioStream* strea * @return the allowed capture policy, for example {@link #AAUDIO_ALLOW_CAPTURE_BY_ALL} */ AAUDIO_API aaudio_allowed_capture_policy_t AAudioStream_getAllowedCapturePolicy( - AAudioStream* stream) __INTRODUCED_IN(29); + AAudioStream* _Nonnull stream) __INTRODUCED_IN(29); /** @@ -1904,7 +2029,7 @@ AAUDIO_API aaudio_allowed_capture_policy_t AAudioStream_getAllowedCapturePolicy( * @param stream reference provided by AAudioStreamBuilder_openStream() * @return true if privacy sensitive, false otherwise */ -AAUDIO_API bool AAudioStream_isPrivacySensitive(AAudioStream* stream) +AAUDIO_API bool AAudioStream_isPrivacySensitive(AAudioStream* _Nonnull stream) __INTRODUCED_IN(30); /** @@ -1916,7 +2041,7 @@ AAUDIO_API bool AAudioStream_isPrivacySensitive(AAudioStream* stream) * @param stream reference provided by AAudioStreamBuilder_openStream() * @return actual channel mask */ -AAUDIO_API aaudio_channel_mask_t AAudioStream_getChannelMask(AAudioStream* stream) +AAUDIO_API aaudio_channel_mask_t AAudioStream_getChannelMask(AAudioStream* _Nonnull stream) __INTRODUCED_IN(32); #ifdef __cplusplus |