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 // PBAP Supported Features 64 65 #define PBAP_SUPPORTED_FEATURES_DOWNLOAD (1<<0) 66 #define PBAP_SUPPORTED_FEATURES_BROWSING (1<<1) 67 #define PBAP_SUPPORTED_FEATURES_DATABASE_IDENTIFIER (1<<2) 68 #define PBAP_SUPPORTED_FEATURES_FOLDER_VERSION_COUNTERS (1<<3) 69 #define PBAP_SUPPORTED_FEATURES_VCARD_SELECTING (1<<4) 70 #define PBAP_SUPPORTED_FEATURES_ENHANCED_MISSED_CALLS (1<<5) 71 #define PBAP_SUPPORTED_FEATURES_X_BT_UCI_VCARD_PROPERTY (1<<6) 72 #define PBAP_SUPPORTED_FEATURES_X_BT_UID_VCARD_PROPERTY (1<<7) 73 #define PBAP_SUPPORTED_FEATURES_CONTACT_REFERENCING (1<<8) 74 #define PBAP_SUPPORTED_FEATURES_DEFAULT_CONTACT_IMAGE_FORMAT (1<<9) 75 76 // PBAP Property Mask - also used for vCardSelector 77 #define PBAP_PROPERTY_MASK_VERSION (1<< 0) // vCard Version 78 #define PBAP_PROPERTY_MASK_FN (1<< 1) // Formatted Name 79 #define PBAP_PROPERTY_MASK_N (1<< 2) // Structured Presentation of Name 80 #define PBAP_PROPERTY_MASK_PHOTO (1<< 3) // Associated Image or Photo 81 #define PBAP_PROPERTY_MASK_BDAY (1<< 4) // Birthday 82 #define PBAP_PROPERTY_MASK_ADR (1<< 5) // Delivery Address 83 #define PBAP_PROPERTY_MASK_LABEL (1<< 6) // Delivery 84 #define PBAP_PROPERTY_MASK_TEL (1<< 7) // Telephone Number 85 #define PBAP_PROPERTY_MASK_EMAIL (1<< 8) // Electronic Mail Address 86 #define PBAP_PROPERTY_MASK_MAILER (1<< 9) // Electronic Mail 87 #define PBAP_PROPERTY_MASK_TZ (1<<10) // Time Zone 88 #define PBAP_PROPERTY_MASK_GEO (1<<11) // Geographic Position 89 #define PBAP_PROPERTY_MASK_TITLE (1<<12) // Job 90 #define PBAP_PROPERTY_MASK_ROLE (1<<13) // Role within the Organization 91 #define PBAP_PROPERTY_MASK_LOGO (1<<14) // Organization Logo 92 #define PBAP_PROPERTY_MASK_AGENT (1<<15) // vCard of Person Representing 93 #define PBAP_PROPERTY_MASK_ORG (1<<16) // Name of Organization 94 #define PBAP_PROPERTY_MASK_NOTE (1<<17) // Comments 95 #define PBAP_PROPERTY_MASK_REV (1<<18) // Revision 96 #define PBAP_PROPERTY_MASK_SOUND (1<<19) // Pronunciation of Name 97 #define PBAP_PROPERTY_MASK_URL (1<<20) // Uniform Resource Locator 98 #define PBAP_PROPERTY_MASK_UID (1<<21) // Unique ID 99 #define PBAP_PROPERTY_MASK_KEY (1<<22) // Public Encryption Key 100 #define PBAP_PROPERTY_MASK_NICKNAME (1<<23) // Nickname 101 #define PBAP_PROPERTY_MASK_CATEGORIES (1<<24) // Categories 102 #define PBAP_PROPERTY_MASK_PROID (1<<25) // Product ID 103 #define PBAP_PROPERTY_MASK_CLASS (1<<26) // Class information 104 #define PBAP_PROPERTY_MASK_SORT_STRING (1<<27) // String used for sorting operations 105 #define PBAP_PROPERTY_MASK_X_IRMC_CALL_DATETIME (1<<28) // Time stamp 106 #define PBAP_PROPERTY_MASK_X_BT_SPEEDDIALKEY (1<<29) // Speed-dial shortcut 107 #define PBAP_PROPERTY_MASK_X_BT_UCI (1<<30) // Uniform Caller Identifier 108 #define PBAP_PROPERTY_MASK_X_BT_UID (1<<31) // Bluetooth Contact Unique Identifier 109 110 // PBAP vCardSelectorOperator 111 #define PBAP_VCARD_SELECTOR_OPERATOR_OR 0 112 #define PBAP_VCARD_SELECTOR_OPERATOR_AND 1 113 114 /** 115 * Setup PhoneBook Access Client 116 */ 117 void pbap_client_init(void); 118 119 /** 120 * @brief Create PBAP connection to a Phone Book Server (PSE) server on a remote device. 121 * If the server requires authentication, a PBAP_SUBEVENT_AUTHENTICATION_REQUEST is emitted, which 122 * can be answered with pbap_authentication_password(..). 123 * The status of PBAP connection establishment is reported via PBAP_SUBEVENT_CONNECTION_OPENED event, 124 * i.e. on success status field is set to ERROR_CODE_SUCCESS. 125 * 126 * @param handler 127 * @param addr 128 * @param out_cid to use for further commands 129 * @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_MEMORY_ALLOC_FAILED if PBAP or GOEP connection already exists. 130 */ 131 uint8_t pbap_connect(btstack_packet_handler_t handler, bd_addr_t addr, uint16_t * out_cid); 132 133 /** 134 * @brief Provide password for OBEX Authentication after receiving PBAP_SUBEVENT_AUTHENTICATION_REQUEST. 135 * The status of PBAP connection establishment is reported via PBAP_SUBEVENT_CONNECTION_OPENED event, 136 * i.e. on success status field is set to ERROR_CODE_SUCCESS. 137 * 138 * @param pbap_cid 139 * @param password (null terminated string) - not copied, needs to stay valid until connection completed 140 * @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_BUSY if in a wrong state. 141 */ 142 uint8_t pbap_authentication_password(uint16_t pbap_cid, const char * password); 143 144 /** 145 * @brief Disconnects PBAP connection with given identifier. 146 * Event PBAP_SUBEVENT_CONNECTION_CLOSED indicates that PBAP connection is closed. 147 * 148 * @param pbap_cid 149 * @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_BUSY if in a wrong state. 150 */ 151 uint8_t pbap_disconnect(uint16_t pbap_cid); 152 153 /** 154 * @brief Set current folder on PSE. The status is reported via PBAP_SUBEVENT_OPERATION_COMPLETED event. 155 * 156 * @param pbap_cid 157 * @param path - note: path is not copied 158 * @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_BUSY if in a wrong state. 159 */ 160 uint8_t pbap_set_phonebook(uint16_t pbap_cid, const char * path); 161 162 /** 163 * @brief Set vCard Selector for get/pull phonebook. No event is emitted. 164 * 165 * @param pbap_cid 166 * @param vcard_selector - combination of PBAP_PROPERTY_MASK_* properties 167 * @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_BUSY if in a wrong state. 168 */ 169 uint8_t pbap_set_vcard_selector(uint16_t pbap_cid, uint32_t vcard_selector); 170 171 /** 172 * @brief Set vCard Selector for get/pull phonebook. No event is emitted. 173 * 174 * @param pbap_cid 175 * @param vcard_selector_operator - PBAP_VCARD_SELECTOR_OPERATOR_OR (default) or PBAP_VCARD_SELECTOR_OPERATOR_AND 176 * @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_BUSY if in a wrong state. 177 */ 178 uint8_t pbap_set_vcard_selector_operator(uint16_t pbap_cid, int vcard_selector_operator); 179 180 /** 181 * @brief Set Property Selector. No event is emitted. 182 * @param pbap_cid 183 * @param property_selector - combination of PBAP_PROPERTY_MASK_* properties 184 * @return 185 */ 186 uint8_t pbap_set_property_selector(uint16_t pbap_cid, uint32_t property_selector); 187 188 /** 189 * @brief Get size of phone book from PSE. The result is reported via PBAP_SUBEVENT_PHONEBOOK_SIZE event. 190 * 191 * @param pbap_cid 192 * @param path - note: path is not copied, common path 'telecom/pb.vcf' 193 * @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_BUSY if in a wrong state. 194 */ 195 uint8_t pbap_get_phonebook_size(uint16_t pbap_cid, const char * path); 196 197 /** 198 * @brief Pull phone book from PSE. The result is reported via registered packet handler (see pbap_connect function), 199 * with packet type set to PBAP_DATA_PACKET. Event PBAP_SUBEVENT_OPERATION_COMPLETED marks the end of the phone book. 200 * 201 * @param pbap_cid 202 * @param path - note: path is not copied, common path 'telecom/pb.vcf' 203 * @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_BUSY if in a wrong state. 204 */ 205 uint8_t pbap_pull_phonebook(uint16_t pbap_cid, const char * path); 206 207 /** 208 * @brief Pull vCard listing. vCard data is emitted via PBAP_SUBEVENT_CARD_RESULT event. 209 * Event PBAP_SUBEVENT_OPERATION_COMPLETED marks the end of vCard listing. 210 * 211 * @param pbap_cid 212 * @param path 213 * @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_BUSY if in a wrong state. 214 */ 215 uint8_t pbap_pull_vcard_listing(uint16_t pbap_cid, const char * path); 216 217 /** 218 * @brief Pull vCard entry. The result is reported via callback (see pbap_connect function), 219 * with packet type set to PBAP_DATA_PACKET. 220 * Event PBAP_SUBEVENT_OPERATION_COMPLETED marks the end of the vCard entry. 221 * 222 * @param pbap_cid 223 * @param path 224 * @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_BUSY if in a wrong state. 225 */ 226 uint8_t pbap_pull_vcard_entry(uint16_t pbap_cid, const char * path); 227 228 /** 229 * @brief Lookup contact(s) by phone number. vCard data is emitted via PBAP_SUBEVENT_CARD_RESULT event. 230 * Event PBAP_SUBEVENT_OPERATION_COMPLETED marks the end of the lookup. 231 * 232 * @param pbap_cid 233 * @param phone_number 234 * @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_BUSY if in a wrong state. 235 */ 236 uint8_t pbap_lookup_by_number(uint16_t pbap_cid, const char * phone_number); 237 238 /** 239 * @brief Abort current operation. No event is emitted. 240 * 241 * @param pbap_cid 242 * @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_BUSY if in a wrong state. 243 */ 244 uint8_t pbap_abort(uint16_t pbap_cid); 245 246 247 /** 248 * @brief Set flow control mode - default is off. No event is emitted. 249 * @note When enabled, pbap_next_packet needs to be called after a packet was processed to receive the next one 250 * 251 * @param pbap_cid 252 * @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_BUSY if in a wrong state. 253 */ 254 uint8_t pbap_set_flow_control_mode(uint16_t pbap_cid, int enable); 255 256 /** 257 * @brief Trigger next packet from PSE when Flow Control Mode is enabled. 258 * @param pbap_cid 259 * @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_BUSY if in a wrong state. 260 */ 261 uint8_t pbap_next_packet(uint16_t pbap_cid); 262 263 /** 264 * @brief De-Init PBAP Client 265 */ 266 void pbap_client_deinit(void); 267 268 /* API_END */ 269 270 #if defined __cplusplus 271 } 272 #endif 273 #endif 274