/*
* Copyright (c) 2022-2023 Huawei Device Co., Ltd.
* 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.
*/
/**
* @addtogroup HdiAudio
* @{
*
* @brief Provides unified APIs for audio services to access audio drivers.
*
* An audio service can obtain an audio driver object or agent and then call APIs provided by this object or agent to
* access different types of audio devices based on the audio IDs, thereby obtaining audio information,
* subscribing to or unsubscribing from audio data, enabling or disabling an audio,
* setting the audio data reporting mode, and setting audio options such as the accuracy and measurement range.
*
* @since 4.0
* @version 1.0
*/
package ohos.hdi.audio.v1_0;
import ohos.hdi.audio.v1_0.AudioTypes;
/**
* @brief Provides capabilities for audio capturing, including controlling the capturing, setting audio attributes,
* scenes, and volume, and capturing audio frames.
* @since 4.0
* @version 1.0
*/
interface IAudioCapture {
/**
* @brief Reads a frame of input data (uplink data) from the audio driver for capturing.
*
* @param capture Indicates the pointer to the IAudioCapture object to operate.
* @param frame Indicates the pointer to the input data to read.
* @param requestBytes Indicates the size of the input data, in bytes.
* @param replyBytes Indicates the pointer to the actual length (in bytes) of the audio data to read.
* @return Returns 0 if the input data is read successfully; returns a negative value otherwise.
*/
CaptureFrame([out] byte[] frame, [out] unsigned long replyBytes);
/**
* @brief Obtains the last number of input audio frames.
*
* @param capture Indicates the pointer to the IAudioCapture object to operate.
* @param frames Indicates the pointer to the last number of input audio frames.
* @param time Indicates the pointer to the timestamp associated with the frame.
* @return Returns 0 if the last number is obtained; returns a negative value otherwise.
* @see CaptureFrame
*/
GetCapturePosition([out] unsigned long frames, [out] struct AudioTimeStamp time);
/**
* @brief Checks whether the configuration of an audio scene is supported.
*
* @param handle Indicates the audio handle.
* @param scene Indicates the pointer to the descriptor of the audio scene.
* @param supported Indicates the pointer to the variable specifying whether the configuration is supported.
* Value true means that the configuration is supported, and false means the opposite.
* @return Returns 0 if the result is obtained; returns a negative value otherwise.
* @see SelectScene
*/
CheckSceneCapability([in] struct AudioSceneDescriptor scene, [out] boolean supported);
/**
* @brief Selects an audio scene.
*
*
* - To select a specific audio scene, you need to specify both the application scenario and output device.
* For example, to select a scene using a smartphone speaker as the output device, set scene according
* to the scenarios where the speaker is used. For example:
*
* - For media playback, set the value to media_speaker.
* - For a voice call, set the value to voice_speaker.
*
* - To select only the application scenario, such as media playback, movie, or gaming, you can set
* scene to media, movie, or game, respectively.
* - To select only the output device, such as media receiver, speaker, or headset, you can set
* scene to receiver, speaker, or headset, respectively.
*
* @param handle Indicates the audio handle.
* @param scene Indicates the pointer to the descriptor of the audio scene to select.
* @return Returns 0 if the scene is selected successfully; returns a negative value otherwise.
* @see CheckSceneCapability
*/
SelectScene([in] struct AudioSceneDescriptor scene);
/**
* @brief Sets the mute operation for the audio.
*
* @param handle Indicates the audio handle.
* @param mute Specifies whether to mute the audio. Value true means to mute the audio,
* and false means the opposite.
* @return Returns 0 if the setting is successful; returns a negative value otherwise.
* @see GetMute
*/
SetMute([in] boolean mute);
/**
* @brief Obtains the mute operation set for the audio.
*
* @param handle Indicates the audio handle.
* @param mute Indicates the pointer to the mute operation set for the audio. Value true means that
* the audio is muted, and false means the opposite.
* @return Returns 0 if the mute operation is obtained; returns a negative value otherwise.
* @see SetMute
*/
GetMute([out] boolean mute);
/**
* @brief Sets the audio volume.
*
* The volume ranges from 0.0 to 1.0. If the volume level in an audio service ranges from 0 to 15,
* 0.0 indicates that the audio is muted, and 1.0 indicates the maximum volume level (15).
*
* @param handle Indicates the audio handle.
* @param volume Indicates the volume to set. The value ranges from 0.0 to 1.0.
* @return Returns 0 if the setting is successful; returns a negative value otherwise.
* @see GetVolume
*/
SetVolume([in] float volume);
/**
* @brief Obtains the audio volume.
*
* @param handle Indicates the audio handle.
* @param volume Indicates the pointer to the volume to obtain. The value ranges from 0.0 to 1.0.
* @return Returns 0 if the volume is obtained; returns a negative value otherwise.
* @see SetVolume
*/
GetVolume([out] float volume);
/**
* @brief Obtains the range of the audio gain.
*
* The audio gain can be expressed in one of the following two ways (depending on the chip platform),
* corresponding to two types of value ranges:
*
* - Actual audio gain values, for example, ranging from -50 to 6 dB
* - Float numbers ranging from 0.0 to 1.0, where 0.0 means to mute the audio,
* and 1.0 means the maximum gain value, for example, 6 dB
*
* @param handle Indicates the audio handle.
* @param min Indicates the pointer to the minimum value of the range.
* @param max Indicates the pointer to the maximum value of the range.
* @return Returns 0 if the range is obtained; returns a negative value otherwise.
* @see GetGain
* @see SetGain
*/
GetGainThreshold([out] float min, [out] float max);
/**
* @brief Obtains the audio gain.
*
* @param handle Indicates the audio handle.
* @param gain Indicates the pointer to the audio gain.
* @return Returns 0 if the audio gain is obtained; returns a negative value otherwise.
* @see GetGainThreshold
* @see SetGain
*/
GetGain([out] float gain);
/**
* @brief Sets the audio gain.
*
* @param handle Indicates the audio handle.
* @param gain Indicates the audio gain to set.
* @return Returns 0 if the setting is successful; returns a negative value otherwise.
* @see GetGainThreshold
* @see GetGain
*/
SetGain([in] float gain);
/**
* @brief Obtains the audio frame size, that is, the length (in bytes) of a frame.
*
* @param handle Indicates the audio handle.
* @param size Indicates the pointer to the audio frame size (in bytes).
* @return Returns 0 if the audio frame size is obtained; returns a negative value otherwise.
*/
GetFrameSize([out] unsigned long size);
/**
* @brief Obtains the number of audio frames in the audio buffer.
*
* @param handle Indicates the audio handle.
* @param count Indicates the pointer to the number of audio frames in the audio buffer.
* @return Returns 0 if the number of audio frames is obtained; returns a negative value otherwise.
*/
GetFrameCount([out] unsigned long count);
/**
* @brief Sets audio sampling attributes.
*
* @param handle Indicates the audio handle.
* @param attrs Indicates the pointer to the audio sampling attributes to set, such as the sampling rate,
* sampling precision, and channel.
* @return Returns 0 if the setting is successful; returns a negative value otherwise.
* @see GetSampleAttributes
*/
SetSampleAttributes([in] struct AudioSampleAttributes attrs);
/**
* @brief Obtains audio sampling attributes.
*
* @param handle Indicates the audio handle.
* @param attrs Indicates the pointer to the audio sampling attributes, such as the sampling rate,
* sampling precision, and channel.
* @return Returns 0 if audio sampling attributes are obtained; returns a negative value otherwise.
* @see SetSampleAttributes
*/
GetSampleAttributes([out] struct AudioSampleAttributes attrs);
/**
* @brief Obtains the data channel ID of the audio.
*
* @param handle Indicates the audio handle.
* @param channelId Indicates the pointer to the data channel ID.
* @return Returns 0 if the data channel ID is obtained; returns a negative value otherwise.
*/
GetCurrentChannelId([out] unsigned int channelId);
/**
* @brief Sets extra audio parameters.
*
* @param handle Indicates the audio handle.
* @param keyValueList Indicates the pointer to the key-value list of the extra audio parameters.
* The format is key=value. Separate multiple key-value pairs by semicolons (;).
* @return Returns 0 if the operation is successful; returns a negative value otherwise.
*/
SetExtraParams([in] String keyValueList);
/**
* @brief Obtains extra audio parameters.
*
* @param handle Indicates the audio handle.
* @param keyValueList Indicates the pointer to the key-value list of the extra audio parameters.
* The format is key=value. Separate multiple key-value pairs by semicolons (;).
* @return Returns 0 if the operation is successful; returns a negative value otherwise.
*/
GetExtraParams([out] String keyValueList);
/**
* @brief Requests a mmap buffer.
*
* @param handle Indicates the audio handle.
* @param reqSize Indicates the size of the request mmap buffer.
* @param desc Indicates the pointer to the mmap buffer descriptor.
* @return Returns 0 if the operation is successful; returns a negative value otherwise.
*/
ReqMmapBuffer([in] int reqSize, [out] struct AudioMmapBufferDescriptor desc);
/**
* @brief Obtains the read/write position of the current mmap buffer.
*
* @param handle Indicates the audio handle.
* @param frames Indicates the pointer to the frame where the read/write starts.
* @param time Indicates the pointer to the timestamp associated with the frame where the read/write starts.
* @return Returns 0 if the operation is successful; returns a negative value otherwise.
*/
GetMmapPosition([out] unsigned long frames, [out] struct AudioTimeStamp time);
/**
* @brief Add the audio effect which the effectid indicated.
*
* @param handle Indicates the audio handle.
* @param effectid Indicates the audio effect instance identifier which is going to be added.
* @return Returns 0 if the audio effect were added succesffully; returns a negative value otherwise.
*/
AddAudioEffect([in] unsigned long effectid);
/**
* @brief Remove the audio effect which the effectid indicated.
*
* @param handle Indicates the audio handle.
* @param effectid Indicates the audio effect which is going to be removed.
* @return Returns 0 if the audio effect were removed succesffully; returns a negative value otherwise.
*/
RemoveAudioEffect([in] unsigned long effectid);
/**
* @brief Get the buffer size of render or capturer
*
* @param handle Indicates the audio handle.
* @param bufferSize Indicates the buffer size (in bytes) queried from the vendor
* @return Returns 0 if the operation is successful; returns a negative value otherwise.
*/
GetFrameBufferSize([out] unsigned long bufferSize);
/**
* @brief Starts audio rendering or capturing.
*
* @param handle Indicates the audio handle.
* @return Returns 0 if the rendering or capturing is successfully started;
* returns a negative value otherwise.
* @see Stop
*/
Start();
/**
* @brief Stops audio rendering or capturing.
*
* @param handle Indicates the audio handle.
* @return Returns 0 if the rendering or capturing is successfully stopped;
* returns a negative value otherwise.
* @see Start
*/
Stop();
/**
* @brief Pauses audio rendering or capturing.
*
* @param handle Indicates the audio handle.
* @return Returns 0 if the rendering or capturing is successfully paused;
* returns a negative value otherwise.
* @see Resume
*/
Pause();
/**
* @brief Resumes audio rendering or capturing.
*
* @param handle Indicates the audio handle.
* @return Returns 0 if the rendering or capturing is successfully resumed;
* returns a negative value otherwise.
* @see Pause
*/
Resume();
/**
* @brief Flushes data in the audio buffer.
*
* @param handle Indicates the audio handle.
* @return Returns 0 if the flush is successful; returns a negative value otherwise.
*/
Flush();
/**
* @brief Sets or cancels the standby mode of the audio device.
*
* @param handle Indicates the audio handle.
* @return Returns 0 if the device is set to standby mode; returns a positive value if the standby mode is
* canceled; returns a negative value if the setting fails.
*/
TurnStandbyMode();
/**
* @brief Dumps information about the audio device.
*
* @param handle Indicates the audio handle.
* @param range Indicates the range of the device information to dump, which can be brief or full information.
* @param fd Indicates the file to which the device information will be dumped.
* @return Returns 0 if the operation is successful; returns a negative value otherwise.
*/
AudioDevDump([in] int range, [in] int fd);
/**
* @brief Query whether the vendor support pause and resume.
*
* @param handle Indicates the audio handle.
* @param supportPause Indicates the state whether the vendor supports pausing. Value true means that
* the vendor supports, and false means the opposite.
* @param supportResume Indicates the state whether the vendor supports resuming. Value true means that
* the vendor supports, and false means the opposite.
* @return Returns 0 if the operation is successful; returns a negative value otherwise.
* @see IsSupportsPauseAndResume
*/
IsSupportsPauseAndResume([out] boolean supportPause, [out] boolean supportResume);
}