xref: /btstack/src/ble/att_db.h (revision 9b31df63510a796c255c9cdd2559d8e594e82df0)
1591423b2SMatthias Ringwald /*
2591423b2SMatthias Ringwald  * Copyright (C) 2014 BlueKitchen GmbH
3591423b2SMatthias Ringwald  *
4591423b2SMatthias Ringwald  * Redistribution and use in source and binary forms, with or without
5591423b2SMatthias Ringwald  * modification, are permitted provided that the following conditions
6591423b2SMatthias Ringwald  * are met:
7591423b2SMatthias Ringwald  *
8591423b2SMatthias Ringwald  * 1. Redistributions of source code must retain the above copyright
9591423b2SMatthias Ringwald  *    notice, this list of conditions and the following disclaimer.
10591423b2SMatthias Ringwald  * 2. Redistributions in binary form must reproduce the above copyright
11591423b2SMatthias Ringwald  *    notice, this list of conditions and the following disclaimer in the
12591423b2SMatthias Ringwald  *    documentation and/or other materials provided with the distribution.
13591423b2SMatthias Ringwald  * 3. Neither the name of the copyright holders nor the names of
14591423b2SMatthias Ringwald  *    contributors may be used to endorse or promote products derived
15591423b2SMatthias Ringwald  *    from this software without specific prior written permission.
16591423b2SMatthias Ringwald  * 4. Any redistribution, use, or modification is done solely for
17591423b2SMatthias Ringwald  *    personal benefit and not for any commercial purpose or for
18591423b2SMatthias Ringwald  *    monetary gain.
19591423b2SMatthias Ringwald  *
20591423b2SMatthias Ringwald  * THIS SOFTWARE IS PROVIDED BY BLUEKITCHEN GMBH AND CONTRIBUTORS
21591423b2SMatthias Ringwald  * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
22591423b2SMatthias Ringwald  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
23591423b2SMatthias Ringwald  * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL MATTHIAS
24591423b2SMatthias Ringwald  * RINGWALD OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
25591423b2SMatthias Ringwald  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
26591423b2SMatthias Ringwald  * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
27591423b2SMatthias Ringwald  * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
28591423b2SMatthias Ringwald  * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
29591423b2SMatthias Ringwald  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
30591423b2SMatthias Ringwald  * THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
31591423b2SMatthias Ringwald  * SUCH DAMAGE.
32591423b2SMatthias Ringwald  *
33591423b2SMatthias Ringwald  * Please inquire about commercial licensing options at
34591423b2SMatthias Ringwald  * [email protected]
35591423b2SMatthias Ringwald  *
36591423b2SMatthias Ringwald  */
37591423b2SMatthias Ringwald 
38591423b2SMatthias Ringwald 
39591423b2SMatthias Ringwald #ifndef __ATT_H
40591423b2SMatthias Ringwald #define __ATT_H
41591423b2SMatthias Ringwald 
42591423b2SMatthias Ringwald #include <stdint.h>
43711e6c80SMatthias Ringwald #include "bluetooth.h"
448ac574d6SMatthias Ringwald #include "btstack_linked_list.h"
45591423b2SMatthias Ringwald 
46591423b2SMatthias Ringwald #if defined __cplusplus
47591423b2SMatthias Ringwald extern "C" {
48591423b2SMatthias Ringwald #endif
49591423b2SMatthias Ringwald 
50591423b2SMatthias Ringwald // custom BTstack error codes
51591423b2SMatthias Ringwald #define ATT_ERROR_HCI_DISCONNECT_RECEIVED          0x1f
52591423b2SMatthias Ringwald 
538ac574d6SMatthias Ringwald // custom BTstack ATT error codes
54591423b2SMatthias Ringwald #define ATT_ERROR_DATA_MISMATCH                    0x7e
55591423b2SMatthias Ringwald #define ATT_ERROR_TIMEOUT                          0x7F
56591423b2SMatthias Ringwald 
57591423b2SMatthias Ringwald typedef struct att_connection {
58711e6c80SMatthias Ringwald     hci_con_handle_t con_handle;
59591423b2SMatthias Ringwald     uint16_t mtu;       // initialized to ATT_DEFAULT_MTU (23), negotiated during MTU exchange
60591423b2SMatthias Ringwald     uint16_t max_mtu;   // local maximal L2CAP_MTU, set to l2cap_max_le_mtu()
61591423b2SMatthias Ringwald     uint8_t  encryption_key_size;
62591423b2SMatthias Ringwald     uint8_t  authenticated;
63591423b2SMatthias Ringwald     uint8_t  authorized;
64591423b2SMatthias Ringwald } att_connection_t;
65591423b2SMatthias Ringwald 
66591423b2SMatthias Ringwald // ATT Client Read Callback for Dynamic Data
67591423b2SMatthias Ringwald // - if buffer == NULL, don't copy data, just return size of value
68591423b2SMatthias Ringwald // - if buffer != NULL, copy data and return number bytes copied
69591423b2SMatthias Ringwald // @param con_handle of hci le connection
70591423b2SMatthias Ringwald // @param attribute_handle to be read
71591423b2SMatthias Ringwald // @param offset defines start of attribute value
72591423b2SMatthias Ringwald // @param buffer
73591423b2SMatthias Ringwald // @param buffer_size
74711e6c80SMatthias Ringwald typedef uint16_t (*att_read_callback_t)(hci_con_handle_t con_handle, uint16_t attribute_handle, uint16_t offset, uint8_t * buffer, uint16_t buffer_size);
75591423b2SMatthias Ringwald 
76591423b2SMatthias Ringwald // ATT Client Write Callback for Dynamic Data
77591423b2SMatthias Ringwald // @param con_handle of hci le connection
78591423b2SMatthias Ringwald // @param attribute_handle to be written
79*9b31df63SMatthias Ringwald // @param transaction - ATT_TRANSACTION_MODE_NONE for regular writes. For prepared writes: ATT_TRANSACTION_MODE_ACTIVE, ATT_TRANSACTION_MODE_VALIDATE, ATT_TRANSACTION_MODE_EXECUTE, ATT_TRANSACTION_MODE_CANCEL
80591423b2SMatthias Ringwald // @param offset into the value - used for queued writes and long attributes
81591423b2SMatthias Ringwald // @param buffer
82591423b2SMatthias Ringwald // @param buffer_size
83591423b2SMatthias Ringwald // @param signature used for signed write commmands
84591423b2SMatthias Ringwald // @returns 0 if write was ok, ATT_ERROR_PREPARE_QUEUE_FULL if no space in queue, ATT_ERROR_INVALID_OFFSET if offset is larger than max buffer
85*9b31df63SMatthias Ringwald //
86*9b31df63SMatthias Ringwald // Each Prepared Write Request triggers a callback with transaction mode ATT_TRANSACTION_MODE_ACTIVE.
87*9b31df63SMatthias Ringwald // On Execute Write, the callback will be called with ATT_TRANSACTION_MODE_VALIDATE and allows to validate all queued writes and return an application error.
88*9b31df63SMatthias Ringwald // If none of the registered callbacks return an error for ATT_TRANSACTION_MODE_VALIDATE and the callback will be called with ATT_TRANSACTION_MODE_EXECUTE.
89*9b31df63SMatthias Ringwald // Otherwise, all callbacks will be called with ATT_TRANSACTION_MODE_CANCEL.
90*9b31df63SMatthias Ringwald //
91*9b31df63SMatthias Ringwald // If the additional validation step is not needed, just return 0 for all callbacks with transaction mode ATT_TRANSACTION_MODE_VALIDATE.
92*9b31df63SMatthias Ringwald //
93711e6c80SMatthias Ringwald typedef int (*att_write_callback_t)(hci_con_handle_t con_handle, uint16_t attribute_handle, uint16_t transaction_mode, uint16_t offset, uint8_t *buffer, uint16_t buffer_size);
94591423b2SMatthias Ringwald 
958ac574d6SMatthias Ringwald // Read & Write Callbacks for handle range
968ac574d6SMatthias Ringwald typedef struct att_service_handler {
978ac574d6SMatthias Ringwald   btstack_linked_item_t * item;
988ac574d6SMatthias Ringwald   uint16_t start_handle;
998ac574d6SMatthias Ringwald   uint16_t end_handle;
1008ac574d6SMatthias Ringwald   att_read_callback_t read_callback;
1018ac574d6SMatthias Ringwald   att_write_callback_t write_callback;
1028ac574d6SMatthias Ringwald } att_service_handler_t;
1038ac574d6SMatthias Ringwald 
104591423b2SMatthias Ringwald // MARK: ATT Operations
105591423b2SMatthias Ringwald 
106591423b2SMatthias Ringwald /*
107591423b2SMatthias Ringwald  * @brief setup ATT database
108591423b2SMatthias Ringwald  */
109591423b2SMatthias Ringwald void att_set_db(uint8_t const * db);
110591423b2SMatthias Ringwald 
111591423b2SMatthias Ringwald /*
112591423b2SMatthias Ringwald  * @brief set callback for read of dynamic attributes
113591423b2SMatthias Ringwald  * @param callback
114591423b2SMatthias Ringwald  */
115591423b2SMatthias Ringwald void att_set_read_callback(att_read_callback_t callback);
116591423b2SMatthias Ringwald 
117591423b2SMatthias Ringwald /*
118591423b2SMatthias Ringwald  * @brief set callback for write of dynamic attributes
119591423b2SMatthias Ringwald  * @param callback
120591423b2SMatthias Ringwald  */
121591423b2SMatthias Ringwald void att_set_write_callback(att_write_callback_t callback);
122591423b2SMatthias Ringwald 
123591423b2SMatthias Ringwald /*
124591423b2SMatthias Ringwald  * @brief debug helper, dump ATT database to stdout using log_info
125591423b2SMatthias Ringwald  */
126591423b2SMatthias Ringwald void att_dump_attributes(void);
127591423b2SMatthias Ringwald 
128591423b2SMatthias Ringwald /*
129591423b2SMatthias Ringwald  * @brief process ATT request against database and put response into response buffer
130591423b2SMatthias Ringwald  * @param att_connection used for mtu and security properties
131591423b2SMatthias Ringwald  * @param request_buffer, request_len: ATT request from clinet
132591423b2SMatthias Ringwald  * @param response_buffer for result
133591423b2SMatthias Ringwald  * @returns len of data in response buffer. 0 = no response
134591423b2SMatthias Ringwald  */
135591423b2SMatthias Ringwald uint16_t att_handle_request(att_connection_t * att_connection,
136591423b2SMatthias Ringwald                             uint8_t * request_buffer,
137591423b2SMatthias Ringwald                             uint16_t request_len,
138591423b2SMatthias Ringwald                             uint8_t * response_buffer);
139591423b2SMatthias Ringwald 
140591423b2SMatthias Ringwald /*
141591423b2SMatthias Ringwald  * @brief setup value notification in response buffer for a given handle and value
142591423b2SMatthias Ringwald  * @param att_connection
143fc64f94aSMatthias Ringwald  * @param attribute_handle
144fc64f94aSMatthias Ringwald  * @param value
145fc64f94aSMatthias Ringwald  * @param value_len
146591423b2SMatthias Ringwald  * @param response_buffer for notification
147591423b2SMatthias Ringwald  */
148591423b2SMatthias Ringwald uint16_t att_prepare_handle_value_notification(att_connection_t * att_connection,
149fc64f94aSMatthias Ringwald                                                uint16_t attribute_handle,
150591423b2SMatthias Ringwald                                                uint8_t *value,
151591423b2SMatthias Ringwald                                                uint16_t value_len,
152591423b2SMatthias Ringwald                                                uint8_t * response_buffer);
153591423b2SMatthias Ringwald 
154591423b2SMatthias Ringwald /*
155591423b2SMatthias Ringwald  * @brief setup value indication in response buffer for a given handle and value
156591423b2SMatthias Ringwald  * @param att_connection
157fc64f94aSMatthias Ringwald  * @param attribute_handle
158fc64f94aSMatthias Ringwald  * @param value
159fc64f94aSMatthias Ringwald  * @param value_len
160591423b2SMatthias Ringwald  * @param response_buffer for indication
161591423b2SMatthias Ringwald  */
162591423b2SMatthias Ringwald uint16_t att_prepare_handle_value_indication(att_connection_t * att_connection,
163fc64f94aSMatthias Ringwald                                              uint16_t attribute_handle,
164591423b2SMatthias Ringwald                                              uint8_t *value,
165591423b2SMatthias Ringwald                                              uint16_t value_len,
166591423b2SMatthias Ringwald                                              uint8_t * response_buffer);
167591423b2SMatthias Ringwald 
168591423b2SMatthias Ringwald /*
169591423b2SMatthias Ringwald  * @brief transcation queue of prepared writes, e.g., after disconnect
170591423b2SMatthias Ringwald  */
171591423b2SMatthias Ringwald void att_clear_transaction_queue(att_connection_t * att_connection);
172591423b2SMatthias Ringwald 
1738ac574d6SMatthias Ringwald /**
1748ac574d6SMatthias Ringwald  * @brief register read/write callbacks for specific handle range
1758ac574d6SMatthias Ringwald  * @param att_service_handler_t
1768ac574d6SMatthias Ringwald  */
1778ac574d6SMatthias Ringwald void att_register_service_handler(att_service_handler_t * handler);
1788ac574d6SMatthias Ringwald 
1798ac574d6SMatthias Ringwald 
180591423b2SMatthias Ringwald  // experimental client API
181fc64f94aSMatthias Ringwald uint16_t att_uuid_for_handle(uint16_t attribute_handle);
182591423b2SMatthias Ringwald 
183660ce368SMatthias Ringwald 
184660ce368SMatthias Ringwald // experimental GATT Server API
185660ce368SMatthias Ringwald 
186660ce368SMatthias Ringwald // returns 1 if service found. only primary service.
187660ce368SMatthias Ringwald int gatt_server_get_get_handle_range_for_service_with_uuid16(uint16_t uuid16, uint16_t * start_handle, uint16_t * end_handle);
188660ce368SMatthias Ringwald 
189660ce368SMatthias Ringwald // returns 0 if not found
190660ce368SMatthias Ringwald uint16_t gatt_server_get_value_handle_for_characteristic_with_uuid16(uint16_t start_handle, uint16_t end_handle, uint16_t uuid16);
191660ce368SMatthias Ringwald 
192660ce368SMatthias Ringwald // returns 0 if not found
193660ce368SMatthias Ringwald uint16_t gatt_server_get_client_configuration_handle_for_characteristic_with_uuid16(uint16_t start_handle, uint16_t end_handle, uint16_t uuid16);
194660ce368SMatthias Ringwald 
195591423b2SMatthias Ringwald #if defined __cplusplus
196591423b2SMatthias Ringwald }
197591423b2SMatthias Ringwald #endif
198591423b2SMatthias Ringwald 
199591423b2SMatthias Ringwald #endif // __ATT_H
200