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 "btstack_config.h" 51 #include "yxml.h" 52 #include <stdint.h> 53 54 // max len of phone number used for lookup in pbap_lookup_by_number 55 #define PBAP_MAX_PHONE_NUMBER_LEN 32 56 57 // max len of name reported in PBAP_SUBEVENT_CARD_RESULT 58 #define PBAP_MAX_NAME_LEN 32 59 // max len of vcard handle reported in PBAP_SUBEVENT_CARD_RESULT 60 #define PBAP_MAX_HANDLE_LEN 16 61 62 63 typedef enum { 64 PBAP_CLIENT_INIT = 0, 65 PBAP_CLIENT_W4_GOEP_CONNECTION, 66 PBAP_CLIENT_W2_SEND_CONNECT_REQUEST, 67 PBAP_CLIENT_W4_CONNECT_RESPONSE, 68 PBAP_CLIENT_W4_USER_AUTHENTICATION, 69 PBAP_CLIENT_W2_SEND_AUTHENTICATED_CONNECT, 70 PBAP_CLIENT_CONNECTED, 71 // 72 PBAP_CLIENT_W2_SEND_DISCONNECT_REQUEST, 73 PBAP_CLIENT_W4_DISCONNECT_RESPONSE, 74 // 75 PBAP_CLIENT_W2_PULL_PHONEBOOK, 76 PBAP_CLIENT_W4_PHONEBOOK, 77 PBAP_CLIENT_W2_SET_PATH_ROOT, 78 PBAP_CLIENT_W4_SET_PATH_ROOT_COMPLETE, 79 PBAP_CLIENT_W2_SET_PATH_ELEMENT, 80 PBAP_CLIENT_W4_SET_PATH_ELEMENT_COMPLETE, 81 PBAP_CLIENT_W2_GET_PHONEBOOK_SIZE, 82 PBAP_CLIENT_W4_GET_PHONEBOOK_SIZE_COMPLETE, 83 // - pull vacard liast 84 PBAP_CLIENT_W2_GET_CARD_LIST, 85 PBAP_CLIENT_W4_GET_CARD_LIST_COMPLETE, 86 // - pull vcard entry 87 PBAP_CLIENT_W2_GET_CARD_ENTRY, 88 PBAP_CLIENT_W4_GET_CARD_ENTRY_COMPLETE, 89 // abort operation 90 PBAP_CLIENT_W4_ABORT_COMPLETE, 91 92 } pbap_client_state_t; 93 94 typedef enum { 95 PBAP_CLIENT_PHONEBOOK_SIZE_PARSER_STATE_W4_TYPE = 0, 96 PBAP_CLIENT_PHONEBOOK_SIZE_PARSER_STATE_W4_LEN, 97 PBAP_CLIENT_PHONEBOOK_SIZE_PARSER_STATE_W4_VALUE, 98 PBAP_CLIENT_PHONEBOOK_SIZE_PARSER_STATE_INVALID, 99 } pbap_client_phonebook_size_parser_state_t; 100 101 typedef struct { 102 // parsing 103 pbap_client_phonebook_size_parser_state_t state; 104 uint8_t type; 105 uint8_t len; 106 uint8_t pos; 107 // data 108 bool have_size; 109 uint8_t size_buffer[2]; 110 } pbap_client_phonebook_size_parser_t; 111 112 typedef struct pbap_client { 113 goep_client_t goep_client; 114 115 pbap_client_state_t state; 116 uint16_t cid; 117 bd_addr_t bd_addr; 118 hci_con_handle_t con_handle; 119 uint8_t incoming; 120 uint16_t goep_cid; 121 btstack_packet_handler_t client_handler; 122 int request_number; 123 const char * current_folder; 124 const char * phone_number; 125 const char * phonebook_path; 126 const char * vcard_name; 127 uint16_t set_path_offset; 128 /* vcard selector / operator */ 129 uint32_t vcard_selector; 130 uint8_t vcard_selector_operator; 131 uint8_t vcard_selector_supported; 132 /* property selector */ 133 uint32_t property_selector; 134 uint16_t list_start_offset; 135 uint16_t max_list_count; 136 /* abort */ 137 uint8_t abort_operation; 138 /* obex parser */ 139 bool obex_parser_waiting_for_response; 140 obex_parser_t obex_parser; 141 uint8_t obex_header_buffer[4]; 142 /* authentication */ 143 obex_auth_parser_t obex_auth_parser; 144 const char * authentication_password; 145 /* xml parser */ 146 yxml_t xml_parser; 147 uint8_t xml_buffer[50]; 148 /* vcard listing parser */ 149 bool parser_card_found; 150 bool parser_name_found; 151 bool parser_handle_found; 152 char parser_name[PBAP_MAX_NAME_LEN]; 153 char parser_handle[PBAP_MAX_HANDLE_LEN]; 154 /* phonebook size */ 155 pbap_client_phonebook_size_parser_t phonebook_size_parser; 156 /* flow control mode */ 157 uint8_t flow_control_enabled; 158 uint8_t flow_next_triggered; 159 bool flow_wait_for_user; 160 /* srm */ 161 obex_srm_t obex_srm; 162 obex_srm_state_t srm_state; 163 } pbap_client_t; 164 165 /* API_START */ 166 167 /** 168 * Setup PhoneBook Access Client 169 */ 170 void pbap_client_init(void); 171 172 /** 173 * @brief Create PBAP connection to a Phone Book Server (PSE) server on a remote device. 174 * If the server requires authentication, a PBAP_SUBEVENT_AUTHENTICATION_REQUEST is emitted, which 175 * can be answered with pbap_authentication_password(..). 176 * The status of PBAP connection establishment is reported via PBAP_SUBEVENT_CONNECTION_OPENED event, 177 * i.e. on success status field is set to ERROR_CODE_SUCCESS. 178 * 179 * @param handler 180 * @param addr 181 * @param out_cid to use for further commands 182 * @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_MEMORY_ALLOC_FAILED if PBAP or GOEP connection already exists. 183 */ 184 uint8_t pbap_connect(btstack_packet_handler_t handler, bd_addr_t addr, uint16_t * out_cid); 185 186 /** 187 * @brief Provide password for OBEX Authentication after receiving PBAP_SUBEVENT_AUTHENTICATION_REQUEST. 188 * The status of PBAP connection establishment is reported via PBAP_SUBEVENT_CONNECTION_OPENED event, 189 * i.e. on success status field is set to ERROR_CODE_SUCCESS. 190 * 191 * @param pbap_cid 192 * @param password (null terminated string) - not copied, needs to stay valid until connection completed 193 * @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_BUSY if in a wrong state. 194 */ 195 uint8_t pbap_authentication_password(uint16_t pbap_cid, const char * password); 196 197 /** 198 * @brief Disconnects PBAP connection with given identifier. 199 * Event PBAP_SUBEVENT_CONNECTION_CLOSED indicates that PBAP connection is closed. 200 * 201 * @param pbap_cid 202 * @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_BUSY if in a wrong state. 203 */ 204 uint8_t pbap_disconnect(uint16_t pbap_cid); 205 206 /** 207 * @brief Set current folder on PSE. The status is reported via PBAP_SUBEVENT_OPERATION_COMPLETED event. 208 * 209 * @param pbap_cid 210 * @param path - note: path is not copied 211 * @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_BUSY if in a wrong state. 212 */ 213 uint8_t pbap_set_phonebook(uint16_t pbap_cid, const char * path); 214 215 /** 216 * @brief Set vCard Selector for get/pull phonebook. No event is emitted. 217 * 218 * @param pbap_cid 219 * @param vcard_selector - combination of PBAP_PROPERTY_MASK_* properties 220 * @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_BUSY if in a wrong state. 221 */ 222 uint8_t pbap_set_vcard_selector(uint16_t pbap_cid, uint32_t vcard_selector); 223 224 /** 225 * @brief Set vCard Selector for get/pull phonebook. No event is emitted. 226 * 227 * @param pbap_cid 228 * @param vcard_selector_operator - PBAP_VCARD_SELECTOR_OPERATOR_OR (default) or PBAP_VCARD_SELECTOR_OPERATOR_AND 229 * @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_BUSY if in a wrong state. 230 */ 231 uint8_t pbap_set_vcard_selector_operator(uint16_t pbap_cid, int vcard_selector_operator); 232 233 /** 234 * @brief Set Property Selector. No event is emitted. 235 * @param pbap_cid 236 * @param property_selector - combination of PBAP_PROPERTY_MASK_* properties 237 * @return 238 */ 239 uint8_t pbap_set_property_selector(uint16_t pbap_cid, uint32_t property_selector); 240 241 /** 242 * @brief Set number of items returned by pull phonebook. 243 * @param pbap_cid 244 * @param max_list_count 245 * @return 246 */ 247 uint8_t pbap_set_max_list_count(uint16_t pbap_cid, uint16_t max_list_count); 248 249 /** 250 * @bbrief Set start offset for pull phonebook 251 * @param pbap_cid 252 * @param list_start_offset 253 * @return 254 */ 255 uint8_t pbap_set_list_start_offset(uint16_t pbap_cid, uint16_t list_start_offset); 256 257 /** 258 * @brief Get size of phone book from PSE. The result is reported via PBAP_SUBEVENT_PHONEBOOK_SIZE event. 259 * 260 * @param pbap_cid 261 * @param path - note: path is not copied, common path 'telecom/pb.vcf' 262 * @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_BUSY if in a wrong state. 263 */ 264 uint8_t pbap_get_phonebook_size(uint16_t pbap_cid, const char * path); 265 266 /** 267 * @brief Pull phone book from PSE. The result is reported via registered packet handler (see pbap_connect function), 268 * with packet type set to PBAP_DATA_PACKET. Event PBAP_SUBEVENT_OPERATION_COMPLETED marks the end of the phone book. 269 * 270 * @param pbap_cid 271 * @param path - note: path is not copied, common path 'telecom/pb.vcf' 272 * @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_BUSY if in a wrong state. 273 */ 274 uint8_t pbap_pull_phonebook(uint16_t pbap_cid, const char * path); 275 276 /** 277 * @brief Pull vCard listing. vCard data is emitted via PBAP_SUBEVENT_CARD_RESULT event. 278 * Event PBAP_SUBEVENT_OPERATION_COMPLETED marks the end of vCard listing. 279 * 280 * @param pbap_cid 281 * @param path 282 * @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_BUSY if in a wrong state. 283 */ 284 uint8_t pbap_pull_vcard_listing(uint16_t pbap_cid, const char * path); 285 286 /** 287 * @brief Pull vCard entry. The result is reported via callback (see pbap_connect function), 288 * with packet type set to PBAP_DATA_PACKET. 289 * Event PBAP_SUBEVENT_OPERATION_COMPLETED marks the end of the vCard entry. 290 * 291 * @param pbap_cid 292 * @param path 293 * @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_BUSY if in a wrong state. 294 */ 295 uint8_t pbap_pull_vcard_entry(uint16_t pbap_cid, const char * path); 296 297 /** 298 * @brief Lookup contact(s) by phone number. vCard data is emitted via PBAP_SUBEVENT_CARD_RESULT event. 299 * Event PBAP_SUBEVENT_OPERATION_COMPLETED marks the end of the lookup. 300 * 301 * @param pbap_cid 302 * @param phone_number 303 * @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_BUSY if in a wrong state. 304 */ 305 uint8_t pbap_lookup_by_number(uint16_t pbap_cid, const char * phone_number); 306 307 /** 308 * @brief Abort current operation. No event is emitted. 309 * 310 * @param pbap_cid 311 * @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_BUSY if in a wrong state. 312 */ 313 uint8_t pbap_abort(uint16_t pbap_cid); 314 315 316 /** 317 * @brief Set flow control mode - default is off. No event is emitted. 318 * @note When enabled, pbap_next_packet needs to be called after a packet was processed to receive the next one 319 * 320 * @param pbap_cid 321 * @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_BUSY if in a wrong state. 322 */ 323 uint8_t pbap_set_flow_control_mode(uint16_t pbap_cid, int enable); 324 325 /** 326 * @brief Trigger next packet from PSE when Flow Control Mode is enabled. 327 * @param pbap_cid 328 * @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_BUSY if in a wrong state. 329 */ 330 uint8_t pbap_next_packet(uint16_t pbap_cid); 331 332 /** 333 * @brief De-Init PBAP Client 334 */ 335 void pbap_client_deinit(void); 336 337 /* API_END */ 338 339 #if defined __cplusplus 340 } 341 #endif 342 #endif 343