/*
* Copyright (C) 2018 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package android.hardware.audio@4.0;
import android.hardware.audio.common@4.0;
import IStreamIn;
import IStreamOut;
interface IDevice {
/**
* Returns whether the audio hardware interface has been initialized.
*
* @return retval OK on success, NOT_INITIALIZED on failure.
*/
initCheck() generates (Result retval);
/**
* Sets the audio volume for all audio activities other than voice call. If
* NOT_SUPPORTED is returned, the software mixer will emulate this
* capability.
*
* @param volume 1.0f means unity, 0.0f is zero.
* @return retval operation completion status.
*/
setMasterVolume(float volume) generates (Result retval);
/**
* Get the current master volume value for the HAL, if the HAL supports
* master volume control. For example, AudioFlinger will query this value
* from the primary audio HAL when the service starts and use the value for
* setting the initial master volume across all HALs. HALs which do not
* support this method must return NOT_SUPPORTED in 'retval'.
*
* @return retval operation completion status.
* @return volume 1.0f means unity, 0.0f is zero.
*/
getMasterVolume() generates (Result retval, float volume);
/**
* Sets microphone muting state.
*
* @param mute whether microphone is muted.
* @return retval operation completion status.
*/
setMicMute(bool mute) generates (Result retval);
/**
* Gets whether microphone is muted.
*
* @return retval operation completion status.
* @return mute whether microphone is muted.
*/
getMicMute() generates (Result retval, bool mute);
/**
* Set the audio mute status for all audio activities. If the return value
* is NOT_SUPPORTED, the software mixer will emulate this capability.
*
* @param mute whether audio is muted.
* @return retval operation completion status.
*/
setMasterMute(bool mute) generates (Result retval);
/**
* Get the current master mute status for the HAL, if the HAL supports
* master mute control. AudioFlinger will query this value from the primary
* audio HAL when the service starts and use the value for setting the
* initial master mute across all HALs. HAL must indicate that the feature
* is not supported by returning NOT_SUPPORTED status.
*
* @return retval operation completion status.
* @return mute whether audio is muted.
*/
getMasterMute() generates (Result retval, bool mute);
/**
* Returns audio input buffer size according to parameters passed or
* INVALID_ARGUMENTS if one of the parameters is not supported.
*
* @param config audio configuration.
* @return retval operation completion status.
* @return bufferSize input buffer size in bytes.
*/
getInputBufferSize(AudioConfig config)
generates (Result retval, uint64_t bufferSize);
/**
* This method creates and opens the audio hardware output stream.
* If the stream can not be opened with the proposed audio config,
* HAL must provide suggested values for the audio config.
*
* @param ioHandle handle assigned by AudioFlinger.
* @param device device type and (if needed) address.
* @param config stream configuration.
* @param flags additional flags.
* @param sourceMetadata Description of the audio that will be played.
May be used by implementations to configure hardware effects.
* @return retval operation completion status.
* @return outStream created output stream.
* @return suggestedConfig in case of invalid parameters, suggested config.
*/
openOutputStream(
AudioIoHandle ioHandle,
DeviceAddress device,
AudioConfig config,
bitfield<AudioOutputFlag> flags,
SourceMetadata sourceMetadata) generates (
Result retval,
IStreamOut outStream,
AudioConfig suggestedConfig);
/**
* This method creates and opens the audio hardware input stream.
* If the stream can not be opened with the proposed audio config,
* HAL must provide suggested values for the audio config.
*
* @param ioHandle handle assigned by AudioFlinger.
* @param device device type and (if needed) address.
* @param config stream configuration.
* @param flags additional flags.
* @param sinkMetadata Description of the audio that is suggested by the client.
* May be used by implementations to configure hardware effects.
* @return retval operation completion status.
* @return inStream in case of success, created input stream.
* @return suggestedConfig in case of invalid parameters, suggested config.
*/
openInputStream(
AudioIoHandle ioHandle,
DeviceAddress device,
AudioConfig config,
bitfield<AudioInputFlag> flags,
SinkMetadata sinkMetadata) generates (
Result retval,
IStreamIn inStream,
AudioConfig suggestedConfig);
/**
* Returns whether HAL supports audio patches.
*
* @return supports true if audio patches are supported.
*/
supportsAudioPatches() generates (bool supports);
/**
* Creates an audio patch between several source and sink ports. The handle
* is allocated by the HAL and must be unique for this audio HAL module.
*
* @param sources patch sources.
* @param sinks patch sinks.
* @return retval operation completion status.
* @return patch created patch handle.
*/
createAudioPatch(vec<AudioPortConfig> sources, vec<AudioPortConfig> sinks)
generates (Result retval, AudioPatchHandle patch);
/**
* Release an audio patch.
*
* @param patch patch handle.
* @return retval operation completion status.
*/
releaseAudioPatch(AudioPatchHandle patch) generates (Result retval);
/**
* Returns the list of supported attributes for a given audio port.
*
* As input, 'port' contains the information (type, role, address etc...)
* needed by the HAL to identify the port.
*
* As output, 'resultPort' contains possible attributes (sampling rates,
* formats, channel masks, gain controllers...) for this port.
*
* @param port port identifier.
* @return retval operation completion status.
* @return resultPort port descriptor with all parameters filled up.
*/
getAudioPort(AudioPort port)
generates (Result retval, AudioPort resultPort);
/**
* Set audio port configuration.
*
* @param config audio port configuration.
* @return retval operation completion status.
*/
setAudioPortConfig(AudioPortConfig config) generates (Result retval);
/**
* Gets the HW synchronization source of the device. Calling this method is
* equivalent to getting AUDIO_PARAMETER_HW_AV_SYNC on the legacy HAL.
* Optional method
*
* @return retval operation completion status: OK or NOT_SUPPORTED.
* @return hwAvSync HW synchronization source
*/
getHwAvSync() generates (Result retval, AudioHwSync hwAvSync);
/**
* Sets whether the screen is on. Calling this method is equivalent to
* setting AUDIO_PARAMETER_KEY_SCREEN_STATE on the legacy HAL.
* Optional method
*
* @param turnedOn whether the screen is turned on.
* @return retval operation completion status.
*/
setScreenState(bool turnedOn) generates (Result retval);
/**
* Generic method for retrieving vendor-specific parameter values.
* The framework does not interpret the parameters, they are passed
* in an opaque manner between a vendor application and HAL.
*
* Multiple parameters can be retrieved at the same time.
* The implementation should return as many requested parameters
* as possible, even if one or more is not supported
*
* @param context provides more information about the request
* @param keys keys of the requested parameters
* @return retval operation completion status.
* OK must be returned if keys is empty.
* NOT_SUPPORTED must be returned if at least one key is unknown.
* @return parameters parameter key value pairs.
* Must contain the value of all requested keys if retval == OK
*/
getParameters(vec<ParameterValue> context, vec<string> keys)
generates (Result retval, vec<ParameterValue> parameters);
/**
* Generic method for setting vendor-specific parameter values.
* The framework does not interpret the parameters, they are passed
* in an opaque manner between a vendor application and HAL.
*
* Multiple parameters can be set at the same time though this is
* discouraged as it make failure analysis harder.
*
* If possible, a failed setParameters should not impact the platform state.
*
* @param context provides more information about the request
* @param parameters parameter key value pairs.
* @return retval operation completion status.
* All parameters must be successfully set for OK to be returned
*/
setParameters(vec<ParameterValue> context, vec<ParameterValue> parameters)
generates (Result retval);
/**
* Returns an array with available microphones in device.
*
* @return retval INVALID_STATE if the call is not successful,
* OK otherwise.
*
* @return microphones array with microphones info
*/
getMicrophones()
generates(Result retval, vec<MicrophoneInfo> microphones);
/**
* Notifies the device module about the connection state of an input/output
* device attached to it. Calling this method is equivalent to setting
* AUDIO_PARAMETER_DEVICE_[DIS]CONNECT on the legacy HAL.
*
* @param address audio device specification.
* @param connected whether the device is connected.
* @return retval operation completion status.
*/
setConnectedState(DeviceAddress address, bool connected)
generates (Result retval);
};