PBAP Client API
src/classic/pbap_client.h
/**
* Setup PhoneBook Access Client
*/
void pbap_client_init(void);
/**
* @brief Create PBAP connection to a Phone Book Server (PSE) server on a remote device.
* If the server requires authentication, a PBAP_SUBEVENT_AUTHENTICATION_REQUEST is emitted, which
* can be answered with pbap_authentication_password(..).
* The status of PBAP connection establishment is reported via PBAP_SUBEVENT_CONNECTION_OPENED event,
* i.e. on success status field is set to ERROR_CODE_SUCCESS.
*
* @param handler
* @param addr
* @param out_cid to use for further commands
* @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_MEMORY_ALLOC_FAILED if PBAP or GOEP connection already exists.
*/
uint8_t pbap_connect(btstack_packet_handler_t handler, bd_addr_t addr, uint16_t * out_cid);
/**
* @brief Provide password for OBEX Authentication after receiving PBAP_SUBEVENT_AUTHENTICATION_REQUEST.
* The status of PBAP connection establishment is reported via PBAP_SUBEVENT_CONNECTION_OPENED event,
* i.e. on success status field is set to ERROR_CODE_SUCCESS.
*
* @param pbap_cid
* @param password (null terminated string) - not copied, needs to stay valid until connection completed
* @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_BUSY if in a wrong state.
*/
uint8_t pbap_authentication_password(uint16_t pbap_cid, const char * password);
/**
* @brief Disconnects PBAP connection with given identifier.
* Event PBAP_SUBEVENT_CONNECTION_CLOSED indicates that PBAP connection is closed.
*
* @param pbap_cid
* @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_BUSY if in a wrong state.
*/
uint8_t pbap_disconnect(uint16_t pbap_cid);
/**
* @brief Set current folder on PSE. The status is reported via PBAP_SUBEVENT_OPERATION_COMPLETED event.
*
* @param pbap_cid
* @param path - note: path is not copied
* @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_BUSY if in a wrong state.
*/
uint8_t pbap_set_phonebook(uint16_t pbap_cid, const char * path);
/**
* @brief Set vCard Selector for get/pull phonebook. No event is emitted.
*
* @param pbap_cid
* @param vcard_selector - combination of PBAP_PROPERTY_MASK_* properties
* @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_BUSY if in a wrong state.
*/
uint8_t pbap_set_vcard_selector(uint16_t pbap_cid, uint32_t vcard_selector);
/**
* @brief Set vCard Selector for get/pull phonebook. No event is emitted.
*
* @param pbap_cid
* @param vcard_selector_operator - PBAP_VCARD_SELECTOR_OPERATOR_OR (default) or PBAP_VCARD_SELECTOR_OPERATOR_AND
* @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_BUSY if in a wrong state.
*/
uint8_t pbap_set_vcard_selector_operator(uint16_t pbap_cid, int vcard_selector_operator);
/**
* @brief Set Property Selector. No event is emitted.
* @param pbap_cid
* @param property_selector - combination of PBAP_PROPERTY_MASK_* properties
* @return
*/
uint8_t pbap_set_property_selector(uint16_t pbap_cid, uint32_t property_selector);
/**
* @brief Get size of phone book from PSE. The result is reported via PBAP_SUBEVENT_PHONEBOOK_SIZE event.
*
* @param pbap_cid
* @param path - note: path is not copied, common path 'telecom/pb.vcf'
* @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_BUSY if in a wrong state.
*/
uint8_t pbap_get_phonebook_size(uint16_t pbap_cid, const char * path);
/**
* @brief Pull phone book from PSE. The result is reported via registered packet handler (see pbap_connect function),
* with packet type set to PBAP_DATA_PACKET. Event PBAP_SUBEVENT_OPERATION_COMPLETED marks the end of the phone book.
*
* @param pbap_cid
* @param path - note: path is not copied, common path 'telecom/pb.vcf'
* @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_BUSY if in a wrong state.
*/
uint8_t pbap_pull_phonebook(uint16_t pbap_cid, const char * path);
/**
* @brief Pull vCard listing. vCard data is emitted via PBAP_SUBEVENT_CARD_RESULT event.
* Event PBAP_SUBEVENT_OPERATION_COMPLETED marks the end of vCard listing.
*
* @param pbap_cid
* @param path
* @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_BUSY if in a wrong state.
*/
uint8_t pbap_pull_vcard_listing(uint16_t pbap_cid, const char * path);
/**
* @brief Pull vCard entry. The result is reported via callback (see pbap_connect function),
* with packet type set to PBAP_DATA_PACKET.
* Event PBAP_SUBEVENT_OPERATION_COMPLETED marks the end of the vCard entry.
*
* @param pbap_cid
* @param path
* @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_BUSY if in a wrong state.
*/
uint8_t pbap_pull_vcard_entry(uint16_t pbap_cid, const char * path);
/**
* @brief Lookup contact(s) by phone number. vCard data is emitted via PBAP_SUBEVENT_CARD_RESULT event.
* Event PBAP_SUBEVENT_OPERATION_COMPLETED marks the end of the lookup.
*
* @param pbap_cid
* @param phone_number
* @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_BUSY if in a wrong state.
*/
uint8_t pbap_lookup_by_number(uint16_t pbap_cid, const char * phone_number);
/**
* @brief Abort current operation. No event is emitted.
*
* @param pbap_cid
* @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_BUSY if in a wrong state.
*/
uint8_t pbap_abort(uint16_t pbap_cid);
/**
* @brief Set flow control mode - default is off. No event is emitted.
* @note When enabled, pbap_next_packet needs to be called after a packet was processed to receive the next one
*
* @param pbap_cid
* @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_BUSY if in a wrong state.
*/
uint8_t pbap_set_flow_control_mode(uint16_t pbap_cid, int enable);
/**
* @brief Trigger next packet from PSE when Flow Control Mode is enabled.
* @param pbap_cid
* @return status ERROR_CODE_SUCCESS on success, otherwise BTSTACK_BUSY if in a wrong state.
*/
uint8_t pbap_next_packet(uint16_t pbap_cid);
/**
* @brief De-Init PBAP Client
*/
void pbap_client_deinit(void);