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