AAudio.h revision f26ad101eb9ee8180ee54f3af44f553905c35c0c 
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/**
18 * This is the 'C' ABI for AAudio.
19 */
20#ifndef AAUDIO_AAUDIO_H
21#define AAUDIO_AAUDIO_H
22
23#include "AAudioDefinitions.h"
24
25#ifdef __cplusplus
26extern "C" {
27#endif
28
29typedef aaudio_handle_t AAudioStream;
30typedef aaudio_handle_t AAudioStreamBuilder;
31
32#define AAUDIO_STREAM_NONE         ((AAudioStream)AAUDIO_HANDLE_INVALID)
33#define AAUDIO_STREAM_BUILDER_NONE ((AAudioStreamBuilder)AAUDIO_HANDLE_INVALID)
34
35/* AAUDIO_API will probably get defined in a Makefile for a specific platform. */
36#ifndef AAUDIO_API
37#define AAUDIO_API /* for exporting symbols */
38#endif
39
40// ============================================================
41// Audio System
42// ============================================================
43
44/**
45 * @return time in the same clock domain as the timestamps
46 */
47AAUDIO_API aaudio_nanoseconds_t AAudio_getNanoseconds(aaudio_clockid_t clockid);
48
49/**
50 * The text is the ASCII symbol corresponding to the returnCode,
51 * or an English message saying the returnCode is unrecognized.
52 * This is intended for developers to use when debugging.
53 * It is not for display to users.
54 *
55 * @return pointer to a text representation of an AAudio result code.
56 */
57AAUDIO_API const char * AAudio_convertResultToText(aaudio_result_t returnCode);
58
59/**
60 * The text is the ASCII symbol corresponding to the stream state,
61 * or an English message saying the state is unrecognized.
62 * This is intended for developers to use when debugging.
63 * It is not for display to users.
64 *
65 * @return pointer to a text representation of an AAudio state.
66 */
67AAUDIO_API const char * AAudio_convertStreamStateToText(aaudio_stream_state_t state);
68
69// ============================================================
70// StreamBuilder
71// ============================================================
72
73/**
74 * Create a StreamBuilder that can be used to open a Stream.
75 *
76 * The deviceId is initially unspecified, meaning that the current default device will be used.
77 *
78 * The default direction is AAUDIO_DIRECTION_OUTPUT.
79 * The default sharing mode is AAUDIO_SHARING_MODE_LEGACY.
80 * The data format, samplesPerFrames and sampleRate are unspecified and will be
81 * chosen by the device when it is opened.
82 *
83 * AAudioStreamBuilder_delete() must be called when you are done using the builder.
84 */
85AAUDIO_API aaudio_result_t AAudio_createStreamBuilder(AAudioStreamBuilder *builder);
86
87/**
88 * Request an audio device identified device using an ID.
89 * The ID is platform specific.
90 * On Android, for example, the ID could be obtained from the Java AudioManager.
91 *
92 * By default, the primary device will be used.
93 *
94 * @param builder handle provided by AAudio_createStreamBuilder()
95 * @param deviceId platform specific identifier or AAUDIO_DEVICE_UNSPECIFIED
96 * @return AAUDIO_OK or a negative error.
97 */
98AAUDIO_API aaudio_result_t AAudioStreamBuilder_setDeviceId(AAudioStreamBuilder builder,
99                                                     aaudio_device_id_t deviceId);
100/**
101 * Passes back requested device ID.
102 * @return AAUDIO_OK or a negative error.
103 */
104AAUDIO_API aaudio_result_t AAudioStreamBuilder_getDeviceId(AAudioStreamBuilder builder,
105                                                     aaudio_device_id_t *deviceId);
106
107/**
108 * Request a sample rate in Hz.
109 * The stream may be opened with a different sample rate.
110 * So the application should query for the actual rate after the stream is opened.
111 *
112 * Technically, this should be called the "frame rate" or "frames per second",
113 * because it refers to the number of complete frames transferred per second.
114 * But it is traditionally called "sample rate". Se we use that term.
115 *
116 * Default is AAUDIO_UNSPECIFIED.
117 *
118 * @return AAUDIO_OK or a negative error.
119 */
120AAUDIO_API aaudio_result_t AAudioStreamBuilder_setSampleRate(AAudioStreamBuilder builder,
121                                                       aaudio_sample_rate_t sampleRate);
122
123/**
124 * Returns sample rate in Hertz (samples per second).
125 * @return AAUDIO_OK or a negative error.
126 */
127AAUDIO_API aaudio_result_t AAudioStreamBuilder_getSampleRate(AAudioStreamBuilder builder,
128                                                       aaudio_sample_rate_t *sampleRate);
129
130
131/**
132 * Request a number of samples per frame.
133 * The stream may be opened with a different value.
134 * So the application should query for the actual value after the stream is opened.
135 *
136 * Default is AAUDIO_UNSPECIFIED.
137 *
138 * Note, this quantity is sometimes referred to as "channel count".
139 *
140 * @return AAUDIO_OK or a negative error.
141 */
142AAUDIO_API aaudio_result_t AAudioStreamBuilder_setSamplesPerFrame(AAudioStreamBuilder builder,
143                                                   int32_t samplesPerFrame);
144
145/**
146 * Note, this quantity is sometimes referred to as "channel count".
147 *
148 * @param builder handle provided by AAudio_createStreamBuilder()
149 * @param samplesPerFrame pointer to a variable to be set to samplesPerFrame.
150 * @return AAUDIO_OK or a negative error.
151 */
152AAUDIO_API aaudio_result_t AAudioStreamBuilder_getSamplesPerFrame(AAudioStreamBuilder builder,
153                                                   int32_t *samplesPerFrame);
154
155
156/**
157 * Request a sample data format, for example AAUDIO_FORMAT_PCM_I16.
158 * The application should query for the actual format after the stream is opened.
159 *
160 * @return AAUDIO_OK or a negative error.
161 */
162AAUDIO_API aaudio_result_t AAudioStreamBuilder_setFormat(AAudioStreamBuilder builder,
163                                                   aaudio_audio_format_t format);
164
165/**
166 * @return AAUDIO_OK or a negative error.
167 */
168AAUDIO_API aaudio_result_t AAudioStreamBuilder_getFormat(AAudioStreamBuilder builder,
169                                                   aaudio_audio_format_t *format);
170
171/**
172 * Request a mode for sharing the device.
173 * The requested sharing mode may not be available.
174 * So the application should query for the actual mode after the stream is opened.
175 *
176 * @param builder handle provided by AAudio_createStreamBuilder()
177 * @param sharingMode AAUDIO_SHARING_MODE_LEGACY or AAUDIO_SHARING_MODE_EXCLUSIVE
178 * @return AAUDIO_OK or a negative error.
179 */
180AAUDIO_API aaudio_result_t AAudioStreamBuilder_setSharingMode(AAudioStreamBuilder builder,
181                                                        aaudio_sharing_mode_t sharingMode);
182
183/**
184 * Return requested sharing mode.
185 * @return AAUDIO_OK or a negative error
186 */
187AAUDIO_API aaudio_result_t AAudioStreamBuilder_getSharingMode(AAudioStreamBuilder builder,
188                                                        aaudio_sharing_mode_t *sharingMode);
189
190/**
191 * Request the direction for a stream. The default is AAUDIO_DIRECTION_OUTPUT.
192 *
193 * @param builder handle provided by AAudio_createStreamBuilder()
194 * @param direction AAUDIO_DIRECTION_OUTPUT or AAUDIO_DIRECTION_INPUT
195 * @return AAUDIO_OK or a negative error.
196 */
197AAUDIO_API aaudio_result_t AAudioStreamBuilder_setDirection(AAudioStreamBuilder builder,
198                                                            aaudio_direction_t direction);
199
200/**
201 * @param builder handle provided by AAudio_createStreamBuilder()
202 * @param direction pointer to a variable to be set to the currently requested direction.
203 * @return AAUDIO_OK or a negative error.
204 */
205AAUDIO_API aaudio_result_t AAudioStreamBuilder_getDirection(AAudioStreamBuilder builder,
206                                                            aaudio_direction_t *direction);
207
208/**
209 * Set the requested maximum buffer capacity in frames.
210 * The final AAudioStream capacity may differ, but will probably be at least this big.
211 *
212 * Default is AAUDIO_UNSPECIFIED.
213 *
214 * @param builder handle provided by AAudio_createStreamBuilder()
215 * @param frames the desired buffer capacity in frames or AAUDIO_UNSPECIFIED
216 * @return AAUDIO_OK or a negative error.
217 */
218AAUDIO_API aaudio_result_t AAudioStreamBuilder_setBufferCapacity(AAudioStreamBuilder builder,
219                                                                 aaudio_size_frames_t frames);
220
221/**
222 * Query the requested maximum buffer capacity in frames that was passed to
223 * AAudioStreamBuilder_setBufferCapacity().
224 *
225 * @param builder handle provided by AAudio_createStreamBuilder()
226 * @param frames pointer to variable to receive the requested buffer capacity
227 * @return AAUDIO_OK or a negative error.
228 */
229AAUDIO_API aaudio_result_t AAudioStreamBuilder_getBufferCapacity(AAudioStreamBuilder builder,
230                                                                 aaudio_size_frames_t *frames);
231
232/**
233 * Open a stream based on the options in the StreamBuilder.
234 *
235 * AAudioStream_close must be called when finished with the stream to recover
236 * the memory and to free the associated resources.
237 *
238 * @param builder handle provided by AAudio_createStreamBuilder()
239 * @param stream pointer to a variable to receive the new stream handle
240 * @return AAUDIO_OK or a negative error.
241 */
242AAUDIO_API aaudio_result_t  AAudioStreamBuilder_openStream(AAudioStreamBuilder builder,
243                                                     AAudioStream *stream);
244
245/**
246 * Delete the resources associated with the StreamBuilder.
247 *
248 * @param builder handle provided by AAudio_createStreamBuilder()
249 * @return AAUDIO_OK or a negative error.
250 */
251AAUDIO_API aaudio_result_t  AAudioStreamBuilder_delete(AAudioStreamBuilder builder);
252
253// ============================================================
254// Stream Control
255// ============================================================
256
257/**
258 * Free the resources associated with a stream created by AAudioStreamBuilder_openStream()
259 *
260 * @param stream handle provided by AAudioStreamBuilder_openStream()
261 * @return AAUDIO_OK or a negative error.
262 */
263AAUDIO_API aaudio_result_t  AAudioStream_close(AAudioStream stream);
264
265/**
266 * Asynchronously request to start playing the stream. For output streams, one should
267 * write to the stream to fill the buffer before starting.
268 * Otherwise it will underflow.
269 * After this call the state will be in AAUDIO_STREAM_STATE_STARTING or AAUDIO_STREAM_STATE_STARTED.
270 *
271 * @param stream handle provided by AAudioStreamBuilder_openStream()
272 * @return AAUDIO_OK or a negative error.
273 */
274AAUDIO_API aaudio_result_t  AAudioStream_requestStart(AAudioStream stream);
275
276/**
277 * Asynchronous request for the stream to pause.
278 * Pausing a stream will freeze the data flow but not flush any buffers.
279 * Use AAudioStream_Start() to resume playback after a pause.
280 * After this call the state will be in AAUDIO_STREAM_STATE_PAUSING or AAUDIO_STREAM_STATE_PAUSED.
281 *
282 * @param stream handle provided by AAudioStreamBuilder_openStream()
283 * @return AAUDIO_OK or a negative error.
284 */
285AAUDIO_API aaudio_result_t  AAudioStream_requestPause(AAudioStream stream);
286
287/**
288 * Asynchronous request for the stream to flush.
289 * Flushing will discard any pending data.
290 * This call only works if the stream is pausing or paused. TODO review
291 * Frame counters are not reset by a flush. They may be advanced.
292 * After this call the state will be in AAUDIO_STREAM_STATE_FLUSHING or AAUDIO_STREAM_STATE_FLUSHED.
293 *
294 * @param stream handle provided by AAudioStreamBuilder_openStream()
295 * @return AAUDIO_OK or a negative error.
296 */
297AAUDIO_API aaudio_result_t  AAudioStream_requestFlush(AAudioStream stream);
298
299/**
300 * Asynchronous request for the stream to stop.
301 * The stream will stop after all of the data currently buffered has been played.
302 * After this call the state will be in AAUDIO_STREAM_STATE_STOPPING or AAUDIO_STREAM_STATE_STOPPED.
303 *
304 * @param stream handle provided by AAudioStreamBuilder_openStream()
305 * @return AAUDIO_OK or a negative error.
306 */
307AAUDIO_API aaudio_result_t  AAudioStream_requestStop(AAudioStream stream);
308
309/**
310 * Query the current state, eg. AAUDIO_STREAM_STATE_PAUSING
311 *
312 * @param stream handle provided by AAudioStreamBuilder_openStream()
313 * @param state pointer to a variable that will be set to the current state
314 * @return AAUDIO_OK or a negative error.
315 */
316AAUDIO_API aaudio_result_t AAudioStream_getState(AAudioStream stream, aaudio_stream_state_t *state);
317
318/**
319 * Wait until the current state no longer matches the input state.
320 *
321 * <pre><code>
322 * aaudio_stream_state_t currentState;
323 * aaudio_result_t result = AAudioStream_getState(stream, &currentState);
324 * while (result == AAUDIO_OK && currentState != AAUDIO_STREAM_STATE_PAUSING) {
325 *     result = AAudioStream_waitForStateChange(
326 *                                   stream, currentState, &currentState, MY_TIMEOUT_NANOS);
327 * }
328 * </code></pre>
329 *
330 * @param stream A handle provided by AAudioStreamBuilder_openStream()
331 * @param inputState The state we want to avoid.
332 * @param nextState Pointer to a variable that will be set to the new state.
333 * @param timeoutNanoseconds Maximum number of nanoseconds to wait for completion.
334 * @return AAUDIO_OK or a negative error.
335 */
336AAUDIO_API aaudio_result_t AAudioStream_waitForStateChange(AAudioStream stream,
337                                            aaudio_stream_state_t inputState,
338                                            aaudio_stream_state_t *nextState,
339                                            aaudio_nanoseconds_t timeoutNanoseconds);
340
341// ============================================================
342// Stream I/O
343// ============================================================
344
345/**
346 * Read data from the stream.
347 *
348 * The call will wait until the read is complete or until it runs out of time.
349 * If timeoutNanos is zero then this call will not wait.
350 *
351 * Note that timeoutNanoseconds is a relative duration in wall clock time.
352 * Time will not stop if the thread is asleep.
353 * So it will be implemented using CLOCK_BOOTTIME.
354 *
355 * This call is "strong non-blocking" unless it has to wait for data.
356 *
357 * @param stream A stream created using AAudioStreamBuilder_openStream().
358 * @param buffer The address of the first sample.
359 * @param numFrames Number of frames to read. Only complete frames will be written.
360 * @param timeoutNanoseconds Maximum number of nanoseconds to wait for completion.
361 * @return The number of frames actually written or a negative error.
362 */
363AAUDIO_API aaudio_result_t AAudioStream_read(AAudioStream stream,
364                               void *buffer,
365                               aaudio_size_frames_t numFrames,
366                               aaudio_nanoseconds_t timeoutNanoseconds);
367
368/**
369 * Write data to the stream.
370 *
371 * The call will wait until the write is complete or until it runs out of time.
372 * If timeoutNanos is zero then this call will not wait.
373 *
374 * Note that timeoutNanoseconds is a relative duration in wall clock time.
375 * Time will not stop if the thread is asleep.
376 * So it will be implemented using CLOCK_BOOTTIME.
377 *
378 * This call is "strong non-blocking" unless it has to wait for room in the buffer.
379 *
380 * @param stream A stream created using AAudioStreamBuilder_openStream().
381 * @param buffer The address of the first sample.
382 * @param numFrames Number of frames to write. Only complete frames will be written.
383 * @param timeoutNanoseconds Maximum number of nanoseconds to wait for completion.
384 * @return The number of frames actually written or a negative error.
385 */
386AAUDIO_API aaudio_result_t AAudioStream_write(AAudioStream stream,
387                               const void *buffer,
388                               aaudio_size_frames_t numFrames,
389                               aaudio_nanoseconds_t timeoutNanoseconds);
390
391
392// ============================================================
393// High priority audio threads
394// ============================================================
395
396typedef void *(aaudio_audio_thread_proc_t)(void *);
397
398/**
399 * Create a thread associated with a stream. The thread has special properties for
400 * low latency audio performance. This thread can be used to implement a callback API.
401 *
402 * Only one thread may be associated with a stream.
403 *
404 * Note that this API is in flux.
405 *
406 * @param stream A stream created using AAudioStreamBuilder_openStream().
407 * @param periodNanoseconds the estimated period at which the audio thread will need to wake up
408 * @param threadProc your thread entry point
409 * @param arg an argument that will be passed to your thread entry point
410 * @return AAUDIO_OK or a negative error.
411 */
412AAUDIO_API aaudio_result_t AAudioStream_createThread(AAudioStream stream,
413                                     aaudio_nanoseconds_t periodNanoseconds,
414                                     aaudio_audio_thread_proc_t *threadProc,
415                                     void *arg);
416
417/**
418 * Wait until the thread exits or an error occurs.
419 * The thread handle will be deleted.
420 *
421 * @param stream A stream created using AAudioStreamBuilder_openStream().
422 * @param returnArg a pointer to a variable to receive the return value
423 * @param timeoutNanoseconds Maximum number of nanoseconds to wait for completion.
424 * @return AAUDIO_OK or a negative error.
425 */
426AAUDIO_API aaudio_result_t AAudioStream_joinThread(AAudioStream stream,
427                                   void **returnArg,
428                                   aaudio_nanoseconds_t timeoutNanoseconds);
429
430// ============================================================
431// Stream - queries
432// ============================================================
433
434
435/**
436 * This can be used to adjust the latency of the buffer by changing
437 * the threshold where blocking will occur.
438 * By combining this with AAudioStream_getUnderrunCount(), the latency can be tuned
439 * at run-time for each device.
440 *
441 * This cannot be set higher than AAudioStream_getBufferCapacity().
442 *
443 * @param stream handle provided by AAudioStreamBuilder_openStream()
444 * @param requestedFrames requested number of frames that can be filled without blocking
445 * @param actualFrames receives final number of frames
446 * @return AAUDIO_OK or a negative error
447 */
448AAUDIO_API aaudio_result_t AAudioStream_setBufferSize(AAudioStream stream,
449                                                      aaudio_size_frames_t requestedFrames,
450                                                      aaudio_size_frames_t *actualFrames);
451
452/**
453 * Query the maximum number of frames that can be filled without blocking.
454 *
455 * @param stream handle provided by AAudioStreamBuilder_openStream()
456 * @param frames pointer to variable to receive the buffer size
457 * @return AAUDIO_OK or a negative error.
458 */
459AAUDIO_API aaudio_result_t AAudioStream_getBufferSize(AAudioStream stream,
460                                                      aaudio_size_frames_t *frames);
461
462/**
463 * Query the number of frames that are read or written by the endpoint at one time.
464 *
465 * @param stream handle provided by AAudioStreamBuilder_openStream()
466 * @param frames pointer to variable to receive the burst size
467 * @return AAUDIO_OK or a negative error.
468 */
469AAUDIO_API aaudio_result_t AAudioStream_getFramesPerBurst(AAudioStream stream,
470                                                          aaudio_size_frames_t *frames);
471
472/**
473 * Query maximum buffer capacity in frames.
474 *
475 * @param stream handle provided by AAudioStreamBuilder_openStream()
476 * @param frames pointer to variable to receive the buffer capacity
477 * @return AAUDIO_OK or a negative error.
478 */
479AAUDIO_API aaudio_result_t AAudioStream_getBufferCapacity(AAudioStream stream,
480                                                          aaudio_size_frames_t *frames);
481
482/**
483 * An XRun is an Underrun or an Overrun.
484 * During playing, an underrun will occur if the stream is not written in time
485 * and the system runs out of valid data.
486 * During recording, an overrun will occur if the stream is not read in time
487 * and there is no place to put the incoming data so it is discarded.
488 *
489 * An underrun or overrun can cause an audible "pop" or "glitch".
490 *
491 * @param stream handle provided by AAudioStreamBuilder_openStream()
492 * @param xRunCount pointer to variable to receive the underrun or overrun count
493 * @return AAUDIO_OK or a negative error.
494 */
495AAUDIO_API aaudio_result_t AAudioStream_getXRunCount(AAudioStream stream, int32_t *xRunCount);
496
497/**
498 * @param stream handle provided by AAudioStreamBuilder_openStream()
499 * @param sampleRate pointer to variable to receive the actual sample rate
500 * @return AAUDIO_OK or a negative error.
501 */
502AAUDIO_API aaudio_result_t AAudioStream_getSampleRate(AAudioStream stream,
503                                                      aaudio_sample_rate_t *sampleRate);
504
505/**
506 * The samplesPerFrame is also known as channelCount.
507 *
508 * @param stream handle provided by AAudioStreamBuilder_openStream()
509 * @param samplesPerFrame pointer to variable to receive the actual samples per frame
510 * @return AAUDIO_OK or a negative error.
511 */
512AAUDIO_API aaudio_result_t AAudioStream_getSamplesPerFrame(AAudioStream stream,
513                                                           int32_t *samplesPerFrame);
514
515/**
516 * @param stream handle provided by AAudioStreamBuilder_openStream()
517 * @param deviceId pointer to variable to receive the actual device ID
518 * @return AAUDIO_OK or a negative error.
519 */
520AAUDIO_API aaudio_result_t AAudioStream_getDeviceId(AAudioStream stream,
521                                                    aaudio_device_id_t *deviceId);
522
523/**
524 * @param stream handle provided by AAudioStreamBuilder_openStream()
525 * @param format pointer to variable to receive the actual data format
526 * @return AAUDIO_OK or a negative error.
527 */
528AAUDIO_API aaudio_result_t AAudioStream_getFormat(AAudioStream stream,
529                                                  aaudio_audio_format_t *format);
530
531/**
532 * Provide actual sharing mode.
533 * @param stream handle provided by AAudioStreamBuilder_openStream()
534 * @param sharingMode pointer to variable to receive the actual sharing mode
535 * @return AAUDIO_OK or a negative error.
536 */
537AAUDIO_API aaudio_result_t AAudioStream_getSharingMode(AAudioStream stream,
538                                        aaudio_sharing_mode_t *sharingMode);
539
540/**
541 * @param stream handle provided by AAudioStreamBuilder_openStream()
542 * @param direction pointer to a variable to be set to the current direction.
543 * @return AAUDIO_OK or a negative error.
544 */
545AAUDIO_API aaudio_result_t AAudioStream_getDirection(AAudioStream stream,
546                                                     aaudio_direction_t *direction);
547
548/**
549 * Passes back the number of frames that have been written since the stream was created.
550 * For an output stream, this will be advanced by the application calling write().
551 * For an input stream, this will be advanced by the device or service.
552 *
553 * The frame position is monotonically increasing.
554 *
555 * @param stream handle provided by AAudioStreamBuilder_openStream()
556 * @param frames pointer to variable to receive the frames written
557 * @return AAUDIO_OK or a negative error.
558 */
559AAUDIO_API aaudio_result_t AAudioStream_getFramesWritten(AAudioStream stream,
560                                                   aaudio_position_frames_t *frames);
561
562/**
563 * Passes back the number of frames that have been read since the stream was created.
564 * For an output stream, this will be advanced by the device or service.
565 * For an input stream, this will be advanced by the application calling read().
566 *
567 * The frame position is monotonically increasing.
568 *
569 * @param stream handle provided by AAudioStreamBuilder_openStream()
570 * @param frames pointer to variable to receive the frames written
571 * @return AAUDIO_OK or a negative error.
572 */
573AAUDIO_API aaudio_result_t AAudioStream_getFramesRead(AAudioStream stream,
574                                                      aaudio_position_frames_t *frames);
575
576/**
577 * Passes back the time at which a particular frame was presented.
578 * This can be used to synchronize audio with video or MIDI.
579 * It can also be used to align a recorded stream with a playback stream.
580 *
581 * Timestamps are only valid when the stream is in AAUDIO_STREAM_STATE_STARTED.
582 * AAUDIO_ERROR_INVALID_STATE will be returned if the stream is not started.
583 * Note that because requestStart() is asynchronous, timestamps will not be valid until
584 * a short time after calling requestStart().
585 * So AAUDIO_ERROR_INVALID_STATE should not be considered a fatal error.
586 * Just try calling again later.
587 *
588 * If an error occurs, then the position and time will not be modified.
589 *
590 * The position and time passed back are monotonically increasing.
591 *
592 * @param stream A handle provided by AAudioStreamBuilder_openStream()
593 * @param clockid AAUDIO_CLOCK_MONOTONIC or AAUDIO_CLOCK_BOOTTIME
594 * @param framePosition pointer to a variable to receive the position
595 * @param timeNanoseconds pointer to a variable to receive the time
596 * @return AAUDIO_OK or a negative error
597 */
598AAUDIO_API aaudio_result_t AAudioStream_getTimestamp(AAudioStream stream,
599                                      aaudio_clockid_t clockid,
600                                      aaudio_position_frames_t *framePosition,
601                                      aaudio_nanoseconds_t *timeNanoseconds);
602
603#ifdef __cplusplus
604}
605#endif
606
607#endif //AAUDIO_AAUDIO_H
608