annotate start/end API

This commit is contained in:
Milanka Ringwald 2015-04-09 14:46:44 +02:00
parent e895ca5748
commit 5e6d58c471
8 changed files with 160 additions and 132 deletions

View File

@ -45,13 +45,6 @@
extern "C" {
#endif
typedef struct le_event {
uint8_t type;
uint16_t handle;
} le_event_t;
typedef void (*gatt_client_callback_t)(le_event_t * event);
typedef enum {
P_READY,
P_W2_SEND_SERVICE_QUERY,
@ -173,6 +166,12 @@ typedef struct gatt_subclient {
gatt_client_callback_t callback;
} gatt_subclient_t;
/* API_START */
typedef struct le_event {
uint8_t type;
uint16_t handle;
} le_event_t;
typedef struct gatt_complete_event{
uint8_t type;
@ -219,7 +218,6 @@ typedef struct le_characteristic_value_event{
} le_characteristic_value_event_t;
typedef struct le_characteristic_descriptor{
// no properties
uint16_t handle;
uint16_t uuid16;
uint8_t uuid128[16];
@ -234,25 +232,25 @@ typedef struct le_characteristic_descriptor_event{
uint8_t * value;
} le_characteristic_descriptor_event_t;
//TODO: define uuid type
typedef void (*gatt_client_callback_t)(le_event_t * event);
// Set up GATT client.
void gatt_client_init();
// Register callback (packet handler) for gatt client. Returns gatt client ID.
// Register callback (packet handler) for GATT client. Returns GATT
// client ID.
uint16_t gatt_client_register_packet_handler (gatt_client_callback_t callback);
// Unregister callback (packet handler) for gatt client.
// Unregister callback (packet handler) for GATT client.
void gatt_client_unregister_packet_handler(uint16_t gatt_client_id);
// MTU is available after the first query has completed.
// If status is equal to BLE_PERIPHERAL_OK, it returns the real value
// otherwise the default value of 23.
// If status is equal to BLE_PERIPHERAL_OK, it returns the real
// value, otherwise the default value of 23.
le_command_status_t gatt_client_get_mtu(uint16_t handle, uint16_t * mtu);
// Returns the GATT client context for the specified handle.
// gatt_client_t * get_gatt_client_context_for_handle(uint16_t con_handle);
// Returns if the gatt client is ready to receive a query. It is used with daemon.
// Returns if the GATT client is ready to receive a query. It is
// used with daemon.
int gatt_client_is_ready(uint16_t handle);
// Discovers all primary services. For each found service, an
@ -387,6 +385,7 @@ le_command_status_t gatt_client_write_long_characteristic_descriptor(uint16_t ga
// GATT_CLIENT_CHARACTERISTICS_CONFIGURATION_INDICATION
// as configuration value.
le_command_status_t gatt_client_write_client_characteristic_configuration(uint16_t gatt_client_id, uint16_t con_handle, le_characteristic_t * characteristic, uint16_t configuration);
/* API_END */
#if defined __cplusplus
}

View File

@ -81,6 +81,7 @@ typedef struct timer {
void (*process)(struct timer *ts); // <-- do processing
} timer_source_t;
/* API_START */
// Set timer based on current time in milliseconds.
void run_loop_set_timer(timer_source_t *a, uint32_t timeout_in_ms);
@ -99,12 +100,10 @@ void run_loop_init(RUN_LOOP_TYPE type);
// Set data source callback.
void run_loop_set_data_source_handler(data_source_t *ds, int (*process)(data_source_t *_ds));
// Add/Remove data source.
void run_loop_add_data_source(data_source_t *dataSource);
int run_loop_remove_data_source(data_source_t *dataSource);
// Execute configured run loop. This function does not return.
void run_loop_execute(void);
@ -116,7 +115,8 @@ uint32_t embedded_ticks_for_ms(uint32_t time_in_ms);
uint32_t embedded_get_ticks(void);
// Queries the current time in ms
uint32_t embedded_get_time_ms(void);
// Allows to update BTstack system ticks based on another already existing clock
// Allows to update BTstack system ticks based on another already
// existing clock.
void embedded_set_ticks(uint32_t ticks);
#endif
#ifdef EMBEDDED
@ -125,10 +125,13 @@ void embedded_set_ticks(uint32_t ticks);
// handler of a data source to signal the run loop that a new data
// is available.
void embedded_trigger(void);
// Execute run_loop once
// can be used to integrate BTstack's timer and data source processing into a foreign run runloop (not recommended)
// Execute run_loop once. It can be used to integrate BTstack's
// timer and data source processing into a foreign run runloop
// (it is not recommended).
void embedded_execute_once(void);
#endif
/* API_END */
#if defined __cplusplus
}
#endif

View File

@ -672,43 +672,22 @@ typedef struct {
*/
void hci_connections_get_iterator(linked_list_iterator_t *it);
le_connection_parameter_range_t gap_le_get_connection_parameter_range();
void gap_le_set_connection_parameter_range(le_connection_parameter_range_t range);
// *************** le client start
le_command_status_t le_central_start_scan(void);
le_command_status_t le_central_stop_scan(void);
le_command_status_t le_central_connect(bd_addr_t addr, bd_addr_type_t addr_type);
le_command_status_t le_central_connect_cancel(void);
le_command_status_t gap_disconnect(hci_con_handle_t handle);
void le_central_set_scan_parameters(uint8_t scan_type, uint16_t scan_interval, uint16_t scan_window);
// *************** le client end
// create and send hci command packets based on a template and a list of parameters
uint16_t hci_create_cmd(uint8_t *hci_cmd_buffer, hci_cmd_t *cmd, ...);
uint16_t hci_create_cmd_internal(uint8_t *hci_cmd_buffer, const hci_cmd_t *cmd, va_list argptr);
void hci_connectable_control(uint8_t enable);
void hci_close(void);
/**
* run the hci control loop once
*/
void hci_run(void);
// send complete CMD packet
int hci_send_cmd_packet(uint8_t *packet, int size);
// send ACL packet prepared in hci packet buffer
int hci_send_acl_packet_buffer(int size);
// send SCO packet prepared in hci packet buffer
int hci_send_sco_packet_buffer(int size);
// new functions replacing hci_can_send_packet_now[_using_packet_buffer]
int hci_can_send_command_packet_now(void);
int hci_can_send_acl_packet_now(hci_con_handle_t con_handle);
int hci_can_send_prepared_acl_packet_now(hci_con_handle_t con_handle);
int hci_can_send_sco_packet_now(hci_con_handle_t con_handle);
@ -723,13 +702,11 @@ int hci_is_packet_buffer_reserved(void);
// get point to packet buffer
uint8_t* hci_get_outgoing_packet_buffer(void);
// gets local address
void hci_local_bd_addr(bd_addr_t address_buffer);
hci_connection_t * hci_connection_for_handle(hci_con_handle_t con_handle);
hci_connection_t * hci_connection_for_bd_addr_and_type(bd_addr_t addr, bd_addr_type_t addr_type);
int hci_is_le_connection(hci_connection_t * connection);
int hci_is_le_connection(hci_connection_t * connection);
uint8_t hci_number_outgoing_packets(hci_con_handle_t handle);
uint8_t hci_number_free_acl_slots_for_handle(hci_con_handle_t con_handle);
int hci_authentication_active_for_handle(hci_con_handle_t handle);
@ -753,7 +730,6 @@ void hci_emit_discoverable_enabled(uint8_t enabled);
void hci_emit_security_level(hci_con_handle_t con_handle, gap_security_level_t level);
void hci_emit_dedicated_bonding_result(bd_addr_t address, uint8_t status);
// query if remote side supports SSP
// query if the local side supports SSP
int hci_local_ssp_activated(void);
@ -769,15 +745,44 @@ void hci_disable_l2cap_timeout_check(void);
// disconnect because of security block
void hci_disconnect_security_block(hci_con_handle_t con_handle);
/** Embedded API **/
// send complete CMD packet
int hci_send_cmd_packet(uint8_t *packet, int size);
// Set up HCI. Needs to be called before any other function
/* API_START */
le_connection_parameter_range_t gap_le_get_connection_parameter_range();
void gap_le_set_connection_parameter_range(le_connection_parameter_range_t range);
/* LE Client Start */
le_command_status_t le_central_start_scan(void);
le_command_status_t le_central_stop_scan(void);
le_command_status_t le_central_connect(bd_addr_t addr, bd_addr_type_t addr_type);
le_command_status_t le_central_connect_cancel(void);
le_command_status_t gap_disconnect(hci_con_handle_t handle);
void le_central_set_scan_parameters(uint8_t scan_type, uint16_t scan_interval, uint16_t scan_window);
/* LE Client End */
void hci_connectable_control(uint8_t enable);
void hci_close(void);
// new functions replacing:
// hci_can_send_packet_now[_using_packet_buffer]
int hci_can_send_command_packet_now(void);
// gets local address
void hci_local_bd_addr(bd_addr_t address_buffer);
// Set up HCI. Needs to be called before any other function.
void hci_init(hci_transport_t *transport, void *config, bt_control_t *control, remote_device_db_t const* remote_device_db);
// Set class of device that will be set during Bluetooth init
// Set class of device that will be set during Bluetooth init.
void hci_set_class_of_device(uint32_t class_of_device);
// Set Public BD ADDR - passed on to Bluetooth chipset if supported in bt_control_h
// Set Public BD ADDR - passed on to Bluetooth chipset if supported
// in bt_control_h
void hci_set_bd_addr(bd_addr_t addr);
// Registers a packet handler. Used if L2CAP is not used (rarely).
@ -797,21 +802,23 @@ int hci_send_cmd(const hci_cmd_t *cmd, ...);
// Deletes link key for remote device with baseband address.
void hci_drop_link_key_for_bd_addr(bd_addr_t addr);
// Configure Secure Simple Pairing
/* Configure Secure Simple Pairing */
// enable will enable SSP during init
// Enable will enable SSP during init.
void hci_ssp_set_enable(int enable);
// if set, BTstack will respond to io capability request using authentication requirement
// If set, BTstack will respond to io capability request using
// authentication requirement.
void hci_ssp_set_io_capability(int ssp_io_capability);
void hci_ssp_set_authentication_requirement(int authentication_requirement);
// if set, BTstack will confirm a numberic comparion and enter '000000' if requested
// If set, BTstack will confirm a numberic comparion and enter
// '000000' if requested.
void hci_ssp_set_auto_accept(int auto_accept);
// get addr type and address used in advertisement packets
// Get addr type and address used in advertisement packets.
void hci_le_advertisement_address(uint8_t * addr_type, bd_addr_t addr);
/* API_END */
#if defined __cplusplus
}

View File

@ -202,69 +202,76 @@ typedef struct l2cap_signaling_response {
void l2cap_block_new_credits(uint8_t blocked);
int l2cap_can_send_packet_now(uint16_t local_cid); // non-blocking UART write
int l2cap_can_send_fixed_channel_packet_now(uint16_t handle);
// @deprecated use l2cap_can_send_fixed_channel_packet_now instead
int l2cap_can_send_connectionless_packet_now(void);
int l2cap_reserve_packet_buffer(void);
void l2cap_release_packet_buffer(void);
// get outgoing buffer and prepare data
uint8_t *l2cap_get_outgoing_buffer(void);
int l2cap_send_prepared(uint16_t local_cid, uint16_t len);
int l2cap_send_prepared_connectionless(uint16_t handle, uint16_t cid, uint16_t len);
// Bluetooth 4.0 - allows to register handler for Attribute Protocol and Security Manager Protocol
void l2cap_register_fixed_channel(btstack_packet_handler_t packet_handler, uint16_t channel_id);
uint16_t l2cap_max_mtu(void);
uint16_t l2cap_max_le_mtu(void);
int l2cap_send_connectionless(uint16_t handle, uint16_t cid, uint8_t *data, uint16_t len);
int l2cap_send_echo_request(uint16_t handle, uint8_t *data, uint16_t len);
void l2cap_require_security_level_2_for_outgoing_sdp(void); // testing
void l2cap_require_security_level_2_for_outgoing_sdp(void); // for PTS testing only
/** Embedded API **/
/* API_START */
// Set up L2CAP and register L2CAP with HCI layer.
void l2cap_init(void);
// Registers a packet handler that handles HCI and general BTstack events.
// Registers a packet handler that handles HCI and general BTstack
// events.
void l2cap_register_packet_handler(void (*handler)(void * connection, uint8_t packet_type, uint16_t channel, uint8_t *packet, uint16_t size));
// Creates L2CAP channel to the PSM of a remote device with baseband address. A new baseband connection will be initiated if necessary.
// Creates L2CAP channel to the PSM of a remote device with baseband
// address. A new baseband connection will be initiated if necessary.
void l2cap_create_channel_internal(void * connection, btstack_packet_handler_t packet_handler, bd_addr_t address, uint16_t psm, uint16_t mtu);
// Disconencts L2CAP channel with given identifier.
void l2cap_disconnect_internal(uint16_t local_cid, uint8_t reason);
// Queries the maximal transfer unit (MTU) for L2CAP channel with given identifier.
// Queries the maximal transfer unit (MTU) for L2CAP channel with
// given identifier.
uint16_t l2cap_get_remote_mtu_for_local_cid(uint16_t local_cid);
// Sends L2CAP data packet to the channel with given identifier.
int l2cap_send_internal(uint16_t local_cid, uint8_t *data, uint16_t len);
// Registers L2CAP service with given PSM and MTU, and assigns a packet handler. On embedded systems, use NULL for connection parameter.
// Registers L2CAP service with given PSM and MTU, and assigns a
// packet handler. On embedded systems, use NULL for connection
// parameter.
void l2cap_register_service_internal(void *connection, btstack_packet_handler_t packet_handler, uint16_t psm, uint16_t mtu, gap_security_level_t security_level);
// Unregisters L2CAP service with given PSM. On embedded systems, use NULL for connection parameter.
// Unregisters L2CAP service with given PSM. On embedded systems,
// use NULL for connection parameter.
void l2cap_unregister_service_internal(void *connection, uint16_t psm);
// Accepts/Deny incoming L2CAP connection.
void l2cap_accept_connection_internal(uint16_t local_cid);
void l2cap_decline_connection_internal(uint16_t local_cid, uint8_t reason);
// Request LE connection parameter update
int l2cap_le_request_connection_parameter_update(uint16_t handle, uint16_t interval_min, uint16_t interval_max, uint16_t slave_latency, uint16_t timeout_multiplier);
// Non-blocking UART write
int l2cap_can_send_packet_now(uint16_t local_cid);
int l2cap_reserve_packet_buffer(void);
void l2cap_release_packet_buffer(void);
// Get outgoing buffer and prepare data.
uint8_t *l2cap_get_outgoing_buffer(void);
int l2cap_send_prepared(uint16_t local_cid, uint16_t len);
int l2cap_send_prepared_connectionless(uint16_t handle, uint16_t cid, uint16_t len);
// Bluetooth 4.0 - allows to register handler for Attribute Protocol
// and Security Manager Protocol
void l2cap_register_fixed_channel(btstack_packet_handler_t packet_handler, uint16_t channel_id);
uint16_t l2cap_max_mtu(void);
uint16_t l2cap_max_le_mtu(void);
int l2cap_send_connectionless(uint16_t handle, uint16_t cid, uint8_t *data, uint16_t len);
/* API_END */
#if defined __cplusplus
}
#endif

View File

@ -365,35 +365,45 @@ typedef struct {
void rfcomm_packet_handler(uint8_t packet_type, uint16_t channel, uint8_t *packet, uint16_t size);
/** Embedded API **/
/* API_START */
// Set up RFCOMM.
void rfcomm_init(void);
// Set security level required for incoming connections, need to be called before registering services
// Set security level required for incoming connections, need to be
// called before registering services.
void rfcomm_set_required_security_level(gap_security_level_t security_level);
// Register packet handler.
void rfcomm_register_packet_handler(void (*handler)(void * connection, uint8_t packet_type,
uint16_t channel, uint8_t *packet, uint16_t size));
void rfcomm_register_packet_handler(void (*handler)(void * connection, uint8_t packet_type, uint16_t channel, uint8_t *packet, uint16_t size));
// Creates RFCOMM connection (channel) to a given server channel on a remote device with baseband address. A new baseband connection will be initiated if necessary.
// This channel will automatically provide enough credits to the remote side
// Creates RFCOMM connection (channel) to a given server channel on
// a remote device with baseband address. A new baseband connection
// will be initiated if necessary. This channel will automatically
// provide enough credits to the remote side
void rfcomm_create_channel_internal(void * connection, bd_addr_t addr, uint8_t channel);
// Creates RFCOMM connection (channel) to a given server channel on a remote device with baseband address. new baseband connection will be initiated if necessary.
// This channel will use explicit credit management. During channel establishment, an initial amount of credits is provided.
// Creates RFCOMM connection (channel) to a given server channel on
// a remote device with baseband address. new baseband connection
// will be initiated if necessary. This channel will use explicit
// credit management. During channel establishment, an initial
// amount of credits is provided.
void rfcomm_create_channel_with_initial_credits_internal(void * connection, bd_addr_t addr, uint8_t server_channel, uint8_t initial_credits);
// Disconencts RFCOMM channel with given identifier.
void rfcomm_disconnect_internal(uint16_t rfcomm_cid);
// Registers RFCOMM service for a server channel and a maximum frame size, and assigns a packet handler. On embedded systems, use NULL for connection parameter.
// This channel provides automatically enough credits to the remote side.
// Registers RFCOMM service for a server channel and a maximum frame
// size, and assigns a packet handler. On embedded systems, use NULL
// for connection parameter. This channel provides automatically
// enough credits to the remote side.
void rfcomm_register_service_internal(void * connection, uint8_t channel, uint16_t max_frame_size);
// Registers RFCOMM service for a server channel and a maximum frame size, and assigns a packet handler. On embedded systems, use NULL for connection parameter.
// This channel will use explicit credit management. During channel establishment, an initial amount of credits is provided.
// Registers RFCOMM service for a server channel and a maximum frame
// size, and assigns a packet handler. On embedded systems, use NULL
// for connection parameter. This channel will use explicit credit
// management. During channel establishment, an initial amount of
// credits is provided.
void rfcomm_register_service_with_initial_credits_internal(void * connection, uint8_t channel, uint16_t max_frame_size, uint8_t initial_credits);
// Unregister RFCOMM service.
@ -403,13 +413,16 @@ void rfcomm_unregister_service_internal(uint8_t service_channel);
void rfcomm_accept_connection_internal(uint16_t rfcomm_cid);
void rfcomm_decline_connection_internal(uint16_t rfcomm_cid);
// Grant more incoming credits to the remote side for the given RFCOMM channel identifier.
// Grant more incoming credits to the remote side for the given
// RFCOMM channel identifier.
void rfcomm_grant_credits(uint16_t rfcomm_cid, uint8_t credits);
// Checks if RFCOMM can send packet. Returns yes if packet can be sent.
// Checks if RFCOMM can send packet. Returns yes if packet can be
// sent.
int rfcomm_can_send_packet_now(uint16_t rfcomm_cid);
// Sends RFCOMM data packet to the RFCOMM channel with given identifier.
// Sends RFCOMM data packet to the RFCOMM channel with given
// identifier.
int rfcomm_send_internal(uint16_t rfcomm_cid, uint8_t *data, uint16_t len);
// Sends Local Lnie Status, see LINE_STATUS_..
@ -424,12 +437,13 @@ int rfcomm_send_port_configuration(uint16_t rfcomm_cid, rpn_baud_t baud_rate, rp
// Query remote port
int rfcomm_query_port_configuration(uint16_t rfcomm_cid);
// allow to create rfcomm packet in outgoing buffer
// Allow to create rfcomm packet in outgoing buffer.
int rfcomm_reserve_packet_buffer(void);
void rfcomm_release_packet_buffer(void);
uint8_t * rfcomm_get_outgoing_buffer(void);
uint16_t rfcomm_get_max_frame_size(uint16_t rfcomm_cid);
int rfcomm_send_prepared(uint16_t rfcomm_cid, uint16_t len);
/* API_END */
#if defined __cplusplus
}

View File

@ -71,32 +71,21 @@ typedef struct {
uint8_t service_record[1]; // waste 1 byte to allow compilation with older compilers
} service_record_item_t;
void sdp_register_packet_handler(void (*handler)(void * connection, uint8_t packet_type,
uint16_t channel, uint8_t *packet, uint16_t size));
//
int sdp_handle_service_search_request(uint8_t * packet, uint16_t remote_mtu);
int sdp_handle_service_attribute_request(uint8_t * packet, uint16_t remote_mtu);
int sdp_handle_service_search_attribute_request(uint8_t * packet, uint16_t remote_mtu);
#ifndef EMBEDDED
// Register service record internally - this version creates a copy of the record
// precondition: AttributeIDs are in ascending order => ServiceRecordHandle is first attribute if present
// @returns ServiceRecordHandle or 0 if registration failed
uint32_t sdp_register_service_internal(void *connection, uint8_t * service_record);
#endif
//
/** Embedded API **/
/* API_START */
// Set up SDP.
void sdp_init(void);
void sdp_register_packet_handler(void (*handler)(void * connection, uint8_t packet_type, uint16_t channel, uint8_t *packet, uint16_t size));
#ifdef EMBEDDED
// Register service record internally - this version doesn't copy the record therefore it must be forever accessible.
// Register service record internally - this version doesn't copy
// the record therefore it must be forever accessible.
// Preconditions:
// - AttributeIDs are in ascending order;
// - ServiceRecordHandle is first attribute and valid.
@ -104,8 +93,17 @@ void sdp_init(void);
uint32_t sdp_register_service_internal(void *connection, service_record_item_t * record_item);
#endif
#ifndef EMBEDDED
// Register service record internally - this version creates a copy
// of the record precondition: AttributeIDs are in ascending order
// => ServiceRecordHandle is first attribute if present.
// @returns ServiceRecordHandle or 0 if registration failed
uint32_t sdp_register_service_internal(void *connection, uint8_t * service_record);
#endif
// Unregister service record internally.
void sdp_unregister_service_internal(void *connection, uint32_t service_record_handle);
/* API_END */
#if defined __cplusplus
}

View File

@ -50,18 +50,19 @@
extern "C" {
#endif
/* SDP Client */
/* API_START */
/* Queries the SDP service of the remote device given a service search pattern
and a list of attribute IDs. The remote data is handled by the SDP parser. The
SDP parser delivers attribute values and done event via a registered callback. */
// Queries the SDP service of the remote device given a service
// search pattern and a list of attribute IDs. The remote data is
// handled by the SDP parser. The SDP parser delivers attribute
// values and done event via a registered callback.
void sdp_client_query(bd_addr_t remote, uint8_t * des_serviceSearchPattern, uint8_t * des_attributeIDList);
#ifdef HAVE_SDP_EXTRA_QUERIES
void sdp_client_service_attribute_search(bd_addr_t remote, uint32_t search_serviceRecordHandle, uint8_t * des_attributeIDList);
void sdp_client_service_search(bd_addr_t remote, uint8_t * des_serviceSearchPattern);
#endif
/* API_END */
#if defined __cplusplus
}

View File

@ -52,9 +52,7 @@
extern "C" {
#endif
/* SDP Queries */
/* SDP Query for RFCOMM */
/* API_START */
// SDP Query RFCOMM event to deliver channel number and service name
// byte by byte.
@ -64,6 +62,11 @@ typedef struct sdp_query_rfcomm_service_event {
uint8_t * service_name;
} sdp_query_rfcomm_service_event_t;
// Registers a callback to receive RFCOMM service and query complete
// event.
void sdp_query_rfcomm_register_callback(void(*sdp_app_callback)(sdp_query_event_t * event, void * context), void * context);
void sdp_query_rfcomm_deregister_callback();
// Searches SDP records on a remote device for RFCOMM services with
// a given UUID.
@ -72,11 +75,7 @@ void sdp_query_rfcomm_channel_and_name_for_uuid(bd_addr_t remote, uint16_t uuid)
// Searches SDP records on a remote device for RFCOMM services with
// a given service search pattern.
void sdp_query_rfcomm_channel_and_name_for_search_pattern(bd_addr_t remote, uint8_t * des_serviceSearchPattern);
// Registers a callback to receive RFCOMM service and query complete event.
void sdp_query_rfcomm_register_callback(void(*sdp_app_callback)(sdp_query_event_t * event, void * context), void * context);
void sdp_query_rfcomm_deregister_callback();
/* API_END */
#if defined __cplusplus
}