* Copyright (c) 2022 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 Audio
* @{
*
* @brief Defines audio-related APIs, including custom data types and functions for loading drivers,
* accessing a driver adapter, and rendering and capturing audios.
*
* @since 1.0
* @version 1.0
*/
* @file audio_attribute.h
*
* @brief Declares APIs for audio attributes.
*
* @since 1.0
* @version 1.0
*/
#ifndef AUDIO_ATTRIBUTE_H
#define AUDIO_ATTRIBUTE_H
#include "audio_types.h"
namespace OHOS {
* @brief Provides attribute-related APIs for audio rendering or capturing, including functions to
* obtain frame information and set audio sampling attributes.
*
* @since 1.0
* @version 1.0
*/
struct AudioAttribute {
* @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 <b>0</b> if the audio frame size is obtained; returns a negative value otherwise.
*/
int32_t (*GetFrameSize)(AudioHandle handle, uint64_t *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 <b>0</b> if the number of audio frames is obtained; returns a negative value otherwise.
*/
int32_t (*GetFrameCount)(AudioHandle handle, uint64_t *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 <b>0</b> if the setting is successful; returns a negative value otherwise.
* @see GetSampleAttributes
*/
int32_t (*SetSampleAttributes)(AudioHandle handle, const 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 <b>0</b> if audio sampling attributes are obtained; returns a negative value otherwise.
* @see SetSampleAttributes
*/
int32_t (*GetSampleAttributes)(AudioHandle handle, 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 <b>0</b> if the data channel ID is obtained; returns a negative value otherwise.
*/
int32_t (*GetCurrentChannelId)(AudioHandle handle, uint32_t *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 <i>key=value</i>. Separate multiple key-value pairs by semicolons (;).
* @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise.
*/
int32_t (*SetExtraParams)(AudioHandle handle, const char *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 <i>key=value</i>. Separate multiple key-value pairs by semicolons (;).
* @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise.
*/
int32_t (*GetExtraParams)(AudioHandle handle, char *keyValueList, int32_t listLenth);
* @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 <b>0</b> if the operation is successful; returns a negative value otherwise.
*/
int32_t (*ReqMmapBuffer)(AudioHandle handle, int32_t reqSize, 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 <b>0</b> if the operation is successful; returns a negative value otherwise.
*/
int32_t (*GetMmapPosition)(AudioHandle handle, uint64_t *frames, 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 <b>0</b> if the audio effect were added succesffully; returns a negative value otherwise.
*/
int32_t (*AddAudioEffect)(AudioHandle handle, uint64_t 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 <b>0</b> if the audio effect were removed succesffully; returns a negative value otherwise.
*/
int32_t (*RemoveAudioEffect)(AudioHandle handle, uint64_t 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 <b>0</b> if the operation is successful; returns a negative value otherwise.
*/
int32_t (*GetFrameBufferSize)(AudioHandle handle, uint64_t *bufferSize);
};
}
#endif
