1 /******************************************************************************
2  *
3  *  Copyright 2003-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  *  This interface file contains the interface to the Audio Video Control
22  *  Transport Protocol (AVCTP).
23  *
24  ******************************************************************************/
25 #ifndef AVCT_API_H
26 #define AVCT_API_H
27 
28 #include "bt_target.h"
29 #include "bt_types.h"
30 
31 /*****************************************************************************
32  *  Constants
33  ****************************************************************************/
34 
35 /* API function return value result codes. */
36 #define AVCT_SUCCESS 0      /* Function successful */
37 #define AVCT_NO_RESOURCES 1 /* Not enough resources */
38 #define AVCT_BAD_HANDLE 2   /* Bad handle */
39 #define AVCT_PID_IN_USE 3   /* PID already in use */
40 #define AVCT_NOT_OPEN 4     /* Connection not open */
41 
42 /* PSM for AVCT. */
43 #define AVCT_PSM 0x0017
44 #define AVCT_BR_PSM 0x001B
45 
46 /* Protocol revision numbers */
47 #define AVCT_REV_1_0 0x0100
48 #define AVCT_REV_1_2 0x0102
49 #define AVCT_REV_1_3 0x0103
50 #define AVCT_REV_1_4 0x0104
51 
52 /* the layer_specific settings */
53 #define AVCT_DATA_CTRL 0x0001    /* for the control channel */
54 #define AVCT_DATA_BROWSE 0x0002  /* for the browsing channel */
55 #define AVCT_DATA_PARTIAL 0x0100 /* Only have room for a partial message */
56 
57 /* Per the AVRC spec, minimum MTU for the control channel */
58 #define AVCT_MIN_CONTROL_MTU 48
59 /* Per the AVRC spec, minimum MTU for the browsing channel */
60 #define AVCT_MIN_BROWSE_MTU 335
61 
62 /* Message offset.  The number of bytes needed by the protocol stack for the
63  * protocol headers of an AVCTP message packet.
64 */
65 #define AVCT_MSG_OFFSET 15
66 #define AVCT_BROWSE_OFFSET 17 /* the default offset for browsing channel */
67 
68 /* Connection role. */
69 #define AVCT_INT 0 /* Initiator connection */
70 #define AVCT_ACP 1 /* Acceptor connection */
71 
72 /* Control role. */
73 #define AVCT_TARGET 1  /* target  */
74 #define AVCT_CONTROL 2 /* controller  */
75 #define AVCT_PASSIVE 4 /* If conflict, allow the other side to succeed  */
76 
77 /* Command/Response indicator. */
78 #define AVCT_CMD 0 /* Command message */
79 #define AVCT_RSP 2 /* Response message */
80 #define AVCT_REJ 3 /* Message rejected */
81 
82 /* Control callback events. */
83 #define AVCT_CONNECT_CFM_EVT 0        /* Connection confirm */
84 #define AVCT_CONNECT_IND_EVT 1        /* Connection indication */
85 #define AVCT_DISCONNECT_CFM_EVT 2     /* Disconnect confirm */
86 #define AVCT_DISCONNECT_IND_EVT 3     /* Disconnect indication */
87 #define AVCT_CONG_IND_EVT 4           /* Congestion indication */
88 #define AVCT_UNCONG_IND_EVT 5         /* Uncongestion indication */
89 #define AVCT_BROWSE_CONN_CFM_EVT 6    /* Browse Connection confirm */
90 #define AVCT_BROWSE_CONN_IND_EVT 7    /* Browse Connection indication */
91 #define AVCT_BROWSE_DISCONN_CFM_EVT 8 /* Browse Disconnect confirm */
92 #define AVCT_BROWSE_DISCONN_IND_EVT 9 /* Browse Disconnect indication */
93 #define AVCT_BROWSE_CONG_IND_EVT 10   /* Congestion indication */
94 #define AVCT_BROWSE_UNCONG_IND_EVT 11 /* Uncongestion indication */
95 
96 /* General purpose failure result code for callback events. */
97 #define AVCT_RESULT_FAIL 5
98 
99 /*****************************************************************************
100  *  Type Definitions
101  ****************************************************************************/
102 
103 /* Control callback function. */
104 typedef void(tAVCT_CTRL_CBACK)(uint8_t handle, uint8_t event, uint16_t result,
105                                const RawAddress* peer_addr);
106 
107 /* Message callback function */
108 /* p_pkt->layer_specific is AVCT_DATA_CTRL or AVCT_DATA_BROWSE */
109 typedef void(tAVCT_MSG_CBACK)(uint8_t handle, uint8_t label, uint8_t cr,
110                               BT_HDR* p_pkt);
111 
112 /* Structure used by AVCT_CreateConn. */
113 typedef struct {
114   tAVCT_CTRL_CBACK* p_ctrl_cback; /* Control callback */
115   tAVCT_MSG_CBACK* p_msg_cback;   /* Message callback */
116   uint16_t pid;                   /* Profile ID */
117   uint8_t role;                   /* Initiator/acceptor role */
118   uint8_t control;                /* Control role (Control/Target) */
119 } tAVCT_CC;
120 
121 /*****************************************************************************
122  *  External Function Declarations
123  ****************************************************************************/
124 
125 /*******************************************************************************
126  *
127  * Function         AVCT_Register
128  *
129  * Description      This is the system level registration function for the
130  *                  AVCTP protocol.  This function initializes AVCTP and
131  *                  prepares the protocol stack for its use.  This function
132  *                  must be called once by the system or platform using AVCTP
133  *                  before the other functions of the API an be used.
134  *
135  *
136  * Returns          void
137  *
138  ******************************************************************************/
139 extern void AVCT_Register(uint16_t mtu, uint16_t mtu_br, uint8_t sec_mask);
140 
141 /*******************************************************************************
142  *
143  * Function         AVCT_Deregister
144  *
145  * Description      This function is called to deregister use AVCTP protocol.
146  *                  It is called when AVCTP is no longer being used by any
147  *                  application in the system.  Before this function can be
148  *                  called, all connections must be removed with
149  *                  AVCT_RemoveConn().
150  *
151  *
152  * Returns          void
153  *
154  ******************************************************************************/
155 extern void AVCT_Deregister(void);
156 
157 /*******************************************************************************
158  *
159  * Function         AVCT_CreateConn
160  *
161  * Description      Create an AVCTP connection.  There are two types of
162  *                  connections, initiator and acceptor, as determined by
163  *                  the p_cc->role parameter.  When this function is called to
164  *                  create an initiator connection, an AVCTP connection to
165  *                  the peer device is initiated if one does not already exist.
166  *                  If an acceptor connection is created, the connection waits
167  *                  passively for an incoming AVCTP connection from a peer
168  *                  device.
169  *
170  *
171  * Returns          AVCT_SUCCESS if successful, otherwise error.
172  *
173  ******************************************************************************/
174 extern uint16_t AVCT_CreateConn(uint8_t* p_handle, tAVCT_CC* p_cc,
175                                 const RawAddress& peer_addr);
176 
177 /*******************************************************************************
178  *
179  * Function         AVCT_RemoveConn
180  *
181  * Description      Remove an AVCTP connection.  This function is called when
182  *                  the application is no longer using a connection.  If this
183  *                  is the last connection to a peer the L2CAP channel for AVCTP
184  *                  will be closed.
185  *
186  *
187  * Returns          AVCT_SUCCESS if successful, otherwise error.
188  *
189  ******************************************************************************/
190 extern uint16_t AVCT_RemoveConn(uint8_t handle);
191 
192 /*******************************************************************************
193  *
194  * Function         AVCT_CreateBrowse
195  *
196  * Description      Create an AVCTP connection.  There are two types of
197  *                  connections, initiator and acceptor, as determined by
198  *                  the p_cc->role parameter.  When this function is called to
199  *                  create an initiator connection, an AVCTP connection to
200  *                  the peer device is initiated if one does not already exist.
201  *                  If an acceptor connection is created, the connection waits
202  *                  passively for an incoming AVCTP connection from a peer
203  *                  device.
204  *
205  *
206  * Returns          AVCT_SUCCESS if successful, otherwise error.
207  *
208  ******************************************************************************/
209 extern uint16_t AVCT_CreateBrowse(uint8_t handle, uint8_t role);
210 
211 /*******************************************************************************
212  *
213  * Function         AVCT_RemoveBrowse
214  *
215  * Description      Remove an AVCTP connection.  This function is called when
216  *                  the application is no longer using a connection.  If this
217  *                  is the last connection to a peer the L2CAP channel for AVCTP
218  *                  will be closed.
219  *
220  *
221  * Returns          AVCT_SUCCESS if successful, otherwise error.
222  *
223  ******************************************************************************/
224 extern uint16_t AVCT_RemoveBrowse(uint8_t handle);
225 
226 /*******************************************************************************
227  *
228  * Function         AVCT_GetBrowseMtu
229  *
230  * Description      Get the peer_mtu for the AVCTP Browse channel of the given
231  *                  connection.
232  *
233  * Returns          the peer browsing channel MTU.
234  *
235  ******************************************************************************/
236 extern uint16_t AVCT_GetBrowseMtu(uint8_t handle);
237 
238 /*******************************************************************************
239  *
240  * Function         AVCT_GetPeerMtu
241  *
242  * Description      Get the peer_mtu for the AVCTP channel of the given
243  *                  connection.
244  *
245  * Returns          the peer MTU size.
246  *
247  ******************************************************************************/
248 extern uint16_t AVCT_GetPeerMtu(uint8_t handle);
249 
250 /*******************************************************************************
251  *
252  * Function         AVCT_MsgReq
253  *
254  * Description      Send an AVCTP message to a peer device.  In calling
255  *                  AVCT_MsgReq(), the application should keep track of the
256  *                  congestion state of AVCTP as communicated with events
257  *                  AVCT_CONG_IND_EVT and AVCT_UNCONG_IND_EVT.   If the
258  *                  application calls AVCT_MsgReq() when AVCTP is congested
259  *                  the message may be discarded.  The application may make its
260  *                  first call to AVCT_MsgReq() after it receives an
261  *                  AVCT_CONNECT_CFM_EVT or AVCT_CONNECT_IND_EVT on control
262  *                  channel or
263  *                  AVCT_BROWSE_CONN_CFM_EVT or AVCT_BROWSE_CONN_IND_EVT on
264  *                  browsing channel.
265  *
266  *                  p_msg->layer_specific must be set to
267  *                  AVCT_DATA_CTRL for control channel traffic;
268  *                  AVCT_DATA_BROWSE for for browse channel traffic.
269  *
270  * Returns          AVCT_SUCCESS if successful, otherwise error.
271  *
272  ******************************************************************************/
273 extern uint16_t AVCT_MsgReq(uint8_t handle, uint8_t label, uint8_t cr,
274                             BT_HDR* p_msg);
275 
276 #endif /* AVCT_API_H */
277