espressif/esp-nimble
1
0
Fork 0
mirror of https://github.com/espressif/esp-nimble.git synced 2026-11-04 03:22:46 +00:00
Code Issues Packages Projects Releases Wiki Activity

nimble/gap: Add missing doxygen documentation

Browse Source
This commit is contained in:
Szymon Janc
2019-06-12 14:17:03 +02:00
parent ff1b3f0d40
commit 78cfce4258
1 changed files with 526 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files
nimble/host/include/host/ble_gap.h
+526 -15
View File
@@ -227,43 +227,99 @@ struct ble_gap_conn_desc {
uint8_t master_clock_accuracy;
};
/** @brief Connection parameters */
struct ble_gap_conn_params {
/** Scan interval in 0.625ms units */
uint16_t scan_itvl;
/** Scan window in 0.625ms units */
uint16_t scan_window;
/** Minimum value for connection interval in 1.25ms units */
uint16_t itvl_min;
/** Maximum value for connection interval in 1.25ms units */
uint16_t itvl_max;
/** Connection latency */
uint16_t latency;
/** Supervision timeout in 10ms units */
uint16_t supervision_timeout;
/** Minimum length of connection event in 0.625ms units */
uint16_t min_ce_len;
/** Maximum length of connection event in 0.625ms units */
uint16_t max_ce_len;
};
/** @brief Extended discovery parameters */
struct ble_gap_ext_disc_params {
/** Scan interval in 0.625ms units */
uint16_t itvl;
/** Scan window in 0.625ms units */
uint16_t window;
/** If passive scan should be used */
uint8_t passive:1;
};
/** @brief Discovery parameters */
struct ble_gap_disc_params {
/** Scan interval in 0.625ms units */
uint16_t itvl;
/** Scan window in 0.625ms units */
uint16_t window;
/** Scan filter policy */
uint8_t filter_policy;
/** If limited discovery procedure should be used */
uint8_t limited:1;
/** If passive scan should be used */
uint8_t passive:1;
/** If enable duplicates filtering */
uint8_t filter_duplicates:1;
};
/** @brief Connection parameters update parameters */
struct ble_gap_upd_params {
/** Minimum value for connection interval in 1.25ms units */
uint16_t itvl_min;
/** Maximum value for connection interval in 1.25ms units */
uint16_t itvl_max;
/** Connection latency */
uint16_t latency;
/** Supervision timeout in 10ms units */
uint16_t supervision_timeout;
/** Minimum length of connection event in 0.625ms units */
uint16_t min_ce_len;
/** Maximum length of connection event in 0.625ms units */
uint16_t max_ce_len;
};
/** @brief Passkey query */
struct ble_gap_passkey_params {
/** Passkey action, can be one of following constants:
* - BLE_SM_IOACT_NONE
* - BLE_SM_IOACT_OOB
* - BLE_SM_IOACT_INPUT
* - BLE_SM_IOACT_DISP
* - BLE_SM_IOACT_NUMCMP
*/
uint8_t action;
/** Passkey to compare, valid for BLE_SM_IOACT_NUMCMP action */
uint32_t numcmp;
};
@@ -273,39 +329,100 @@ struct ble_gap_passkey_params {
#define BLE_GAP_EXT_ADV_DATA_STATUS_INCOMPLETE 0x01
#define BLE_GAP_EXT_ADV_DATA_STATUS_TRUNCATED 0x02
/** @brief Extended advertising report */
struct ble_gap_ext_disc_desc {
/*** Common fields. */
/** Report properties bitmask
* - BLE_HCI_ADV_CONN_MASK
* - BLE_HCI_ADV_SCAN_MASK
* - BLE_HCI_ADV_DIRECT_MASK
* - BLE_HCI_ADV_SCAN_RSP_MASK
* - BLE_HCI_ADV_LEGACY_MASK
* */
uint8_t props;
/** Advertising data status, can be one of following constants:
* - BLE_GAP_EXT_ADV_DATA_STATUS_COMPLETE
* - BLE_GAP_EXT_ADV_DATA_STATUS_INCOMPLETE
* - BLE_GAP_EXT_ADV_DATA_STATUS_TRUNCATED
*/
uint8_t data_status;
/** Legacy advertising PDU type. Valid if BLE_HCI_ADV_LEGACY_MASK props is
* set. Can be one of following constants:
* - BLE_HCI_ADV_RPT_EVTYPE_ADV_IND
* - BLE_HCI_ADV_RPT_EVTYPE_DIR_IND
* - BLE_HCI_ADV_RPT_EVTYPE_SCAN_IND
* - BLE_HCI_ADV_RPT_EVTYPE_NONCONN_IND
* - BLE_HCI_ADV_RPT_EVTYPE_SCAN_RSP
*/
uint8_t legacy_event_type;
/** Advertiser address */
ble_addr_t addr;
/** Received signal strength indication in dBm (127 if unavailable) */
int8_t rssi;
/** Advertiser transmit power in dBm (127 if unavailable) */
int8_t tx_power;
/** Advertising Set ID */
uint8_t sid;
/** Primary advertising PHY, can be one of following constants:
* - BLE_HCI_LE_PHY_1M
* - BLE_HCI_LE_PHY_CODED
*/
uint8_t prim_phy;
/** Secondary advertising PHY, can be one of following constants:
* - BLE_HCI_LE_PHY_1M
* - LE_HCI_LE_PHY_2M
* - BLE_HCI_LE_PHY_CODED
*/
uint8_t sec_phy;
/** Periodic advertising interval. 0 if no periodic advertising. */
uint16_t periodic_adv_itvl;
/** Advertising Data length */
uint8_t length_data;
/** Advertising data */
uint8_t *data;
/***
* LE direct advertising report fields; direct_addr is BLE_ADDR_ANY if
* direct address fields are not present.
/** Directed advertising address. Valid if BLE_HCI_ADV_DIRECT_MASK props is
* set (BLE_ADDR_ANY otherwise).
*/
ble_addr_t direct_addr;
};
#endif
/** @brief Advertising report */
struct ble_gap_disc_desc {
/*** Common fields. */
/** Advertising PDU type. Can be one of following constants:
* - BLE_HCI_ADV_RPT_EVTYPE_ADV_IND
* - BLE_HCI_ADV_RPT_EVTYPE_DIR_IND
* - BLE_HCI_ADV_RPT_EVTYPE_SCAN_IND
* - BLE_HCI_ADV_RPT_EVTYPE_NONCONN_IND
* - BLE_HCI_ADV_RPT_EVTYPE_SCAN_RSP
*/
uint8_t event_type;
/** Advertising Data length */
uint8_t length_data;
/** Advertiser address */
ble_addr_t addr;
/** Received signal strength indication in dBm (127 if unavailable) */
int8_t rssi;
/** Advertising data */
uint8_t *data;
/***
* LE direct advertising report fields; direct_addr is BLE_ADDR_ANY if
* direct address fields are not present.
/** Directed advertising address. Valid for BLE_HCI_ADV_RPT_EVTYPE_DIR_IND
* event type (BLE_ADDR_ANY otherwise).
*/
ble_addr_t direct_addr;
};
@@ -719,12 +836,30 @@ struct ble_gap_event {
* o BLE_GAP_EVENT_PERIODIC_SYNC
*/
struct {
/** BLE_ERR_SUCCESS on success or error code on failure. Other
* fields are valid only for success
*/
uint8_t status;
/** Periodic sync handle */
uint16_t sync_handle;
/** Advertising Set ID */
uint8_t sid;
/** Advertiser address */
ble_addr_t adv_addr;
/** Advertising PHY, can be one of following constants:
* - BLE_HCI_LE_PHY_1M
* - LE_HCI_LE_PHY_2M
* - BLE_HCI_LE_PHY_CODED
*/
uint8_t adv_phy;
/** Periodic advertising interval */
uint16_t per_adv_ival;
/** Advertiser clock accuracy */
uint8_t adv_clk_accuracy;
} periodic_sync;
@@ -734,11 +869,26 @@ struct ble_gap_event {
* o BLE_GAP_EVENT_PERIODIC_REPORT
*/
struct {
/** Periodic sync handle */
uint16_t sync_handle;
/** Advertiser transmit power in dBm (127 if unavailable) */
int8_t tx_power;
/** Received signal strength indication in dBm (127 if unavailable) */
int8_t rssi;
/** Advertising data status, can be one of following constants:
* - BLE_HCI_PERIODIC_DATA_STATUS_COMPLETE
* - BLE_HCI_PERIODIC_DATA_STATUS_INCOMPLETE
* - BLE_HCI_PERIODIC_DATA_STATUS_TRUNCATED
*/
uint8_t data_status;
/** Advertising Data length */
uint8_t data_length;
/** Advertising data */
uint8_t *data;
} periodic_report;
@@ -750,7 +900,12 @@ struct ble_gap_event {
* o BLE_GAP_EVENT_PERIODIC_SYNC_LOST
*/
struct {
/** Periodic sync handle */
uint16_t sync_handle;
/** Reason for sync lost, can be BLE_HS_ETIMEOUT for timeout or
* BLE_HS_EDONE for locally terminated sync
*/
int reason;
} periodic_sync_lost;
#endif
@@ -927,40 +1082,169 @@ int ble_gap_adv_set_fields(const struct ble_hs_adv_fields *rsp_fields);
int ble_gap_adv_rsp_set_fields(const struct ble_hs_adv_fields *rsp_fields);
#if MYNEWT_VAL(BLE_EXT_ADV)
/** @brief Extended advertising parameters */
struct ble_gap_ext_adv_params {
/** If perform connectable advertising */
unsigned int connectable:1;
/** If perform scannable advertising */
unsigned int scannable:1;
/** If perform directed advertising */
unsigned int directed:1;
/** If perform high-duty directed advertising */
unsigned int high_duty_directed:1;
/** If use legacy PDUs for advertising */
unsigned int legacy_pdu:1;
/** If perform anonymous advertising */
unsigned int anonymous:1;
/** If include TX power in advertising PDU */
unsigned int include_tx_power:1;
/** If enable scan request notification */
unsigned int scan_req_notif:1;
/** Minimum advertising interval in 0.625ms units, if 0 stack use sane
* defaults
*/
uint32_t itvl_min;
/** Maximum advertising interval in 0.625ms units, if 0 stack use sane
* defaults
*/
uint32_t itvl_max;
/** Advertising channel map , if 0 stack use sane defaults */
uint8_t channel_map;
/** Own address type to be used by advertising instance */
uint8_t own_addr_type;
/** Peer address for directed advertising, valid only if directed is set */
ble_addr_t peer;
/** Advertising Filter policy */
uint8_t filter_policy;
/** Primary advertising PHY to use , can be one of following constants:
* - BLE_HCI_LE_PHY_1M
* - BLE_HCI_LE_PHY_CODED
*/
uint8_t primary_phy;
/** Secondary advertising PHY to use, can be one of following constants:
* - BLE_HCI_LE_PHY_1M
* - LE_HCI_LE_PHY_2M
* - BLE_HCI_LE_PHY_CODED
*/
uint8_t secondary_phy;
/** Preferred advertiser transmit power */
int8_t tx_power;
/** Advertising Set ID */
uint8_t sid;
};
/**
* Configure extended advertising instance
*
* @param instance Instance ID
* @param params Additional arguments specifying the particulars
* of the advertising.
* @param selected_tx_power Selected advertising transmit power will be
* stored in that param if non-NULL.
* @param cb The callback to associate with this advertising
* procedure. Advertising complete event is reported
* through this callback
* @param cb_arg The optional argument to pass to the callback
* function.
*
* @return 0 on success; nonzero on failure.
*/
int ble_gap_ext_adv_configure(uint8_t instance,
const struct ble_gap_ext_adv_params *params,
int8_t *selected_tx_power,
ble_gap_event_fn *cb, void *cb_arg);
int ble_gap_ext_adv_set_addr(uint8_t instance, const ble_addr_t *addr);
int ble_gap_ext_adv_start(uint8_t instance, int duration, int max_events);
int ble_gap_ext_adv_stop(uint8_t instance);
int ble_gap_ext_adv_set_data(uint8_t instance, struct os_mbuf *data);
int ble_gap_ext_adv_rsp_set_data(uint8_t instance, struct os_mbuf *data);
int ble_gap_ext_adv_remove(uint8_t instance);
/**
* Clear All existing extended Adv Sets.
* Set random address for configured advertising instance.
*
* @param instance Instance ID
* @param addr Random address to be set
*
* @return 0 on success; nonzero on failure.
*/
int ble_gap_ext_adv_set_addr(uint8_t instance, const ble_addr_t *addr);
/**
* Start advertising instance.
*
* @param instance Instance ID
* @param duration The duration of the advertisement procedure. On
* expiration, the procedure ends and
* a BLE_HS_FOREVER event is reported.
* Units are milliseconds. Specify 0 for no
* expiration.
* @params max_events Number of advertising events that should be sent
* before advertising ends and
* a BLE_GAP_EVENT_ADV_COMPLETE event is reported.
* Specify 0 for no limit.
*
* @return 0 on success, error code on failure.
*/
int ble_gap_ext_adv_start(uint8_t instance, int duration, int max_events);
/**
* Stops advertising procedure for specified instance.
*
* @param instance Instance ID
*
* @return 0 on success, BLE_HS_EALREADY if there is no active advertising
* procedure for instance, other error code on failure.
*/
int ble_gap_ext_adv_stop(uint8_t instance);
/**
* Configures the data to include in advertisements packets for specified
* advertising instance.
*
* @param instance Instance ID
* @param data Chain containing the advertising data.
*
* @return 0 on success or error code on failure.
*/
int ble_gap_ext_adv_set_data(uint8_t instance, struct os_mbuf *data);
/**
* Configures the data to include in subsequent scan responses for specified
* advertisign instance.
*
* @param instance Instance ID
* @param data Chain containing the scan response data.
*
* @return 0 on success or error code on failure.
*/
int ble_gap_ext_adv_rsp_set_data(uint8_t instance, struct os_mbuf *data);
/**
* Remove existing advertising instance.
*
* @param instance Instance ID
*
* @return 0 on success,
* BLE_HS_EBUSY if advertising is in progress,
* other error code on failure.
*/
int ble_gap_ext_adv_remove(uint8_t instance);
/**
* Clear all existing advertising instances
* @return 0 on success,
* BLE_HS_EBUSY if advertising is in progress,
* other error code on failure.
@@ -970,34 +1254,151 @@ int ble_gap_ext_adv_clear(void);
/* Periodic Advertising */
#if MYNEWT_VAL(BLE_PERIODIC_ADV)
/** @brief Periodic advertising parameters */
struct ble_gap_periodic_adv_params {
/** If include TX power in advertising PDU */
unsigned int include_tx_power:1;
/** Minimum advertising interval in 0.625ms units, if 0 stack use sane
* defaults
*/
uint16_t itvl_min;
/** Maximum advertising interval in 0.625ms units, if 0 stack use sane
* defaults
*/
uint16_t itvl_max;
};
/** @brief Periodic sync parameters */
struct ble_gap_periodic_sync_params {
/** The maximum number of periodic advertising events that controller can
* skip after a successful receive.
* */
uint16_t skip;
/** Synchronization timeout for the periodic advertising train in 10ms units
*/
uint16_t sync_timeout;
};
/**
* Configure periodic advertising for specified advertising instance
*
* This is allowed only for instances configured as non-announymous,
* non-connectable and non-scannable.
*
* @param instance Instance ID
* @param params Additional arguments specifying the particulars
* of periodic advertising.
*
* @return 0 on success; nonzero on failure.
*/
int ble_gap_periodic_adv_configure(uint8_t instance,
const struct ble_gap_periodic_adv_params *params);
/**
* Start periodic advertising for specified advertising instance.
*
* @param instance Instance ID
*
* @return 0 on success, error code on failure.
*/
int ble_gap_periodic_adv_start(uint8_t instance);
/**
* Stop periodic advertising for specified advertising instance.
*
* @param instance Instance ID
*
* @return 0 on success, error code on failure.
*/
int ble_gap_periodic_adv_stop(uint8_t instance);
/**
* Configures the data to include in periodic advertisements for specified
* advertising instance.
*
* @param instance Instance ID
* @param data Chain containing the periodic advertising data.
*
* @return 0 on success or error code on failure.
*/
int ble_gap_periodic_adv_set_data(uint8_t instance, struct os_mbuf *data);
/**
* Performs the Synchronization procedure with periodic advertiser.
*
* @param addr Peer address to synchronize with. If NULL than
* peers from periodic list are used.
* @param adv_sid Advertiser Set ID
* @param params Additional arguments specifying the particulars
* of the synchronization procedure.
* @param cb The callback to associate with this synchrnization
* procedure. BLE_GAP_EVENT_PERIODIC_REPORT events
* are reported only by this callback.
* @param cb_arg The optional argument to pass to the callback
* function.
*
* @return 0 on success; nonzero on failure.
*/
int ble_gap_periodic_adv_create_sync(const ble_addr_t *addr, uint8_t adv_sid,
const struct ble_gap_periodic_sync_params *params,
ble_gap_event_fn *cb, void *cb_arg);
/**
* Cancel pending synchronization procedure.
*
* @return 0 on success; nonzero on failure.
*/
int ble_gap_periodic_adv_create_sync_cancel(void);
/**
* Terminate synchronization procedure.
*
* @param sync_handle Handle identifying synchronization to terminate.
*
* @return 0 on success; nonzero on failure.
*/
int ble_gap_periodic_adv_terminate_sync(uint16_t sync_handle);
/**
* Add peer device to periodic synchronization list.
*
* @param addr Peer address to add to list.
* @param adv_sid Advertiser Set ID
*
* @return 0 on success; nonzero on failure.
*/
int ble_gap_add_dev_to_periodic_adv_list(const ble_addr_t *peer_addr,
uint8_t adv_sid);
/**
* Remove peer device from periodic synchronization list.
*
* @param addr Peer address to remove from list.
* @param adv_sid Advertiser Set ID
*
* @return 0 on success; nonzero on failure.
*/
int ble_gap_rem_dev_from_periodic_adv_list(const ble_addr_t *peer_addr,
uint8_t adv_sid);
/**
* Clear periodic synchrnization list.
*
* @return 0 on success; nonzero on failure.
*/
int ble_gap_clear_periodic_adv_list(void);
/**
* Get periodic synchronization list size.
*
* @param per_adv_list_size On success list size is stored here.
*
* @return 0 on success; nonzero on failure.
*/
int ble_gap_read_periodic_adv_list_size(uint8_t *per_adv_list_size);
#endif
@@ -1034,6 +1435,46 @@ int ble_gap_disc(uint8_t own_addr_type, int32_t duration_ms,
const struct ble_gap_disc_params *disc_params,
ble_gap_event_fn *cb, void *cb_arg);
/**
* Performs the Limited or General Extended Discovery Procedures.
*
* @param own_addr_type The type of address the stack should use for
* itself when sending scan requests. Valid
* values are:
* - BLE_ADDR_TYPE_PUBLIC
* - BLE_ADDR_TYPE_RANDOM
* - BLE_ADDR_TYPE_RPA_PUB_DEFAULT
* - BLE_ADDR_TYPE_RPA_RND_DEFAULT
* This parameter is ignored unless active
* scanning is being used.
* @param duration The duration of the discovery procedure.
* On expiration, if period is set to 0, the
* procedure ends and a
* BLE_GAP_EVENT_DISC_COMPLETE event is
* reported. Units are 10 milliseconds.
* Specify 0 for no expiration.
* @param period Time interval from when the Controller started
* its last Scan Duration until it begins the
* subsequent Scan Duration. Specify 0 to scan
* continuously. Units are 1.28 second.
* @param limited If limited discovery procedure should be used.
* @param uncoded_params Additional arguments specifying the particulars
* of the discovery procedure for uncoded PHY.
* If NULL is provided no scan is performed for
* this PHY.
* @param coded_params Additional arguments specifying the particulars
* of the discovery procedure for coded PHY.
* If NULL is provided no scan is performed for
* this PHY.
* @param cb The callback to associate with this discovery
* procedure. Advertising reports and discovery
* termination events are reported through this
* callback.
* @param cb_arg The optional argument to pass to the callback
* function.
*
* @return 0 on success; nonzero on failure.
*/
int ble_gap_ext_disc(uint8_t own_addr_type, uint16_t duration, uint16_t period,
uint8_t filter_duplicates, uint8_t filter_policy,
uint8_t limited,
@@ -1328,23 +1769,93 @@ int ble_gap_unpair_oldest_peer(void);
#define BLE_GAP_PRIVATE_MODE_NETWORK 0
#define BLE_GAP_PRIVATE_MODE_DEVICE 1
/**
* Set privacy mode for specified peer device
*
* @param peer_addr Peer device address
* @param priv_mode Privacy mode to be used. Can be one of following
* constants:
* - BLE_GAP_PRIVATE_MODE_NETWORK
* - BLE_GAP_PRIVATE_MODE_DEVICE
*
* @return 0 on success; nonzero on failure.
*/
int ble_gap_set_priv_mode(const ble_addr_t *peer_addr, uint8_t priv_mode);
#define BLE_GAP_LE_PHY_1M 1
#define BLE_GAP_LE_PHY_2M 2
#define BLE_GAP_LE_PHY_CODED 3
/**
* Read PHYs used for specified connection.
*
* On success output parameters are filled with information about used PHY type.
*
* @param conn_handle Connection handle
* @param tx_phy TX PHY used. Can be one of following constants:
* - BLE_GAP_LE_PHY_1M
* - BLE_GAP_LE_PHY_2M
* - BLE_GAP_LE_PHY_CODED
* @param rx_phy RX PHY used. Can be one of following constants:
* - BLE_GAP_LE_PHY_1M
* - BLE_GAP_LE_PHY_2M
* - BLE_GAP_LE_PHY_CODED
*
* @return 0 on success; nonzero on failure.
*/
int ble_gap_read_le_phy(uint16_t conn_handle, uint8_t *tx_phy, uint8_t *rx_phy);
#define BLE_GAP_LE_PHY_1M_MASK 0x01
#define BLE_GAP_LE_PHY_2M_MASK 0x02
#define BLE_GAP_LE_PHY_CODED_MASK 0x04
#define BLE_GAP_LE_PHY_ANY_MASK 0x0F
/**
* Set preferred default PHYs to be used for connections.
*
* @params tx_phys_mask Preferred TX PHY. Can be mask of following
* constants:
* - BLE_GAP_LE_PHY_1M_MASK
* - BLE_GAP_LE_PHY_2M_MASK
* - BLE_GAP_LE_PHY_CODED_MASK
* - BLE_GAP_LE_PHY_ANY_MASK
* @params rx_phys_mask Preferred RX PHY. Can be mask of following
* constants:
* - BLE_GAP_LE_PHY_1M_MASK
* - BLE_GAP_LE_PHY_2M_MASK
* - BLE_GAP_LE_PHY_CODED_MASK
* - BLE_GAP_LE_PHY_ANY_MASK
* @return 0 on success; nonzero on failure.
*/
int ble_gap_set_prefered_default_le_phy(uint8_t tx_phys_mask,
uint8_t rx_phys_mask);
#define BLE_GAP_LE_PHY_CODED_ANY 0
#define BLE_GAP_LE_PHY_CODED_S2 1
#define BLE_GAP_LE_PHY_CODED_S8 2
/**
* Set preferred PHYs to be used for connection.
*
* @param conn_handle Connection handle
* @params tx_phys_mask Preferred TX PHY. Can be mask of following
* constants:
* - BLE_GAP_LE_PHY_1M_MASK
* - BLE_GAP_LE_PHY_2M_MASK
* - BLE_GAP_LE_PHY_CODED_MASK
* - BLE_GAP_LE_PHY_ANY_MASK
* @params rx_phys_mask Preferred RX PHY. Can be mask of following
* constants:
* - BLE_GAP_LE_PHY_1M_MASK
* - BLE_GAP_LE_PHY_2M_MASK
* - BLE_GAP_LE_PHY_CODED_MASK
* - BLE_GAP_LE_PHY_ANY_MASK
* @param phy_opts Additional PHY options. Valid values are:
* - BLE_GAP_LE_PHY_CODED_ANY
* - BLE_GAP_LE_PHY_CODED_S2
* - BLE_GAP_LE_PHY_CODED_S8
*
* @return 0 on success; nonzero on failure.
*/
int ble_gap_set_prefered_le_phy(uint16_t conn_handle, uint8_t tx_phys_mask,
uint8_t rx_phys_mask, uint16_t phy_opts);