1 /*
2  * Copyright (c) 2024 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 12
25  * @version 1.0
26  */
27 
28 /**
29  * @file native_audio_device_base.h
30  *
31  * @brief Declare audio device related interfaces for audio device descriptor.
32  *
33  * Defines the types of audio device parameters and the interfaces for obtaining the parameters of each device.
34  *
35  * @library libohaudio.so
36  * @syscap SystemCapability.Multimedia.Audio.Core
37  * @kit AudioKit
38  * @since 12
39  * @version 1.0
40  */
41 
42 #ifndef NATIVE_AUDIO_DEVICE_BASE_H
43 #define NATIVE_AUDIO_DEVICE_BASE_H
44 
45 #include "native_audiostream_base.h"
46 #include "native_audio_common.h"
47 #ifdef __cplusplus
48 extern "C" {
49 #endif
50 
51 /**
52  * @brief Defines the audio device change type.
53  *
54  * @since 12
55  */
56 typedef enum {
57     /**
58      * @brief Device connection.
59      */
60     AUDIO_DEVICE_CHANGE_TYPE_CONNECT = 0,
61 
62     /**
63      * @brief Device disconnection.
64      */
65     AUDIO_DEVICE_CHANGE_TYPE_DISCONNECT = 1,
66 } OH_AudioDevice_ChangeType;
67 
68 /**
69  * @brief Defines the audio device device role.
70  *
71  * @since 12
72  */
73 typedef enum {
74     /**
75      * @brief Input role.
76      */
77     AUDIO_DEVICE_ROLE_INPUT = 1,
78 
79     /**
80      * @brief Output role.
81      */
82     AUDIO_DEVICE_ROLE_OUTPUT = 2,
83 } OH_AudioDevice_Role;
84 
85 /**
86  * @brief Defines the audio device device type.
87  *
88  * @since 12
89  */
90 typedef enum {
91     /**
92      * @brief Invalid device.
93      */
94     AUDIO_DEVICE_TYPE_INVALID = 0,
95 
96     /**
97      * @brief Built-in earpiece.
98      */
99     AUDIO_DEVICE_TYPE_EARPIECE = 1,
100 
101     /**
102      * @brief Built-in speaker.
103      */
104     AUDIO_DEVICE_TYPE_SPEAKER = 2,
105 
106     /**
107      * @brief Wired headset, which is a combination of a pair of earpieces and a microphone.
108      */
109     AUDIO_DEVICE_TYPE_WIRED_HEADSET = 3,
110 
111     /**
112      * @brief A pair of wired headphones.
113      */
114     AUDIO_DEVICE_TYPE_WIRED_HEADPHONES = 4,
115 
116     /**
117      * @brief Bluetooth device using the synchronous connection oriented link (SCO).
118      */
119     AUDIO_DEVICE_TYPE_BLUETOOTH_SCO = 7,
120 
121     /**
122      * @brief Bluetooth device using advanced audio distibution profile (A2DP).
123      */
124     AUDIO_DEVICE_TYPE_BLUETOOTH_A2DP = 8,
125 
126     /**
127      * @brief Built-in microphone.
128      */
129     AUDIO_DEVICE_TYPE_MIC = 15,
130 
131     /**
132      * @brief USB audio headset.
133      */
134     AUDIO_DEVICE_TYPE_USB_HEADSET = 22,
135 
136     /**
137      * @brief Display port device.
138      */
139     AUDIO_DEVICE_TYPE_DISPLAY_PORT = 23,
140 
141     /**
142      * @brief Device type for rerouting audio to other remote devices by system application.
143      */
144     AUDIO_DEVICE_TYPE_REMOTE_CAST = 24,
145 
146     /**
147      * @brief Default device type.
148      */
149     AUDIO_DEVICE_TYPE_DEFAULT = 1000,
150 } OH_AudioDevice_Type;
151 
152 /**
153  * @brief Defines the audio device flag.
154  *
155  * @since 12
156  */
157 typedef enum {
158     /**
159      * @brief None device.
160      */
161     AUDIO_DEVICE_FLAG_NONE = 0,
162 
163     /**
164      * @brief Output device.
165      */
166     AUDIO_DEVICE_FLAG_OUTPUT = 1,
167 
168     /**
169      * @brief Input device.
170      */
171     AUDIO_DEVICE_FLAG_INPUT = 2,
172 
173     /**
174      * @brief All device.
175      */
176     AUDIO_DEVICE_FLAG_ALL = 3,
177 } OH_AudioDevice_Flag;
178 
179 /**
180  * @brief Defines the audio device usage.
181  *
182  * @since 12
183  */
184 typedef enum {
185     /**
186      * @brief Device used for media ouput.
187      *
188      * @since 12
189      */
190     AUDIO_DEVICE_USAGE_MEDIA_OUTPUT = 1,
191 
192     /**
193      * @brief Device used for media input.
194      *
195      * @since 12
196      */
197     AUDIO_DEVICE_USAGE_MEDIA_INPUT = 2,
198 
199     /**
200      * @brief Device used for media, including input and output.
201      *
202      * @since 12
203      */
204     AUDIO_DEVICE_USAGE_MEDIA_ALL = 3,
205 
206     /**
207      * @brief Device used for call output.
208      *
209      * @since 12
210      */
211     AUDIO_DEVICE_USAGE_CALL_OUTPUT = 4,
212 
213     /**
214      * @brief Device used for call input.
215      *
216      * @since 12
217      */
218     AUDIO_DEVICE_USAGE_CALL_INPUT = 8,
219 
220     /**
221      * @brief Device used for call, including input and output.
222      *
223      * @since 12
224      */
225     AUDIO_DEVICE_USAGE_CALL_ALL = 12,
226 } OH_AudioDevice_Usage;
227 
228 /**
229  * @brief Declaring the audio device descriptor.
230  * The instance is used to get more audio device detail attributes.
231  *
232  * @since 12
233  */
234 typedef struct OH_AudioDeviceDescriptor OH_AudioDeviceDescriptor;
235 
236 /**
237  * @brief Declaring the audio device descriptor array.
238  *
239  * @since 12
240  */
241 typedef struct OH_AudioDeviceDescriptorArray {
242     /**
243      * @brief Audio device descriptor array size.
244      */
245     uint32_t size;
246 
247     /**
248      * @brief Audio device descriptor array.
249      */
250     OH_AudioDeviceDescriptor **descriptors;
251 } OH_AudioDeviceDescriptorArray;
252 
253 /**
254  * @brief Declaring the audio device blocked status. By default, the audio device is considered as unbloked.
255  *
256  * @since 13
257  */
258 typedef enum {
259     /**
260      * @brief Audio device is unblocked.
261      *
262      * @since 13
263      */
264     AUDIO_DEVICE_UNBLOCKED = 0,
265 
266     /**
267      * @brief Audio Device is blocked.
268      *
269      * @since 13
270      */
271     AUDIO_DEVICE_BLOCKED = 1,
272 } OH_AudioDevice_BlockStatus;
273 
274 
275 /**
276  * @brief Query the device role of the target audio device descriptor.
277  *
278  * @param audioDeviceDescriptor reference returned by {@link OH_AudioRoutingManager_GetDevices} or
279  * {@link OH_AudioRouterManager_OnDeviceChangedCallback}.
280  * @param deviceRole the pointer {@link OH_AudioDevice_DeviceRole} variable that will be set the device role value.
281  * @return {@link #AUDIOCOMMON_RESULT_SUCCESS} or {@link #AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM}.
282  * @since 12
283  */
284 OH_AudioCommon_Result OH_AudioDeviceDescriptor_GetDeviceRole(OH_AudioDeviceDescriptor *audioDeviceDescriptor,
285     OH_AudioDevice_Role *deviceRole);
286 
287 /**
288  * @brief Query the device type of the target audio device descriptor.
289  *
290  * @param audioDeviceDescriptor reference returned by {@link OH_AudioRoutingManager_GetDevices} or
291  * {@link OH_AudioRouterManager_OnDeviceChangedCallback}.
292  * @param deviceType the pointer {@link OH_AudioDevice_DeviceType}
293  * pointer variable that will be set the device type value.
294  * @return {@link #AUDIOCOMMON_RESULT_SUCCESS} or {@link #AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM}.
295  * @since 12
296  */
297 OH_AudioCommon_Result OH_AudioDeviceDescriptor_GetDeviceType(OH_AudioDeviceDescriptor *audioDeviceDescriptor,
298     OH_AudioDevice_Type *deviceType);
299 
300 /**
301  * @brief Query the device id of the target audio device descriptor.
302  *
303  * @param audioDeviceDescriptor reference returned by {@link OH_AudioRoutingManager_GetDevices} or
304  * {@link OH_AudioRouterManager_OnDeviceChangedCallback}.
305  * @param id pointer variable that will be set the device id value.
306  * @return {@link #AUDIODEVICE_SUCCESS} or {@link #AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM}.
307  * @since 12
308  */
309 OH_AudioCommon_Result OH_AudioDeviceDescriptor_GetDeviceId(OH_AudioDeviceDescriptor *audioDeviceDescriptor,
310     uint32_t *id);
311 
312 /**
313  * @brief Query the device name of the target audio device descriptor.
314  *
315  * @param audioDeviceDescriptor reference returned by {@link OH_AudioRoutingManager_GetDevices} or
316  * {@link OH_AudioRouterManager_OnDeviceChangedCallback}.
317  * @param name pointer variable that will be set the device name value.
318  * Do not release the name pointer separately
319  * instead call {@link OH_AudioRoutingManager_ReleaseDevices} to release the DeviceDescriptor array
320  * when it is no use anymore.
321  * @return {@link #AUDIOCOMMON_RESULT_SUCCESS} or {@link #AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM}.
322  * @since 12
323  */
324 OH_AudioCommon_Result OH_AudioDeviceDescriptor_GetDeviceName(OH_AudioDeviceDescriptor *audioDeviceDescriptor,
325     char **name);
326 
327 /**
328  * @brief Query the device address of the target audio device descriptor.
329  *
330  * @param audioDeviceDescriptor reference returned by {@link OH_AudioRoutingManager_GetDevices} or
331  * {@link OH_AudioRouterManager_OnDeviceChangedCallback}.
332  * @param address pointer variable that will be set the device address value.
333  * Do not release the address pointer separately
334  * instead call {@link OH_AudioRoutingManager_ReleaseDevices} to release the DeviceDescriptor array
335  * when it is no use anymore.
336  * @return {@link #AUDIOCOMMON_RESULT_SUCCESS} or {@link #AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM}.
337  * @since 12
338  */
339 OH_AudioCommon_Result OH_AudioDeviceDescriptor_GetDeviceAddress(OH_AudioDeviceDescriptor *audioDeviceDescriptor,
340     char **address);
341 
342 /**
343  * @brief Query the sample rate array of the target audio device descriptor.
344  *
345  * @param audioDeviceDescriptor reference returned by {@link OH_AudioRoutingManager_GetDevices} or
346  * {@link OH_AudioRouterManager_OnDeviceChangedCallback}.
347  * @param sampleRates array pointer variable that will be set the sample rate array value.
348  * Do not release the sampleRates pointer separately
349  * instead call {@link OH_AudioRoutingManager_ReleaseDevices} to release the DeviceDescriptor array
350  * when it is no use anymore.
351  * @param size pointer variable that will be set the sample rate size value.
352  * @return {@link #AUDIOCOMMON_RESULT_SUCCESS} or {@link #AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM}.
353  * @since 12
354  */
355 OH_AudioCommon_Result OH_AudioDeviceDescriptor_GetDeviceSampleRates(OH_AudioDeviceDescriptor *audioDeviceDescriptor,
356     uint32_t **sampleRates, uint32_t *size);
357 
358 /**
359  * @brief Query the device channel count array of the target audio device descriptor.
360  *
361  * @param audioDeviceDescriptor reference returned by {@link OH_AudioRoutingManager_GetDevices} or
362  * {@link OH_AudioRouterManager_OnDeviceChangedCallback}.
363  * @param channelCounts array pointer variable that will be set the channel count array value.
364  * Do not release the channelCounts pointer separately
365  * instead call {@link OH_AudioRoutingManager_ReleaseDevices} to release the DeviceDescriptor array
366  * when it is no use anymore.
367  * @param size pointer variable that will be set the channel count size value.
368  * @return {@link #AUDIOCOMMON_RESULT_SUCCESS} or {@link #AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM}.
369  * @since 12
370  */
371 OH_AudioCommon_Result OH_AudioDeviceDescriptor_GetDeviceChannelCounts(OH_AudioDeviceDescriptor *audioDeviceDescriptor,
372     uint32_t **channelCounts, uint32_t *size);
373 
374 /**
375  * @brief Query the display name of the target audio device descriptor.
376  *
377  * @param audioDeviceDescriptor reference returned by {@link OH_AudioRoutingManager_GetDevices} or
378  * {@link OH_AudioRouterManager_OnDeviceChangedCallback}.
379  * @param displayName pointer variable that will be set the display name value.
380  * Do not release the displayName pointer separately
381  * instead call {@link OH_AudioRoutingManager_ReleaseDevices} to release the DeviceDescriptor array
382  * when it is no use anymore.
383  * @return {@link #AUDIOCOMMON_RESULT_SUCCESS} or {@link #AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM}.
384  * @since 12
385  */
386 OH_AudioCommon_Result OH_AudioDeviceDescriptor_GetDeviceDisplayName(OH_AudioDeviceDescriptor *audioDeviceDescriptor,
387     char **displayName);
388 
389 /**
390  * @brief Query the encoding type array of the target audio device descriptor.
391  *
392  * @param audioDeviceDescriptor reference returned by {@link OH_AudioRoutingManager_GetDevices} or
393  * {@link OH_AudioRouterManager_OnDeviceChangedCallback}.
394  * @param encodingTypes the {@link OH_AudioStream_EncodingType}
395  * Do not release the encodingTypes pointer separately
396  * instead call {@link OH_AudioRoutingManager_ReleaseDevices} to release the DeviceDescriptor array
397  * when it is no use anymore.
398  * @param size pointer variable that will be set the encoding type size value.
399  * @return {@link #AUDIOCOMMON_RESULT_SUCCESS} or {@link #AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM}.
400  * @since 12
401  */
402 OH_AudioCommon_Result OH_AudioDeviceDescriptor_GetDeviceEncodingTypes(OH_AudioDeviceDescriptor *audioDeviceDescriptor,
403     OH_AudioStream_EncodingType **encodingTypes, uint32_t *size);
404 #ifdef __cplusplus
405 }
406 #endif
407 /** @} */
408 #endif // NATIVE_AUDIO_DEVICE_BASE_H
409