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