1/*
2 * Copyright (C) 2021 Huawei Device Co., Ltd.
3 * Licensed under the Apache License, Version 2.0 (the "License");
4 * you may not use this file except in compliance with the License.
5 * You may obtain a copy of the License at
6 *
7 *     http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software
10 * distributed under the License is distributed on an "AS IS" BASIS,
11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 * See the License for the specific language governing permissions and
13 * limitations under the License.
14 */
15/**
16 * @addtogroup Bluetooth
17 * @{
18 *
19 * @brief This file is a part of BTStack.
20 * @since 6.0
21 */
22
23/**
24 * @file avctp.h
25 *
26 * @brief AVCT protocal Interface.
27 *
28 * @since 6.0
29 */
30#ifndef AVCTP_H
31#define AVCTP_H
32
33#include <stdint.h>
34
35#include "btstack.h"
36#include "gap_if.h"
37#include "packet.h"
38
39#ifdef __cplusplus
40extern "C" {
41#endif
42
43/*****************************************************************************
44 *  Constants
45 ****************************************************************************/
46/** PSM for AVCT. */
47#define AVCT_PSM 0x0017
48#define AVCT_BR_PSM 0x001B
49
50/** Protocol Revision Numbers */
51#define AVCT_REV_1_4 0x0104
52
53/** The role to create the connection. */
54#define AVCT_INIT 0  // Initiator
55#define AVCT_ACPT 1  // Acceptor
56#define AVCT_CT 0    // Control Role
57#define AVCT_TG 1    // Target Role
58
59/** The Channel Type */
60#define AVCT_DATA_CTRL 0x01  // The control channel
61#define AVCT_DATA_BR 0x02    // The browse channel
62
63/** The C/R value. */
64#define AVCT_COMMAND 0   // command
65#define AVCT_RESPONSE 1  // response
66
67/** Control channel callback events. */
68typedef enum {
69    AVCT_CONNECT_IND_EVT = 0,    // Connection indication
70    AVCT_CONNECT_CFM_EVT,        // Connection confirm
71    AVCT_DISCONNECT_IND_EVT,     // Disconnect indication
72    AVCT_DISCONNECT_CFM_EVT,     // Disconnect confirm
73    AVCT_CHANNEL_BUSY_EVT,       // Channel is busy on Enhance Mode
74    AVCT_CHANNEL_UNBUSY_EVT,     // Channel is unbusy on Enhance Mode
75    AVCT_BR_CONNECT_IND_EVT,     // Browse Connection indication, Browser auto connect in background,so it's unused.
76    AVCT_BR_CONNECT_CFM_EVT,     // Browse Connection confirm
77    AVCT_BR_DISCONNECT_IND_EVT,  // Browse Disconnect indication
78    AVCT_BR_DISCONNECT_CFM_EVT,  // Browse Disconnect confirm
79    AVCT_BR_CHANNEL_BUSY_EVT,    // Browse Channel is busy on Enhance Mode
80    AVCT_BR_CHANNEL_UNBUSY_EVT,  // Browse Channel is unbusy on Enhance Mode
81} AvctCallbackEvt;
82
83/** API function return value result codes. */
84typedef enum {
85    AVCT_SUCCESS = 0,        // Function Success
86    AVCT_ERR_NO_RESOURCES,   // Not enough resources
87    AVCT_ERR_CONN_BAD,       // Bad channel can't be used
88    AVCT_ERR_CONN_NOT_OPEN,  // Connection not open
89    AVCT_ERR_PID_USED,       // PID already in used
90    AVCT_ERR_PARAM,          // Paramas error
91    AVCT_FAILED,             // Function Failed
92} AvctRet;
93/***********************************************************************************
94 *  Type Definitions
95 ***********************************************************************************/
96/** @brief      HCI Event callback function.
97 * @details     The aim of this primitive is to request an application callback when the selected indication Event
98 *              occurs. Each profile shall register for being called back separately.
99 * @param[in]   connId    Connection channel Id
100 * @param[in]   event     Control link callback events
101 * @param[in]   result    Control link callback result
102 * @param[in]   peerAddr  Peer device address
103 * @reutrn      @c void
104 */
105typedef void (*AvctChannelEventCallback)(
106    uint8_t connId, uint8_t event, uint16_t result, const BtAddr *peerAddr, void *context);
107
108/** @brief      Protocal Message data callback function
109 * @details     This is the callback function used by AVCTP to report received AV control messages.
110 * @param[in]   connId    Connection channel Id
111 * @param[in]   lable     Message lable from app
112 * @param[in]   cr        Command/Response
113 * @param[in]   ch_type   Message come from (AVCT_DATA_CTRL or AVCT_DATA_BROWSE)
114 * @param[in]   pkt       The point of message data
115 * @reutrn      @c void
116 */
117typedef void (*AvctMsgCallback)(uint8_t connId, uint8_t label, uint8_t cr, uint8_t ch_type, Packet *pkt, void *context);
118
119/**
120 * @brief Connect parameter used by avct_connect_req.
121 */
122typedef struct {
123    AvctChannelEventCallback chEvtCallback;  // HCI Event callback
124    AvctMsgCallback msgCallback;             // Message Data callback
125    uint16_t pid;                            // Profile ID
126    uint8_t role;                            // Initiator/Acceptor
127    void *context;                           // context from  app
128} AvctConnectParam;
129
130/***********************************************************************************
131 *  External Function Declarations
132 ***********************************************************************************/
133
134/**
135 * @brief       Function    AVCT_Register
136 *
137 * @details     This is the system level registration function for the AVCTP
138 *              protocol. This function initializes AVCTP protocal and prepares
139 *              the protocol stack for its use.  This function must be called
140 *              once by the system before the other functions of the API can be
141 *              used.
142 *
143 * @param[in]   mtu     Max transcation unit for control.
144 * @param[in]   mtuBr   Max transcation unit for browser.
145 *
146 * @return      @c void
147 *
148 */
149BTSTACK_API void AVCT_Register(uint16_t mtu, uint16_t mtuBr, uint16_t role);
150
151/**
152 *
153 * @brief       Function    AVCT_Deregister
154 *
155 * @details     This function is called to deregister AVCTP protocol.
156 *              It is called when AVCTP is no longer being used by any
157 *              application in the system. All connections must be
158 *              disconned in advance.
159 *
160 * @param[in]   void
161 *
162 * @return      @c void
163 *
164 */
165BTSTACK_API void AVCT_Deregister(void);
166
167/**
168 *
169 * @brief       Function    AVCT_ConnectReq
170 *
171 * @details     This function is called to create an avctp control connection
172 *              session for peer device.
173 *              AVCT.ICS #Table 2/11 3/11 Connect Request.
174 *              AVCT.ICS #Table 3/9 Event register for connection request.
175 *              AVCT Profile #11.2.1 #11.1.
176 *
177 * @param[in]   connParam   The point to the param of the connection request.
178 *                          Such as the Role、Profile ID、Callback func point.
179 * @param[in]   peerAddr    The peer address to be connected.
180 * @param[out]  connId      The point of the connection session handle.
181 *
182 * @return      @c AVCT_SUCCESS Success @c otherwise Error
183 *
184 */
185BTSTACK_API uint16_t AVCT_ConnectReq(uint8_t *connId, const AvctConnectParam *connParam, const BtAddr *peerAddr);
186
187/**
188 *
189 * @brief       Function    AVCT_DisconnectReq
190 *
191 * @details     This function is called to disconnect the avctp control
192 *              connection session. AVCT.ICS #Table 2/12 3/12 Disconnect Request. AVCT.ICS
193 *              #Table 3/10 Event register for disconnection request. AVCT Profile #11.2.2
194 *              #11.2.3 #11.1.
195 *
196 * @param[in]   connId   The id of the connection session to be disconnected.
197 *
198 * @return      @c AVCT_SUCCESS Success @c otherwise Error
199 *
200 */
201BTSTACK_API uint16_t AVCT_DisconnectReq(uint8_t connId);
202
203/**
204 *
205 * @brief       Function    AVCT_SendMsgReq
206 *
207 * @details     This function is called to send an message to the control
208 *              connection session. AVCT.ICS #Table 2/13 3/13 Send Message AVCT.ICS #Table
209 *              3/10 Event register for message  reception. AVCT Profile #11.2.3 #11.2.4
210 *              #11.1
211 *
212 * @param[in]   connId  The id of the connection session which the message is send to.
213 * @param[in]   label   Message label from application.
214 * @param[in]   cr      Command/Tesponse
215 * @param[in]   msg     The point of Message data.
216 *
217 * @return      @c AVCT_SUCCESS Success @c otherwise Error
218 *
219 */
220BTSTACK_API uint16_t AVCT_SendMsgReq(uint8_t connId, uint8_t label, uint8_t cr, const Packet *msg);
221
222/**
223 *
224 * @brief       Function    AVCT_GetMtu
225 *
226 * @details     This function is called to get the mtu of the control connection session.
227 *
228 * @param[in]   connId   The id of the connection session.
229 *
230 * @return      @c MTU
231 *
232 */
233BTSTACK_API uint16_t AVCT_GetPeerMtu(uint8_t connId);
234
235/**
236 *
237 * @brief       Function    AVCT_BrConnectReq
238 *
239 * @details     This function is called to create an avctp browse connection session if the peer device has.
240 *
241 * @param[in]   connId  The control connection session id.
242 * @param[in]   role    The connection session role.
243 *
244 * @return      @c AVCT_SUCCESS Success @c otherwise Error
245 *
246 */
247BTSTACK_API uint16_t AVCT_BrConnectReq(uint8_t connId, uint8_t role);
248
249/**
250 *
251 * @brief       Function    AVCT_BrDisconnectReq
252 *
253 * @details     Remove an AVCTP browse connection session.
254 *
255 * @param[in]   connId      The connection session id.
256 *
257 * @return      @c AVCT_SUCCESS Success @c otherwise Error
258 *
259 */
260BTSTACK_API uint16_t AVCT_BrDisconnectReq(uint8_t connId);
261
262/**
263 *
264 * @brief       Function    AVCT_BrSendMsgReq
265 *
266 * @details     This function is called to send an  message to the browse session.
267 *              AVCT.ICS #Table 2/13 3/13 Send Message.
268 *              AVCT.ICS #Table 3/10 Event register for message reception.
269 *              AVCT Profile #11.2.3 #11.2.4 #11.1.
270 *
271 * @param[in]   connId  The id of the connection session which the message is send to.
272 * @param[in]   label   Message label from application.
273 * @param[in]   cr      Command/Tesponse
274 * @param[in]   msg     Message data point.
275 *
276 * @return      @c AVCT_SUCCESS Success @c otherwise Error
277 *
278 */
279BTSTACK_API uint16_t AVCT_BrSendMsgReq(uint8_t connId, uint8_t label, uint8_t cr, const Packet *msg);
280
281/**
282 *
283 * @brief       Function    AVCT_BrGetMtu
284 *
285 * @details     This function is called to get the mtu of the browse connection session.
286 *
287 * @param[in]   connId   The id of the connection session.
288 *
289 * @return      @c MTU
290 *
291 */
292BTSTACK_API uint16_t AVCT_BrGetPeerMtu(uint8_t connId);
293
294#ifdef __cplusplus
295}
296#endif
297
298#endif /* AVCTP_H */
299