1 /* 2 * Copyright (C) 2014 BlueKitchen GmbH 3 * 4 * Redistribution and use in source and binary forms, with or without 5 * modification, are permitted provided that the following conditions 6 * are met: 7 * 8 * 1. Redistributions of source code must retain the above copyright 9 * notice, this list of conditions and the following disclaimer. 10 * 2. Redistributions in binary form must reproduce the above copyright 11 * notice, this list of conditions and the following disclaimer in the 12 * documentation and/or other materials provided with the distribution. 13 * 3. Neither the name of the copyright holders nor the names of 14 * contributors may be used to endorse or promote products derived 15 * from this software without specific prior written permission. 16 * 4. Any redistribution, use, or modification is done solely for 17 * personal benefit and not for any commercial purpose or for 18 * monetary gain. 19 * 20 * THIS SOFTWARE IS PROVIDED BY BLUEKITCHEN GMBH AND CONTRIBUTORS 21 * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 22 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 23 * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL BLUEKITCHEN 24 * GMBH OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 25 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 26 * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS 27 * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 28 * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 29 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF 30 * THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 31 * SUCH DAMAGE. 32 * 33 * Please inquire about commercial licensing options at 34 * [email protected] 35 * 36 */ 37 38 /** 39 * @title PBAP Client 40 * 41 */ 42 43 #ifndef PBAP_CLIENT_H 44 #define PBAP_CLIENT_H 45 46 #if defined __cplusplus 47 extern "C" { 48 #endif 49 50 #include <stdint.h> 51 52 #include "btstack_config.h" 53 #include "yxml.h" 54 #include "classic/obex_srm_client.h" 55 56 // max len of phone number used for lookup in pbap_lookup_by_number 57 #define PBAP_MAX_PHONE_NUMBER_LEN 32 58 59 // max len of name reported in PBAP_SUBEVENT_CARD_RESULT 60 #define PBAP_MAX_NAME_LEN 32 61 // max len of vcard handle reported in PBAP_SUBEVENT_CARD_RESULT 62 #define PBAP_MAX_HANDLE_LEN 16 63 64 65 typedef enum { 66 PBAP_CLIENT_INIT = 0, 67 PBAP_CLIENT_W4_GOEP_CONNECTION, 68 PBAP_CLIENT_W2_SEND_CONNECT_REQUEST, 69 PBAP_CLIENT_W4_CONNECT_RESPONSE, 70 PBAP_CLIENT_W4_USER_AUTHENTICATION, 71 PBAP_CLIENT_W2_SEND_AUTHENTICATED_CONNECT, 72 PBAP_CLIENT_CONNECTED, 73 // 74 PBAP_CLIENT_W2_SEND_DISCONNECT_REQUEST, 75 PBAP_CLIENT_W4_DISCONNECT_RESPONSE, 76 // 77 PBAP_CLIENT_W2_PULL_PHONEBOOK, 78 PBAP_CLIENT_W4_PHONEBOOK, 79 PBAP_CLIENT_W2_SET_PATH_ROOT, 80 PBAP_CLIENT_W4_SET_PATH_ROOT_COMPLETE, 81 PBAP_CLIENT_W2_SET_PATH_ELEMENT, 82 PBAP_CLIENT_W4_SET_PATH_ELEMENT_COMPLETE, 83 PBAP_CLIENT_W2_GET_PHONEBOOK_SIZE, 84 PBAP_CLIENT_W4_GET_PHONEBOOK_SIZE_COMPLETE, 85 // - pull vacard liast 86 PBAP_CLIENT_W2_GET_CARD_LIST, 87 PBAP_CLIENT_W4_GET_CARD_LIST_COMPLETE, 88 // - pull vcard entry 89 PBAP_CLIENT_W2_GET_CARD_ENTRY, 90 PBAP_CLIENT_W4_GET_CARD_ENTRY_COMPLETE, 91 // abort operation 92 PBAP_CLIENT_W4_ABORT_COMPLETE, 93 94 } pbap_client_state_t; 95 96 typedef enum { 97 PBAP_CLIENT_PHONEBOOK_SIZE_PARSER_STATE_W4_TYPE = 0, 98 PBAP_CLIENT_PHONEBOOK_SIZE_PARSER_STATE_W4_LEN, 99 PBAP_CLIENT_PHONEBOOK_SIZE_PARSER_STATE_W4_VALUE, 100 PBAP_CLIENT_PHONEBOOK_SIZE_PARSER_STATE_INVALID, 101 } pbap_client_phonebook_size_parser_state_t; 102 103 typedef struct { 104 // parsing 105 pbap_client_phonebook_size_parser_state_t state; 106 uint8_t type; 107 uint8_t len; 108 uint8_t pos; 109 // data 110 bool have_size; 111 uint8_t size_buffer[2]; 112 } pbap_client_phonebook_size_parser_t; 113 114 typedef enum { 115 OBEX_AUTH_PARSER_STATE_W4_TYPE = 0, 116 OBEX_AUTH_PARSER_STATE_W4_LEN, 117 OBEX_AUTH_PARSER_STATE_W4_VALUE, 118 OBEX_AUTH_PARSER_STATE_INVALID, 119 } pbap_client_obex_auth_parser_state_t; 120 121 typedef struct { 122 // parsing 123 pbap_client_obex_auth_parser_state_t state; 124 uint8_t type; 125 uint8_t len; 126 uint8_t pos; 127 // data 128 uint8_t authentication_options; 129 uint16_t authentication_nonce[16]; 130 } pbap_client_obex_auth_parser_t; 131 132 typedef struct pbap_client { 133 // pbap client linked list 134 btstack_linked_item_t item; 135 136 // goep client linked list 137 goep_client_t goep_client; 138 139 pbap_client_state_t state; 140 bd_addr_t bd_addr; 141 hci_con_handle_t con_handle; 142 uint16_t goep_cid; 143 btstack_packet_handler_t client_handler; 144 int request_number; 145 const char * current_folder; 146 const char * phone_number; 147 const char * phonebook_path; 148 const char * vcard_name; 149 uint16_t set_path_offset; 150 /* vcard selector / operator */ 151 uint32_t vcard_selector; 152 uint8_t vcard_selector_operator; 153 uint8_t vcard_selector_supported; 154 /* property selector */ 155 uint32_t property_selector; 156 uint16_t list_start_offset; 157 uint16_t max_list_count; 158 uint8_t order; 159 uint8_t search_property; 160 const char * search_value; 161 /* abort */ 162 uint8_t abort_operation; 163 /* obex parser */ 164 bool obex_parser_waiting_for_response; 165 obex_parser_t obex_parser; 166 uint8_t obex_header_buffer[4]; 167 /* authentication */ 168 pbap_client_obex_auth_parser_t obex_auth_parser; 169 const char * authentication_password; 170 /* xml parser */ 171 yxml_t xml_parser; 172 uint8_t xml_buffer[50]; 173 /* vcard listing parser */ 174 bool parser_card_found; 175 bool parser_name_found; 176 bool parser_handle_found; 177 char parser_name[PBAP_MAX_NAME_LEN]; 178 char parser_handle[PBAP_MAX_HANDLE_LEN]; 179 /* phonebook size */ 180 pbap_client_phonebook_size_parser_t phonebook_size_parser; 181 /* flow control mode */ 182 uint8_t flow_control_enabled; 183 uint8_t flow_next_triggered; 184 bool flow_wait_for_user; 185 /* srm */ 186 obex_srm_client_t obex_srm; 187 } pbap_client_t; 188 189 /* API_START */ 190 191 /** 192 * Setup PhoneBook Access Client 193 */ 194 void pbap_client_init(void); 195 196 /** 197 * @brief Create PBAP connection to a Phone Book Server (PSE) server on a remote device. 198 * If the server requires authentication, a PBAP_SUBEVENT_AUTHENTICATION_REQUEST is emitted, which 199 * can be answered with pbap_authentication_password(..). 200 * The status of PBAP connection establishment is reported via PBAP_SUBEVENT_CONNECTION_OPENED event, 201 * i.e. on success status field is set to ERROR_CODE_SUCCESS. 202 * 203 * This function allows for multiple parallel connections. 204 * 205 * @param client storage for connection state. Must stay valid until connection closes 206 * @param l2cap_ertm_config 207 * @param l2cap_ertm_buffer_size 208 * @param l2cap_ertm_buffer 209 * @param handler 210 * @param addr 211 * @param out_cid to use for further commands 212 * @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_MEMORY_ALLOC_FAILED if PBAP or GOEP connection already exists. 213 */ 214 215 uint8_t pbap_client_connect(pbap_client_t * client, l2cap_ertm_config_t *l2cap_ertm_config, uint8_t *l2cap_ertm_buffer, 216 uint16_t l2cap_ertm_buffer_size, btstack_packet_handler_t handler, bd_addr_t addr, uint16_t * out_cid); 217 218 /** 219 * @brief Create PBAP connection to a Phone Book Server (PSE) server on a remote device. 220 * If the server requires authentication, a PBAP_SUBEVENT_AUTHENTICATION_REQUEST is emitted, which 221 * can be answered with pbap_authentication_password(..). 222 * The status of PBAP connection establishment is reported via PBAP_SUBEVENT_CONNECTION_OPENED event, 223 * i.e. on success status field is set to ERROR_CODE_SUCCESS. 224 * 225 * This function uses a single pbap_client_t and l2cap ertm buffer instance and can only be used for a single connection. 226 * Fur multiple parallel connections, use pbap_client_connect. 227 * 228 * @param handler 229 * @param addr 230 * @param out_cid to use for further commands 231 * @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_MEMORY_ALLOC_FAILED if PBAP or GOEP connection already exists. 232 */ 233 uint8_t pbap_connect(btstack_packet_handler_t handler, bd_addr_t addr, uint16_t * out_cid); 234 235 /** 236 * @brief Provide password for OBEX Authentication after receiving PBAP_SUBEVENT_AUTHENTICATION_REQUEST. 237 * The status of PBAP connection establishment is reported via PBAP_SUBEVENT_CONNECTION_OPENED event, 238 * i.e. on success status field is set to ERROR_CODE_SUCCESS. 239 * 240 * @param pbap_cid 241 * @param password (null terminated string) - not copied, needs to stay valid until connection completed 242 * @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_BUSY if in a wrong state. 243 */ 244 uint8_t pbap_authentication_password(uint16_t pbap_cid, const char * password); 245 246 /** 247 * @brief Disconnects PBAP connection with given identifier. 248 * Event PBAP_SUBEVENT_CONNECTION_CLOSED indicates that PBAP connection is closed. 249 * 250 * @param pbap_cid 251 * @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_BUSY if in a wrong state. 252 */ 253 uint8_t pbap_disconnect(uint16_t pbap_cid); 254 255 /** 256 * @brief Set current folder on PSE. The status is reported via PBAP_SUBEVENT_OPERATION_COMPLETED event. 257 * 258 * @param pbap_cid 259 * @param path - note: path is not copied 260 * @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_BUSY if in a wrong state. 261 */ 262 uint8_t pbap_set_phonebook(uint16_t pbap_cid, const char * path); 263 264 /** 265 * @brief Set vCard Selector for get/pull phonebook. No event is emitted. 266 * 267 * @param pbap_cid 268 * @param vcard_selector - combination of PBAP_PROPERTY_MASK_* properties 269 * @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_BUSY if in a wrong state. 270 */ 271 uint8_t pbap_set_vcard_selector(uint16_t pbap_cid, uint32_t vcard_selector); 272 273 /** 274 * @brief Set vCard Selector for get/pull phonebook. No event is emitted. 275 * 276 * @param pbap_cid 277 * @param vcard_selector_operator - PBAP_VCARD_SELECTOR_OPERATOR_OR (default) or PBAP_VCARD_SELECTOR_OPERATOR_AND 278 * @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_BUSY if in a wrong state. 279 */ 280 uint8_t pbap_set_vcard_selector_operator(uint16_t pbap_cid, int vcard_selector_operator); 281 282 /** 283 * @brief Set Property Selector. No event is emitted. 284 * @param pbap_cid 285 * @param property_selector - combination of PBAP_PROPERTY_MASK_* properties 286 * @return 287 */ 288 uint8_t pbap_set_property_selector(uint16_t pbap_cid, uint32_t property_selector); 289 290 /** 291 * @brief Set number of items returned by pull phonebook. 292 * @param pbap_cid 293 * @param max_list_count 294 * @return 295 */ 296 uint8_t pbap_set_max_list_count(uint16_t pbap_cid, uint16_t max_list_count); 297 298 /** 299 * @bbrief Set start offset for pull phonebook 300 * @param pbap_cid 301 * @param list_start_offset 302 * @return 303 */ 304 uint8_t pbap_set_list_start_offset(uint16_t pbap_cid, uint16_t list_start_offset); 305 306 /** 307 * @bbrief Set order for pbap_pull_vcard_listing 308 * @param pbap_cid 309 * @param order 310 * @return 311 */ 312 uint8_t pbap_set_order(uint16_t pbap_cid, uint8_t order); 313 314 /** 315 * @bbrief Set search property for pbap_pull_vcard_listing 316 * @param pbap_cid 317 * @param search_property 318 * @return 319 */ 320 uint8_t pbap_set_search_property(uint16_t pbap_cid, uint8_t search_property); 321 322 /** 323 * @bbrief Set search property for pbap_pull_vcard_listing 324 * @param pbap_cid 325 * @param search_value 326 * @return 327 */ 328 uint8_t pbap_set_search_value(uint16_t pbap_cid, const char * search_value); 329 330 /** 331 * @brief Get size of phone book from PSE. The result is reported via PBAP_SUBEVENT_PHONEBOOK_SIZE event. 332 * 333 * @param pbap_cid 334 * @param path - note: path is not copied, common path 'telecom/pb.vcf' 335 * @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_BUSY if in a wrong state. 336 */ 337 uint8_t pbap_get_phonebook_size(uint16_t pbap_cid, const char * path); 338 339 /** 340 * @brief Pull phone book from PSE. The result is reported via registered packet handler (see pbap_connect function), 341 * with packet type set to PBAP_DATA_PACKET. Event PBAP_SUBEVENT_OPERATION_COMPLETED marks the end of the phone book. 342 * 343 * @param pbap_cid 344 * @param path - note: path is not copied, common path 'telecom/pb.vcf' 345 * @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_BUSY if in a wrong state. 346 */ 347 uint8_t pbap_pull_phonebook(uint16_t pbap_cid, const char * path); 348 349 /** 350 * @brief Pull vCard listing. vCard data is emitted via PBAP_SUBEVENT_CARD_RESULT event. 351 * Event PBAP_SUBEVENT_OPERATION_COMPLETED marks the end of vCard listing. 352 * 353 * @param pbap_cid 354 * @param path 355 * @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_BUSY if in a wrong state. 356 */ 357 uint8_t pbap_pull_vcard_listing(uint16_t pbap_cid, const char * path); 358 359 /** 360 * @brief Pull vCard entry. The result is reported via callback (see pbap_connect function), 361 * with packet type set to PBAP_DATA_PACKET. 362 * Event PBAP_SUBEVENT_OPERATION_COMPLETED marks the end of the vCard entry. 363 * 364 * @param pbap_cid 365 * @param path 366 * @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_BUSY if in a wrong state. 367 */ 368 uint8_t pbap_pull_vcard_entry(uint16_t pbap_cid, const char * path); 369 370 /** 371 * @brief Lookup contact(s) by phone number. vCard data is emitted via PBAP_SUBEVENT_CARD_RESULT event. 372 * Event PBAP_SUBEVENT_OPERATION_COMPLETED marks the end of the lookup. 373 * 374 * @param pbap_cid 375 * @param phone_number 376 * @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_BUSY if in a wrong state. 377 */ 378 uint8_t pbap_lookup_by_number(uint16_t pbap_cid, const char * phone_number); 379 380 /** 381 * @brief Abort current operation. No event is emitted. 382 * 383 * @param pbap_cid 384 * @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_BUSY if in a wrong state. 385 */ 386 uint8_t pbap_abort(uint16_t pbap_cid); 387 388 389 /** 390 * @brief Set flow control mode - default is off. No event is emitted. 391 * @note When enabled, pbap_next_packet needs to be called after a packet was processed to receive the next one 392 * 393 * @param pbap_cid 394 * @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_BUSY if in a wrong state. 395 */ 396 uint8_t pbap_set_flow_control_mode(uint16_t pbap_cid, int enable); 397 398 /** 399 * @brief Trigger next packet from PSE when Flow Control Mode is enabled. 400 * @param pbap_cid 401 * @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_BUSY if in a wrong state. 402 */ 403 uint8_t pbap_next_packet(uint16_t pbap_cid); 404 405 /** 406 * @brief De-Init PBAP Client 407 */ 408 void pbap_client_deinit(void); 409 410 /* API_END */ 411 412 #if defined __cplusplus 413 } 414 #endif 415 #endif 416