1 /* 2 * Copyright (c) 2025 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 /** 17 * @addtogroup OHAudio 18 * @{ 19 * 20 * @brief Provide the definition of the C interface for the audio module. 21 * 22 * @since 20 23 */ 24 25 /** 26 * @file native_audio_resource_manager.h 27 * 28 * @brief Declare audio stream manager related interfaces. 29 * 30 * This file interfaces are used for the creation of AudioResourceManager. 31 * 32 * @library libohaudio.so 33 * @syscap SystemCapability.Multimedia.Audio.Core 34 * @kit AudioKit 35 * @since 20 36 */ 37 38 #ifndef NATIVE_AUDIO_RESOURCE_MANAGER_H 39 #define NATIVE_AUDIO_RESOURCE_MANAGER_H 40 41 #include "native_audio_common.h" 42 43 #ifdef __cplusplus 44 extern "C" { 45 #endif 46 47 /** 48 * @brief Declare the audio resource manager. 49 * Audio resource manager provides many functions for developer to manage system resources to avoid 50 * underrun or overrun in audio playback and recording. 51 * 52 * @since 20 53 */ 54 typedef struct OH_AudioResourceManager OH_AudioResourceManager; 55 56 /** 57 * @brief Fetch the audio resource manager handle, which is a singleton. 58 * 59 * @param resourceManager output parameter to get {@link #OH_AudioResourceManager}. 60 * @return 61 * {@link #AUDIOCOMMON_RESULT_SUCCESS} if execution succeeds 62 * {@link #AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM} if input param is nullptr 63 * @since 20 64 */ 65 OH_AudioCommon_Result OH_AudioManager_GetAudioResourceManager(OH_AudioResourceManager **resourceManager); 66 67 /** 68 * @brief Declare the audio workgroup. 69 * The handle of audio workgroup is used for workgroup related functions. 70 * The system will manage cpu resources on a workgroup basis instead of thread. 71 * For parallel task threads, you can add them into one workgroup, and for 72 * asynchronous task threads, use one workgroup for each thread. 73 * There is an upper limit to the total number of workgroups for each process, 74 * so application should release the workgroup which is no longer in use. 75 * 76 * @since 20 77 */ 78 typedef struct OH_AudioWorkgroup OH_AudioWorkgroup; 79 80 /** 81 * @brief Create a workgroup for audio data processing threads in application. 82 * System manages cpu resources by workgroup configuration. 83 * 84 * @param resourceManager {@link OH_AudioResourceManager} handle 85 * provided by {@link OH_AudioManager_GetAudioRoutingManager}. 86 * @param name workgroup name 87 * @param group {@link OH_AudioWorkgroup} handle for managing audio data processing threads. 88 * @return 89 * {@link #AUDIOCOMMON_RESULT_SUCCESS} if execution succeeds 90 * {@link #AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM} if input param is nullptr 91 * {@link #AUDIOCOMMON_RESULT_ERROR_NO_MEMORY} out of workgroup resources 92 * {@link #AUDIOCOMMON_RESULT_ERROR_SYSTEM} system process error occurs 93 * @since 20 94 */ 95 OH_AudioCommon_Result OH_AudioResourceManager_CreateWorkgroup(OH_AudioResourceManager *resourceManager, 96 const char *name, OH_AudioWorkgroup **group); 97 98 /** 99 * @brief Release the workgroup created before. 100 * 101 * @param resourceManager {@link OH_AudioResourceManager} handle 102 * provided by {@link OH_AudioManager_GetAudioRoutingManager}. 103 * @param group {@link OH_AudioWorkgroup} handle provided by {@link OH_AudioResourceManager_CreateWorkgroup}. 104 * @return 105 * {@link #AUDIOCOMMON_RESULT_SUCCESS} if execution succeeds 106 * {@link #AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM} if input param is nullptr 107 * {@link #AUDIOCOMMON_RESULT_ERROR_SYSTEM} system process error occurs 108 * @since 20 109 */ 110 OH_AudioCommon_Result OH_AudioResourceManager_ReleaseWorkgroup(OH_AudioResourceManager *resourceManager, 111 OH_AudioWorkgroup *group); 112 113 /** 114 * @brief Add current thread into a specified audio workgroup as audio data processing thread. 115 * 116 * @param group {@link OH_AudioWorkgroup} handle provided by {@link OH_AudioResourceManager_CreateWorkgroup}. 117 * @param tokenId a token id that represent the thread added. 118 * @return 119 * {@link #AUDIOCOMMON_RESULT_SUCCESS} if execution succeeds 120 * {@link #AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM} if input param is nullptr 121 * {@link #AUDIOCOMMON_RESULT_ERROR_NO_MEMORY} out of resources for the new thread 122 * {@link #AUDIOCOMMON_RESULT_ERROR_SYSTEM} system process error occurs 123 * @since 20 124 */ 125 OH_AudioCommon_Result OH_AudioWorkgroup_AddCurrentThread(OH_AudioWorkgroup *group, int32_t *tokenId); 126 127 /** 128 * @brief Remove the thread from a specified audio workgroup. 129 * 130 * @param group {@link OH_AudioWorkgroup} handle provided by {@link OH_AudioResourceManager_CreateWorkgroup}. 131 * @param tokenId id for thread returned by {link OH_AudioWorkgroup_AddCurrentThread} 132 * @return 133 * {@link #AUDIOCOMMON_RESULT_SUCCESS} if execution succeeds 134 * {@link #AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM} if input param is nullptr or token id is invalid 135 * {@link #AUDIOCOMMON_RESULT_ERROR_SYSTEM} system process error occurs 136 * @since 20 137 */ 138 OH_AudioCommon_Result OH_AudioWorkgroup_RemoveThread(OH_AudioWorkgroup *group, int32_t tokenId); 139 140 /** 141 * @brief Notify system the audio workgroup start working. Call this function before processing the audio frame. 142 * 143 * @param group {@link OH_AudioWorkgroup} handle provided by {@link OH_AudioResourceManager_CreateWorkgroup}. 144 * @param startTime the time when audio thread start working, using system time. The unit of time is milliseconds. 145 * @param deadlineTime the time before which audio work should be finished, otherwise underrun may happens. 146 * The unit of time is milliseconds. 147 * @return 148 * {@link #AUDIOCOMMON_RESULT_SUCCESS} if execution succeeds 149 * {@link #AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM} if input param is nullptr, or time is invalid 150 * {@link #AUDIOCOMMON_RESULT_ERROR_SYSTEM} system process error occurs 151 * @since 20 152 */ 153 OH_AudioCommon_Result OH_AudioWorkgroup_Start(OH_AudioWorkgroup *group, uint64_t startTime, uint64_t deadlineTime); 154 155 /** 156 * @brief Notify system the audio workgroup stop working. Call this function after the audio frame processing 157 * is completed. 158 * 159 * @param group {@link OH_AudioWorkgroup} handle provided by {@link OH_AudioResourceManager_CreateWorkgroup}. 160 * @return 161 * {@link #AUDIOCOMMON_RESULT_SUCCESS} if execution succeeds 162 * {@link #AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM} if input param is nullptr 163 * {@link #AUDIOCOMMON_RESULT_ERROR_SYSTEM} system process error occurs 164 * @since 20 165 */ 166 OH_AudioCommon_Result OH_AudioWorkgroup_Stop(OH_AudioWorkgroup *group); 167 168 #ifdef __cplusplus 169 } 170 #endif 171 172 #endif // NATIVE_AUDIO_RESOURCE_MANAGER_H 173 /** @} */ 174