harmonyos-best-practices-mcp 0.1.0

package/data/docs/bpta-malloc-dispatch-table.md

@@ -0,0 +1,144 @@
+# 内存泄漏定制能力开放使用指导
+
+> 来源: https://developer.huawei.com/consumer/cn/doc/best-practices/bpta-malloc-dispatch-table
+> 文档标识(fileName): bpta-malloc-dispatch-table  
+> 目录(catalogName): best-practices  
+> 语言: cn  
+> 更新时间: 2026-06-23 03:40:27  
+> 导航地址: /hmos/hmos-dp1
+
+---
+#### 概述
+
+三方应用的内存泄漏问题往往难以定位，传统分析方式效率低下。为提升排查效率，HarmonyOS提供了MallocDispatchTable机制，支持开发者定制内存分配函数的Hook行为，灵活插入自定义监控逻辑，从而实现对内存分配行为的精准追踪与泄漏场景的主动捕获。通过这一能力，开发者可按需定制Hook策略，如记录调用栈、统计分配频次、设置阈值告警等，显著增强内存泄漏问题的定制化分析能力。
+
+注：Hook是计算机编程中的一种钩子技术，它允许开发者拦截、修改或扩展函数的行为。通过使用钩子，开发者可以注入自定义代码，在特定事件发生时修改程序的行为。
+
+本文将介绍以下内容：
+
+- [MallocDispatchTable简介](#section192072233251)
+- [MallocDispatchTable的Hook流程](#section18679163332511)
+- [场景案例](#section1893852252419)
+
+#### 实现原理
+
+## MallocDispatchTable简介
+
+MallocDispatchTable简称内存分配表，提供对HarmonyOS [libc标准库](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/musl)中的malloc、calloc、realloc、free等内存操作系列函数的Hook能力。此能力可用于跟踪应用的内存分配/释放信息，辅助内存泄漏问题快速定界定位。
+
+注：内存基础知识参考文档：[内存基础知识](https://developer.huawei.com/consumer/cn/doc/best-practices/bpta-memory-basic-knowledge#section085818715389)。
+
+## MallocDispatchTable的Hook流程
+
+如下图示例，开发者可使用自定义函数替换标准库函数，应用程序调用标准库函数时实际上执行的是自定义的函数。通过MallocDispatchTable里的函数指针，调用标准库函数时可以重定向到自定义的函数。MallocDispatchTable的主要功能在于将标准库函数的实现和自定义函数进行解耦。
+
+![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/26/v3/ZVp5ZZExSWiNnVs-wywx3w/zh-cn_image_0000002501437914.png?HW-CC-KV=V1&HW-CC-Date=20260623T075708Z&HW-CC-Expire=86400&HW-CC-Sign=36CED740D63BCD2809C982370D4E9B4C38E32D930B9C221ABD3FC1B2CA4BD486)
+
+开发人员可使用提供的[OH_HiDebug_SetMallocDispatchTable()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-hidebug-h#oh_hidebug_setmallocdispatchtable)接口设置libc标准库中使用的MallocDispatchTable；使用[OH_HiDebug_GetDefaultMallocDispatchTable()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-hidebug-h#oh_hidebug_getdefaultmallocdispatchtable)接口获取libc中默认的MallocDispatchTable。
+
+#### 场景案例
+
+## 场景描述
+
+开发者观察到程序的匿名内存大小持续上涨，需要记录程序调用标准库的mmap和munmap函数的信息（包括分配内存大小、地址），从而统计使用mmap分配但未被释放（未记录到使用munmap释放对应内存地址）的内存大小。
+
+## 开发步骤
+
+1. **添加头文件依赖。**
+
+   ```
+   #include "hidebug/hidebug.h"
+   #include "hidebug/hidebug_type.h"
+   ```
+
+   开发首先需要引用MallocDispatchTable相关的头文件。
+2. **创建自定义mmap和munmap方法。**
+
+   ```
+   static void* MyMmap(void* addr, size_t len, int prot, int flags, int fd, off_t offset)
+   {
+       HiDebug_MallocDispatch* original = (HiDebug_MallocDispatch*)OH_HiDebug_GetDefaultMallocDispatchTable();
+       void* returnAddr = original->mmap(addr, len, prot, flags, fd, offset);
+       OH_LOG_INFO(LOG_APP, "test MyMmap with len:%{public}d and addr:%{public}p", len, returnAddr);
+       return returnAddr;
+   }
+
+   static int MyMunmap(void* addr, size_t len)
+   {
+       HiDebug_MallocDispatch* original = (HiDebug_MallocDispatch*)OH_HiDebug_GetDefaultMallocDispatchTable();
+       OH_LOG_INFO(LOG_APP, "test MyMunmap with len:%{public}d and addr:%{public}p", len, addr);
+       return original->munmap(addr, len);
+   }
+   ```
+
+   自定义的函数中将内存地址（函数参数addr）以及内存区间大小（函数参数len）通过日志打印。
+3. **创建一个[HiDebug_MallocDispatch](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-hidebug-hidebug-mallocdispatch)类型的分配表。**
+
+   ```
+   //Obtain default MallocDispatchTable that can allocate memory directly.
+   HiDebug_MallocDispatch* original = (HiDebug_MallocDispatch*)OH_HiDebug_GetDefaultMallocDispatchTable();
+   //Create a MallocDispatchTable struct called current.
+   HiDebug_MallocDispatch* current = (HiDebug_MallocDispatch*)original->malloc(sizeof(HiDebug_MallocDispatch));
+   memset(current, 0, sizeof(HiDebug_MallocDispatch));
+   //replace function pointers of current, from which self-defined functions can be redirected.
+   current->mmap = MyMmap;
+   current->munmap = MyMunmap;
+   ```
+
+   创建一个HiDebug_MallocDispatch结构体current，通过[OH_HiDebug_GetDefaultMallocDispatchTable()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-hidebug-h#oh_hidebug_getdefaultmallocdispatchtable)分配其占用的堆内存。修改结构体中的函数指针，让其指向之前定义的MyMmap和MyMunmap函数。
+4. **启用自定义 MallocDispatchTable。**
+
+   ```
+   OH_HiDebug_SetMallocDispatchTable(current);
+   ```
+
+   将[libc标准库](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/musl)中使用的MallocDispatchTable替换成自定义的分配表。
+5. **调用libc标准库中的mmap函数。**
+
+   ```
+   char* mapPtr = nullptr;
+   const size_t bufferSize = 100;  // 100 : the size of memory
+   mapPtr = (char*)mmap(nullptr, bufferSize, PROT_READ | PROT_WRITE, MAP_SHARED | MAP_ANONYMOUS, -1, 0);
+   if (mapPtr == MAP_FAILED) {
+       printf("mmap failed\n");
+       return;
+   }
+   munmap(mapPtr, bufferSize);
+   ```
+
+   在执行上述基础库mmap函数时，会自动重定向到先前定义的MyMmap函数，完成业务自定义功能。
+6. **停用自定义 MallocDispatchTable。**
+
+   ```
+   //release memory of self-defined MallocDispatchTable struct.
+   HiDebug_MallocDispatch* original = (HiDebug_MallocDispatch*)OH_HiDebug_GetDefaultMallocDispatchTable();
+   original->free(current);
+   //reset MallocDispatchTable strut that libc uses.
+   OH_HiDebug_RestoreMallocDispatchTable();
+   ```
+
+   调用[OH_HiDebug_RestoreMallocDispatchTable()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-hidebug-h#oh_hidebug_restoremallocdispatchtable)接口可以恢复标准库默认的MallocDispatchTable。
+7. **CMakeLists.txt文件中添加如下依赖项。**
+
+   ```
+   add_library(entry SHARED napi_init.cpp test_backtrace.cpp test_malloc_dispatch.cpp)
+   target_link_libraries(entry PUBLIC libace_napi.z.so libhilog_ndk.z.so libohhidebug.so)
+   ```
+
+![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/96/v3/EJqssnsNSqiTgGeu6Lum5g/caution_3.0-zh-cn.png?HW-CC-KV=V1&HW-CC-Date=20260623T075708Z&HW-CC-Expire=86400&HW-CC-Sign=2E133F7A300108F1C5DEEBED0C277EB4A0D8AF0E826096B87A3D18DD6366C4B3) 
+
+若应用程序设置了自定义的MallocDispatchTable，则与HarmonyOS提供的部分机制存在互斥，请在上述步骤4启用自定义MallocDispatchTable后注意。
+
+具体限制如下：
+
+1. 无法通过GWP-ASan功能进行内存越界检测。GWP-ASan 的工作原理详见文档：[GWP-ASan检测原理](https://developer.huawei.com/consumer/cn/doc/best-practices/bpta-stability-address-sanitizer-principle#section555616291854)。
+2. 无法通过使用[native hook插件](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/hiprofiler#native-hook插件)对该应用程序进行函数调用栈捕获。
+
+![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/65/v3/V3vWaUT-RXGhEgDbyPWcWg/warning_3.0-zh-cn.png?HW-CC-KV=V1&HW-CC-Date=20260623T075708Z&HW-CC-Expire=86400&HW-CC-Sign=CE766A60E08D5F1D0CDC0BF457E4A48E3F4BEC16119D99B38EEEA641902723CF) 
+
+1. 禁止在自定义方法中调用[libc标准库](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/musl)内存操作函数（malloc/free/mmap/munmap），否则会导致死循环。
+2. 禁止在自定义malloc方法中使用[hilog](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/hilog)进行日志打印，否则会导致死锁问题。
+
+#### 示例代码
+
+- [性能分析工具](https://gitcode.com/HarmonyOS_Samples/guide-snippets/blob/master/PerformanceAnalysisKit/HiDebugTool/README_zh.md)

package/data/docs/bpta-managing-audio-input-devices.md

@@ -0,0 +1,350 @@
+# 管理音频输入设备开发实践
+
+> 来源: https://developer.huawei.com/consumer/cn/doc/best-practices/bpta-managing-audio-input-devices
+> 文档标识(fileName): bpta-managing-audio-input-devices  
+> 目录(catalogName): best-practices  
+> 语言: cn  
+> 更新时间: 2026-06-23 03:35:39  
+> 导航地址: /hmos/hmos-dp1
+
+---
+#### 概述
+
+在录音、语音通话、录制语音消息等场景下，经常需要切换输入设备，例如从手机麦克风切换到蓝牙耳机。因此，开发者需要对系统的音频输入设备进行管理。开发者可使用以下模块实现音频输入设备的管理功能。
+
+| **模块** | **应用场景** |
+| --- | --- |
+| [AudioRoutingManager](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-audio-audioroutingmanager) | 管理全局音频输入设备，提供系统输入设备查询及状态变化的监听接口 |
+| [AudioSessionManager](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-audio-audiosessionmanager) | 管理应用音频输入设备，提供切换输入设备的API接口 |
+| [AudioCapturer](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-audio-audiocapturer) | 管理音频流输入设备，提供音频流输入设备变化的监听接口 |
+| [AVInputCastPicker](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ohos-multimedia-avinputcastpicker#avinputcastpicker) | 切换音频输入设备的系统组件，目前仅支持PC/2in1设备 |
+
+本文基于上述模块提供的能力，指导开发者实现获取输入设备信息、切换输入设备、响应设备变更等场景，并提供开发过程中常见问题的解决方案。
+
+#### 获取输入设备信息
+
+## 场景描述
+
+在开始录制音频之前，获取系统的输入设备信息并展示；当设备发生变化时，同步更新设备列表。例如，当蓝牙耳机上线时，将蓝牙耳机添加到设备列表中；当蓝牙耳机下线时，将蓝牙耳机从设备列表中移除。如下图所示：
+
+![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/79/v3/RxcCfGg7RHmb_KFSgsixNQ/zh-cn_image_0000002513603472.gif?HW-CC-KV=V1&HW-CC-Date=20260623T075557Z&HW-CC-Expire=86400&HW-CC-Sign=847F756AB6D9CDBF471AF52F1C0474A41E1509BE63D3EB18007E2552768B157D "点击放大")
+
+## 实现原理
+
+[AudioRoutingManager](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-audio-audioroutingmanager)提供管理全局音频输入设备的能力，包括查询设备信息、监听设备连接状态变化等。
+
+## 开发步骤
+
+1. 创建AudioRoutingManager实例。
+
+   ```
+   private audioManager = audio.getAudioManager();
+   // ...
+   private audioRoutingManager: audio.AudioRoutingManager = this.audioManager.getRoutingManager();
+   ```
+2. 使用[AudioRoutingManager.getDevices(deviceFlag: DeviceFlag)](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-audio-audioroutingmanager#getdevices9-1)获取所有已连接的输入设备。设置deviceFlag参数为[INPUT_DEVICES_FLAG](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-audio-e#deviceflag)表示获取输入设备。
+
+   ```
+   // Get all input devices and display them.
+   async getDevices(inputDeviceType: string) {
+     this.deviceType = inputDeviceType;
+     this.audioRoutingManager.getDevices(audio.DeviceFlag.INPUT_DEVICES_FLAG)
+       .then((audioDeviceDescriptors: audio.AudioDeviceDescriptors) => {
+         hilog.info(DOMAIN, 'testTag', '%{public}s',
+           `Succeeded in getting devices, AudioDeviceDescriptors: ${JSON.stringify(audioDeviceDescriptors)}.`);
+         this.getAvailableDevices();
+         this.watchDeviceChange(); // Get changes in the status of audio devices.
+         this.watchCurrentInputDeviceChanged(); // Monitor current input device change events.
+         let deviceUsage = this.deviceType === CommonConstants.MEDIA_EQUIPMENT ? audio.DeviceUsage.MEDIA_INPUT_DEVICES :
+           audio.DeviceUsage.CALL_INPUT_DEVICES;
+         this.watchSessionAvailableDeviceChange(deviceUsage); // Available device connection status change events.
+         this.watchRoutingAvailableDeviceChange(deviceUsage); // Available device connection status change events.
+       })
+       .catch((err: BusinessError) => {
+         hilog.error(DOMAIN, 'testTag', '%{public}s', `Failed to get devices. error: ${err.code}, ${err.message}`);
+       });
+   }
+   ```
+3. 使用[AudioRoutingManager.on('deviceChange')](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-audio-audioroutingmanager#ondevicechange9)监听输入设备连接状态的变化。
+
+   ```
+   // Get changes in the status of audio devices.
+   watchDeviceChange() {
+     try {
+       this.audioRoutingManager.on('deviceChange', audio.DeviceFlag.INPUT_DEVICES_FLAG,
+         (deviceChanged: audio.DeviceChangeAction) => {
+           // The device connection status changes, with 0 indicating connection and 1 indicating disconnection.
+           if (deviceChanged.type === audio.DeviceChangeType.CONNECT) {
+             hilog.info(DOMAIN, 'testTag', '%{public}s',
+               'device connected : ' + deviceChanged.deviceDescriptors[0].displayName);
+           } else if (deviceChanged.type === audio.DeviceChangeType.DISCONNECT) {
+             hilog.info(DOMAIN, 'testTag', '%{public}s',
+               'device disconnected : ' + deviceChanged.deviceDescriptors[0].displayName);
+           }
+         });
+     } catch (err) {
+       let error = err as BusinessError;
+       hilog.error(DOMAIN, 'testTag', '%{public}s', `Failed to deviceChange. error: ${error.code}, ${error.message}`);
+     }
+   }
+   ```
+4. 使用[AudioRoutingManager.getAvailableDevices(deviceUsage: DeviceUsage)](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-audio-audioroutingmanager#getavailabledevices12)获取可用输入设备。通过[DeviceUsage](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-audio-e#deviceusage12)参数区分不同的使用场景，[MEDIA_INPUT_DEVICES](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-audio-e#deviceusage12)表示媒体输入设备，[CALL_INPUT_DEVICES](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-audio-e#deviceusage12)表示通话输入设备。
+
+   ```
+   // Get the current list of available audio input devices.
+   getAvailableDevices() {
+     let data: audio.AudioDeviceDescriptors = [];
+     // Distinguish between media and calling devices.
+     let deviceUsage = this.deviceType === CommonConstants.MEDIA_EQUIPMENT ? audio.DeviceUsage.MEDIA_INPUT_DEVICES :
+       audio.DeviceUsage.CALL_INPUT_DEVICES;
+     try {
+       data = this.audioRoutingManager.getAvailableDevices(deviceUsage);
+       hilog.info(DOMAIN, 'testTag', '%{public}s',
+         `Succeeded in getting availableDevices: ${JSON.stringify(data)}.`);
+       AppStorage.setOrCreate(CommonConstants.AVAILABLE_DEVICES, data);
+     } catch (err) {
+       let error = err as BusinessError;
+       hilog.error(DOMAIN, 'testTag', '%{public}s',
+         `Failed to getAvailableDevices. error: ${error.code}, ${error.message}`);
+     }
+   }
+   ```
+5. 使用[AudioRoutingManager.on('availableDeviceChange')](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-audio-audioroutingmanager#onavailabledevicechange12)监听可用输入设备的变化，并在设备变化时更新设备列表。
+
+   ```
+   // Available device connection status change events.
+   watchRoutingAvailableDeviceChange(deviceUsage: audio.DeviceUsage) {
+     let availableDeviceChangeCallback = (deviceChanged: audio.DeviceChangeAction) => {
+       let data: audio.AudioDeviceDescriptors = deviceChanged.deviceDescriptors;
+       hilog.info(DOMAIN, 'testTag', '%{public}s',
+         `Get available device audioRoutingManager ChangeCallback, AudioDeviceDescriptors: ${data}.` +
+         JSON.stringify(data));
+       this.getAvailableDevices(); // Update available devices.
+     };
+     try {
+       this.audioRoutingManager.on('availableDeviceChange', deviceUsage, availableDeviceChangeCallback);
+     } catch (err) {
+       let error = err as BusinessError;
+       hilog.error(DOMAIN, 'testTag', '%{public}s',
+         `Failed to availableDeviceChange. error: ${error.code}, ${error.message}`);
+     }
+   }
+   ```
+6. 使用[AudioRoutingManager.getPreferredInputDeviceForCapturerInfo()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-audio-audioroutingmanager#getpreferredinputdeviceforcapturerinfo10-1)获取录制使用的设备。通过[AudioCapturerInfo.source](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-audio-i#audiocapturerinfo8)参数区分不同的使用场景，例如SOURCE_TYPE_MIC表示普通录音，SOURCE_TYPE_VOICE_COMMUNICATION表示语音通话。
+
+   ```
+   // Get default or preferred input device.
+   getPreferredInputDevice() {
+     this.audioRoutingManager.getPreferredInputDeviceForCapturerInfo(this.audioCapturerInfo,
+       (err: BusinessError, audioDeviceDescriptors: audio.AudioDeviceDescriptors) => {
+         if (err) {
+           hilog.error(DOMAIN, 'testTag', '%{public}s',
+             `Failed to get preferred input device for capturer info. Code: ${err.code}, message: ${err.message}`);
+         } else {
+           hilog.info(DOMAIN, 'testTag', '%{public}s',
+             `Succeeded in getting preferred input device for capturer info, AudioDeviceDescriptors: ${JSON.stringify(audioDeviceDescriptors)}.`);
+           if (audioDeviceDescriptors.length > 0) {
+             AppStorage.setOrCreate(CommonConstants.SELECTED_DEVICE_ID, audioDeviceDescriptors[0].id);
+           }
+         }
+       });
+   }
+   ```
+7. 使用[AudioRoutingManager.on('preferredInputDeviceChangeForCapturerInfo')](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-audio-audioroutingmanager#onpreferredinputdevicechangeforcapturerinfo10)监听录制设备的变化，并在变化时弹框提示用户。
+
+   ```
+   // Monitor the status changes of preferred input device.
+   watchPreferredInputDeviceChange() {
+     try {
+       this.audioRoutingManager.on('preferredInputDeviceChangeForCapturerInfo', this.audioCapturerInfo,
+         (audioDeviceDescriptors: audio.AudioDeviceDescriptors) => {
+           hilog.info(DOMAIN, 'testTag', '%{public}s',
+             `Succeeded in using on function, AudioDeviceDescriptors: ${JSON.stringify(audioDeviceDescriptors)}.`);
+           if (audioDeviceDescriptors.length > 0) {
+             AppStorage.setOrCreate(CommonConstants.SELECTED_DEVICE_ID, audioDeviceDescriptors[0].id);
+           }
+         });
+     } catch (err) {
+       let error = err as BusinessError;
+       hilog.error(DOMAIN, 'testTag', '%{public}s',
+         `Failed to preferredInputDeviceChangeForCapturerInfo. error: ${error.code}, ${error.message}`);
+     }
+   }
+   ```
+
+#### 通过API切换输入设备
+
+## 场景描述
+
+音频流类型对输入设备的选择具有决定性影响，对于不同类型的音频流，系统会自动选择相应的输入设备。例如音频流类型是SOURCE_TYPE_MIC时，系统使用内置麦克风作为音频输入设备。如果默认的输入设备不符合使用需求，应用可以调用相关接口进行修改。
+
+![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/9f/v3/u2apAuBqTLaBf-do4w2Vig/zh-cn_image_0000002545043447.gif?HW-CC-KV=V1&HW-CC-Date=20260623T075557Z&HW-CC-Expire=86400&HW-CC-Sign=41DEDB3D13E7D6AA5D1A309725B04AFDF854580DAD4B6047EF4EFA19D1B2042A "点击放大")
+
+## 实现原理
+
+使用[AudioSessionManager](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-audio-audiosessionmanager)管理音频输入设备。通过该组件，可默认将蓝牙设备设为音频输入源，同时支持动态切换不同的媒体输入设备。
+
+整体流程如图：
+
+![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/3a/v3/GSY30_U9StKoZ00W8m7NDw/zh-cn_image_0000002545123443.png?HW-CC-KV=V1&HW-CC-Date=20260623T075557Z&HW-CC-Expire=86400&HW-CC-Sign=D5C82794F40D5C9A53C22119B72536062F2399708ECFD91ADE220C242C0B791B)
+
+![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/1d/v3/dZ9eX8blTd2VhWQvXNVUsg/note_3.0-zh-cn.png?HW-CC-KV=V1&HW-CC-Date=20260623T075557Z&HW-CC-Expire=86400&HW-CC-Sign=DD57CBDB06D0CCBB1719D70F162F47CB5A5512A47218AE3699E3A4CF3BE16DEC) 
+
+在语音通话场景下，由于输入设备跟随当前输出设备，因此使用AudioSessionManager的API无法切换输入设备。
+
+## 开发步骤
+
+1. 创建AudioSessionManager实例。
+
+   ```
+   private audioManager = audio.getAudioManager();
+   private audioSessionManager: audio.AudioSessionManager = this.audioManager.getSessionManager();
+   ```
+2. 使用[AudioSessionManager.setBluetoothAndNearlinkPreferredRecordCategory(category)](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-audio-audiosessionmanager#setbluetoothandnearlinkpreferredrecordcategory21)设置优先选择蓝牙设备作为输入设备，当蓝牙设备上线后，会自动切换到蓝牙设备进行录制。通过[category](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-audio-e#bluetoothandnearlinkpreferredrecordcategory21)参数设置蓝牙设备使用模式，当设置[PREFERRED_NONE](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-audio-e#bluetoothandnearlinkpreferredrecordcategory21)时，取消优先选择蓝牙设备。
+
+   ```
+   // Set priority to select Bluetooth devices as input devices.
+   async setBluetooth(category: number) {
+     await this.audioSessionManager.setBluetoothAndNearlinkPreferredRecordCategory(category)
+       .then(() => {
+         hilog.info(DOMAIN, 'testTag', '%{public}s',
+           'Succeeded in doing setBluetoothAndNearlinkPreferredRecordCategory.' + category);
+         AppStorage.setOrCreate(CommonConstants.BLUETOOTH_AND_NEARLINK_PREFERRED, category);
+       })
+       .catch((err: BusinessError) => {
+         hilog.error(DOMAIN, 'testTag', '%{public}s',
+           `Failed to setBluetoothAndNearlinkPreferredRecordCategory. error: ${err.code}, ${err.message}`);
+       });
+   }
+   ```
+3. 使用[AudioSessionManager.selectMediaInputDevice()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-audio-audiosessionmanager#selectmediainputdevice21)将用户选择的设备设置为输入设备。
+
+   ```
+   // Set input device.
+   async setInputDevice(data: audio.AudioDeviceDescriptor) {
+     this.audioSessionManager.selectMediaInputDevice(data).then(() => {
+       hilog.info(DOMAIN, 'testTag', '%{public}s', 'Succeeded in doing selectMediaInputDevice.');
+       this.getSelectedMediaInputDevice();
+     }).catch((err: BusinessError) => {
+       hilog.error(DOMAIN, 'testTag', '%{public}s',
+         `Failed to selectMediaInputDevice. error: ${err.code}, ${err.message}`);
+     });
+   }
+   ```
+4. 使用[AudioSessionManager.on('currentInputDeviceChanged')](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-audio-audiosessionmanager#oncurrentinputdevicechanged21)监听输入设备变化，当输入设备切换成功后会触发该回调。
+
+   ```
+   // Monitor current input device change events.
+   watchCurrentInputDeviceChanged() {
+     hilog.info(DOMAIN, 'testTag', '%{public}s', 'currentInputDeviceChangedCallback');
+     let currentInputDeviceChangedCallback = (currentInputDeviceChangedEvent: audio.CurrentInputDeviceChangedEvent) => {
+       hilog.info(DOMAIN, 'testTag', '%{public}s',
+         `reason of currentInputDeviceChanged: ${currentInputDeviceChangedEvent.changeReason} `);
+     };
+     try {
+       this.audioSessionManager.on('currentInputDeviceChanged', currentInputDeviceChangedCallback);
+       hilog.info(DOMAIN, 'testTag', '%{public}s', 'currentInputDeviceChanged');
+     } catch (err) {
+       let error = err as BusinessError;
+       hilog.error(DOMAIN, 'testTag', '%{public}s',
+         `Failed to currentInputDeviceChangedCallback. error: ${error.code}, ${error.message}`);
+     }
+   }
+   ```
+5. 使用[AudioSessionManager.getSelectedMediaInputDevice()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-audio-audiosessionmanager#getselectedmediainputdevice21)获取当前设置的输入设备。
+
+   ```
+   // Get the currently selected input device.
+   getSelectedMediaInputDevice() {
+     try {
+       let device: audio.AudioDeviceDescriptor = this.audioSessionManager.getSelectedMediaInputDevice();
+       hilog.info(DOMAIN, 'testTag', '%{public}s',
+         'Succeeded in doing getSelectedMediaInputDevice.' + JSON.stringify(device) + ',' + device?.id);
+       AppStorage.setOrCreate(CommonConstants.SELECTED_DEVICE_ID, device.id);
+     } catch (err) {
+       let error = err as BusinessError;
+       hilog.error(DOMAIN, 'testTag', '%{public}s',
+         `Failed to getSelectedMediaInputDevice. error: ${error.code}, ${error.message}`);
+     }
+   }
+   ```
+
+#### 通过系统组件切换输入设备
+
+## 场景描述
+
+在PC设备上，通过系统提供的录音设备选择组件[AVInputCastPicker](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ohos-multimedia-avinputcastpicker)切换音频输入设备。
+
+![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/97/v3/_ZFMXGSGQNC2uKKiHPoR0w/zh-cn_image_0000002513443564.gif?HW-CC-KV=V1&HW-CC-Date=20260623T075557Z&HW-CC-Expire=86400&HW-CC-Sign=D7D94E56CF7FD1E8B6D330F97DC339586562F7B1D6A579BF89126EF97BC43B1F "点击放大")
+
+## 实现原理
+
+系统提供录音设备选择组件[AVInputCastPicker](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ohos-multimedia-avinputcastpicker)，作为音频输入设备发现与连接的统一入口。点击组件图标将弹出可选设备列表，从列表中选择设备后，即可切换至相应设备。
+
+## 开发步骤
+
+1. 在需要切换设备的界面创建AVInputCastPicker组件。
+
+   ```
+   @Builder
+   customPickerBuilder() {
+     Image($r('app.media.devices'))
+       .width('100%')
+       .height('100%')
+   }
+   ```
+
+   ```
+   AVInputCastPicker({
+     customPicker: () => this.customPickerBuilder(),
+     onStateChange: this.onStateChange
+   })
+   ```
+2. 手动点击AVInputCastPicker组件，并在弹框中选择目标设备，即可切换输入设备。
+
+#### 响应音频流输入设备变更
+
+## 场景描述
+
+当系统因音频输入设备上下线、用户主动切换设备、设备抢占或设备选择策略变更等导致音频流输入设备变更时，应用可以根据需要做出对应的处理。
+
+![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/ea/v3/b6seAxJzT3C7fWfPrjD9_A/zh-cn_image_0000002513603474.gif?HW-CC-KV=V1&HW-CC-Date=20260623T075557Z&HW-CC-Expire=86400&HW-CC-Sign=4684BE94CAA5B819054D6D605054EE656381ED1A2661A301396EA48D30312955 "点击放大")
+
+## 实现原理
+
+[AudioCapturer.on('inputDeviceChange')](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-audio-audiocapturer#oninputdevicechange11)可以监听音频流输入设备变化并返回切换后的设备信息。应用可以根据切换后的新设备做对应的处理。
+
+## 开发步骤
+
+使用[AudioCapturer.on('inputDeviceChange')](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-audio-audiocapturer#oninputdevicechange11)监听到音频流输入设备变化时，显示新设备信息。
+
+```
+// Monitor the status changes of input device.
+watchInputDeviceChange() {
+  try {
+    // Use the inputDeviceChange method of audioCapturer to listen for changes in input devices.
+    this.audioCapturer?.on('inputDeviceChange', (deviceChangeInfo: audio.AudioDeviceDescriptors) => {
+      hilog.info(DOMAIN, 'testTag', '%{public}s', `inputDevice id: ${deviceChangeInfo[0].id}`);
+      if (deviceChangeInfo.length > 0) {
+        AppStorage.setOrCreate(CommonConstants.SELECTED_DEVICE_ID, deviceChangeInfo[0].id);
+      }
+    });
+  } catch (err) {
+    // ...
+  }
+}
+```
+
+#### 常见问题
+
+## 确定麦克风是否能够进行录制，判断麦克风是否处于被占用的状态
+
+**解决方案**
+
+API20提供了[AudioStreamManager.isRecordingAvailable(capturerInfo: AudioCapturerInfo)](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-audio-audiostreammanager#isrecordingavailable20)接口，设置AudioCapturerInfo.source为Audio.SourceType.SOURCE_TYPE_MIC，然后根据返回值判断麦克风状态。如果返回true，表明可以使用麦克风进行录制；如果返回false，表明麦克风可能已被占用。
+
+API20之前，可以初始化一个AudioCapturer对象并开始录音，如果成功，说明可以使用麦克风进行录制；如果失败，表明麦克风可能已被占用。
+
+#### 示例代码
+
+- [实现音频输入设备管理功能](https://gitcode.com/HarmonyOS_Samples/managing-audio-input-devices)