Document the reference count rules for I/O handles
Change-Id: Ia7cd27ad84bbd7bf2657011057f89386f938a807
diff --git a/include/media/AudioSystem.h b/include/media/AudioSystem.h
index ca9aaf7..3f4d01d 100644
--- a/include/media/AudioSystem.h
+++ b/include/media/AudioSystem.h
@@ -200,12 +200,16 @@
static status_t setPhoneState(audio_mode_t state);
static status_t setForceUse(audio_policy_force_use_t usage, audio_policy_forced_cfg_t config);
static audio_policy_forced_cfg_t getForceUse(audio_policy_force_use_t usage);
+
+ // Client must successfully hand off the handle reference to AudioFlinger via createTrack(),
+ // or release it with releaseOutput().
static audio_io_handle_t getOutput(audio_stream_type_t stream,
uint32_t samplingRate = 0,
audio_format_t format = AUDIO_FORMAT_DEFAULT,
audio_channel_mask_t channelMask = AUDIO_CHANNEL_OUT_STEREO,
audio_output_flags_t flags = AUDIO_OUTPUT_FLAG_NONE,
const audio_offload_info_t *offloadInfo = NULL);
+
static status_t startOutput(audio_io_handle_t output,
audio_stream_type_t stream,
int session);
@@ -213,11 +217,15 @@
audio_stream_type_t stream,
int session);
static void releaseOutput(audio_io_handle_t output);
+
+ // Client must successfully hand off the handle reference to AudioFlinger via openRecord(),
+ // or release it with releaseInput().
static audio_io_handle_t getInput(audio_source_t inputSource,
uint32_t samplingRate,
audio_format_t format,
audio_channel_mask_t channelMask,
int sessionId);
+
static status_t startInput(audio_io_handle_t input);
static status_t stopInput(audio_io_handle_t input);
static void releaseInput(audio_io_handle_t input);
diff --git a/include/media/IAudioFlinger.h b/include/media/IAudioFlinger.h
index 899d79f..4feb684 100644
--- a/include/media/IAudioFlinger.h
+++ b/include/media/IAudioFlinger.h
@@ -67,6 +67,9 @@
size_t frameCount,
track_flags_t *flags,
const sp<IMemory>& sharedBuffer,
+ // On successful return, AudioFlinger takes over the handle
+ // reference and will release it when the track is destroyed.
+ // However on failure, the client is responsible for release.
audio_io_handle_t output,
pid_t tid, // -1 means unused, otherwise must be valid non-0
int *sessionId,
@@ -78,6 +81,9 @@
status_t *status) = 0;
virtual sp<IAudioRecord> openRecord(
+ // On successful return, AudioFlinger takes over the handle
+ // reference and will release it when the track is destroyed.
+ // However on failure, the client is responsible for release.
audio_io_handle_t input,
uint32_t sampleRate,
audio_format_t format,
@@ -188,6 +194,7 @@
effect_descriptor_t *pDesc,
const sp<IEffectClient>& client,
int32_t priority,
+ // AudioFlinger doesn't take over handle reference from client
audio_io_handle_t output,
int sessionId,
status_t *status,