1# @ohos.multimedia.avsession (媒体会话管理)(系统接口) 2<!--Kit: AVSession Kit--> 3<!--Subsystem:Multimedia--> 4<!--Owner: @ccfriend; @liao_qian--> 5<!--Designer: @ccfriend--> 6<!--Tester:@chenmingxi1_huawei--> 7<!--Adviser: @zengyawen--> 8 9媒体会话管理提供媒体播控相关功能的接口，目的是让应用接入播控中心。 10 11该模块提供以下媒体会话相关的常用功能： 12 13- [AVCastController](#avcastcontroller10): 投播控制器，可用于投播场景下，完成播放控制、远端播放状态监听、远端播放状态信息获取等操作。 14 15> **说明：** 16> 17> - 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 18> - 当前页面仅包含本模块的系统接口，其他公开接口参见[@ohos.multimedia.avsession (媒体会话管理)](arkts-apis-avsession.md)。 19 20## 导入模块 21 22```ts 23import { avSession } from '@kit.AVSessionKit'; 24``` 25 26## 使用说明 27 28本文档仅提供系统接口说明，以下接口的使用说明均需先创建实例，请参考公开接口[avSession.createAVSession](arkts-apis-avsession-f.md#avsessioncreateavsession10)的说明及示例，创建对应实例。 29 30## avSession.getAllSessionDescriptors 31 32getAllSessionDescriptors(): Promise\<Array\<Readonly\<AVSessionDescriptor>>> 33 34获取所有设置过媒体信息且注册控制回调的会话的相关描述。结果通过Promise异步回调方式返回。 35 36**需要权限：** ohos.permission.MANAGE_MEDIA_RESOURCES，仅系统应用可用。 37 38**系统能力：** SystemCapability.Multimedia.AVSession.Manager 39 40**系统接口：** 该接口为系统接口。 41 42**返回值：** 43 44| 类型 | 说明 | 45| ------------------------------------------------------------ | --------------------------------------------- | 46| Promise\<Array\<Readonly\<[AVSessionDescriptor](#avsessiondescriptor)\>\>\> | Promise对象。返回所有会话描述的只读对象。 | 47 48**错误码：** 49 50以下错误码的详细介绍请参见[媒体会话管理错误码](errorcode-avsession.md)。 51 52| 错误码ID | 错误信息 | 53| -------- | ---------------------------------------- | 54| 201 | permission denied. | 55| 6600101 | Session service exception. | 56 57**示例：** 58 59```ts 60import { BusinessError } from '@kit.BasicServicesKit'; 61 62avSession.getAllSessionDescriptors().then((descriptors: avSession.AVSessionDescriptor[]) => { 63 console.info(`getAllSessionDescriptors : SUCCESS : descriptors.length : ${descriptors.length}`); 64 if (descriptors.length > 0 ) { 65 console.info(`getAllSessionDescriptors : SUCCESS : descriptors[0].isActive : ${descriptors[0].isActive}`); 66 console.info(`GetAllSessionDescriptors : SUCCESS : descriptors[0].type : ${descriptors[0].type}`); 67 console.info(`GetAllSessionDescriptors : SUCCESS : descriptors[0].sessionTag : ${descriptors[0].sessionTag}`); 68 } 69}).catch((err: BusinessError) => { 70 console.error(`GetAllSessionDescriptors BusinessError: code: ${err.code}, message: ${err.message}`); 71}); 72``` 73 74## avSession.getAllSessionDescriptors 75 76getAllSessionDescriptors(callback: AsyncCallback\<Array\<Readonly\<AVSessionDescriptor>>>): void 77 78获取所有设置过媒体信息且注册控制回调的会话的相关描述。结果通过callback异步回调方式返回。 79 80**需要权限：** ohos.permission.MANAGE_MEDIA_RESOURCES 81 82**系统能力：** SystemCapability.Multimedia.AVSession.Manager 83 84**系统接口：** 该接口为系统接口。 85 86**参数：** 87 88| 参数名 | 类型 | 必填 | 说明 | 89| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------ | 90| callback | AsyncCallback<Array<Readonly<[AVSessionDescriptor](#avsessiondescriptor)\>\>\> | 是 | 回调函数。返回所有会话描述的只读对象。 | 91 92**错误码：** 93 94以下错误码的详细介绍请参见[媒体会话管理错误码](errorcode-avsession.md)。 95 96| 错误码ID | 错误信息 | 97| -------- | ---------------------------------------- | 98| 201 | permission denied. | 99| 6600101 |Session service exception. | 100 101**示例：** 102 103```ts 104import { BusinessError } from '@kit.BasicServicesKit'; 105 106avSession.getAllSessionDescriptors((err: BusinessError, descriptors: avSession.AVSessionDescriptor[]) => { 107 if (err) { 108 console.error(`GetAllSessionDescriptors BusinessError: code: ${err.code}, message: ${err.message}`); 109 } else { 110 console.info(`GetAllSessionDescriptors : SUCCESS : descriptors.length : ${descriptors.length}`); 111 if (descriptors.length > 0 ) { 112 console.info(`getAllSessionDescriptors : SUCCESS : descriptors[0].isActive : ${descriptors[0].isActive}`); 113 console.info(`getAllSessionDescriptors : SUCCESS : descriptors[0].type : ${descriptors[0].type}`); 114 console.info(`getAllSessionDescriptors : SUCCESS : descriptors[0].sessionTag : ${descriptors[0].sessionTag}`); 115 } 116 } 117}); 118``` 119 120## avSession.getHistoricalSessionDescriptors<sup>10+</sup> 121 122getHistoricalSessionDescriptors(maxSize?: number): Promise\<Array\<Readonly\<AVSessionDescriptor>>> 123 124获取所有已被销毁的会话相关描述。结果通过Promise异步回调方式返回。 125 126**需要权限：** ohos.permission.MANAGE_MEDIA_RESOURCES 127 128**系统能力：** SystemCapability.Multimedia.AVSession.Manager 129 130**系统接口：** 该接口为系统接口。 131 132**参数：** 133 134| 参数名 | 类型 | 必填 | 说明 | 135| -------- | ------ | ---- | -----------------------------------------------------------------| 136| maxSize | number | 否 | 指定获取描述符数量的最大值，可选范围是0-10，不填则取默认值，默认值为3。| 137 138**返回值：** 139 140| 类型 | 说明 | 141| --------------------------------------------------------------------------- | -------------------------------------- | 142| Promise\<Array\<Readonly\<[AVSessionDescriptor](#avsessiondescriptor)\>\>\> | Promise对象。返回所有会话描述的只读对象。 | 143 144**错误码：** 145 146以下错误码的详细介绍请参见[媒体会话管理错误码](errorcode-avsession.md)。 147 148| 错误码ID | 错误信息 | 149| -------- | ---------------------------------------- | 150| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 151| 6600101 | Session service exception. | 152 153**示例：** 154 155```ts 156import { BusinessError } from '@kit.BasicServicesKit'; 157 158avSession.getHistoricalSessionDescriptors().then((descriptors: avSession.AVSessionDescriptor[]) => { 159 console.info(`getHistoricalSessionDescriptors : SUCCESS : descriptors.length : ${descriptors.length}`); 160 if (descriptors.length > 0 && descriptors[0]) { 161 console.info(`getHistoricalSessionDescriptors : SUCCESS : descriptors[0].isActive : ${descriptors[0].isActive}`); 162 console.info(`getHistoricalSessionDescriptors : SUCCESS : descriptors[0].type : ${descriptors[0].type}`); 163 console.info(`getHistoricalSessionDescriptors : SUCCESS : descriptors[0].sessionTag : ${descriptors[0].sessionTag}`); 164 console.info(`getHistoricalSessionDescriptors : SUCCESS : descriptors[0].sessionId : ${descriptors[0].sessionId}`); 165 console.info(`getHistoricalSessionDescriptors : SUCCESS : descriptors[0].elementName.bundleName : ${descriptors[0].elementName.bundleName}`); 166 } 167}).catch((err: BusinessError) => { 168 console.error(`getHistoricalSessionDescriptors BusinessError: code: ${err.code}, message: ${err.message}`); 169}); 170``` 171 172## avSession.getHistoricalSessionDescriptors<sup>10+</sup> 173 174getHistoricalSessionDescriptors(maxSize: number, callback: AsyncCallback\<Array\<Readonly\<AVSessionDescriptor>>>): void 175 176获取所有已被销毁的会话相关描述。结果通过callback异步回调方式返回。 177 178**需要权限：** ohos.permission.MANAGE_MEDIA_RESOURCES。 179 180**系统能力：** SystemCapability.Multimedia.AVSession.Manager 181 182**系统接口：** 该接口为系统接口。 183 184**参数：** 185 186| 参数名 | 类型 | 必填 | 说明 | 187| -------- | ------------------------------------------------------------------------------ | ---- | -----------------------------------------------------------------| 188| maxSize | number | 是 | 指定获取描述符数量的最大值，可选范围是0-10。| 189| callback | AsyncCallback<Array<Readonly<[AVSessionDescriptor](#avsessiondescriptor)\>\>\> | 是 | 回调函数。返回所有会话描述的只读对象。 | 190 191**错误码：** 192 193以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[媒体会话管理错误码](errorcode-avsession.md)。 194 195| 错误码ID | 错误信息 196| -------- | ---------------------------------------- | 197| 201 | permission denied. | 198| 202 | Not System App. | 199| 401 | parameter check failed. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 200| 6600101 |Session service exception. | 201 202**示例：** 203 204```ts 205import { BusinessError } from '@kit.BasicServicesKit'; 206 207avSession.getHistoricalSessionDescriptors(1, (err: BusinessError, descriptors: avSession.AVSessionDescriptor[]) => { 208 if (err) { 209 console.error(`getHistoricalSessionDescriptors BusinessError: code: ${err.code}, message: ${err.message}`); 210 } else { 211 console.info(`getHistoricalSessionDescriptors : SUCCESS : descriptors.length : ${descriptors.length}`); 212 if (descriptors.length > 0 ) { 213 console.info(`getHistoricalSessionDescriptors : SUCCESS : descriptors[0].isActive : ${descriptors[0].isActive}`); 214 console.info(`getHistoricalSessionDescriptors : SUCCESS : descriptors[0].type : ${descriptors[0].type}`); 215 console.info(`getHistoricalSessionDescriptors : SUCCESS : descriptors[0].sessionTag : ${descriptors[0].sessionTag}`); 216 console.info(`getHistoricalSessionDescriptors : SUCCESS : descriptors[0].sessionId : ${descriptors[0].sessionId}`); 217 console.info(`getHistoricalSessionDescriptors : SUCCESS : descriptors[0].elementName.bundleName : ${descriptors[0].elementName.bundleName}`); 218 } 219 } 220}); 221``` 222 223## avSession.getHistoricalAVQueueInfos<sup>11+</sup> 224 225getHistoricalAVQueueInfos(maxSize: number, maxAppSize: number) : Promise\<Array\<Readonly\<AVQueueInfo>>> 226 227获取全部的历史播放歌单。结果通过Promise异步回调方式返回。 228 229**需要权限：** ohos.permission.MANAGE_MEDIA_RESOURCES 230 231**系统能力：** SystemCapability.Multimedia.AVSession.Manager 232 233**系统接口：** 该接口为系统接口。 234 235**参数：** 236 237| 参数名 | 类型 | 必填 | 说明 | 238| -------- | ------ | ---- | ---------------------------------------------------------------| 239| maxSize | number | 是 | 指定获取歌曲列表数量的最大值，暂与获取歌单数量无关。 | 240| maxAppSize | number | 是 | 指定获取歌曲列表所属应用数量的最大值，暂与获取歌单数量无关。 | 241 242**返回值：** 243 244| 类型 | 说明 | 245| --------------------------------------------------------------------------- | ------------------------------------- | 246| Promise\<Array\<Readonly\<[AVQueueInfo](#avqueueinfo11)\>\>\> | Promise对象。返回所有历史播放歌单的只读对象。 | 247 248**错误码：** 249 250以下错误码的详细介绍请参见[媒体会话管理错误码](errorcode-avsession.md)。 251 252| 错误码ID | 错误信息 | 253| -------- | ---------------------------------------- | 254| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 255| 6600101 | Session service exception. | 256 257**示例：** 258 259```ts 260import { BusinessError } from '@kit.BasicServicesKit'; 261 262avSession.getHistoricalAVQueueInfos(3, 5).then((avQueueInfos: avSession.AVQueueInfo[]) => { 263 console.info(`getHistoricalAVQueueInfos : SUCCESS : avQueueInfos.length : ${avQueueInfos.length}`); 264}).catch((err: BusinessError) => { 265 console.error(`getHistoricalAVQueueInfos BusinessError: code: ${err.code}, message: ${err.message}`); 266}); 267``` 268 269## avSession.getHistoricalAVQueueInfos<sup>11+</sup> 270 271getHistoricalAVQueueInfos(maxSize: number, maxAppSize: number, callback: AsyncCallback\<Array\<Readonly\<AVQueueInfo>>>): void; 272 273获取全部的历史播放歌单。结果通过callback异步回调方式返回。 274 275**需要权限：** ohos.permission.MANAGE_MEDIA_RESOURCES。 276 277**系统能力：** SystemCapability.Multimedia.AVSession.Manager 278 279**系统接口：** 该接口为系统接口。 280 281**参数：** 282 283| 参数名 | 类型 | 必填 | 说明 | 284| -------- | ----------------------------------------------------------------------------- | ---- | ---------------------------------------------------------------| 285| maxSize | number | 是 | 指定获取歌曲列表数量的最大值，暂与获取歌单数量无关。 | 286| maxAppSize | number | 是 | 指定获取歌曲列表所属应用数量的最大值，暂与获取歌单数量无关。 | 287| callback | AsyncCallback<Array<Readonly<[AVQueueInfo](#avqueueinfo11)\>\>\> | 是 | 回调函数。返回所有历史播放歌单的只读对象。 | 288 289**错误码：** 290 291以下错误码的详细介绍请参见[媒体会话管理错误码](errorcode-avsession.md)。 292 293| 错误码ID | 错误信息 | 294| -------- | ---------------------------------------- | 295| 201 | permission denied. | 296| 202 | Not System App. | 297| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 298| 6600101 |Session service exception. | 299 300**示例：** 301 302```ts 303import { BusinessError } from '@kit.BasicServicesKit'; 304 305avSession.getHistoricalAVQueueInfos(3, 5, (err: BusinessError, avQueueInfos: avSession.AVQueueInfo[]) => { 306 if (err) { 307 console.error(`getHistoricalAVQueueInfos BusinessError: code: ${err.code}, message: ${err.message}`); 308 } else { 309 console.info(`getHistoricalAVQueueInfos : SUCCESS : avQueueInfos.length : ${avQueueInfos.length}`); 310 } 311}); 312``` 313 314## avSession.createController 315 316createController(sessionId: string): Promise\<AVSessionController> 317 318根据会话ID创建会话控制器，可以创建多个会话控制器。结果通过Promise异步回调方式返回。 319 320**需要权限：** ohos.permission.MANAGE_MEDIA_RESOURCES，仅系统应用可用。 321 322**系统能力：** SystemCapability.Multimedia.AVSession.Manager 323 324**系统接口：** 该接口为系统接口。 325 326**参数：** 327 328| 参数名 | 类型 | 必填 | 说明 | 329| --------- | ------ | ---- | -------- | 330| sessionId | string | 是 | 会话ID，如果提供 'default'，系统将创建一个默认控制器，用于控制系统默认会话。 | 331 332**返回值：** 333 334| 类型 | 说明 | 335| ----------------------------------------------------- | ------------------------------------------------------------ | 336| Promise<[AVSessionController](arkts-apis-avsession-AVSessionController.md)\> | Promise对象。返回会话控制器实例，可查看会话ID，<br>并完成对会话发送命令及事件，获取元数据、播放状态信息等操作。| 337 338**错误码：** 339 340以下错误码的详细介绍请参见[媒体会话管理错误码](errorcode-avsession.md)。 341 342| 错误码ID | 错误信息 | 343| -------- | ---------------------------------------- | 344| 201 | permission denied. | 345| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Parameter verification failed. | 346| 6600101 | Session service exception. | 347| 6600102 | The session does not exist. | 348 349**示例：** 350 351```ts 352import { BusinessError } from '@kit.BasicServicesKit'; 353 354let currentAVcontroller: avSession.AVSessionController | undefined = undefined; 355currentAvSession.createController(sessionId).then((avcontroller: avSession.AVSessionController) => { 356 currentAVcontroller = avcontroller; 357 console.info('CreateController : SUCCESS '); 358}).catch((err: BusinessError) => { 359 console.error(`CreateController BusinessError: code: ${err.code}, message: ${err.message}`); 360}); 361``` 362 363## avSession.createController 364 365createController(sessionId: string, callback: AsyncCallback\<AVSessionController>): void 366 367根据会话ID创建会话控制器，可以创建多个会话控制器。结果通过callback异步回调方式返回。 368 369**需要权限：** ohos.permission.MANAGE_MEDIA_RESOURCES，仅系统应用可用。 370 371**系统能力：** SystemCapability.Multimedia.AVSession.Manager 372 373**系统接口：** 该接口为系统接口。 374 375**参数：** 376 377| 参数名 | 类型 | 必填 | 说明 | 378| --------- | ----------------------------------------------------------- | ---- | ------------------------------------------------------------ | 379| sessionId | string | 是 | 会话ID，如果提供 'default'，系统将创建一个默认控制器，用于控制系统默认会话。 | 380| callback | AsyncCallback<[AVSessionController](arkts-apis-avsession-AVSessionController.md)\> | 是 | 回调函数。返回会话控制器实例，可查看会话ID，<br>并完成对会话发送命令及事件，获取元数据、播放状态信息等操作。 | 381 382**错误码：** 383 384以下错误码的详细介绍请参见[媒体会话管理错误码](errorcode-avsession.md)。 385 386| 错误码ID | 错误信息 | 387| -------- | ---------------------------------------- | 388| 201 | permission denied. | 389| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Parameter verification failed. | 390| 6600101 | Session service exception. | 391| 6600102 | The session does not exist. | 392 393**示例：** 394 395```ts 396import { BusinessError } from '@kit.BasicServicesKit'; 397 398let currentAVcontroller: avSession.AVSessionController | undefined = undefined; 399currentAvSession.createController(sessionId, (err: BusinessError, avcontroller: avSession.AVSessionController) => { 400 if (err) { 401 console.error(`CreateController BusinessError: code: ${err.code}, message: ${err.message}`); 402 } else { 403 currentAVcontroller = avcontroller; 404 console.info('CreateController : SUCCESS '); 405 } 406}); 407``` 408 409## avSession.castAudio 410 411castAudio(session: SessionToken | 'all', audioDevices: Array<audio.AudioDeviceDescriptor>): Promise\<void> 412 413投播会话到指定设备列表。结果通过Promise异步回调方式返回。 414 415调用此接口之前，需要导入`ohos.multimedia.audio`模块获取AudioDeviceDescriptor的相关描述。 416 417**需要权限：** ohos.permission.MANAGE_MEDIA_RESOURCES，仅系统应用可用。 418 419**系统能力：** SystemCapability.Multimedia.AVSession.Manager 420 421**系统接口：** 该接口为系统接口。 422 423**参数：** 424 425| 参数名 | 类型 | 必填 | 说明 | 426| ------------ | -------------- |------|------| 427| session | [SessionToken](#sessiontoken) | 'all' | 是 | 会话令牌。SessionToken表示单个token；字符串`'all'`指所有token。 | 428| audioDevices | Array\<[audio.AudioDeviceDescriptor](../apis-audio-kit/arkts-apis-audio-i.md#audiodevicedescriptor)\> | 是 | 媒体设备列表。 | 429 430**返回值：** 431 432| 类型 | 说明 | 433| -------------- | ----------------------------- | 434| Promise\<void> | Promise对象。当投播成功，无返回结果，否则返回错误对象。 | 435 436**错误码：** 437 438以下错误码的详细介绍请参见[媒体会话管理错误码](errorcode-avsession.md)。 439 440| 错误码ID | 错误信息 | 441| -------- | ---------------------------------------- | 442| 201 | permission denied. | 443| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Parameter verification failed. | 444| 6600101 | Session service exception. | 445| 6600102 | The session does not exist. | 446| 6600104 | The remote session connection failed. | 447 448**示例：** 449 450```ts 451import { audio } from '@kit.AudioKit'; 452import { BusinessError } from '@kit.BasicServicesKit'; 453 454let audioManager = audio.getAudioManager(); 455let audioRoutingManager = audioManager.getRoutingManager(); 456let audioDevices: audio.AudioDeviceDescriptors | undefined = undefined; 457audioRoutingManager.getDevices(audio.DeviceFlag.OUTPUT_DEVICES_FLAG).then((data) => { 458 audioDevices = data; 459 console.info('Promise returned to indicate that the device list is obtained.'); 460}).catch((err: BusinessError) => { 461 console.error(`GetDevices BusinessError: code: ${err.code}, message: ${err.message}`); 462}); 463 464if (audioDevices !== undefined) { 465 avSession.castAudio('all', audioDevices as audio.AudioDeviceDescriptors).then(() => { 466 console.info('CreateController : SUCCESS'); 467 }).catch((err: BusinessError) => { 468 console.error(`CreateController BusinessError: code: ${err.code}, message: ${err.message}`); 469 }); 470} 471``` 472 473## avSession.castAudio 474 475castAudio(session: SessionToken | 'all', audioDevices: Array<audio.AudioDeviceDescriptor>, callback: AsyncCallback\<void>): void 476 477投播会话到指定设备列表。结果通过callback异步回调方式返回。 478 479需要导入`ohos.multimedia.audio`模块获取AudioDeviceDescriptor的相关描述。 480 481**需要权限：** ohos.permission.MANAGE_MEDIA_RESOURCES，仅系统应用可用。 482 483**系统能力：** SystemCapability.Multimedia.AVSession.Manager 484 485**系统接口：** 该接口为系统接口。 486 487**参数：** 488 489| 参数名 | 类型 | 必填 | 说明 | 490| ------------ |--------------------------------------------| ---- | ------------------------------------------------------------ | 491| session | [SessionToken](#sessiontoken) | 'all' | 是 | 会话令牌。SessionToken表示单个token；字符串`'all'`指所有token。 | 492| audioDevices | Array\<[audio.AudioDeviceDescriptor](../apis-audio-kit/arkts-apis-audio-i.md#audiodevicedescriptor)\> | 是 | 媒体设备列表。 | 493| callback | AsyncCallback\<void> | 是 | 回调函数。当投播成功，err为undefined，否则返回错误对象。 | 494 495**错误码：** 496 497以下错误码的详细介绍请参见[媒体会话管理错误码](errorcode-avsession.md)。 498 499| 错误码ID | 错误信息 | 500| -------- | ---------------------------------------- | 501| 201 | permission denied. | 502| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Parameter verification failed. | 503| 6600101 | Session service exception. | 504| 6600102 | The session does not exist. | 505| 6600104 | The remote session connection failed. | 506 507**示例：** 508 509```ts 510import { audio } from '@kit.AudioKit'; 511import { BusinessError } from '@kit.BasicServicesKit'; 512 513let audioManager = audio.getAudioManager(); 514let audioRoutingManager = audioManager.getRoutingManager(); 515let audioDevices: audio.AudioDeviceDescriptors | undefined = undefined; 516audioRoutingManager.getDevices(audio.DeviceFlag.OUTPUT_DEVICES_FLAG).then((data) => { 517 audioDevices = data; 518 console.info('Promise returned to indicate that the device list is obtained.'); 519}).catch((err: BusinessError) => { 520 console.error(`GetDevices BusinessError: code: ${err.code}, message: ${err.message}`); 521}); 522 523if (audioDevices !== undefined) { 524 avSession.castAudio('all', audioDevices as audio.AudioDeviceDescriptors, (err: BusinessError) => { 525 if (err) { 526 console.error(`CastAudio BusinessError: code: ${err.code}, message: ${err.message}`); 527 } else { 528 console.info('CastAudio : SUCCESS '); 529 } 530 }); 531} 532``` 533 534## avSession.startAVPlayback<sup>11+</sup> 535 536startAVPlayback(bundleName: string, assetId: string): Promise\<void> 537 538启动媒体播放应用程序。结果通过Promise异步回调方式返回。 539 540**需要权限：** ohos.permission.MANAGE_MEDIA_RESOURCES，仅系统应用可用。 541 542**系统能力：** SystemCapability.Multimedia.AVSession.Manager 543 544**系统接口：** 该接口为系统接口。 545 546**参数：** 547 548| 参数名 | 类型 | 必填 | 说明 | 549| ------------ | -------------- |------|------| 550| bundleName | string | 是 | 指定应用包名。 | 551| assetId |string | 是 | 指定媒体ID。 | 552 553**返回值：** 554 555| 类型 | 说明 | 556| -------------- | ----------------------------- | 557| Promise\<void> | Promise对象。当播放成功，无返回结果，否则返回错误对象。 | 558 559**错误码：** 560 561以下错误码的详细介绍请参见[媒体会话管理错误码](errorcode-avsession.md)。 562 563| 错误码ID | 错误信息 | 564| -------- | ---------------------------------------- | 565| 201 | permission denied. | 566| 202 | Not System App. Interface caller is not a system app. | 567| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 568| 6600101 | Session service exception. | 569 570**示例：** 571 572```ts 573import { audio } from '@kit.AudioKit'; 574import { BusinessError } from '@kit.BasicServicesKit'; 575 576avSession.startAVPlayback("com.example.myapplication", "121278").then(() => { 577 console.info('startAVPlayback : SUCCESS'); 578}).catch((err: BusinessError) => { 579 console.error(`startAVPlayback BusinessError: code: ${err.code}, message: ${err.message}`); 580}); 581``` 582 583## avSession.getDistributedSessionController<sup>18+</sup> 584 585getDistributedSessionController(distributedSessionType: DistributedSessionType): Promise<Array\<AVSessionController>> 586 587根据远端会话类型，获取远端分布式会话控制器。结果通过Promise异步回调方式返回。 588 589**需要权限：** ohos.permission.MANAGE_MEDIA_RESOURCES 590 591**系统能力：** SystemCapability.Multimedia.AVSession.Manager 592 593**系统接口：** 该接口为系统接口。 594 595**参数：** 596 597| 参数名 | 类型 | 必填 | 说明 | 598| --------- |-------------------------------------------------------------------------| ---- |---------| 599| distributedSessionType | [DistributedSessionType](#distributedsessiontype18) | 是 | 远端会话类型。 | 600 601**返回值：** 602 603| 类型 | 说明 | 604|------------------------------------------------------------------------------------|-----------------------------------------------------------------------| 605| Promise<Array<[AVSessionController](arkts-apis-avsession-AVSessionController.md)\>> | Promise对象。返回对应类型的会话控制器实例列表，可查看会话ID，并完成对会话发送命令及事件，获取元数据、播放状态信息等操作。 | 606 607**错误码：** 608 609以下错误码的详细介绍请参见[媒体会话管理错误码](errorcode-avsession.md)。 610 611| 错误码ID | 错误信息 | 612|---------|-------------------------------------------------------------------------------------------------------| 613| 201 | permission denied. | 614| 202 | Not System App. Interface caller is not a system app. | 615| 6600101 | Session service exception. | 616| 6600109 | The remote connection is not established. | 617 618**示例：** 619 620```ts 621import { BusinessError } from '@kit.BasicServicesKit'; 622import { avSession } from '@kit.AVSessionKit'; 623 624avSession.getDistributedSessionController(avSession.DistributedSessionType.TYPE_SESSION_REMOTE).then((sessionControllers: Array<avSession.AVSessionController>) => { 625 console.info(`getDistributedSessionController : SUCCESS : sessionControllers.length : ${sessionControllers.length}`); 626}).catch((err: BusinessError) => { 627 console.error(`getDistributedSessionController BusinessError: code: ${err.code}, message: ${err.message}`); 628}); 629``` 630 631 632## SessionToken 633 634会话令牌的信息。 635 636**需要权限：** ohos.permission.MANAGE_MEDIA_RESOURCES，仅系统应用可用。 637 638**系统能力：** SystemCapability.Multimedia.AVSession.Manager 639 640**系统接口：** 该接口为系统接口。 641 642| 名称 | 类型 | 必填 | 说明 | 643| :-------- | :----- | :--- | :----------- | 644| sessionId | string | 是 | 会话ID。 | 645| pid | number | 否 | 会话的进程ID。 | 646| uid | number | 否 | 用户ID。 | 647 648## avSession.on('sessionCreate') 649 650on(type: 'sessionCreate', callback: (session: AVSessionDescriptor) => void): void 651 652会话的创建监听事件。 653 654**需要权限：** ohos.permission.MANAGE_MEDIA_RESOURCES，仅系统应用可用。 655 656**系统能力：** SystemCapability.Multimedia.AVSession.Manager 657 658**系统接口：** 该接口为系统接口。 659 660**参数：** 661 662| 参数名 | 类型 | 必填 | 说明 | 663| -------- | ---------------------- | ---- | ------------------------------------------------------------ | 664| type | string | 是 | 事件回调类型，支持的事件是'sessionCreate'：会话创建事件，检测到会话创建时触发。| 665| callback | (session: [AVSessionDescriptor](#avsessiondescriptor)) => void | 是 | 回调函数。参数为会话相关描述。 | 666 667**错误码：** 668 669以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[媒体会话管理错误码](errorcode-avsession.md)。 670 671| 错误码ID | 错误信息 | 672| -------- | ---------------------------------------- | 673| 202 | Not System App. | 674| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 675| 6600101 | Session service exception. | 676 677**示例：** 678 679```ts 680avSession.on('sessionCreate', (descriptor: avSession.AVSessionDescriptor) => { 681 console.info(`on sessionCreate : isActive : ${descriptor.isActive}`); 682 console.info(`on sessionCreate : type : ${descriptor.type}`); 683 console.info(`on sessionCreate : sessionTag : ${descriptor.sessionTag}`); 684}); 685 686``` 687 688## avSession.on('sessionDestroy') 689 690on(type: 'sessionDestroy', callback: (session: AVSessionDescriptor) => void): void 691 692会话的销毁监听事件。 693 694**需要权限：** ohos.permission.MANAGE_MEDIA_RESOURCES，仅系统应用可用。 695 696**系统能力：** SystemCapability.Multimedia.AVSession.Manager 697 698**系统接口：** 该接口为系统接口。 699 700**参数：** 701 702| 参数名 | 类型 | 必填 | 说明 | 703| -------- | ---------------| ---- | ------------------------------------------------------------ | 704| type | string | 是 | 事件回调类型，支持的事件包括是`'sessionDestroy'`：会话销毁事件，检测到会话销毁时触发。| 705| callback | (session: [AVSessionDescriptor](#avsessiondescriptor)) => void | 是 | 回调函数。参数为会话相关描述。 | 706 707**错误码：** 708 709以下错误码的详细介绍请参见[ohos.multimedia.avsession(多媒体会话)错误码](errorcode-avsession.md)。 710 711| 错误码ID | 错误信息 | 712| -------- | ---------------------------------------- | 713| 201 | permission denied. | 714| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 715| 6600101 | Session service exception. | 716 717**示例：** 718 719```ts 720avSession.on('sessionDestroy', (descriptor: avSession.AVSessionDescriptor) => { 721 console.info(`on sessionDestroy : isActive : ${descriptor.isActive}`); 722 console.info(`on sessionDestroy : type : ${descriptor.type}`); 723 console.info(`on sessionDestroy : sessionTag : ${descriptor.sessionTag}`); 724}); 725``` 726 727## avSession.on('topSessionChange') 728 729on(type: 'topSessionChange', callback: (session: AVSessionDescriptor) => void): void 730 731最新会话变更的监听事件。 732 733**需要权限：** ohos.permission.MANAGE_MEDIA_RESOURCES，仅系统应用可用。 734 735**系统能力：** SystemCapability.Multimedia.AVSession.Manager 736 737**系统接口：** 该接口为系统接口。 738 739**参数：** 740 741| 参数名 | 类型 | 必填 | 说明 | 742| -------- | --------------------| ---- | ------------------------------------------------------------ | 743| type | string | 是 | 事件回调类型，支持的事件包括是 `'topSessionChange'`：最新会话的变化事件，检测到最新的会话改变时触发。| 744| callback | (session: [AVSessionDescriptor](#avsessiondescriptor)) => void | 是 | 回调函数。参数为会话相关描述。 | 745 746**错误码：** 747 748以下错误码的详细介绍请参见[ohos.multimedia.avsession(多媒体会话)错误码](errorcode-avsession.md)。 749 750| 错误码ID | 错误信息 | 751| -------- | ---------------------------------------- | 752| 201 | permission denied. | 753| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 754| 6600101 | Session service exception. | 755 756**示例：** 757 758```ts 759avSession.on('topSessionChange', (descriptor: avSession.AVSessionDescriptor) => { 760 console.info(`on topSessionChange : isActive : ${descriptor.isActive}`); 761 console.info(`on topSessionChange : type : ${descriptor.type}`); 762 console.info(`on topSessionChange : sessionTag : ${descriptor.sessionTag}`); 763}); 764``` 765 766## avSession.off('sessionCreate') 767 768off(type: 'sessionCreate', callback?: (session: AVSessionDescriptor) => void): void 769 770取消会话创建事件监听，取消后，不再进行该事件的监听。 771 772**需要权限：** ohos.permission.MANAGE_MEDIA_RESOURCES，仅系统应用可用。 773 774**系统能力：** SystemCapability.Multimedia.AVSession.Manager 775 776**系统接口：** 该接口为系统接口。 777 778**参数：** 779 780| 参数名 | 类型 | 必填 | 说明 | 781| -------- | ----------| ---- | ----------| 782| type | string | 是 | 事件回调类型，支持的事件为：`'sessionCreate'`。| 783| callback | (session: [AVSessionDescriptor](#avsessiondescriptor)) => void | 否 | 回调函数。当监听事件取消成功，err为undefined，否则返回错误对象。<br>该参数为会话相关描述，为可选参数，若不填写该参数，则认为取消所有相关会话的事件监听。 | 784 785**错误码：** 786 787以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[媒体会话管理错误码](errorcode-avsession.md)。 788 789| 错误码ID | 错误信息 | 790| -------- | ---------------------------------------- | 791| 202 | Not System App. | 792| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 793| 6600101 | Session service exception. | 794 795**示例：** 796 797```ts 798avSession.off('sessionCreate'); 799``` 800 801## avSession.off('sessionDestroy') 802 803off(type: 'sessionDestroy', callback?: (session: AVSessionDescriptor) => void): void 804 805取消会话销毁事件监听，取消后，不再进行该事件的监听。 806 807**需要权限：** ohos.permission.MANAGE_MEDIA_RESOURCES，仅系统应用可用。 808 809**系统能力：** SystemCapability.Multimedia.AVSession.Manager 810 811**系统接口：** 该接口为系统接口。 812 813**参数：** 814 815| 参数名 | 类型 | 必填 | 说明 | 816| -------- | -----------| ---- | -------------------------| 817| type | string | 是 | 事件回调类型，支持的事件为`'sessionDestroy'`。| 818| callback | (session: [AVSessionDescriptor](#avsessiondescriptor)) => void | 否 | 回调函数。当监听事件取消成功，err为undefined，否则返回错误对象。<br>该参数为会话相关描述，为可选参数，若不填写该参数，则认为取消所有相关会话的事件监听。| 819 820**错误码：** 821 822以下错误码的详细介绍请参见[ohos.multimedia.avsession(多媒体会话)错误码](errorcode-avsession.md)。 823 824| 错误码ID | 错误信息 | 825| -------- | ---------------------------------------- | 826| 201 | permission denied. | 827| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 828| 6600101 | Session service exception. | 829 830**示例：** 831 832```ts 833avSession.off('sessionDestroy'); 834``` 835 836## avSession.off('topSessionChange') 837 838off(type: 'topSessionChange', callback?: (session: AVSessionDescriptor) => void): void 839 840取消最新会话变更事件监听，取消后，不再进行该事件的监听。 841 842**需要权限：** ohos.permission.MANAGE_MEDIA_RESOURCES，仅系统应用可用。 843 844**系统能力：** SystemCapability.Multimedia.AVSession.Manager 845 846**系统接口：** 该接口为系统接口。 847 848**参数：** 849 850| 参数名 | 类型 | 必填 | 说明 | 851| -------- | -----------------| ---- | ---------------------------- | 852| type | string | 是 | 事件回调类型，支持的事件为`'topSessionChange'`。| 853| callback | (session: [AVSessionDescriptor](#avsessiondescriptor)) => void | 否 | 回调函数。当监听事件取消成功，err为undefined，否则返回错误对象。<br>该参数为会话相关描述，为可选参数，若不填写该参数，则认为取消所有相关会话的事件监听。 | 854 855**错误码：** 856 857以下错误码的详细介绍请参见[ohos.multimedia.avsession(多媒体会话)错误码](errorcode-avsession.md)。 858 859| 错误码ID | 错误信息 | 860| -------- | ---------------------------------------- | 861| 201 | permission denied. | 862| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 863| 6600101 | Session service exception. | 864 865**示例：** 866 867```ts 868avSession.off('topSessionChange'); 869``` 870 871## avSession.on('sessionServiceDie') 872 873on(type: 'sessionServiceDie', callback: () => void): void 874 875监听会话的服务死亡事件。通知应用清理资源。 876 877**系统能力：** SystemCapability.Multimedia.AVSession.Core 878 879**系统接口：** 该接口为系统接口。 880 881**参数：** 882 883| 参数名 | 类型 | 必填 | 说明 | 884| -------- | -------------------- | ---- | ------------------------------------------------------------ | 885| type | string | 是 | 事件回调类型，支持事件`'sessionServiceDie'`：会话服务死亡事件，检测到会话的服务死亡时触发。 | 886| callback | callback: () => void | 是 | 回调函数。当监听事件注册成功，err为undefined，否则返回错误对象。 | 887 888**错误码：** 889 890以下错误码的详细介绍请参见[媒体会话管理错误码](errorcode-avsession.md)。 891 892| 错误码ID | 错误信息 | 893| -------- | ---------------------------------------- | 894| 201 | permission denied. | 895| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 896| 6600101 | Session service exception. | 897 898**示例：** 899 900```ts 901avSession.on('sessionServiceDie', () => { 902 console.info('on sessionServiceDie : session is Died '); 903}); 904``` 905 906## avSession.off('sessionServiceDie') 907 908off(type: 'sessionServiceDie', callback?: () => void): void 909 910取消会话服务死亡监听，取消后，不再进行服务死亡监听。 911 912**系统能力：** SystemCapability.Multimedia.AVSession.Core 913 914**系统接口：** 该接口为系统接口。 915 916**参数：** 917 918| 参数名 | 类型 | 必填 | 说明 | 919| ------ | ---------------------- | ---- | ------------------------------------------------------- | 920| type | string | 是 | 事件回调类型，支持事件`'sessionServiceDie'`：会话服务死亡事件。| 921| callback | callback: () => void | 否 | 回调函数。当监听事件取消成功，err为undefined，否则返回错误对象。<br>该参数为可选参数，若不填写该参数，则认为取消所有相关会话的服务死亡监听。 | 922 923**错误码：** 924 925以下错误码的详细介绍请参见[媒体会话管理错误码](errorcode-avsession.md)。 926 927| 错误码ID | 错误信息 | 928| -------- | ---------------------------------------- | 929| 201 | permission denied. | 930| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 931| 6600101 | Session service exception. | 932 933**示例：** 934 935```ts 936avSession.off('sessionServiceDie'); 937``` 938 939 940## avSession.on('distributedSessionChange')<sup>18+</sup> 941 942on(type: 'distributedSessionChange', distributedSessionType: DistributedSessionType, callback: Callback<Array\<AVSessionController>>): void 943 944最新分布式远端会话变更的监听事件。 945 946**需要权限：** ohos.permission.MANAGE_MEDIA_RESOURCES 947 948**系统能力：** SystemCapability.Multimedia.AVSession.Manager 949 950**系统接口：** 该接口为系统接口。 951 952**参数：** 953 954| 参数名 | 类型 | 必填 | 说明 | 955| -------- |-------------------------------------------------------------------------------------| ---- |--------------------------------------------------------------------------| 956| type | string | 是 | 事件回调类型，支持的事件为 `'distributedSessionChange'`：最新远端分布式会话的变化事件，检测到最新的会话改变时触发。 | 957| distributedSessionType | [DistributedSessionType](#distributedsessiontype18) | 是 | 远端会话类型。 | 958| callback | Callback<Array<[AVSessionController](arkts-apis-avsession-AVSessionController.md)\>> | 是 | 回调函数。参数为对应类型的会话控制器实例列表，可查看会话ID，并完成对会话发送命令及事件，获取元数据、播放状态信息等操作。 | 959 960**错误码：** 961 962以下错误码的详细介绍请参见[ohos.multimedia.avsession(多媒体会话)错误码](errorcode-avsession.md)。 963 964| 错误码ID | 错误信息 | 965|---------|---------------------------------------------------------------------------------------------------| 966| 202 | Not System App. Interface caller is not a system app. | 967| 6600101 | Session service exception. | 968 969**示例：** 970 971```ts 972avSession.on('distributedSessionChange', avSession.DistributedSessionType.TYPE_SESSION_REMOTE, (sessionControllers: Array<avSession.AVSessionController>) => { 973 console.info(`on distributedSessionChange size: ${sessionControllers.length}`); 974}); 975``` 976 977 978## avSession.off('distributedSessionChange')<sup>18+</sup> 979 980off(type: 'distributedSessionChange', distributedSessionType: DistributedSessionType, callback?: Callback<Array\<AVSessionController>>): void 981 982取消最新分布式远端会话变更的监听事件，取消后，不再进行该事件的监听。 983 984**需要权限：** ohos.permission.MANAGE_MEDIA_RESOURCES 985 986**系统能力：** SystemCapability.Multimedia.AVSession.Manager 987 988**系统接口：** 该接口为系统接口。 989 990**参数：** 991 992| 参数名 | 类型 | 必填 | 说明 | 993| -------- |-------------------------------------------------------------------------------------|----|---------------------------------------------------------------| 994| type | string | 是 | 事件回调类型，支持的事件为`'distributedSessionChange'`。 | 995| distributedSessionType | [DistributedSessionType](#distributedsessiontype18) | 是 | 远端会话类型。 | 996| callback | Callback<Array<[AVSessionController](arkts-apis-avsession-AVSessionController.md)\>> | 否 | 回调函数。参数为对应类型的会话控制器实例列表，可查看会话ID，并完成对会话发送命令及事件，获取元数据、播放状态信息等操作。 | 997 998**错误码：** 999 1000以下错误码的详细介绍请参见[ohos.multimedia.avsession(多媒体会话)错误码](errorcode-avsession.md)。 1001 1002| 错误码ID | 错误信息 | 1003|---------|---------------------------------------------------------------------------------------------------| 1004| 202 | Not System App. Interface caller is not a system app. | 1005| 6600101 | Session service exception. | 1006 1007**示例：** 1008 1009```ts 1010avSession.off('distributedSessionChange', avSession.DistributedSessionType.TYPE_SESSION_REMOTE); 1011``` 1012 1013## avSession.sendSystemAVKeyEvent 1014 1015sendSystemAVKeyEvent(event: KeyEvent, callback: AsyncCallback\<void>): void 1016 1017发送按键事件给置顶会话。结果通过callback异步回调方式返回。 1018 1019**需要权限：** ohos.permission.MANAGE_MEDIA_RESOURCES，仅系统应用可用。 1020 1021**系统能力：** SystemCapability.Multimedia.AVSession.Manager 1022 1023**系统接口：** 该接口为系统接口。 1024 1025**参数：** 1026 1027| 参数名 | 类型 | 必填 | 说明 | 1028| -------- | ------------------------------------------------------------ | ---- | ------------------------------------- | 1029| event | [KeyEvent](../apis-input-kit/js-apis-keyevent.md#keyevent) | 是 | 按键事件。 | 1030| callback | AsyncCallback\<void> | 是 | 回调函数。当事件发送成功，err为undefined，否则返回错误对象。 | 1031 1032**错误码：** 1033 1034以下错误码的详细介绍请参见[媒体会话管理错误码](errorcode-avsession.md)。 1035 1036| 错误码ID | 错误信息 | 1037| -------- | ---------------------------------------- | 1038| 201 | permission denied. | 1039| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Parameter verification failed. | 1040| 6600101 | Session service exception. | 1041| 6600105 | Invalid session command. | 1042 1043**示例：** 1044 1045```ts 1046import { KeyEvent } from '@kit.InputKit'; 1047import { BusinessError } from '@kit.BasicServicesKit'; 1048 1049let keyItem: keyEvent.Key = {code:0x49, pressedTime:2, deviceId:0}; 1050let event: keyEvent.KeyEvent = {id:1, deviceId:0, actionTime:1, screenId:1, windowId:1, action:2, key:keyItem, unicodeChar:0, keys:[keyItem], ctrlKey:false, altKey:false, shiftKey:false, logoKey:false, fnKey:false, capsLock:false, numLock:false, scrollLock:false}; 1051 1052avSession.sendSystemAVKeyEvent(event, (err: BusinessError) => { 1053 if (err) { 1054 console.error(`SendSystemAVKeyEvent BusinessError: code: ${err.code}, message: ${err.message}`); 1055 } else { 1056 console.info('SendSystemAVKeyEvent : SUCCESS '); 1057 } 1058}); 1059``` 1060 1061## avSession.sendSystemAVKeyEvent 1062 1063sendSystemAVKeyEvent(event: KeyEvent): Promise\<void> 1064 1065发送按键事件给置顶会话。结果通过Promise异步回调方式返回。 1066 1067**需要权限：** ohos.permission.MANAGE_MEDIA_RESOURCES，仅系统应用可用。 1068 1069**系统能力：** SystemCapability.Multimedia.AVSession.Manager 1070 1071**系统接口：** 该接口为系统接口。 1072 1073**参数：** 1074 1075| 参数名 | 类型 | 必填 | 说明 | 1076| ------ | ------------------------------- | ---- | ---------- | 1077| event | [KeyEvent](../apis-input-kit/js-apis-keyevent.md#keyevent) | 是 | 按键事件。 | 1078 1079**返回值：** 1080 1081| 类型 | 说明 | 1082| -------------- | ----------------------------- | 1083| Promise\<void> | Promise对象。当事件发送成功，无返回结果，否则返回错误对象。 | 1084 1085**错误码：** 1086 1087以下错误码的详细介绍请参见[媒体会话管理错误码](errorcode-avsession.md)。 1088 1089| 错误码ID | 错误信息 | 1090| -------- | ---------------------------------------- | 1091| 201 | permission denied. | 1092| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Parameter verification failed. | 1093| 6600101 | Session service exception. | 1094| 6600105 | Invalid session command. | 1095 1096**示例：** 1097 1098```ts 1099import { KeyEvent } from '@kit.InputKit'; 1100import { BusinessError } from '@kit.BasicServicesKit'; 1101 1102let keyItem: keyEvent.Key = {code:0x49, pressedTime:2, deviceId:0}; 1103let event: keyEvent.KeyEvent = {id:1, deviceId:0, actionTime:1, screenId:1, windowId:1, action:2, key:keyItem, unicodeChar:0, keys:[keyItem], ctrlKey:false, altKey:false, shiftKey:false, logoKey:false, fnKey:false, capsLock:false, numLock:false, scrollLock:false}; 1104 1105avSession.sendSystemAVKeyEvent(event).then(() => { 1106 console.info('SendSystemAVKeyEvent Successfully'); 1107}).catch((err: BusinessError) => { 1108 console.error(`SendSystemAVKeyEvent BusinessError: code: ${err.code}, message: ${err.message}`); 1109}); 1110``` 1111 1112## avSession.sendSystemControlCommand 1113 1114sendSystemControlCommand(command: AVControlCommand, callback: AsyncCallback\<void>): void 1115 1116发送控制命令给置顶会话。结果通过callback异步回调方式返回。 1117 1118**需要权限：** ohos.permission.MANAGE_MEDIA_RESOURCES，仅系统应用可用。 1119 1120**系统能力：** SystemCapability.Multimedia.AVSession.Manager 1121 1122**系统接口：** 该接口为系统接口。 1123 1124**参数：** 1125 1126| 参数名 | 类型 | 必填 | 说明 | 1127| -------- | ------------------------------------- | ---- | ------------------------------------- | 1128| command | [AVControlCommand](arkts-apis-avsession-i.md#avcontrolcommand10) | 是 | AVSession的相关命令和命令相关参数。 | 1129| callback | AsyncCallback\<void> | 是 | 回调函数。当命令发送成功，err为undefined，否则返回错误对象。 | 1130 1131**错误码：** 1132 1133以下错误码的详细介绍请参见[媒体会话管理错误码](errorcode-avsession.md)。 1134 1135| 错误码ID | 错误信息 | 1136| -------- | ---------------------------------------- | 1137| 201 | permission denied. | 1138| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Parameter verification failed. | 1139| 6600101 | Session service exception. | 1140| 6600105 | Invalid session command. | 1141| 6600107 | Too many commands or events. | 1142 1143**示例：** 1144 1145```ts 1146let cmd : avSession.AVControlCommandType = 'play'; 1147// let cmd : avSession.AVControlCommandType = 'pause'; 1148// let cmd : avSession.AVControlCommandType = 'stop'; 1149// let cmd : avSession.AVControlCommandType = 'playNext'; 1150// let cmd : avSession.AVControlCommandType = 'playPrevious'; 1151// let cmd : avSession.AVControlCommandType = 'fastForward'; 1152// let cmd : avSession.AVControlCommandType = 'rewind'; 1153let avcommand: avSession.AVControlCommand = {command:cmd}; 1154// let cmd : avSession.AVControlCommandType = 'seek'; 1155// let avcommand = {command:cmd, parameter:10}; 1156// let cmd : avSession.AVControlCommandType = 'setSpeed'; 1157// let avcommand = {command:cmd, parameter:2.6}; 1158// let cmd : avSession.AVControlCommandType = 'setLoopMode'; 1159// let avcommand = {command:cmd, parameter:avSession.LoopMode.LOOP_MODE_SINGLE}; 1160// let cmd : avSession.AVControlCommandType = 'toggleFavorite'; 1161// let avcommand = {command:cmd, parameter:"false"}; 1162avSession.sendSystemControlCommand(avcommand, (err) => { 1163 if (err) { 1164 console.error(`SendSystemControlCommand BusinessError: code: ${err.code}, message: ${err.message}`); 1165 } else { 1166 console.info('sendSystemControlCommand successfully'); 1167 } 1168}); 1169``` 1170 1171## avSession.sendSystemControlCommand 1172 1173sendSystemControlCommand(command: AVControlCommand): Promise\<void> 1174 1175发送控制命令给置顶会话。结果通过Promise异步回调方式返回。 1176 1177**需要权限：** ohos.permission.MANAGE_MEDIA_RESOURCES，仅系统应用可用。 1178 1179**系统能力：** SystemCapability.Multimedia.AVSession.Manager 1180 1181**系统接口：** 该接口为系统接口。 1182 1183**参数：** 1184 1185| 参数名 | 类型 | 必填 | 说明 | 1186| ------- | ------------------------------------- | ---- | ----------------------------------- | 1187| command | [AVControlCommand](arkts-apis-avsession-i.md#avcontrolcommand10) | 是 | AVSession的相关命令和命令相关参数。 | 1188 1189**返回值：** 1190 1191| 类型 | 说明 | 1192| -------------- | ----------------------------- | 1193| Promise\<void> | Promise对象。当命令发送成功，无返回结果，否则返回错误对象。 | 1194 1195**错误码：** 1196 1197以下错误码的详细介绍请参见[媒体会话管理错误码](errorcode-avsession.md)。 1198 1199| 错误码ID | 错误信息 | 1200| -------- | ---------------------------------------- | 1201| 201 | permission denied. | 1202| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Parameter verification failed. | 1203| 6600101 | Session service exception. | 1204| 6600105 | Invalid session command. | 1205| 6600107 | Too many commands or events. | 1206 1207**示例：** 1208 1209```ts 1210import { BusinessError } from '@kit.BasicServicesKit'; 1211 1212let cmd : avSession.AVControlCommandType = 'play'; 1213// let cmd : avSession.AVControlCommandType = 'pause'; 1214// let cmd : avSession.AVControlCommandType = 'stop'; 1215// let cmd : avSession.AVControlCommandType = 'playNext'; 1216// let cmd : avSession.AVControlCommandType = 'playPrevious'; 1217// let cmd : avSession.AVControlCommandType = 'fastForward'; 1218// let cmd : avSession.AVControlCommandType = 'rewind'; 1219let avcommand: avSession.AVControlCommand = {command:cmd}; 1220// let cmd : avSession.AVControlCommandType = 'seek'; 1221// let avcommand = {command:cmd, parameter:10}; 1222// let cmd : avSession.AVControlCommandType = 'setSpeed'; 1223// let avcommand = {command:cmd, parameter:2.6}; 1224// let cmd : avSession.AVControlCommandType = 'setLoopMode'; 1225// let avcommand = {command:cmd, parameter:avSession.LoopMode.LOOP_MODE_SINGLE}; 1226// let cmd : avSession.AVControlCommandType = 'toggleFavorite'; 1227// let avcommand = {command:cmd, parameter:"false"}; 1228avSession.sendSystemControlCommand(avcommand).then(() => { 1229 console.info('SendSystemControlCommand successfully'); 1230}).catch((err: BusinessError) => { 1231 console.error(`SendSystemControlCommand BusinessError: code: ${err.code}, message: ${err.message}`); 1232}); 1233``` 1234 1235## ProtocolType<sup>10+</sup> 1236 1237远端设备支持的协议类型。 1238 1239**系统能力：** SystemCapability.Multimedia.AVSession.AVCast 1240 1241| 名称 | 值 | 说明 | 1242| --------------------------- | ---- | ----------- | 1243| TYPE_CAST_PLUS_MIRROR | 1 | Cast+的镜像模式。 <br> **系统接口：** 该接口为系统接口。 | 1244 1245## avSession.startCastDeviceDiscovery<sup>10+</sup> 1246 1247startCastDeviceDiscovery(callback: AsyncCallback\<void>): void 1248 1249开始设备搜索发现。结果通过callback异步回调方式返回。 1250 1251**系统能力：** SystemCapability.Multimedia.AVSession.AVCast 1252 1253**系统接口：** 该接口为系统接口。 1254 1255**参数：** 1256 1257| 参数名 | 类型 | 必填 | 说明 | 1258| -------- | ------------------------------------- | ---- | ------------------------------------- | 1259| callback | AsyncCallback\<void> | 是 | 回调函数。当命令发送成功并开始搜索，err为undefined，否则返回错误对象。 | 1260 1261 1262**示例：** 1263 1264```ts 1265import { BusinessError } from '@kit.BasicServicesKit'; 1266 1267avSession.startCastDeviceDiscovery((err: BusinessError) => { 1268 if (err) { 1269 console.error(`startCastDeviceDiscovery BusinessError: code: ${err.code}, message: ${err.message}`); 1270 } else { 1271 console.info('startCastDeviceDiscovery successfully'); 1272 } 1273}); 1274``` 1275 1276## DistributedSessionType<sup>18+</sup> 1277 1278远端分布式设备支持的会话类型。 1279 1280**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 1281 1282**系统能力：** SystemCapability.Multimedia.AVSession.AVCast 1283 1284| 名称 | 值 | 说明 | 1285|----------------------------------------|---|---------------------------| 1286| TYPE_SESSION_REMOTE | 0 | 远端设备会话。 | 1287| TYPE_SESSION_MIGRATE_IN | 1 | 迁移至本端的设备会话。 | 1288| TYPE_SESSION_MIGRATE_OUT | 2 | 迁移至远端的设备会话。 | 1289 1290## avSession.startCastDeviceDiscovery<sup>10+</sup> 1291 1292startCastDeviceDiscovery(filter: number, callback: AsyncCallback\<void>): void 1293 1294指定过滤条件，开始设备搜索发现。结果通过callback异步回调方式返回。 1295 1296**系统能力：** SystemCapability.Multimedia.AVSession.AVCast 1297 1298**系统接口：** 该接口为系统接口。 1299 1300**参数：** 1301 1302| 参数名 | 类型 | 必填 | 说明 | 1303| -------- | ------------------------------------- | ---- | ------------------------------------- | 1304| filter | number | 是 | 进行设备发现的过滤条件，由ProtocolType的组合而成。 | 1305| callback | AsyncCallback\<void> | 是 | 回调函数。当命令发送成功并开始搜索，err为undefined，否则返回错误对象。 | 1306 1307**错误码：** 1308 1309以下错误码的详细介绍请参见[ohos.multimedia.avsession(多媒体会话)错误码](errorcode-avsession.md)。 1310 1311| 错误码ID | 错误信息 | 1312| -------- | ---------------------------------------- | 1313| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Parameter verification failed. | 1314 1315**示例：** 1316 1317```ts 1318import { BusinessError } from '@kit.BasicServicesKit'; 1319 1320let filter = 2; 1321avSession.startCastDeviceDiscovery(filter, (err: BusinessError) => { 1322 if (err) { 1323 console.error(`startCastDeviceDiscovery BusinessError: code: ${err.code}, message: ${err.message}`); 1324 } else { 1325 console.info('startCastDeviceDiscovery successfully'); 1326 } 1327}); 1328``` 1329 1330## avSession.startCastDeviceDiscovery<sup>10+</sup> 1331 1332startCastDeviceDiscovery(filter?: number, drmSchemes?: Array\<string>): Promise\<void> 1333 1334开始设备搜索发现。结果通过Promise异步回调方式返回。 1335 1336**系统能力：** SystemCapability.Multimedia.AVSession.AVCast 1337 1338**系统接口：** 该接口为系统接口。 1339 1340**参数：** 1341 1342| 参数名 | 类型 | 必填 | 说明 | 1343| -------- | ------------------------------------- | ---- | ------------------------------------- | 1344| filter | number | 否 | 进行设备发现的过滤条件，由ProtocolType的组合而成。 | 1345| drmSchemes | Array\<string> | 否 | 进行支持DRM资源播放的设备发现的过滤条件，由DRM uuid组合而成。 <br/>从API version 12开始支持该可选参数。| 1346 1347**返回值：** 1348 1349| 类型 | 说明 | 1350| -------------- | ----------------------------- | 1351| Promise\<void> | Promise对象。当命令发送成功并开始搜索，无返回结果，否则返回错误对象。 | 1352 1353**错误码：** 1354 1355以下错误码的详细介绍请参见[ohos.multimedia.avsession(多媒体会话)错误码](errorcode-avsession.md)。 1356 1357| 错误码ID | 错误信息 | 1358| -------- | ---------------------------------------- | 1359| 202 | Not System App. | 1360| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Parameter verification failed. | 1361 1362**示例：** 1363 1364```ts 1365import { BusinessError } from '@kit.BasicServicesKit'; 1366 1367let filter = 2; 1368let drmSchemes = ['3d5e6d35-9b9a-41e8-b843-dd3c6e72c42c']; 1369avSession.startCastDeviceDiscovery(filter, drmSchemes).then(() => { 1370 console.info('startCastDeviceDiscovery successfully'); 1371}).catch((err: BusinessError) => { 1372 console.error(`startCastDeviceDiscovery BusinessError: code: ${err.code}, message: ${err.message}`); 1373}); 1374``` 1375 1376## avSession.stopCastDeviceDiscovery<sup>10+</sup> 1377 1378stopCastDeviceDiscovery(callback: AsyncCallback\<void>): void 1379 1380结束设备搜索发现。结果通过callback异步回调方式返回。 1381 1382**系统能力：** SystemCapability.Multimedia.AVSession.AVCast 1383 1384**系统接口：** 该接口为系统接口。 1385 1386**参数：** 1387 1388| 参数名 | 类型 | 必填 | 说明 | 1389| -------- | ------------------------------------- | ---- | ------------------------------------- | 1390| callback | AsyncCallback\<void> | 是 | 回调函数。当成功停止搜索，err为undefined，否则返回错误对象。 | 1391 1392 1393**示例：** 1394 1395```ts 1396import { BusinessError } from '@kit.BasicServicesKit'; 1397 1398avSession.stopCastDeviceDiscovery((err: BusinessError) => { 1399 if (err) { 1400 console.error(`stopCastDeviceDiscovery BusinessError: code: ${err.code}, message: ${err.message}`); 1401 } else { 1402 console.info('stopCastDeviceDiscovery successfully'); 1403 } 1404}); 1405``` 1406 1407## avSession.stopCastDeviceDiscovery<sup>10+</sup> 1408 1409stopCastDeviceDiscovery(): Promise\<void> 1410 1411结束设备搜索发现。结果通过Promise异步回调方式返回。 1412 1413**系统能力：** SystemCapability.Multimedia.AVSession.AVCast 1414 1415**系统接口：** 该接口为系统接口。 1416 1417**返回值：** 1418 1419| 类型 | 说明 | 1420| -------------- | ----------------------------- | 1421| Promise\<void> | Promise对象。当成功停止搜索，无返回结果，否则返回错误对象。 | 1422 1423**示例：** 1424 1425```ts 1426import { BusinessError } from '@kit.BasicServicesKit'; 1427 1428avSession.stopCastDeviceDiscovery().then(() => { 1429 console.info('stopCastDeviceDiscovery successfully'); 1430}).catch((err: BusinessError) => { 1431 console.error(`stopCastDeviceDiscovery BusinessError: code: ${err.code}, message: ${err.message}`); 1432}); 1433``` 1434 1435## avSession.setDiscoverable<sup>10+</sup> 1436 1437setDiscoverable(enable: boolean, callback: AsyncCallback\<void>): void 1438 1439设置设备是否可被发现，用于投播接收端。结果通过callback异步回调方式返回。 1440 1441**系统能力：** SystemCapability.Multimedia.AVSession.AVCast 1442 1443**系统接口：** 该接口为系统接口。 1444 1445**参数：** 1446 1447| 参数名 | 类型 | 必填 | 说明 | 1448| -------- | ------------------------------------- | ---- | ------------------------------------- | 1449| enable | boolean | 是 | 是否允许本设备被发现。true：允许被发现，false：不允许被发现。 | 1450| callback | AsyncCallback\<void> | 是 | 回调函数。当设置成功，err为undefined，否则返回错误对象。 | 1451 1452**错误码：** 1453 1454以下错误码的详细介绍请参见[ohos.multimedia.avsession(多媒体会话)错误码](errorcode-avsession.md)。 1455 1456| 错误码ID | 错误信息 | 1457| -------- | ---------------------------------------- | 1458| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Parameter verification failed. | 1459 1460**示例：** 1461 1462```ts 1463import { BusinessError } from '@kit.BasicServicesKit'; 1464 1465avSession.setDiscoverable(true, (err: BusinessError) => { 1466 if (err) { 1467 console.error(`setDiscoverable BusinessError: code: ${err.code}, message: ${err.message}`); 1468 } else { 1469 console.info('setDiscoverable successfully'); 1470 } 1471}); 1472``` 1473 1474## avSession.setDiscoverable<sup>10+</sup> 1475 1476setDiscoverable(enable: boolean): Promise\<void> 1477 1478设置设备是否可被发现，用于投播接收端。结果通过Promise异步回调方式返回。 1479 1480**系统能力：** SystemCapability.Multimedia.AVSession.AVCast 1481 1482**系统接口：** 该接口为系统接口。 1483 1484**参数：** 1485 1486| 参数名 | 类型 | 必填 | 说明 | 1487| -------- | ------------------------------------- | ---- | ------------------------------------- | 1488| enable | boolean | 是 | 是否允许本设备被发现。true：允许被发现，false：不允许被发现。 | 1489 1490**错误码：** 1491 1492以下错误码的详细介绍请参见[ohos.multimedia.avsession(多媒体会话)错误码](errorcode-avsession.md)。 1493 1494| 错误码ID | 错误信息 | 1495| -------- | ---------------------------------------- | 1496| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Parameter verification failed. | 1497 1498**返回值：** 1499 1500| 类型 | 说明 | 1501| -------------- | ----------------------------- | 1502| Promise\<void> | Promise对象。当设置成功，无返回结果，否则返回错误对象。 | 1503 1504**示例：** 1505 1506```ts 1507import { BusinessError } from '@kit.BasicServicesKit'; 1508 1509avSession.setDiscoverable(true).then(() => { 1510 console.info('setDiscoverable successfully'); 1511}).catch((err: BusinessError) => { 1512 console.error(`setDiscoverable BusinessError: code: ${err.code}, message: ${err.message}`); 1513}); 1514``` 1515 1516## avSession.on('deviceAvailable')<sup>10+</sup> 1517 1518on(type: 'deviceAvailable', callback: (device: OutputDeviceInfo) => void): void 1519 1520设备发现回调监听。 1521 1522**系统能力：** SystemCapability.Multimedia.AVSession.AVCast 1523 1524**系统接口：** 该接口为系统接口。 1525 1526**参数：** 1527 1528| 参数名 | 类型 | 必填 | 说明 | 1529| -------- | -------------------- | ---- | ------------------------------------------------------------ | 1530| type | string | 是 | 事件回调类型，支持事件`'deviceAvailable'`，有设备被发现时触发回调。 | 1531| callback | (device: [OutputDeviceInfo](arkts-apis-avsession-i.md#outputdeviceinfo10)) => void | 是 | 回调函数。当监听事件注册成功，err为undefined，否则返回错误对象。 | 1532 1533**错误码：** 1534 1535以下错误码的详细介绍请参见[ohos.multimedia.avsession(多媒体会话)错误码](errorcode-avsession.md)。 1536 1537| 错误码ID | 错误信息 | 1538| -------- | ---------------------------------------- | 1539| 201 | permission denied. | 1540| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 1541 1542**示例：** 1543 1544```ts 1545let castDevice: avSession.OutputDeviceInfo; 1546avSession.on('deviceAvailable', (device: avSession.OutputDeviceInfo) => { 1547 castDevice = device; 1548 console.info(`on deviceAvailable : ${device} `); 1549}); 1550``` 1551 1552## avSession.off('deviceAvailable')<sup>10+</sup> 1553 1554off(type: 'deviceAvailable', callback?: (device: OutputDeviceInfo) => void): void 1555 1556取消设备发现回调的监听。 1557 1558**系统能力：** SystemCapability.Multimedia.AVSession.AVCast 1559 1560**系统接口：** 该接口为系统接口。 1561 1562**参数：** 1563 1564| 参数名 | 类型 | 必填 | 说明 | 1565| ------ | ---------------------- | ---- | ------------------------------------------------------- | 1566| type | string | 是 | 事件回调类型，支持事件`'deviceAvailable'`：设备发现回调。| 1567| callback | (device: [OutputDeviceInfo](arkts-apis-avsession-i.md#outputdeviceinfo10)) => void | 否 | 用于返回设备信息。| 1568 1569**错误码：** 1570 1571以下错误码的详细介绍请参见[ohos.multimedia.avsession(多媒体会话)错误码](errorcode-avsession.md)。 1572 1573| 错误码ID | 错误信息 | 1574| -------- | ---------------------------------------- | 1575| 201 | permission denied. | 1576| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 1577 1578**示例：** 1579 1580```ts 1581avSession.off('deviceAvailable'); 1582``` 1583 1584## avSession.on('deviceOffline')<sup>11+</sup> 1585 1586on(type: 'deviceOffline', callback: (deviceId: string) => void): void 1587 1588设备下线回调监听。 1589 1590**系统能力：** SystemCapability.Multimedia.AVSession.AVCast 1591 1592**系统接口：** 该接口为系统接口。 1593 1594**参数：** 1595 1596| 参数名 | 类型 | 必填 | 说明 | 1597| -------- | -------------------- | ---- | ------------------------------------------------------------ | 1598| type | string | 是 | 事件回调类型，支持事件`'deviceOffline'`，有设备下线时触发回调。 | 1599| callback | (deviceId: string) => void | 是 | 回调函数，参数deviceId是设备的ID。当监听事件注册成功，err为undefined，否则返回错误对象。 | 1600 1601**错误码：** 1602 1603以下错误码的详细介绍请参见[ohos.multimedia.avsession(多媒体会话)错误码](errorcode-avsession.md)。 1604 1605| 错误码ID | 错误信息 | 1606| -------- | ---------------------------------------- | 1607| 201 | permission denied. | 1608| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 1609 1610**示例：** 1611 1612```ts 1613let castDeviceId: string; 1614avSession.on('deviceOffline', (deviceId: string) => { 1615 castDeviceId = deviceId; 1616 console.info(`on deviceOffline : ${deviceId} `); 1617}); 1618``` 1619 1620## avSession.off('deviceOffline')<sup>11+</sup> 1621 1622off(type: 'deviceOffline', callback?: (deviceId: string) => void): void 1623 1624取消设备下线回调的监听。 1625 1626**需要权限：** ohos.permission.MANAGE_MEDIA_RESOURCES 1627 1628**系统能力：** SystemCapability.Multimedia.AVSession.AVCast 1629 1630**系统接口：** 该接口为系统接口。 1631 1632**参数：** 1633 1634| 参数名 | 类型 | 必填 | 说明 | 1635| ------ | ---------------------- | ---- | ------------------------------------------------------- | 1636| type | string | 是 | 事件回调类型，支持事件`'deviceOffline'`：设备下线回调。| 1637| callback | (deviceId: string) => void | 否 | 回调函数，参数deviceId是设备的ID。当监听事件取消成功，err为undefined，否则返回错误对象。该参数为可选参数，若不填写该参数，则认为取消所有相关会话的事件监听。| 1638 1639**错误码：** 1640 1641以下错误码的详细介绍请参见[ohos.multimedia.avsession(多媒体会话)错误码](errorcode-avsession.md)。 1642 1643| 错误码ID | 错误信息 | 1644| -------- | ---------------------------------------- | 1645| 201 | permission denied. | 1646| 202 | Not System App. | 1647| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 1648 1649**示例：** 1650 1651```ts 1652avSession.off('deviceOffline'); 1653``` 1654 1655## avSession.getAVCastController<sup>10+</sup> 1656 1657getAVCastController(sessionId: string, callback: AsyncCallback\<AVCastController>): void 1658 1659设备建立连接后，获取投播控制器。结果通过callback异步回调方式返回。 1660 1661此功能在本端和远端都可以使用，通过该接口可以获取一个相同的控制器，进行投播音频的播放控制。 1662 1663**系统能力：** SystemCapability.Multimedia.AVSession.AVCast 1664 1665**需要权限：** ohos.permission.MANAGE_MEDIA_RESOURCES 1666 1667**系统接口：** 该接口为系统接口。 1668 1669**参数：** 1670 1671| 参数名 | 类型 | 必填 | 说明 | 1672| --------- | ----------------------------------------------------------- | ---- | ------------------------------------------------------------ | 1673| sessionId | string | 是 |用于指定要获取的投播控制器的sessionId。 | 1674| callback | AsyncCallback<[AVCastController](#avcastcontroller10)\> | 是 | 回调函数，返回投播控制器实例。 | 1675 1676**错误码：** 1677 1678以下错误码的详细介绍请参见[媒体会话管理错误码](errorcode-avsession.md)。 1679 1680| 错误码ID | 错误信息 | 1681| -------- | ---------------------------------------- | 1682| 201 | permission denied. | 1683| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Parameter verification failed. | 1684| 6600101 | Session service exception | 1685| 6600102 | session does not exist | 1686 1687**示例：** 1688 1689```ts 1690import { BusinessError } from '@kit.BasicServicesKit'; 1691import { avSession } from '@kit.AVSessionKit'; 1692@Entry 1693@Component 1694struct Index { 1695 @State message: string = 'hello world'; 1696 1697 build() { 1698 Column() { 1699 Text(this.message) 1700 .onClick(()=>{ 1701 let currentAVSession: avSession.AVSession | undefined = undefined; 1702 let tag = "createNewSession"; 1703 let context = this.getUIContext().getHostContext() as Context; 1704 let sessionId: string = ""; // 供后续函数入参使用。 1705 1706 let aVCastController: avSession.AVCastController; 1707 avSession.getAVCastController(sessionId , (err: BusinessError, avcontroller: avSession.AVCastController) => { 1708 if (err) { 1709 console.error(`getAVCastController BusinessError: code: ${err.code}, message: ${err.message}`); 1710 } else { 1711 aVCastController = avcontroller; 1712 console.info('getAVCastController : SUCCESS '); 1713 } 1714 }); 1715 }) 1716 } 1717 .width('100%') 1718 .height('100%') 1719 } 1720} 1721``` 1722 1723## avSession.getAVCastController<sup>10+</sup> 1724 1725getAVCastController(sessionId: string): Promise\<AVCastController> 1726 1727设备建立连接后，获取投播控制器。结果通过Promise方式返回。 1728 1729此功能在本端和远端都可以使用，通过该接口可以获取一个相同的控制器，进行投播音频的播放控制。 1730 1731**系统能力：** SystemCapability.Multimedia.AVSession.AVCast 1732 1733**需要权限：** ohos.permission.MANAGE_MEDIA_RESOURCES 1734 1735**系统接口：** 该接口为系统接口。 1736 1737**参数：** 1738 1739| 参数名 | 类型 | 必填 | 说明 | 1740| --------- | ------------------------- | ---- | ------------------------------------------------------------ | 1741| sessionId | string | 是 |用于指定要获取的投播控制器的sessionId。 | 1742 1743**返回值：** 1744 1745| 类型 | 说明 | 1746| --------- | ------------------------------------------------------------ | 1747| Promise<[AVCastController](#avcastcontroller10)\> | Promise对象。返回投播控制器实例。 | 1748 1749**错误码：** 1750 1751以下错误码的详细介绍请参见[媒体会话管理错误码](errorcode-avsession.md)。 1752 1753| 错误码ID | 错误信息 | 1754| -------- | ---------------------------------------- | 1755| 201 | permission denied. | 1756| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Parameter verification failed. | 1757| 6600101 | server exception | 1758| 6600102 | The session does not exist | 1759 1760**示例：** 1761 1762```ts 1763import { BusinessError } from '@kit.BasicServicesKit'; 1764import { avSession } from '@kit.AVSessionKit'; 1765@Entry 1766@Component 1767struct Index { 1768 @State message: string = 'hello world'; 1769 1770 build() { 1771 Column() { 1772 Text(this.message) 1773 .onClick(()=>{ 1774 let currentAVSession: avSession.AVSession | undefined = undefined; 1775 let tag = "createNewSession"; 1776 let context = this.getUIContext().getHostContext() as Context; 1777 let sessionId: string = ""; // 供后续函数入参使用。 1778 1779 let aVCastController: avSession.AVCastController; 1780 avSession.getAVCastController(sessionId).then((avcontroller: avSession.AVCastController) => { 1781 aVCastController = avcontroller; 1782 console.info('getAVCastController : SUCCESS'); 1783 }).catch((err: BusinessError) => { 1784 console.error(`getAVCastController BusinessError: code: ${err.code}, message: ${err.message}`); 1785 }); 1786 }) 1787 } 1788 .width('100%') 1789 .height('100%') 1790 } 1791} 1792``` 1793 1794## avSession.startCasting<sup>10+</sup> 1795 1796startCasting(session: SessionToken, device: OutputDeviceInfo, callback: AsyncCallback\<void>): void 1797 1798启动投播。结果通过callback异步回调方式返回。 1799 1800**需要权限：** ohos.permission.MANAGE_MEDIA_RESOURCES，仅系统应用可用。 1801 1802**系统能力：** SystemCapability.Multimedia.AVSession.AVCast 1803 1804**系统接口：** 该接口为系统接口。 1805 1806**参数：** 1807 1808| 参数名 | 类型 | 必填 | 说明 | 1809| -------- | ------------------------------------- | ---- | ------------------------------------- | 1810| session | [SessionToken](#sessiontoken) | 是 | 会话令牌。SessionToken表示单个token。 | 1811| device | [OutputDeviceInfo](arkts-apis-avsession-i.md#outputdeviceinfo10) | 是 | 设备相关信息。 | 1812| callback | AsyncCallback\<void> | 是 | 回调函数。当命令发送成功并启动投播，err为undefined，否则返回错误对象。 | 1813 1814**错误码：** 1815 1816以下错误码的详细介绍请参见[媒体会话管理错误码](errorcode-avsession.md)。 1817 1818| 错误码ID | 错误信息 | 1819| -------- | ---------------------------------------- | 1820| 201 | permission denied. | 1821| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 1822| 6600101 | Session service exception. | 1823| 6600108 | Device connection failed. | 1824 1825**示例：** 1826 1827```ts 1828import { BusinessError } from '@kit.BasicServicesKit'; 1829 1830let myToken: avSession.SessionToken = { 1831 sessionId: sessionId, 1832} 1833let castDevice: avSession.OutputDeviceInfo | undefined = undefined; 1834avSession.on('deviceAvailable', (device: avSession.OutputDeviceInfo) => { 1835 castDevice = device; 1836 console.info(`on deviceAvailable : ${device} `); 1837}); 1838if (castDevice !== undefined) { 1839 avSession.startCasting(myToken, castDevice, (err: BusinessError) => { 1840 if (err) { 1841 console.error(`startCasting BusinessError: code: ${err.code}, message: ${err.message}`); 1842 } else { 1843 console.info('startCasting successfully'); 1844 } 1845 }); 1846} 1847``` 1848 1849 1850## avSession.startCasting<sup>10+</sup> 1851 1852startCasting(session: SessionToken, device: OutputDeviceInfo): Promise\<void> 1853 1854启动投播。结果通过Promise异步回调方式返回。 1855 1856**需要权限：** ohos.permission.MANAGE_MEDIA_RESOURCES，仅系统应用可用。 1857 1858**系统能力：** SystemCapability.Multimedia.AVSession.AVCast 1859 1860**系统接口：** 该接口为系统接口。 1861 1862**参数：** 1863 1864| 参数名 | 类型 | 必填 | 说明 | 1865| -------- | ------------------------------------- | ---- | ------------------------------------- | 1866| session | [SessionToken](#sessiontoken) | 是 | 会话令牌。SessionToken表示单个token。 | 1867| device | [OutputDeviceInfo](arkts-apis-avsession-i.md#outputdeviceinfo10) | 是 | 设备相关信息。 | 1868 1869**返回值：** 1870 1871| 类型 | 说明 | 1872| -------------- | ----------------------------- | 1873| Promise\<void> | Promise对象。当命令发送成功并启动投播，无返回结果，否则返回错误对象。 | 1874 1875**错误码：** 1876 1877以下错误码的详细介绍请参见[媒体会话管理错误码](errorcode-avsession.md)。 1878 1879| 错误码ID | 错误信息 | 1880| -------- | ---------------------------------------- | 1881| 201 | permission denied. | 1882| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 1883| 6600101 | Session service exception. | 1884| 6600108 | Device connection failed. | 1885 1886**示例：** 1887 1888```ts 1889import { BusinessError } from '@kit.BasicServicesKit'; 1890 1891let myToken: avSession.SessionToken = { 1892 sessionId: sessionId, 1893} 1894let castDevice: avSession.OutputDeviceInfo | undefined = undefined; 1895avSession.on('deviceAvailable', (device: avSession.OutputDeviceInfo) => { 1896 castDevice = device; 1897 console.info(`on deviceAvailable : ${device} `); 1898}); 1899if (castDevice !== undefined) { 1900 avSession.startCasting(myToken, castDevice).then(() => { 1901 console.info('startCasting successfully'); 1902 }).catch((err: BusinessError) => { 1903 console.error(`startCasting BusinessError: code: ${err.code}, message: ${err.message}`); 1904 }); 1905} 1906``` 1907 1908## avSession.stopCasting<sup>10+</sup> 1909 1910stopCasting(session: SessionToken, callback: AsyncCallback\<void>): void 1911 1912结束投播。结果通过callback异步回调方式返回。 1913 1914**系统能力：** SystemCapability.Multimedia.AVSession.AVCast 1915 1916**系统接口：** 该接口为系统接口。 1917 1918**参数：** 1919 1920| 参数名 | 类型 | 必填 | 说明 | 1921| -------- | ------------------------------------- | ---- | ------------------------------------- | 1922| session | [SessionToken](#sessiontoken) | 是 | 会话令牌。SessionToken表示单个token。 | 1923| callback | AsyncCallback\<void> | 是 | 回调函数。当成功结束投播，err为undefined，否则返回错误对象。 | 1924 1925**错误码：** 1926 1927以下错误码的详细介绍请参见[媒体会话管理错误码](errorcode-avsession.md)。 1928 1929| 错误码ID | 错误信息 | 1930| -------- | ---------------------------------------- | 1931| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 1932| 6600109 | The remote connection is not established. | 1933 1934**示例：** 1935 1936```ts 1937import { BusinessError } from '@kit.BasicServicesKit'; 1938 1939let myToken: avSession.SessionToken = { 1940 sessionId: sessionId, 1941} 1942avSession.stopCasting(myToken, (err: BusinessError) => { 1943 if (err) { 1944 console.error(`stopCasting BusinessError: code: ${err.code}, message: ${err.message}`); 1945 } else { 1946 console.info('stopCasting successfully'); 1947 } 1948}); 1949``` 1950 1951## avSession.stopCasting<sup>10+</sup> 1952 1953stopCasting(session: SessionToken): Promise\<void> 1954 1955结束投播。结果通过Promise异步回调方式返回。 1956 1957**系统能力：** SystemCapability.Multimedia.AVSession.AVCast 1958 1959**系统接口：** 该接口为系统接口。 1960 1961**参数：** 1962 1963| 参数名 | 类型 | 必填 | 说明 | 1964| -------- | ------------------------------------- | ---- | ------------------------------------- | 1965| session | [SessionToken](#sessiontoken) | 是 | 会话令牌。SessionToken表示单个token。 | 1966 1967**返回值：** 1968 1969| 类型 | 说明 | 1970| -------------- | ----------------------------- | 1971| Promise\<void> | Promise对象。当成功结束投播，无返回结果，否则返回错误对象。 | 1972 1973**错误码：** 1974 1975错误码的详细介绍请参见[媒体会话管理错误码](errorcode-avsession.md)。 1976 1977| 错误码ID | 错误信息 | 1978| -------- | ---------------------------------------- | 1979| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 1980| 6600109 | The remote connection is not established. | 1981 1982**示例：** 1983 1984```ts 1985import { BusinessError } from '@kit.BasicServicesKit'; 1986 1987let myToken: avSession.SessionToken = { 1988 sessionId: sessionId, 1989} 1990avSession.stopCasting(myToken).then(() => { 1991 console.info('stopCasting successfully'); 1992}).catch((err: BusinessError) => { 1993 console.error(`stopCasting BusinessError: code: ${err.code}, message: ${err.message}`); 1994}); 1995``` 1996 1997## avSession.startDeviceLogging<sup>13+</sup> 1998 1999startDeviceLogging(url: string, maxSize?: number): Promise\<void> 2000 2001开始将设备日志写入文件。结果通过Promise异步回调方式返回。 2002 2003**系统能力：** SystemCapability.Multimedia.AVSession.AVCast 2004 2005**系统接口：** 该接口为系统接口。 2006 2007**参数：** 2008 2009| 参数名 | 类型 | 必填 | 说明 | 2010| -------- | ------------------------------------- | ---- | ------------------------------------- | 2011| url | string | 是 | 目标文件描述符（打开文件的唯一标识）。 | 2012| maxSize | number | 否 | 写入最大日志大小（以KB为单位）。 | 2013 2014**返回值：** 2015 2016| 类型 | 说明 | 2017| -------------- | ----------------------------- | 2018| Promise\<void> | Promise对象。当设备日志写入文件成功时，无返回结果，否则返回错误对象。 | 2019 2020**错误码：** 2021 2022以下错误码的详细介绍请参见[媒体会话管理错误码](errorcode-avsession.md)。 2023 2024| 错误码ID | 错误信息 | 2025| -------- | ---------------------------------------- | 2026| 202 | Not System App. | 2027| 401 | Parameter check failed. 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.| 2028| 6600101 | Session service exception. | 2029| 6600102 | The session does not exist. | 2030 2031**示例：** 2032 2033```ts 2034import { BusinessError } from '@kit.BasicServicesKit'; 2035import { fileIo } from '@kit.CoreFileKit'; 2036 2037let file = await fileIo.open("filePath"); 2038let url = file.fd.toString(); 2039avSession.startDeviceLogging(url, 2048).then(() => { 2040 console.info('startDeviceLogging successfully'); 2041}).catch((err: BusinessError) => { 2042 console.error(`startDeviceLogging BusinessError: code: ${err.code}, message: ${err.message}`); 2043}) 2044``` 2045 2046## avSession.stopDeviceLogging<sup>13+</sup> 2047 2048stopDeviceLogging(): Promise\<void> 2049 2050停止当前设备日志写入。结果通过Promise异步回调方式返回。 2051 2052**系统能力：** SystemCapability.Multimedia.AVSession.AVCast 2053 2054**系统接口：** 该接口为系统接口。 2055 2056**返回值：** 2057 2058| 类型 | 说明 | 2059| -------------- | ----------------------------- | 2060| Promise\<void> | Promise对象。当停止当前设备日志写入，无返回结果，否则返回错误对象。 | 2061 2062**错误码：** 2063 2064以下错误码的详细介绍请参见[媒体会话管理错误码](errorcode-avsession.md)。 2065 2066| 错误码ID | 错误信息 | 2067| -------- | ---------------------------------------- | 2068| 202 | Not System App. | 2069| 6600101 | Session service exception. | 2070| 6600102 | The session does not exist. | 2071 2072**示例：** 2073 2074```ts 2075import { BusinessError } from '@kit.BasicServicesKit'; 2076 2077avSession.stopDeviceLogging().then(() => { 2078 console.info('stopCasting successfully'); 2079}).catch((err: BusinessError) => { 2080 console.error(`stopCasting BusinessError: code: ${err.code}, message: ${err.message}`); 2081}); 2082``` 2083 2084## avSession.on('deviceLogEvent')<sup>13+</sup> 2085 2086on(type: 'deviceLogEvent', callback: Callback\<DeviceLogEventCode>): void 2087 2088监听日志事件的回调。 2089 2090**系统能力：** SystemCapability.Multimedia.AVSession.AVCast 2091 2092**系统接口：** 该接口为系统接口。 2093 2094**参数：** 2095 2096| 参数名 | 类型 | 必填 | 说明 | 2097| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 2098| type | string | 是 | 事件回调类型，支持事件`'deviceLogEvent'`。 | 2099| callback | (callback: [DeviceLogEventCode](#devicelogeventcode13)) => void | 是 | 回调函数，参数DeviceLogEventCode是当前设备日志返回值。 | 2100 2101**错误码：** 2102 2103以下错误码的详细介绍请参见[媒体会话管理错误码](errorcode-avsession.md)。 2104 2105| 错误码ID | 错误信息 | 2106| -------- | ---------------------------------------- | 2107| 202 | Not System App. | 2108| 401 | Parameter check failed. 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.| 2109| 6600101 | Session service exception. | 2110| 6600102 | The session does not exist. | 2111 2112**示例：** 2113 2114```ts 2115avSession.on('deviceLogEvent', (eventCode: avSession.DeviceLogEventCode) => { 2116 console.info(`on deviceLogEvent code : ${eventCode}`); 2117}); 2118``` 2119 2120## avSession.off('deviceLogEvent')<sup>13+</sup> 2121 2122off(type: 'deviceLogEvent', callback?: Callback\<DeviceLogEventCode>): void 2123 2124取消监听日志事件的回调。 2125 2126**系统能力：** SystemCapability.Multimedia.AVSession.AVCast 2127 2128**系统接口：** 该接口为系统接口。 2129 2130**参数：** 2131 2132| 参数名 | 类型 | 必填 | 说明 | 2133| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 2134| type | string | 是 | 取消对应的监听事件，支持事件`'deviceLogEvent'`。 | 2135| callback | (callback: [DeviceLogEventCode](#devicelogeventcode13)) => void | 否 | 回调函数。当监听事件取消成功，err为undefined，否则返回错误对象。该参数为可选参数，若不填写该参数，则认为取消所有相关会话的事件监听。 | 2136 2137**错误码：** 2138 2139以下错误码的详细介绍请参见[媒体会话管理错误码](errorcode-avsession.md)。 2140 2141| 错误码ID | 错误信息 | 2142| -------- | ---------------------------------------- | 2143| 202 | Not System App. | 2144| 401 | Parameter check failed. 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.| 2145| 6600101 | Session service exception. | 2146| 6600102 | The session does not exist. | 2147 2148**示例：** 2149 2150```ts 2151avSession.off('deviceLogEvent'); 2152``` 2153 2154## DeviceState<sup>20+</sup> 2155 2156投播设备的连接状态。 2157 2158**系统接口：** 该接口为系统接口。 2159 2160**系统能力：** SystemCapability.Multimedia.AVSession.AVCast 2161 2162| 名称 | 类型 | 只读 | 可选 | 说明 | 2163| :------------- | :----- | :--- | :--- | :----------- | 2164| deviceId | string | 是 | 否 | 投播设备ID。 | 2165| deviceState | number | 是 | 否 | 投播设备连接状态码。 | 2166| reasonCode | number | 是 | 否 | 投播设备连接错误码。 | 2167| radarErrorCode | number | 是 | 否 | 系统雷达错误码。 | 2168 2169## avSession.on('deviceStateChanged')<sup>20+</sup> 2170 2171on(type: 'deviceStateChanged', callback: Callback\<DeviceState\>): void 2172 2173投播设备连接状态的回调函数。 2174 2175**系统接口：** 该接口为系统接口。 2176 2177**需要权限：** ohos.permission.MANAGE_MEDIA_RESOURCES 2178 2179**系统能力：** SystemCapability.Multimedia.AVSession.AVCast 2180 2181**参数：** 2182 2183| 参数名 | 类型 | 必填 | 说明 | 2184| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 2185| type | string | 是 | 事件回调类型，支持事件`'deviceStateChanged'`，投播设备连接状态发生变化时触发回调。 | 2186| callback | (callback: [DeviceState](#devicestate20)) => void | 是 | 回调函数，参数DeviceState包含投播设备ID、连接状态码、连接错误码和系统雷达错误码。| 2187 2188**错误码：** 2189 2190以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 2191 2192| 错误码ID | 错误信息 | 2193| -------- | ---------------------------------------- | 2194| 201 | Permission denied. | 2195| 202 | Not System App. | 2196 2197**示例：** 2198 2199```ts 2200avSession.on('deviceStateChanged', (state: avSession.DeviceState) => { 2201 console.info(`on deviceStateChanged state, deviceId=${state.deviceId}, connect status=${state.deviceState}, 2202 reasonCode=${state.reasonCode}, radarErrorCode=${state.radarErrorCode}`) 2203}) 2204``` 2205 2206## avSession.off('deviceStateChanged')<sup>20+</sup> 2207 2208off(type: 'deviceStateChanged', callback?: Callback\<DeviceState>): void 2209 2210取消投播设备连接状态的监听。 2211 2212**系统接口：** 该接口为系统接口。 2213 2214**需要权限：** ohos.permission.MANAGE_MEDIA_RESOURCES 2215 2216**系统能力：** SystemCapability.Multimedia.AVSession.AVCast 2217 2218**参数：** 2219 2220| 参数名 | 类型 | 必填 | 说明 | 2221| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 2222| type | string | 是 | 取消对应的监听事件，支持事件`'deviceStateChanged'`，投播设备连接状态变化的回调。 | 2223| callback | (callback: [DeviceState](#devicestate20)) => void | 否 | 回调函数，当监听事件取消成功时，err为undefined；否则返回错误对象。该参数为可选参数，若未填写，则取消所有相关会话的事件监听。 | 2224 2225**错误码：** 2226 2227以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 2228 2229| 错误码ID | 错误信息 | 2230| -------- | ---------------------------------------- | 2231| 201 | Permission denied. | 2232| 202 | Not System App. | 2233 2234**示例：** 2235 2236```ts 2237avSession.off('deviceStateChanged'); 2238``` 2239 2240## AVCastController<sup>10+</sup> 2241 2242在投播建立后，调用[avSession.getAVCastController](arkts-apis-avsession-AVSession.md#getavcastcontroller10)后，返回会话控制器实例。控制器可查看会话ID，并可完成对会话发送命令及事件，获取会话元数据，播放状态信息等操作。 2243 2244### setDisplaySurface<sup>10+</sup> 2245 2246setDisplaySurface(surfaceId: string): Promise\<void> 2247 2248设置播放的surfaceId，在投播sink端使用。结果通过Promise异步回调方式返回。 2249 2250**系统能力：** SystemCapability.Multimedia.AVSession.AVCast 2251 2252**系统接口：** 该接口为系统接口。 2253 2254**参数：** 2255 2256| 参数名 | 类型 | 必填 | 说明 | 2257| -------- | --------------------------------------------------- | ---- | ---------------------------- | 2258| surfaceId | string | 是 | 设置播放的surfaceId。 | 2259 2260**返回值：** 2261 2262| 类型 | 说明 | 2263| --------------------------------------------- | --------------------------- | 2264| Promise\<void> | Promise对象。返回设置结果。 | 2265 2266**错误码：** 2267 2268以下错误码的详细介绍请参见[媒体会话管理错误码](errorcode-avsession.md)。 2269 2270| 错误码ID | 错误信息 | 2271| -------- | ---------------------------------------- | 2272| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Parameter verification failed. | 2273| 6600109 | The remote connection is not established. | 2274 2275**示例：** 2276 2277```ts 2278import { media } from '@kit.MediaKit'; 2279let surfaceID: string = ''; 2280media.createAVRecorder().then((avRecorder) => { 2281 avRecorder.getInputSurface((err: BusinessError, surfaceId: string) => { 2282 if (err == null) { 2283 console.info('getInputSurface success'); 2284 surfaceID = surfaceId; 2285 } else { 2286 console.error('getInputSurface failed and error is ' + err.message); 2287 } 2288 }); 2289}) 2290aVCastController.setDisplaySurface(surfaceID).then(() => { 2291 console.info('setDisplaySurface : SUCCESS'); 2292}); 2293``` 2294 2295### setDisplaySurface<sup>10+</sup> 2296 2297setDisplaySurface(surfaceId: string, callback: AsyncCallback\<void>): void 2298 2299设置播放的surfaceId，在投播sink端使用。结果通过callback异步回调方式返回。 2300 2301**系统能力：** SystemCapability.Multimedia.AVSession.AVCast 2302 2303**系统接口：** 该接口为系统接口。 2304 2305**参数：** 2306 2307| 参数名 | 类型 | 必填 | 说明 | 2308| -------- | --------------------------------------------------- | ---- | ---------------------------- | 2309| callback | AsyncCallback\<void> | 是 | 回调函数，返回当前设置结果。 | 2310| surfaceId | string | 是 | 设置播放的surfaceId。 | 2311 2312 2313**错误码：** 2314 2315以下错误码的详细介绍请参见[媒体会话管理错误码](errorcode-avsession.md)。 2316 2317| 错误码ID | 错误信息 | 2318| -------- | ---------------------------------------- | 2319| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Parameter verification failed. | 2320| 6600109 | The remote connection is not established. | 2321 2322**示例：** 2323 2324```ts 2325import { BusinessError } from '@kit.BasicServicesKit'; 2326import { media } from '@kit.MediaKit'; 2327let surfaceID: string = ''; 2328media.createAVRecorder().then((avRecorder) => { 2329 avRecorder.getInputSurface((err: BusinessError, surfaceId: string) => { 2330 if (err == null) { 2331 console.info('getInputSurface success'); 2332 surfaceID = surfaceId; 2333 } else { 2334 console.error('getInputSurface failed and error is ' + err.message); 2335 } 2336 }); 2337}) 2338aVCastController.setDisplaySurface(surfaceID, (err: BusinessError) => { 2339 if (err) { 2340 console.error(`setDisplaySurface BusinessError: code: ${err.code}, message: ${err.message}`); 2341 } else { 2342 console.info('setDisplaySurface : SUCCESS'); 2343 } 2344}); 2345``` 2346 2347### on('videoSizeChange')<sup>12+</sup> 2348 2349on(type: 'videoSizeChange', callback: (width:number, height:number) => void): void 2350 2351设置video尺寸更改监听事件。 2352 2353**系统能力：** SystemCapability.Multimedia.AVSession.AVCast 2354 2355**系统接口：** 该接口为系统接口。 2356 2357**参数：** 2358 2359| 参数名 | 类型 | 必填 | 说明 | 2360| -------- | ------------------------------------------------------------ | ---- | ----------------------------------------------------- | 2361| type | string | 是 | 事件回调类型，支持事件`'videoSizeChange'`：当video尺寸更改时，触发该事件。 | 2362| callback | (width:number, height:number) => void | 是 | 回调函数，返回video的宽度和高度。 | 2363 2364**错误码：** 2365 2366以下错误码的详细介绍请参见[媒体会话管理错误码](errorcode-avsession.md)。 2367 2368| 错误码ID | 错误信息 | 2369| -------- | ---------------- | 2370| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 2371| 6600101 | Session service exception. | 2372 2373**示例：** 2374 2375```ts 2376aVCastController.on('videoSizeChange', (width: number, height: number) => { 2377 console.info(`width ：${width} `); 2378 console.info(`height：${height} `); 2379}); 2380``` 2381 2382### off('videoSizeChange')<sup>12+</sup> 2383 2384off(type: 'videoSizeChange'): void 2385 2386取消设置video尺寸更改监听事件。 2387 2388**系统能力：** SystemCapability.Multimedia.AVSession.AVCast 2389 2390**系统接口：** 该接口为系统接口。 2391 2392**参数：** 2393 2394| 参数名 | 类型 | 必填 | 说明 | 2395| -------- | ------------------------------------------------------------ | ---- | ----------------------------------------------------- | 2396| type | string | 是 | 取消对应的监听事件，支持事件`'videoSizeChange'`。 | 2397 2398**错误码：** 2399 2400以下错误码的详细介绍请参见[媒体会话管理错误码](errorcode-avsession.md)。 2401 2402| 错误码ID | 错误信息 | 2403| -------- | ---------------- | 2404| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 2405| 6600101 | Session service exception. | 2406 2407**示例：** 2408 2409```ts 2410aVCastController.off('videoSizeChange'); 2411``` 2412 2413## AVMetadata<sup>10+</sup> 2414 2415媒体元数据的相关属性。 2416 2417**系统能力：** SystemCapability.Multimedia.AVSession.Core 2418 2419| 名称 | 类型 | 必填 | 说明 | 2420| --------------- |-------------------------| ---- |---------------------------------------------------------------------| 2421| avQueueName<sup>12+</sup> | string | 否 | 歌单（歌曲列表）名称。<br/>此接口为系统接口。 | 2422 2423## AVQueueInfo<sup>11+</sup> 2424 2425歌单（歌曲列表）的相关属性。 2426 2427**系统能力：** SystemCapability.Multimedia.AVSession.Core 2428 2429**系统接口：** 该接口为系统接口。 2430 2431| 名称 | 类型 | 必填 | 说明 | 2432| --------------- |-------------------------| ---- |--------------------------------------------------------------------- | 2433| bundleName | string | 是 | 歌单所属应用包名。 | 2434| avQueueName | string | 是 | 歌单（歌曲列表）名称。 | 2435| avQueueId | string | 是 | 歌单（歌曲列表）唯一标识Id。 | 2436| avQueueImage | image.PixelMap | string |是 | 歌单（歌曲列表）封面图，图片的像素数据或者图片路径地址(本地路径或网络路径)。 | 2437| lastPlayedTime | number | 否 | 歌单最后播放时间。 | 2438 2439## DeviceInfo<sup>10+</sup> 2440 2441播放设备的相关信息。 2442 2443| 名称 | 类型 | 必填 | 说明 | 2444| ---------- | -------------- | ---- | ---------------------- | 2445| ipAddress | string | 否 | 播放设备的ip地址。<br/>此接口为系统接口。<br> **系统能力：** SystemCapability.Multimedia.AVSession.AVCast | 2446| providerId | number | 否 | 播放设备提供商。<br/>此接口为系统接口。<br> **系统能力：** SystemCapability.Multimedia.AVSession.AVCast | 2447| authenticationStatus<sup>11+</sup> | number | 否 | 播放设备是否可信。默认为0。0代表设备不可信，1代表设备可信。<br/>此接口为系统接口。<br> **系统能力：** SystemCapability.Multimedia.AVSession.AVCast | 2448| networkId<sup>13+</sup> | string | 否 | 播放设备的网络ID。 <br/>此接口为系统接口。<br> **系统能力：** SystemCapability.Multimedia.AVSession.AVCast| 2449 2450## AVSessionDescriptor 2451 2452会话的相关描述信息。 2453 2454**系统能力：** SystemCapability.Multimedia.AVSession.Manager 2455 2456**系统接口：** 该接口为系统接口。 2457 2458| 名称 | 类型 | 只读 | 可选 | 说明 | 2459| --------------| ---------------- | ---------------- | ---------------- |------| 2460| sessionId | string | 否 | 否 | 会话ID。 | 2461| type | [AVSessionType](arkts-apis-avsession-t.md#avsessiontype10) | 否 | 否 | 会话类型。 | 2462| sessionTag | string | 否 | 否 | 会话的自定义名称。 | 2463| elementName | [ElementName](../apis-ability-kit/js-apis-bundle-ElementName.md) | 否 | 否 | 会话所属应用的信息（包含bundleName、abilityName等）。 | 2464| isActive | boolean | 否 | 否 | 会话是否被激活。<br>true：已被激活。 <br>false：没有被激活。 | 2465| isTopSession | boolean | 否 | 否 | 会话是否为最新的会话。 <br>true：是最新的会话。<br>false：不是最新的会话。 | 2466| outputDevice | [OutputDeviceInfo](arkts-apis-avsession-i.md#outputdeviceinfo10) | 否 | 否 | 分布式设备相关信息。 | 2467 2468## DeviceLogEventCode<sup>13+</sup> 2469 2470设备日志事件返回值的枚举。 2471 2472**系统能力：** SystemCapability.Multimedia.AVSession.AVCast 2473 2474**系统接口：** 该接口为系统接口。 2475 2476| 名称 | 值 | 说明 | 2477| --------------------------- | ---- | ----------- | 2478| DEVICE_LOG_FULL | 1 | 日志已满。 | 2479| DEVICE_LOG_EXCEPTION | 2 | 日志写入异常。 |