1 /* 2 * Copyright (c) 2023 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 * @syscap SystemCapability.Multimedia.Audio.Core 23 * 24 * @since 10 25 * @version 1.0 26 */ 27 28 /** 29 * @file native_audiocapturer.h 30 * 31 * @brief Declare audio stream related interfaces for input type. 32 * 33 * @library libohaudio.so 34 * @syscap SystemCapability.Multimedia.Audio.Core 35 * @kit AudioKit 36 * @since 10 37 * @version 1.0 38 */ 39 40 #ifndef NATIVE_AUDIOCAPTURER_H 41 #define NATIVE_AUDIOCAPTURER_H 42 43 #include <time.h> 44 #include "native_audiostream_base.h" 45 #include "native_audio_device_base.h" 46 #ifdef __cplusplus 47 extern "C" { 48 #endif 49 /** 50 * Request to release the capturer stream. 51 * 52 * @since 10 53 * @permission ohos.permission.MICROPHONE 54 * 55 * @param capturer reference created by OH_AudioStreamBuilder_GenerateCapturer() 56 * @return Function result code: 57 * {@link AUDIOSTREAM_SUCCESS} If the execution is successful. 58 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM} The param of capturer is nullptr. 59 * {@link AUDIOSTREAM_ERROR_ILLEGAL_STATE} Execution status exception. 60 */ 61 OH_AudioStream_Result OH_AudioCapturer_Release(OH_AudioCapturer* capturer); 62 63 /** 64 * Request to start the capturer stream. 65 * 66 * @since 10 67 * @permission ohos.permission.MICROPHONE 68 * 69 * @param capturer reference created by OH_AudioStreamBuilder_GenerateCapturer() 70 * @return Function result code: 71 * {@link AUDIOSTREAM_SUCCESS} If the execution is successful. 72 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM} The param of capturer is nullptr. 73 * {@link AUDIOSTREAM_ERROR_ILLEGAL_STATE} Execution status exception. 74 */ 75 OH_AudioStream_Result OH_AudioCapturer_Start(OH_AudioCapturer* capturer); 76 77 /** 78 * Request to pause the capturer stream. 79 * 80 * @since 10 81 * @permission ohos.permission.MICROPHONE 82 * 83 * @param capturer reference created by OH_AudioStreamBuilder_GenerateCapturer() 84 * @return Function result code: 85 * {@link AUDIOSTREAM_SUCCESS} If the execution is successful. 86 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM} The param of capturer is nullptr. 87 * {@link AUDIOSTREAM_ERROR_ILLEGAL_STATE} Execution status exception. 88 */ 89 OH_AudioStream_Result OH_AudioCapturer_Pause(OH_AudioCapturer* capturer); 90 91 /** 92 * Request to stop the capturer stream. 93 * 94 * @since 10 95 * @permission ohos.permission.MICROPHONE 96 * 97 * @param capturer reference created by OH_AudioStreamBuilder_GenerateCapturer() 98 * @return Function result code: 99 * {@link AUDIOSTREAM_SUCCESS} If the execution is successful. 100 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM} The param of capturer is nullptr. 101 * {@link AUDIOSTREAM_ERROR_ILLEGAL_STATE} Execution status exception. 102 */ 103 OH_AudioStream_Result OH_AudioCapturer_Stop(OH_AudioCapturer* capturer); 104 105 /** 106 * Request to flush the capturer stream. 107 * 108 * @since 10 109 * 110 * @param capturer reference created by OH_AudioStreamBuilder_GenerateCapturer() 111 * @return Function result code: 112 * {@link AUDIOSTREAM_SUCCESS} If the execution is successful. 113 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM} The param of capturer is nullptr. 114 * {@link AUDIOSTREAM_ERROR_ILLEGAL_STATE} Execution status exception. 115 */ 116 OH_AudioStream_Result OH_AudioCapturer_Flush(OH_AudioCapturer* capturer); 117 118 /** 119 * Query the current state of the capturer client. 120 * 121 * This function will return the capturer state without updating the state. 122 * 123 * @since 10 124 * 125 * @param capturer Reference created by OH_AudioStreamBuilder_GenerateCapturer() 126 * @param state Pointer to a variable that will be set for the state value. 127 * @return Function result code: 128 * {@link AUDIOSTREAM_SUCCESS} If the execution is successful. 129 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM} The param of capturer is nullptr. 130 */ 131 OH_AudioStream_Result OH_AudioCapturer_GetCurrentState(OH_AudioCapturer* capturer, OH_AudioStream_State* state); 132 133 /** 134 * Query the latency mode of the capturer client. 135 * 136 * @since 10 137 * 138 * @param capturer Reference created by OH_AudioStreamBuilder_GenerateCapturer() 139 * @param latencyMode Pointer to a variable that will be set for the latency mode. 140 * @return Function result code: 141 * {@link AUDIOSTREAM_SUCCESS} If the execution is successful. 142 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM} The param of capturer is nullptr. 143 */ 144 OH_AudioStream_Result OH_AudioCapturer_GetLatencyMode(OH_AudioCapturer* capturer, 145 OH_AudioStream_LatencyMode* latencyMode); 146 147 /** 148 * Query the stream id of the capturer client. 149 * 150 * @since 10 151 * 152 * @param capturer Reference created by OH_AudioStreamBuilder_GenerateCapturer() 153 * @param streamId Pointer to a variable that will be set for the stream id. 154 * @return Function result code: 155 * {@link AUDIOSTREAM_SUCCESS} If the execution is successful. 156 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM} The param of capturer is nullptr. 157 */ 158 OH_AudioStream_Result OH_AudioCapturer_GetStreamId(OH_AudioCapturer* capturer, uint32_t* streamId); 159 160 /** 161 * Query the sample rate value of the capturer client. 162 * 163 * This function will return the capturer sample rate value without updating the state. 164 * 165 * @since 10 166 * 167 * @param capturer Reference created by OH_AudioStreamBuilder_GenerateCapturer() 168 * @param rate The state value to be updated 169 * @return Function result code: 170 * {@link AUDIOSTREAM_SUCCESS} If the execution is successful. 171 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM} The param of capturer is nullptr. 172 */ 173 OH_AudioStream_Result OH_AudioCapturer_GetSamplingRate(OH_AudioCapturer* capturer, int32_t* rate); 174 175 /** 176 * Query the channel count of the capturer client. 177 * 178 * @since 10 179 * 180 * @param capturer Reference created by OH_AudioStreamBuilder_GenerateCapturer() 181 * @param channelCount Pointer to a variable that will be set for the channel count. 182 * @return Function result code: 183 * {@link AUDIOSTREAM_SUCCESS} If the execution is successful. 184 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM} The param of capturer is nullptr. 185 */ 186 OH_AudioStream_Result OH_AudioCapturer_GetChannelCount(OH_AudioCapturer* capturer, int32_t* channelCount); 187 188 /** 189 * Query the sample format of the capturer client. 190 * 191 * @since 10 192 * 193 * @param capturer Reference created by OH_AudioStreamBuilder_GenerateCapturer() 194 * @param sampleFormat Pointer to a variable that will be set for the sample format. 195 * @return Function result code: 196 * {@link AUDIOSTREAM_SUCCESS} If the execution is successful. 197 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM} The param of capturer is nullptr. 198 */ 199 OH_AudioStream_Result OH_AudioCapturer_GetSampleFormat(OH_AudioCapturer* capturer, 200 OH_AudioStream_SampleFormat* sampleFormat); 201 202 /** 203 * Query the encoding type of the capturer client. 204 * 205 * @since 10 206 * 207 * @param capturer Reference created by OH_AudioStreamBuilder_GenerateCapturer() 208 * @param encodingType Pointer to a variable that will be set for the encoding type. 209 * @return Function result code: 210 * {@link AUDIOSTREAM_SUCCESS} If the execution is successful. 211 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM} The param of capturer is nullptr. 212 */ 213 OH_AudioStream_Result OH_AudioCapturer_GetEncodingType(OH_AudioCapturer* capturer, 214 OH_AudioStream_EncodingType* encodingType); 215 216 /** 217 * Query the capturer info of the capturer client. 218 * 219 * @since 10 220 * 221 * @param capturer Reference created by OH_AudioStreamBuilder_GenerateCapturer() 222 * @param sourceType Pointer to a variable that will be set for the stream sourceType. 223 * @return Function result code: 224 * {@link AUDIOSTREAM_SUCCESS} If the execution is successful. 225 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM} The param of capturer is nullptr. 226 */ 227 OH_AudioStream_Result OH_AudioCapturer_GetCapturerInfo(OH_AudioCapturer* capturer, 228 OH_AudioStream_SourceType* sourceType); 229 230 /** 231 * Query the frame size in callback, it is a fixed length of the buffer returned by each callback. 232 * 233 * @since 10 234 * 235 * @param capturer Reference created by OH_AudioStreamBuilder_GenerateCapturer() 236 * @param frameSize Pointer to a variable that will be set for the frame size. 237 * @return Function result code: 238 * {@link AUDIOSTREAM_SUCCESS} If the execution is successful. 239 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM} The param of capturer is nullptr. 240 * {@link AUDIOSTREAM_ERROR_ILLEGAL_STATE} Execution status exception. 241 */ 242 OH_AudioStream_Result OH_AudioCapturer_GetFrameSizeInCallback(OH_AudioCapturer* capturer, int32_t* frameSize); 243 244 /** 245 * Query the the time at which a particular frame was presented 246 * 247 * @since 10 248 * 249 * @param capturer Reference created by OH_AudioStreamBuilder_GenerateCapturer() 250 * @param clockId {@link #CLOCK_MONOTONIC} 251 * @param framePosition Pointer to a variable to receive the position 252 * @param timestamp Pointer to a variable to receive the timestamp 253 * @return Function result code: 254 * {@link AUDIOSTREAM_SUCCESS} If the execution is successful. 255 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM}: 256 * 1.The param of capturer is nullptr; 257 * 2.The param of clockId invalid. 258 * {@link AUDIOSTREAM_ERROR_ILLEGAL_STATE} Execution status exception. 259 */ 260 OH_AudioStream_Result OH_AudioCapturer_GetTimestamp(OH_AudioCapturer* capturer, 261 clockid_t clockId, int64_t* framePosition, int64_t* timestamp); 262 263 /** 264 * Query the the number of frames that have been read since the stream was created. 265 * 266 * @since 10 267 * 268 * @param capturer Reference created by OH_AudioStreamBuilder_GenerateCapturer() 269 * @param frames Pointer to a variable that will be set for the frame count number. 270 * @return Function result code: 271 * {@link AUDIOSTREAM_SUCCESS} If the execution is successful. 272 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM} The param of capturer is nullptr. 273 */ 274 OH_AudioStream_Result OH_AudioCapturer_GetFramesRead(OH_AudioCapturer* capturer, int64_t* frames); 275 276 /** 277 * @brief Gets the overflow count on this stream. 278 * 279 * @since 12 280 * 281 * @param capturer Capturer generated by OH_AudioStreamBuilder_GenerateCapturer() 282 * @param count Pointer to a variable that will be set for the overflow count number. 283 * @return Function result code: 284 * {@link AUDIOSTREAM_SUCCESS} If the execution is successful. 285 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM} The param of capturer is nullptr. 286 */ 287 OH_AudioStream_Result OH_AudioCapturer_GetOverflowCount(OH_AudioCapturer* capturer, uint32_t* count); 288 289 /** 290 * @brief Called when audio data is available to read. This function is similar to 291 * OH_AudioCapturer_Callbacks_Struct.OH_AudioCapturer_OnReadData. 292 * 293 * @param capturer Pointer to the AudioCapturer instance that triggers the callback. 294 * @param userData Pointer to the user data passed when setting the callback via 295 * OH_AudioStreamBuilder_SetCapturerReadDataCallback. 296 * @param audioData Pointer to the available audio data. 297 * @param audioDataSize Size of the available audio data. 298 * @see OH_AudioCapturer_Callbacks_Struct.OH_AudioCapturer_OnReadData 299 * @since 20 300 */ 301 typedef void (*OH_AudioCapturer_OnReadDataCallback)(OH_AudioCapturer* capturer, void* userData, void* audioData, 302 int32_t audioDataSize); 303 304 /** 305 * @brief Called when the input device of an AudioCapturer instance changes. 306 * This function is similar to OH_AudioCapturer_Callbacks_Struct.OH_AudioCapturer_OnStreamEvent. 307 * 308 * @param capturer Pointer to the AudioCapturer instance that triggers the callback. 309 * @param userData Pointer to the user data passed when setting the callback via 310 * OH_AudioStreamBuilder_SetCapturerDeviceChangeCallback. 311 * @param deviceArray Pointer to an array of the new input devices. 312 * @see OH_AudioCapturer_Callbacks_Struct.OH_AudioCapturer_OnStreamEvent 313 * @since 20 314 */ 315 typedef void (*OH_AudioCapturer_OnDeviceChangeCallback)(OH_AudioCapturer* capturer, void* userData, 316 OH_AudioDeviceDescriptorArray* deviceArray); 317 318 /** 319 * @brief Called when an interrupt event occurs in an AudioCapturer instance. 320 * This function is similar to OH_AudioCapturer_Callbacks_Struct.OH_AudioCapturer_OnInterruptEvent. 321 * 322 * @param capturer Pointer to the AudioCapturer instance that triggers the callback. 323 * @param userData Pointer to the user data passed when setting the callback via 324 * OH_AudioStreamBuilder_SetCapturerInterruptCallback. 325 * @param type Type of force that causes the interrupt event. 326 * @param hint Hint provided along with the interrupt event. 327 * @see OH_AudioCapturer_Callbacks_Struct.OH_AudioCapturer_OnInterruptEvent. 328 * @since 20 329 */ 330 typedef void (*OH_AudioCapturer_OnInterruptCallback)(OH_AudioCapturer* capturer, void* userData, 331 OH_AudioInterrupt_ForceType type, OH_AudioInterrupt_Hint hint); 332 333 /** 334 * @brief Called when an error event occurs in an AudioCapturer instance. 335 * This function is similar to OH_AudioCapturer_Callbacks_Struct.OH_AudioCapturer_OnError. 336 * 337 * @param capturer Pointer to the AudioCapturer instance that triggers the callback. 338 * @param userData Pointer to the user data passed when setting the callback via 339 * OH_AudioStreamBuilder_SetCapturerErrorCallback. 340 * @param error Specific error information. 341 * @see OH_AudioCapturer_Callbacks_Struct.OH_AudioCapturer_OnError 342 * @since 20 343 */ 344 typedef void (*OH_AudioCapturer_OnErrorCallback)(OH_AudioCapturer* capturer, void* userData, 345 OH_AudioStream_Result error); 346 347 /** 348 * @brief Gets audio capturer running status, check if it works in fast status. 349 * 350 * @param capturer Reference created by OH_AudioStreamBuilder_GenerateCapturer. 351 * @param status Pointer to a variable to receive the status. 352 * @return 353 * {@link AUDIOSTREAM_SUCCESS} if the execution is successful. 354 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM} the param of capturer is nullptr. 355 * {@link AUDIOSTREAM_ERROR_ILLEGAL_STATE} function called in invalid state, only available before release state. 356 * @since 20 357 */ 358 OH_AudioStream_Result OH_AudioCapturer_GetFastStatus(OH_AudioCapturer* capturer, 359 OH_AudioStream_FastStatus* status); 360 361 /** 362 * @brief Callback function of fast status change event for audio capturer. 363 * 364 * @param capturer Pointer to an audio capturer instance for which this callback occurs. 365 * @param userData Userdata which is passed by register. 366 * @param status Current fast status. 367 * @since 20 368 */ 369 typedef void (*OH_AudioCapturer_OnFastStatusChange)( 370 OH_AudioCapturer* capturer, 371 void* userData, 372 OH_AudioStream_FastStatus status 373 ); 374 375 #ifdef __cplusplus 376 } 377 #endif 378 379 #endif // NATIVE_AUDIOCAPTURER_H 380 /** @} */ 381