1/****************************************************************************** 2 * 3 * Copyright (C) 2006-2012 Broadcom Corporation 4 * 5 * Licensed under the Apache License, Version 2.0 (the "License"); 6 * you may not use this file except in compliance with the License. 7 * You may obtain a copy of the License at: 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 * 17 ******************************************************************************/ 18 19/****************************************************************************** 20 * 21 * nterface to AVRCP Application Programming Interface 22 * 23 ******************************************************************************/ 24#ifndef AVRC_API_H 25#define AVRC_API_H 26#include "bt_target.h" 27#include "avct_api.h" 28#include "sdp_api.h" 29#include "avrc_defs.h" 30 31/***************************************************************************** 32** constants 33*****************************************************************************/ 34 35/* API function return value result codes. */ 36#define AVRC_SUCCESS AVCT_SUCCESS /* 0 Function successful */ 37#define AVRC_NO_RESOURCES AVCT_NO_RESOURCES /* 1 Not enough resources */ 38#define AVRC_BAD_HANDLE AVCT_BAD_HANDLE /* 2 Bad handle */ 39#define AVRC_PID_IN_USE AVCT_PID_IN_USE /* 3 PID already in use */ 40#define AVRC_NOT_OPEN AVCT_NOT_OPEN /* 4 Connection not open */ 41#define AVRC_MSG_TOO_BIG 5 /* 5 the message length exceed the MTU of the browsing channel */ 42#define AVRC_FAIL 0x10 /* 0x10 generic failure */ 43#define AVRC_BAD_PARAM 0x11 /* 0x11 bad parameter */ 44 45/* Control role - same as AVCT_TARGET/AVCT_CONTROL */ 46#define AVRC_CT_TARGET 1 /* target */ 47#define AVRC_CT_CONTROL 2 /* controller */ 48#define AVRC_CT_PASSIVE 4 /* If conflict, allow the other side to succeed */ 49 50/* Connection role */ 51#define AVRC_CONN_INT AVCT_INT /* initiator */ 52#define AVRC_CONN_ACP AVCT_ACP /* Acceptor */ 53 54 55/* AVRC CTRL events */ 56/* AVRC_OPEN_IND_EVT event is sent when the connection is successfully opened. 57 * This eventis sent in response to an AVRC_Open(). */ 58#define AVRC_OPEN_IND_EVT 0 59 60/* AVRC_CLOSE_IND_EVT event is sent when a connection is closed. 61 * This event can result from a call to AVRC_Close() or when the peer closes 62 * the connection. It is also sent when a connection attempted through 63 * AVRC_Open() fails. */ 64#define AVRC_CLOSE_IND_EVT 1 65 66/* AVRC_CONG_IND_EVT event indicates that AVCTP is congested and cannot send 67 * any more messages. */ 68#define AVRC_CONG_IND_EVT 2 69 70/* AVRC_UNCONG_IND_EVT event indicates that AVCTP is uncongested and ready to 71 * send messages. */ 72#define AVRC_UNCONG_IND_EVT 3 73 74 /* AVRC_BROWSE_OPEN_IND_EVT event is sent when the browse channel is successfully opened. 75 * This eventis sent in response to an AVRC_Open() or AVRC_OpenBrowse() . */ 76#define AVRC_BROWSE_OPEN_IND_EVT 4 77 78/* AVRC_BROWSE_CLOSE_IND_EVT event is sent when a browse channel is closed. 79 * This event can result from a call to AVRC_Close(), AVRC_CloseBrowse() or when the peer closes 80 * the connection. It is also sent when a connection attempted through 81 * AVRC_OpenBrowse() fails. */ 82#define AVRC_BROWSE_CLOSE_IND_EVT 5 83 84/* AVRC_BROWSE_CONG_IND_EVT event indicates that AVCTP browse channel is congested and cannot send 85 * any more messages. */ 86#define AVRC_BROWSE_CONG_IND_EVT 6 87 88/* AVRC_BROWSE_UNCONG_IND_EVT event indicates that AVCTP browse channel is uncongested and ready to 89 * send messages. */ 90#define AVRC_BROWSE_UNCONG_IND_EVT 7 91 92/* Supported categories */ 93#define AVRC_SUPF_CT_CAT1 0x0001 /* Category 1 */ 94#define AVRC_SUPF_CT_CAT2 0x0002 /* Category 2 */ 95#define AVRC_SUPF_CT_CAT3 0x0004 /* Category 3 */ 96#define AVRC_SUPF_CT_CAT4 0x0008 /* Category 4 */ 97#define AVRC_SUPF_CT_BROWSE 0x0040 /* Browsing */ 98 99#define AVRC_SUPF_TG_CAT1 0x0001 /* Category 1 */ 100#define AVRC_SUPF_TG_CAT2 0x0002 /* Category 2 */ 101#define AVRC_SUPF_TG_CAT3 0x0004 /* Category 3 */ 102#define AVRC_SUPF_TG_CAT4 0x0008 /* Category 4 */ 103#define AVRC_SUPF_TG_APP_SETTINGS 0x0010 /* Player Application Settings */ 104#define AVRC_SUPF_TG_GROUP_NAVI 0x0020 /* Group Navigation */ 105#define AVRC_SUPF_TG_BROWSE 0x0040 /* Browsing */ 106#define AVRC_SUPF_TG_MULTI_PLAYER 0x0080 /* Muliple Media Player */ 107 108#define AVRC_META_SUCCESS AVRC_SUCCESS 109#define AVRC_META_FAIL AVRC_FAIL 110#define AVRC_METADATA_CMD 0x0000 111#define AVRC_METADATA_RESP 0x0001 112 113 114 115/***************************************************************************** 116** data type definitions 117*****************************************************************************/ 118 119/* This data type is used in AVRC_FindService() to initialize the SDP database 120 * to hold the result service search. */ 121typedef struct 122{ 123 UINT32 db_len; /* Length, in bytes, of the discovery database */ 124 tSDP_DISCOVERY_DB *p_db; /* Pointer to the discovery database */ 125 UINT16 num_attr;/* The number of attributes in p_attrs */ 126 UINT16 *p_attrs; /* The attributes filter. If NULL, AVRCP API sets the attribute filter 127 * to be ATTR_ID_SERVICE_CLASS_ID_LIST, ATTR_ID_BT_PROFILE_DESC_LIST, 128 * ATTR_ID_SUPPORTED_FEATURES, ATTR_ID_SERVICE_NAME and ATTR_ID_PROVIDER_NAME. 129 * If not NULL, the input is taken as the filter. */ 130} tAVRC_SDP_DB_PARAMS; 131 132/* This callback function returns service discovery information to the 133 * application after the AVRC_FindService() API function is called. The 134 * implementation of this callback function must copy the p_service_name 135 * and p_provider_name parameters passed to it as they are not guaranteed 136 * to remain after the callback function exits. */ 137typedef void (tAVRC_FIND_CBACK) (UINT16 status); 138 139 140/* This is the control callback function. This function passes events 141 * listed in Table 20 to the application. */ 142typedef void (tAVRC_CTRL_CBACK) (UINT8 handle, UINT8 event, UINT16 result, 143 BD_ADDR peer_addr); 144 145 146/* This is the message callback function. It is executed when AVCTP has 147 * a message packet ready for the application. The implementation of this 148 * callback function must copy the tAVRC_MSG structure passed to it as it 149 * is not guaranteed to remain after the callback function exits. */ 150typedef void (tAVRC_MSG_CBACK) (UINT8 handle, UINT8 label, UINT8 opcode, 151 tAVRC_MSG *p_msg); 152 153typedef struct 154{ 155 tAVRC_CTRL_CBACK *p_ctrl_cback; /* pointer to application control callback */ 156 tAVRC_MSG_CBACK *p_msg_cback; /* pointer to application message callback */ 157 UINT32 company_id; /* the company ID */ 158 UINT8 conn; /* Connection role (Initiator/acceptor) */ 159 UINT8 control; /* Control role (Control/Target) */ 160} tAVRC_CONN_CB; 161 162 163 164/***************************************************************************** 165** external function declarations 166*****************************************************************************/ 167#ifdef __cplusplus 168extern "C" 169{ 170#endif 171 172/****************************************************************************** 173** 174** Function AVRC_AddRecord 175** 176** Description This function is called to build an AVRCP SDP record. 177** Prior to calling this function the application must 178** call SDP_CreateRecord() to create an SDP record. 179** 180** Input Parameters: 181** service_uuid: Indicates TG(UUID_SERVCLASS_AV_REM_CTRL_TARGET) 182** or CT(UUID_SERVCLASS_AV_REMOTE_CONTROL) 183** 184** p_service_name: Pointer to a null-terminated character 185** string containing the service name. 186** If service name is not used set this to NULL. 187** 188** p_provider_name: Pointer to a null-terminated character 189** string containing the provider name. 190** If provider name is not used set this to NULL. 191** 192** categories: Supported categories. 193** 194** sdp_handle: SDP handle returned by SDP_CreateRecord(). 195** 196** Output Parameters: 197** None. 198** 199** Returns AVRC_SUCCESS if successful. 200** AVRC_NO_RESOURCES if not enough resources to build the SDP record. 201** 202******************************************************************************/ 203AVRC_API extern UINT16 AVRC_AddRecord(UINT16 service_uuid, char *p_service_name, 204 char *p_provider_name, UINT16 categories, UINT32 sdp_handle); 205 206/****************************************************************************** 207** 208** Function AVRC_FindService 209** 210** Description This function is called by the application to perform service 211** discovery and retrieve AVRCP SDP record information from a 212** peer device. Information is returned for the first service 213** record found on the server that matches the service UUID. 214** The callback function will be executed when service discovery 215** is complete. There can only be one outstanding call to 216** AVRC_FindService() at a time; the application must wait for 217** the callback before it makes another call to the function. 218** The application is responsible for allocating memory for the 219** discovery database. It is recommended that the size of the 220** discovery database be at least 300 bytes. The application 221** can deallocate the memory after the callback function has 222** executed. 223** 224** Input Parameters: 225** service_uuid: Indicates TG(UUID_SERVCLASS_AV_REM_CTRL_TARGET) 226** or CT(UUID_SERVCLASS_AV_REMOTE_CONTROL) 227** 228** bd_addr: BD address of the peer device. 229** 230** p_db: SDP discovery database parameters. 231** 232** p_cback: Pointer to the callback function. 233** 234** Output Parameters: 235** None. 236** 237** Returns AVRC_SUCCESS if successful. 238** AVRC_BAD_PARAMS if discovery database parameters are invalid. 239** AVRC_NO_RESOURCES if there are not enough resources to 240** perform the service search. 241** 242******************************************************************************/ 243AVRC_API extern UINT16 AVRC_FindService(UINT16 service_uuid, BD_ADDR bd_addr, 244 tAVRC_SDP_DB_PARAMS *p_db, tAVRC_FIND_CBACK *p_cback); 245 246/****************************************************************************** 247** 248** Function AVRC_Open 249** 250** Description This function is called to open a connection to AVCTP. 251** The connection can be either an initiator or acceptor, as 252** determined by the p_ccb->stream parameter. 253** The connection can be a target, a controller or for both role, 254** as determined by the p_ccb->control parameter. 255** By definition, a target connection is an acceptor connection 256** that waits for an incoming AVCTP connection from the peer. 257** The connection remains available to the application until 258** the application closes it by calling AVRC_Close(). The 259** application does not need to reopen the connection after an 260** AVRC_CLOSE_IND_EVT is received. 261** 262** Input Parameters: 263** p_ccb->company_id: Company Identifier. 264** 265** p_ccb->p_ctrl_cback: Pointer to control callback function. 266** 267** p_ccb->p_msg_cback: Pointer to message callback function. 268** 269** p_ccb->conn: AVCTP connection role. This is set to 270** AVCTP_INT for initiator connections and AVCTP_ACP 271** for acceptor connections. 272** 273** p_ccb->control: Control role. This is set to 274** AVRC_CT_TARGET for target connections, AVRC_CT_CONTROL 275** for control connections or (AVRC_CT_TARGET|AVRC_CT_CONTROL) 276** for connections that support both roles. 277** 278** peer_addr: BD address of peer device. This value is 279** only used for initiator connections; for acceptor 280** connections it can be set to NULL. 281** 282** Output Parameters: 283** p_handle: Pointer to handle. This parameter is only 284** valid if AVRC_SUCCESS is returned. 285** 286** Returns AVRC_SUCCESS if successful. 287** AVRC_NO_RESOURCES if there are not enough resources to open 288** the connection. 289** 290******************************************************************************/ 291AVRC_API extern UINT16 AVRC_Open(UINT8 *p_handle, tAVRC_CONN_CB *p_ccb, 292 BD_ADDR_PTR peer_addr); 293 294/****************************************************************************** 295** 296** Function AVRC_Close 297** 298** Description Close a connection opened with AVRC_Open(). 299** This function is called when the 300** application is no longer using a connection. 301** 302** Input Parameters: 303** handle: Handle of this connection. 304** 305** Output Parameters: 306** None. 307** 308** Returns AVRC_SUCCESS if successful. 309** AVRC_BAD_HANDLE if handle is invalid. 310** 311******************************************************************************/ 312AVRC_API extern UINT16 AVRC_Close(UINT8 handle); 313 314/****************************************************************************** 315** 316** Function AVRC_OpenBrowse 317** 318** Description This function is called to open a browsing connection to AVCTP. 319** The connection can be either an initiator or acceptor, as 320** determined by the conn_role. 321** The handle is returned by a previous call to AVRC_Open. 322** 323** Returns AVRC_SUCCESS if successful. 324** AVRC_NO_RESOURCES if there are not enough resources to open 325** the connection. 326** 327******************************************************************************/ 328AVRC_API extern UINT16 AVRC_OpenBrowse(UINT8 handle, UINT8 conn_role); 329 330/****************************************************************************** 331** 332** Function AVRC_CloseBrowse 333** 334** Description Close a connection opened with AVRC_OpenBrowse(). 335** This function is called when the 336** application is no longer using a connection. 337** 338** Returns AVRC_SUCCESS if successful. 339** AVRC_BAD_HANDLE if handle is invalid. 340** 341******************************************************************************/ 342AVRC_API extern UINT16 AVRC_CloseBrowse(UINT8 handle); 343 344/****************************************************************************** 345** 346** Function AVRC_MsgReq 347** 348** Description This function is used to send the AVRCP byte stream in p_pkt 349** down to AVCTP. 350** 351** It is expected that p_pkt->offset is at least AVCT_MSG_OFFSET 352** p_pkt->layer_specific is AVCT_DATA_CTRL or AVCT_DATA_BROWSE 353** p_pkt->event is AVRC_OP_VENDOR, AVRC_OP_PASS_THRU or AVRC_OP_BROWSING 354** The above BT_HDR settings are set by the AVRC_Bld* functions. 355** 356** Returns AVRC_SUCCESS if successful. 357** AVRC_BAD_HANDLE if handle is invalid. 358** 359******************************************************************************/ 360AVRC_API extern UINT16 AVRC_MsgReq (UINT8 handle, UINT8 label, UINT8 ctype, BT_HDR *p_pkt); 361 362/****************************************************************************** 363** 364** Function AVRC_UnitCmd 365** 366** Description Send a UNIT INFO command to the peer device. This 367** function can only be called for controller role connections. 368** Any response message from the peer is passed back through 369** the tAVRC_MSG_CBACK callback function. 370** 371** Input Parameters: 372** handle: Handle of this connection. 373** 374** label: Transaction label. 375** 376** Output Parameters: 377** None. 378** 379** Returns AVRC_SUCCESS if successful. 380** AVRC_BAD_HANDLE if handle is invalid. 381** 382******************************************************************************/ 383AVRC_API extern UINT16 AVRC_UnitCmd(UINT8 handle, UINT8 label); 384 385/****************************************************************************** 386** 387** Function AVRC_SubCmd 388** 389** Description Send a SUBUNIT INFO command to the peer device. This 390** function can only be called for controller role connections. 391** Any response message from the peer is passed back through 392** the tAVRC_MSG_CBACK callback function. 393** 394** Input Parameters: 395** handle: Handle of this connection. 396** 397** label: Transaction label. 398** 399** page: Specifies which part of the subunit type table 400** is requested. For AVRCP it is typically zero. 401** Value range is 0-7. 402** 403** Output Parameters: 404** None. 405** 406** Returns AVRC_SUCCESS if successful. 407** AVRC_BAD_HANDLE if handle is invalid. 408** 409******************************************************************************/ 410AVRC_API extern UINT16 AVRC_SubCmd(UINT8 handle, UINT8 label, UINT8 page); 411 412 413/****************************************************************************** 414** 415** Function AVRC_PassCmd 416** 417** Description Send a PASS THROUGH command to the peer device. This 418** function can only be called for controller role connections. 419** Any response message from the peer is passed back through 420** the tAVRC_MSG_CBACK callback function. 421** 422** Input Parameters: 423** handle: Handle of this connection. 424** 425** label: Transaction label. 426** 427** p_msg: Pointer to PASS THROUGH message structure. 428** 429** Output Parameters: 430** None. 431** 432** Returns AVRC_SUCCESS if successful. 433** AVRC_BAD_HANDLE if handle is invalid. 434** 435******************************************************************************/ 436AVRC_API extern UINT16 AVRC_PassCmd(UINT8 handle, UINT8 label, tAVRC_MSG_PASS *p_msg); 437 438/****************************************************************************** 439** 440** Function AVRC_PassRsp 441** 442** Description Send a PASS THROUGH response to the peer device. This 443** function can only be called for target role connections. 444** This function must be called when a PASS THROUGH command 445** message is received from the peer through the 446** tAVRC_MSG_CBACK callback function. 447** 448** Input Parameters: 449** handle: Handle of this connection. 450** 451** label: Transaction label. Must be the same value as 452** passed with the command message in the callback function. 453** 454** p_msg: Pointer to PASS THROUGH message structure. 455** 456** Output Parameters: 457** None. 458** 459** Returns AVRC_SUCCESS if successful. 460** AVRC_BAD_HANDLE if handle is invalid. 461** 462******************************************************************************/ 463AVRC_API extern UINT16 AVRC_PassRsp(UINT8 handle, UINT8 label, tAVRC_MSG_PASS *p_msg); 464 465 466/****************************************************************************** 467** 468** Function AVRC_VendorCmd 469** 470** Description Send a VENDOR DEPENDENT command to the peer device. This 471** function can only be called for controller role connections. 472** Any response message from the peer is passed back through 473** the tAVRC_MSG_CBACK callback function. 474** 475** Input Parameters: 476** handle: Handle of this connection. 477** 478** label: Transaction label. 479** 480** p_msg: Pointer to VENDOR DEPENDENT message structure. 481** 482** Output Parameters: 483** None. 484** 485** Returns AVRC_SUCCESS if successful. 486** AVRC_BAD_HANDLE if handle is invalid. 487** 488******************************************************************************/ 489AVRC_API extern UINT16 AVRC_VendorCmd(UINT8 handle, UINT8 label, tAVRC_MSG_VENDOR *p_msg); 490 491 492/****************************************************************************** 493** 494** Function AVRC_VendorRsp 495** 496** Description Send a VENDOR DEPENDENT response to the peer device. This 497** function can only be called for target role connections. 498** This function must be called when a VENDOR DEPENDENT 499** command message is received from the peer through the 500** tAVRC_MSG_CBACK callback function. 501** 502** Input Parameters: 503** handle: Handle of this connection. 504** 505** label: Transaction label. Must be the same value as 506** passed with the command message in the callback function. 507** 508** p_msg: Pointer to VENDOR DEPENDENT message structure. 509** 510** Output Parameters: 511** None. 512** 513** Returns AVRC_SUCCESS if successful. 514** AVRC_BAD_HANDLE if handle is invalid. 515** 516******************************************************************************/ 517AVRC_API extern UINT16 AVRC_VendorRsp(UINT8 handle, UINT8 label, tAVRC_MSG_VENDOR *p_msg); 518 519 520/****************************************************************************** 521** 522** Function AVRC_SetTraceLevel 523** 524** Description Sets the trace level for AVRC. If 0xff is passed, the 525** current trace level is returned. 526** 527** Input Parameters: 528** new_level: The level to set the AVRC tracing to: 529** 0xff-returns the current setting. 530** 0-turns off tracing. 531** >= 1-Errors. 532** >= 2-Warnings. 533** >= 3-APIs. 534** >= 4-Events. 535** >= 5-Debug. 536** 537** Returns The new trace level or current trace level if 538** the input parameter is 0xff. 539** 540******************************************************************************/ 541AVRC_API extern UINT8 AVRC_SetTraceLevel (UINT8 new_level); 542 543/******************************************************************************* 544** 545** Function AVRC_Init 546** 547** Description This function is called at stack startup to allocate the 548** control block (if using dynamic memory), and initializes the 549** control block and tracing level. 550** 551** Returns void 552** 553*******************************************************************************/ 554AVRC_API extern void AVRC_Init(void); 555 556/******************************************************************************* 557** 558** Function AVRC_ParsCommand 559** 560** Description This function is used to parse the received command. 561** 562** Returns AVRC_STS_NO_ERROR, if the message in p_data is parsed successfully. 563** Otherwise, the error code defined by AVRCP 1.4 564** 565*******************************************************************************/ 566AVRC_API extern tAVRC_STS AVRC_ParsCommand (tAVRC_MSG *p_msg, tAVRC_COMMAND *p_result, 567 UINT8 *p_buf, UINT16 buf_len); 568 569/******************************************************************************* 570** 571** Function AVRC_ParsResponse 572** 573** Description This function is used to parse the received response. 574** 575** Returns AVRC_STS_NO_ERROR, if the message in p_data is parsed successfully. 576** Otherwise, the error code defined by AVRCP 1.4 577** 578*******************************************************************************/ 579AVRC_API extern tAVRC_STS AVRC_ParsResponse (tAVRC_MSG *p_msg, tAVRC_RESPONSE *p_result, 580 UINT8 *p_buf, UINT16 buf_len); 581 582/******************************************************************************* 583** 584** Function AVRC_BldCommand 585** 586** Description This function builds the given AVRCP command to the given 587** GKI buffer 588** 589** Returns AVRC_STS_NO_ERROR, if the command is built successfully 590** Otherwise, the error code. 591** 592*******************************************************************************/ 593AVRC_API extern tAVRC_STS AVRC_BldCommand( tAVRC_COMMAND *p_cmd, BT_HDR **pp_pkt); 594 595/******************************************************************************* 596** 597** Function AVRC_BldResponse 598** 599** Description This function builds the given AVRCP response to the given 600** GKI buffer 601** 602** Returns AVRC_STS_NO_ERROR, if the response is built successfully 603** Otherwise, the error code. 604** 605*******************************************************************************/ 606AVRC_API extern tAVRC_STS AVRC_BldResponse( UINT8 handle, tAVRC_RESPONSE *p_rsp, BT_HDR **pp_pkt); 607 608/************************************************************************** 609** 610** Function AVRC_IsValidAvcType 611** 612** Description Check if correct AVC type is specified 613** 614** Returns returns TRUE if it is valid 615** 616** 617*******************************************************************************/ 618AVRC_API extern BOOLEAN AVRC_IsValidAvcType(UINT8 pdu_id, UINT8 avc_type); 619 620/******************************************************************************* 621** 622** Function AVRC_IsValidPlayerAttr 623** 624** Description Check if the given attrib value is a valid one 625** 626** 627** Returns returns TRUE if it is valid 628** 629*******************************************************************************/ 630AVRC_API extern BOOLEAN AVRC_IsValidPlayerAttr(UINT8 attr); 631 632#ifdef __cplusplus 633} 634#endif 635 636#endif /* AVRC_API_H */ 637