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 <stdint.h> 52 53 // max len of phone number used for lookup in pbap_lookup_by_number 54 #define PBAP_MAX_PHONE_NUMBER_LEN 32 55 56 // max len of name reported in PBAP_SUBEVENT_CARD_RESULT 57 #define PBAP_MAX_NAME_LEN 32 58 // max len of vcard handle reported in PBAP_SUBEVENT_CARD_RESULT 59 #define PBAP_MAX_HANDLE_LEN 16 60 61 /* API_START */ 62 63 /** 64 * Setup PhoneBook Access Client 65 */ 66 void pbap_client_init(void); 67 68 /** 69 * @brief Create PBAP connection to a Phone Book Server (PSE) server on a remote device. 70 * If the server requires authentication, a PBAP_SUBEVENT_AUTHENTICATION_REQUEST is emitted, which 71 * can be answered with pbap_authentication_password(..). 72 * The status of PBAP connection establishment is reported via PBAP_SUBEVENT_CONNECTION_OPENED event, 73 * i.e. on success status field is set to ERROR_CODE_SUCCESS. 74 * 75 * @param handler 76 * @param addr 77 * @param out_cid to use for further commands 78 * @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_MEMORY_ALLOC_FAILED if PBAP or GOEP connection already exists. 79 */ 80 uint8_t pbap_connect(btstack_packet_handler_t handler, bd_addr_t addr, uint16_t * out_cid); 81 82 /** 83 * @brief Provide password for OBEX Authentication after receiving PBAP_SUBEVENT_AUTHENTICATION_REQUEST. 84 * The status of PBAP connection establishment is reported via PBAP_SUBEVENT_CONNECTION_OPENED event, 85 * i.e. on success status field is set to ERROR_CODE_SUCCESS. 86 * 87 * @param pbap_cid 88 * @param password (null terminated string) - not copied, needs to stay valid until connection completed 89 * @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_BUSY if in a wrong state. 90 */ 91 uint8_t pbap_authentication_password(uint16_t pbap_cid, const char * password); 92 93 /** 94 * @brief Disconnects PBAP connection with given identifier. 95 * Event PBAP_SUBEVENT_CONNECTION_CLOSED indicates that PBAP connection is closed. 96 * 97 * @param pbap_cid 98 * @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_BUSY if in a wrong state. 99 */ 100 uint8_t pbap_disconnect(uint16_t pbap_cid); 101 102 /** 103 * @brief Set current folder on PSE. The status is reported via PBAP_SUBEVENT_OPERATION_COMPLETED event. 104 * 105 * @param pbap_cid 106 * @param path - note: path is not copied 107 * @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_BUSY if in a wrong state. 108 */ 109 uint8_t pbap_set_phonebook(uint16_t pbap_cid, const char * path); 110 111 /** 112 * @brief Set vCard Selector for get/pull phonebook. No event is emitted. 113 * 114 * @param pbap_cid 115 * @param vcard_selector - combination of PBAP_PROPERTY_MASK_* properties 116 * @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_BUSY if in a wrong state. 117 */ 118 uint8_t pbap_set_vcard_selector(uint16_t pbap_cid, uint32_t vcard_selector); 119 120 /** 121 * @brief Set vCard Selector for get/pull phonebook. No event is emitted. 122 * 123 * @param pbap_cid 124 * @param vcard_selector_operator - PBAP_VCARD_SELECTOR_OPERATOR_OR (default) or PBAP_VCARD_SELECTOR_OPERATOR_AND 125 * @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_BUSY if in a wrong state. 126 */ 127 uint8_t pbap_set_vcard_selector_operator(uint16_t pbap_cid, int vcard_selector_operator); 128 129 /** 130 * @brief Set Property Selector. No event is emitted. 131 * @param pbap_cid 132 * @param property_selector - combination of PBAP_PROPERTY_MASK_* properties 133 * @return 134 */ 135 uint8_t pbap_set_property_selector(uint16_t pbap_cid, uint32_t property_selector); 136 137 /** 138 * @brief Set number of items returned by pull phonebook. 139 * @param pbap_cid 140 * @param max_list_count 141 * @return 142 */ 143 uint8_t pbap_set_max_list_count(uint16_t pbap_cid, uint16_t max_list_count); 144 145 /** 146 * @bbrief Set start offset for pull phonebook 147 * @param pbap_cid 148 * @param list_start_offset 149 * @return 150 */ 151 uint8_t pbap_set_list_start_offset(uint16_t pbap_cid, uint16_t list_start_offset); 152 153 /** 154 * @brief Get size of phone book from PSE. The result is reported via PBAP_SUBEVENT_PHONEBOOK_SIZE event. 155 * 156 * @param pbap_cid 157 * @param path - note: path is not copied, common path 'telecom/pb.vcf' 158 * @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_BUSY if in a wrong state. 159 */ 160 uint8_t pbap_get_phonebook_size(uint16_t pbap_cid, const char * path); 161 162 /** 163 * @brief Pull phone book from PSE. The result is reported via registered packet handler (see pbap_connect function), 164 * with packet type set to PBAP_DATA_PACKET. Event PBAP_SUBEVENT_OPERATION_COMPLETED marks the end of the phone book. 165 * 166 * @param pbap_cid 167 * @param path - note: path is not copied, common path 'telecom/pb.vcf' 168 * @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_BUSY if in a wrong state. 169 */ 170 uint8_t pbap_pull_phonebook(uint16_t pbap_cid, const char * path); 171 172 /** 173 * @brief Pull vCard listing. vCard data is emitted via PBAP_SUBEVENT_CARD_RESULT event. 174 * Event PBAP_SUBEVENT_OPERATION_COMPLETED marks the end of vCard listing. 175 * 176 * @param pbap_cid 177 * @param path 178 * @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_BUSY if in a wrong state. 179 */ 180 uint8_t pbap_pull_vcard_listing(uint16_t pbap_cid, const char * path); 181 182 /** 183 * @brief Pull vCard entry. The result is reported via callback (see pbap_connect function), 184 * with packet type set to PBAP_DATA_PACKET. 185 * Event PBAP_SUBEVENT_OPERATION_COMPLETED marks the end of the vCard entry. 186 * 187 * @param pbap_cid 188 * @param path 189 * @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_BUSY if in a wrong state. 190 */ 191 uint8_t pbap_pull_vcard_entry(uint16_t pbap_cid, const char * path); 192 193 /** 194 * @brief Lookup contact(s) by phone number. vCard data is emitted via PBAP_SUBEVENT_CARD_RESULT event. 195 * Event PBAP_SUBEVENT_OPERATION_COMPLETED marks the end of the lookup. 196 * 197 * @param pbap_cid 198 * @param phone_number 199 * @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_BUSY if in a wrong state. 200 */ 201 uint8_t pbap_lookup_by_number(uint16_t pbap_cid, const char * phone_number); 202 203 /** 204 * @brief Abort current operation. No event is emitted. 205 * 206 * @param pbap_cid 207 * @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_BUSY if in a wrong state. 208 */ 209 uint8_t pbap_abort(uint16_t pbap_cid); 210 211 212 /** 213 * @brief Set flow control mode - default is off. No event is emitted. 214 * @note When enabled, pbap_next_packet needs to be called after a packet was processed to receive the next one 215 * 216 * @param pbap_cid 217 * @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_BUSY if in a wrong state. 218 */ 219 uint8_t pbap_set_flow_control_mode(uint16_t pbap_cid, int enable); 220 221 /** 222 * @brief Trigger next packet from PSE when Flow Control Mode is enabled. 223 * @param pbap_cid 224 * @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_BUSY if in a wrong state. 225 */ 226 uint8_t pbap_next_packet(uint16_t pbap_cid); 227 228 /** 229 * @brief De-Init PBAP Client 230 */ 231 void pbap_client_deinit(void); 232 233 /* API_END */ 234 235 #if defined __cplusplus 236 } 237 #endif 238 #endif 239