Consistently say "Available since API level".
Bug: http://b/143470841
Test: treehugger
Change-Id: I716a1b407a694edf1150b7dee6d1a901aa8f238b
diff --git a/media/libaaudio/include/aaudio/AAudio.h b/media/libaaudio/include/aaudio/AAudio.h
index ee5d089..8173e3c 100644
--- a/media/libaaudio/include/aaudio/AAudio.h
+++ b/media/libaaudio/include/aaudio/AAudio.h
@@ -472,6 +472,8 @@
* This is intended for developers to use when debugging.
* It is not for display to users.
*
+ * Available since API level 26.
+ *
* @return pointer to a text representation of an AAudio result code.
*/
AAUDIO_API const char * AAudio_convertResultToText(aaudio_result_t returnCode) __INTRODUCED_IN(26);
@@ -482,6 +484,8 @@
* This is intended for developers to use when debugging.
* It is not for display to users.
*
+ * Available since API level 26.
+ *
* @return pointer to a text representation of an AAudio state.
*/
AAUDIO_API const char * AAudio_convertStreamStateToText(aaudio_stream_state_t state)
@@ -502,6 +506,8 @@
* chosen by the device when it is opened.
*
* AAudioStreamBuilder_delete() must be called when you are done using the builder.
+ *
+ * Available since API level 26.
*/
AAUDIO_API aaudio_result_t AAudio_createStreamBuilder(AAudioStreamBuilder** builder)
__INTRODUCED_IN(26);
@@ -513,6 +519,8 @@
* The default, if you do not call this function, is {@link #AAUDIO_UNSPECIFIED},
* in which case the primary device will be used.
*
+ * Available since API level 26.
+ *
* @param builder reference provided by AAudio_createStreamBuilder()
* @param deviceId device identifier or {@link #AAUDIO_UNSPECIFIED}
*/
@@ -530,6 +538,8 @@
* If an exact value is specified then an opened stream will use that value.
* If a stream cannot be opened with the specified value then the open will fail.
*
+ * Available since API level 26.
+ *
* @param builder reference provided by AAudio_createStreamBuilder()
* @param sampleRate frames per second. Common rates include 44100 and 48000 Hz.
*/
@@ -547,6 +557,8 @@
* If an exact value is specified then an opened stream will use that value.
* If a stream cannot be opened with the specified value then the open will fail.
*
+ * Available since API level 26.
+ *
* @param builder reference provided by AAudio_createStreamBuilder()
* @param channelCount Number of channels desired.
*/
@@ -556,6 +568,8 @@
/**
* Identical to AAudioStreamBuilder_setChannelCount().
*
+ * Available since API level 26.
+ *
* @param builder reference provided by AAudio_createStreamBuilder()
* @param samplesPerFrame Number of samples in a frame.
*/
@@ -573,6 +587,8 @@
* If an exact value is specified then an opened stream will use that value.
* If a stream cannot be opened with the specified value then the open will fail.
*
+ * Available since API level 26.
+ *
* @param builder reference provided by AAudio_createStreamBuilder()
* @param format common formats are {@link #AAUDIO_FORMAT_PCM_FLOAT} and
* {@link #AAUDIO_FORMAT_PCM_I16}.
@@ -588,6 +604,8 @@
* The requested sharing mode may not be available.
* The application can query for the actual mode after the stream is opened.
*
+ * Available since API level 26.
+ *
* @param builder reference provided by AAudio_createStreamBuilder()
* @param sharingMode {@link #AAUDIO_SHARING_MODE_SHARED} or {@link #AAUDIO_SHARING_MODE_EXCLUSIVE}
*/
@@ -599,6 +617,8 @@
*
* The default, if you do not call this function, is {@link #AAUDIO_DIRECTION_OUTPUT}.
*
+ * Available since API level 26.
+ *
* @param builder reference provided by AAudio_createStreamBuilder()
* @param direction {@link #AAUDIO_DIRECTION_OUTPUT} or {@link #AAUDIO_DIRECTION_INPUT}
*/
@@ -611,6 +631,8 @@
*
* The default, if you do not call this function, is {@link #AAUDIO_UNSPECIFIED}.
*
+ * Available since API level 26.
+ *
* @param builder reference provided by AAudio_createStreamBuilder()
* @param numFrames the desired buffer capacity in frames or {@link #AAUDIO_UNSPECIFIED}
*/
@@ -629,6 +651,8 @@
* You can call AAudioStream_getPerformanceMode()
* to find out the final mode for the stream.
*
+ * Available since API level 26.
+ *
* @param builder reference provided by AAudio_createStreamBuilder()
* @param mode the desired performance mode, eg. {@link #AAUDIO_PERFORMANCE_MODE_LOW_LATENCY}
*/
@@ -644,7 +668,7 @@
*
* The default, if you do not call this function, is {@link #AAUDIO_USAGE_MEDIA}.
*
- * Added in API level 28.
+ * Available since API level 28.
*
* @param builder reference provided by AAudio_createStreamBuilder()
* @param usage the desired usage, eg. {@link #AAUDIO_USAGE_GAME}
@@ -661,7 +685,7 @@
*
* The default, if you do not call this function, is {@link #AAUDIO_CONTENT_TYPE_MUSIC}.
*
- * Added in API level 28.
+ * Available since API level 28.
*
* @param builder reference provided by AAudio_createStreamBuilder()
* @param contentType the type of audio data, eg. {@link #AAUDIO_CONTENT_TYPE_SPEECH}
@@ -681,7 +705,7 @@
* That is because VOICE_RECOGNITION is the preset with the lowest latency
* on many platforms.
*
- * Added in API level 28.
+ * Available since API level 28.
*
* @param builder reference provided by AAudio_createStreamBuilder()
* @param inputPreset the desired configuration for recording
@@ -697,7 +721,7 @@
* Note that an application can also set its global policy, in which case the most restrictive
* policy is always applied. See {@link android.media.AudioAttributes#setAllowedCapturePolicy(int)}
*
- * Added in API level 29.
+ * Available since API level 29.
*
* @param builder reference provided by AAudio_createStreamBuilder()
* @param inputPreset the desired level of opt-out from being captured.
@@ -727,7 +751,7 @@
*
* Allocated session IDs will always be positive and nonzero.
*
- * Added in API level 28.
+ * Available since API level 28.
*
* @param builder reference provided by AAudio_createStreamBuilder()
* @param sessionId an allocated sessionID or {@link #AAUDIO_SESSION_ID_ALLOCATE}
@@ -826,6 +850,8 @@
*
* Note that the AAudio callbacks will never be called simultaneously from multiple threads.
*
+ * Available since API level 26.
+ *
* @param builder reference provided by AAudio_createStreamBuilder()
* @param callback pointer to a function that will process audio data.
* @param userData pointer to an application data structure that will be passed
@@ -854,6 +880,8 @@
* If you do call this function then the requested size should be less than
* half the buffer capacity, to allow double buffering.
*
+ * Available since API level 26.
+ *
* @param builder reference provided by AAudio_createStreamBuilder()
* @param numFrames the desired buffer size in frames or {@link #AAUDIO_UNSPECIFIED}
*/
@@ -905,6 +933,8 @@
*
* Note that the AAudio callbacks will never be called simultaneously from multiple threads.
*
+ * Available since API level 26.
+ *
* @param builder reference provided by AAudio_createStreamBuilder()
* @param callback pointer to a function that will be called if an error occurs.
* @param userData pointer to an application data structure that will be passed
@@ -919,6 +949,8 @@
* AAudioStream_close() must be called when finished with the stream to recover
* the memory and to free the associated resources.
*
+ * Available since API level 26.
+ *
* @param builder reference provided by AAudio_createStreamBuilder()
* @param stream pointer to a variable to receive the new stream reference
* @return {@link #AAUDIO_OK} or a negative error.
@@ -929,6 +961,8 @@
/**
* Delete the resources associated with the StreamBuilder.
*
+ * Available since API level 26.
+ *
* @param builder reference provided by AAudio_createStreamBuilder()
* @return {@link #AAUDIO_OK} or a negative error.
*/
@@ -942,6 +976,8 @@
/**
* Free the resources associated with a stream created by AAudioStreamBuilder_openStream()
*
+ * Available since API level 26.
+ *
* @param stream reference provided by AAudioStreamBuilder_openStream()
* @return {@link #AAUDIO_OK} or a negative error.
*/
@@ -954,6 +990,8 @@
* After this call the state will be in {@link #AAUDIO_STREAM_STATE_STARTING} or
* {@link #AAUDIO_STREAM_STATE_STARTED}.
*
+ * Available since API level 26.
+ *
* @param stream reference provided by AAudioStreamBuilder_openStream()
* @return {@link #AAUDIO_OK} or a negative error.
*/
@@ -969,6 +1007,8 @@
* This will return {@link #AAUDIO_ERROR_UNIMPLEMENTED} for input streams.
* For input streams use AAudioStream_requestStop().
*
+ * Available since API level 26.
+ *
* @param stream reference provided by AAudioStreamBuilder_openStream()
* @return {@link #AAUDIO_OK} or a negative error.
*/
@@ -984,6 +1024,8 @@
*
* This will return {@link #AAUDIO_ERROR_UNIMPLEMENTED} for input streams.
*
+ * Available since API level 26.
+ *
* @param stream reference provided by AAudioStreamBuilder_openStream()
* @return {@link #AAUDIO_OK} or a negative error.
*/
@@ -995,6 +1037,8 @@
* After this call the state will be in {@link #AAUDIO_STREAM_STATE_STOPPING} or
* {@link #AAUDIO_STREAM_STATE_STOPPED}.
*
+ * Available since API level 26.
+ *
* @param stream reference provided by AAudioStreamBuilder_openStream()
* @return {@link #AAUDIO_OK} or a negative error.
*/
@@ -1008,6 +1052,8 @@
* call AAudioStream_waitForStateChange() with currentState
* set to {@link #AAUDIO_STREAM_STATE_UNKNOWN} and a zero timeout.
*
+ * Available since API level 26.
+ *
* @param stream reference provided by AAudioStreamBuilder_openStream()
*/
AAUDIO_API aaudio_stream_state_t AAudioStream_getState(AAudioStream* stream) __INTRODUCED_IN(26);
@@ -1028,6 +1074,8 @@
* }
* </code></pre>
*
+ * Available since API level 26.
+ *
* @param stream A reference provided by AAudioStreamBuilder_openStream()
* @param inputState The state we want to avoid.
* @param nextState Pointer to a variable that will be set to the new state.
@@ -1056,6 +1104,8 @@
*
* If the call times out then zero or a partial frame count will be returned.
*
+ * Available since API level 26.
+ *
* @param stream A stream created using AAudioStreamBuilder_openStream().
* @param buffer The address of the first sample.
* @param numFrames Number of frames to read. Only complete frames will be written.
@@ -1079,6 +1129,8 @@
*
* If the call times out then zero or a partial frame count will be returned.
*
+ * Available since API level 26.
+ *
* @param stream A stream created using AAudioStreamBuilder_openStream().
* @param buffer The address of the first sample.
* @param numFrames Number of frames to write. Only complete frames will be written.
@@ -1104,6 +1156,8 @@
* You can check the return value or call AAudioStream_getBufferSizeInFrames()
* to see what the actual final size is.
*
+ * Available since API level 26.
+ *
* @param stream reference provided by AAudioStreamBuilder_openStream()
* @param numFrames requested number of frames that can be filled without blocking
* @return actual buffer size in frames or a negative error
@@ -1114,6 +1168,8 @@
/**
* Query the maximum number of frames that can be filled without blocking.
*
+ * Available since API level 26.
+ *
* @param stream reference provided by AAudioStreamBuilder_openStream()
* @return buffer size in frames.
*/
@@ -1129,6 +1185,8 @@
* For some endpoints, the burst size can vary dynamically.
* But these tend to be devices with high latency.
*
+ * Available since API level 26.
+ *
* @param stream reference provided by AAudioStreamBuilder_openStream()
* @return burst size
*/
@@ -1137,6 +1195,8 @@
/**
* Query maximum buffer capacity in frames.
*
+ * Available since API level 26.
+ *
* @param stream reference provided by AAudioStreamBuilder_openStream()
* @return buffer capacity in frames
*/
@@ -1158,6 +1218,8 @@
* {@link #AAUDIO_UNSPECIFIED} indicates that the callback buffer size for this stream
* may vary from one dataProc callback to the next.
*
+ * Available since API level 26.
+ *
* @param stream reference provided by AAudioStreamBuilder_openStream()
* @return callback buffer size in frames or {@link #AAUDIO_UNSPECIFIED}
*/
@@ -1175,12 +1237,16 @@
* Note that some INPUT devices may not support this function.
* In that case a 0 will always be returned.
*
+ * Available since API level 26.
+ *
* @param stream reference provided by AAudioStreamBuilder_openStream()
* @return the underrun or overrun count
*/
AAUDIO_API int32_t AAudioStream_getXRunCount(AAudioStream* stream) __INTRODUCED_IN(26);
/**
+ * Available since API level 26.
+ *
* @param stream reference provided by AAudioStreamBuilder_openStream()
* @return actual sample rate
*/
@@ -1190,6 +1256,8 @@
* A stream has one or more channels of data.
* A frame will contain one sample for each channel.
*
+ * Available since API level 26.
+ *
* @param stream reference provided by AAudioStreamBuilder_openStream()
* @return actual number of channels
*/
@@ -1198,18 +1266,24 @@
/**
* Identical to AAudioStream_getChannelCount().
*
+ * Available since API level 26.
+ *
* @param stream reference provided by AAudioStreamBuilder_openStream()
* @return actual number of samples frame
*/
AAUDIO_API int32_t AAudioStream_getSamplesPerFrame(AAudioStream* stream) __INTRODUCED_IN(26);
/**
+ * Available since API level 26.
+ *
* @param stream reference provided by AAudioStreamBuilder_openStream()
* @return actual device ID
*/
AAUDIO_API int32_t AAudioStream_getDeviceId(AAudioStream* stream) __INTRODUCED_IN(26);
/**
+ * Available since API level 26.
+ *
* @param stream reference provided by AAudioStreamBuilder_openStream()
* @return actual data format
*/
@@ -1217,6 +1291,9 @@
/**
* Provide actual sharing mode.
+ *
+ * Available since API level 26.
+ *
* @param stream reference provided by AAudioStreamBuilder_openStream()
* @return actual sharing mode
*/
@@ -1226,12 +1303,16 @@
/**
* Get the performance mode used by the stream.
*
+ * Available since API level 26.
+ *
* @param stream reference provided by AAudioStreamBuilder_openStream()
*/
AAUDIO_API aaudio_performance_mode_t AAudioStream_getPerformanceMode(AAudioStream* stream)
__INTRODUCED_IN(26);
/**
+ * Available since API level 26.
+ *
* @param stream reference provided by AAudioStreamBuilder_openStream()
* @return direction
*/
@@ -1245,6 +1326,8 @@
*
* The frame position is monotonically increasing.
*
+ * Available since API level 26.
+ *
* @param stream reference provided by AAudioStreamBuilder_openStream()
* @return frames written
*/
@@ -1258,6 +1341,8 @@
*
* The frame position is monotonically increasing.
*
+ * Available since API level 26.
+ *
* @param stream reference provided by AAudioStreamBuilder_openStream()
* @return frames read
*/
@@ -1281,7 +1366,7 @@
*
* The sessionID for a stream should not change once the stream has been opened.
*
- * Added in API level 28.
+ * Available since API level 28.
*
* @param stream reference provided by AAudioStreamBuilder_openStream()
* @return session ID or {@link #AAUDIO_SESSION_ID_NONE}
@@ -1304,6 +1389,8 @@
*
* The position and time passed back are monotonically increasing.
*
+ * Available since API level 26.
+ *
* @param stream reference provided by AAudioStreamBuilder_openStream()
* @param clockid CLOCK_MONOTONIC or CLOCK_BOOTTIME
* @param framePosition pointer to a variable to receive the position
@@ -1316,7 +1403,7 @@
/**
* Return the use case for the stream.
*
- * Added in API level 28.
+ * Available since API level 28.
*
* @param stream reference provided by AAudioStreamBuilder_openStream()
* @return frames read
@@ -1326,7 +1413,7 @@
/**
* Return the content type for the stream.
*
- * Added in API level 28.
+ * Available since API level 28.
*
* @param stream reference provided by AAudioStreamBuilder_openStream()
* @return content type, for example {@link #AAUDIO_CONTENT_TYPE_MUSIC}
@@ -1337,7 +1424,7 @@
/**
* Return the input preset for the stream.
*
- * Added in API level 28.
+ * Available since API level 28.
*
* @param stream reference provided by AAudioStreamBuilder_openStream()
* @return input preset, for example {@link #AAUDIO_INPUT_PRESET_CAMCORDER}
@@ -1349,7 +1436,7 @@
* Return the policy that determines whether the audio may or may not be captured
* by other apps or the system.
*
- * Added in API level 29.
+ * Available since API level 29.
*
* @param stream reference provided by AAudioStreamBuilder_openStream()
* @return the allowed capture policy, for example {@link #AAUDIO_ALLOW_CAPTURE_BY_ALL}