BLE_API v2.1.3

Functions
BLE Command Function
BLE Common » BLE Command Function

## Functions
BleStackStatus | setBLE_BleStackInit (void)
void | setBLE_BleStackGpio_Isr (void)
BleStackStatus | setBLE_BleDeviceAddr (BLE_Addr_Param *addrParam)
BleStackStatus | getBLE_BleDeviceAddr (BLE_Addr_Param *addrParam)
BleStackStatus | setBLE_AdvParam (BLE_Adv_Param *advParam)
BleStackStatus | setBLE_AdvData (uint8_t *advData, uint8_t length)
BleStackStatus | setBLE_ScanRspData (uint8_t *scanRspData, uint8_t length)
BleStackStatus | setBLE_AdvEnable (uint8_t hostId)
BleStackStatus | setBLE_AdvDisable (void)
BleStackStatus | setBLE_ScanParam (BLE_Scan_Param *scanParam)
BleStackStatus | setBLE_ScanEnable (void)
BleStackStatus | setBLE_ScanDisable (void)
BleStackStatus | getBLE_GapAdDataByAdType (BLE_Event_ScanReportParam *rptData, BLE_GAP_AD_TYPE parsingAdType, uint8_t *parsingData, uint8_t *parsingDataLen)
BleStackStatus | setBLE_ConnCreate (uint8_t hostId, BLE_Addr_Param *peerAddrParam, BLE_Scan_Param *scanParam, BLE_Conn_Param *connParam)
BleStackStatus | setBLE_ConnCreateWithSetScanParam (uint8_t hostId, BLE_Addr_Param *peerAddrParam, BLE_Conn_Param *connParam)
BleStackStatus | setBLE_ConnCancel (void)
BleStackStatus | setBLE_Disconnect (uint8_t hostId)
BleStackStatus | setBLE_ConnUpdate (uint8_t hostId, BLE_Conn_Param *connParam)
BleStackStatus | setBLE_TxPower (uint8_t power_index, BleMode bleMode)
BleStackStatus | setBLE_Phy (uint8_t hostId, BLE_Phy_Param *blePhy)
BleStackStatus | getBLE_Phy (uint8_t hostId)
BleStackStatus | getBLE_RssiValue (uint8_t hostId)
BleStackStatus | setBLE_SecurityRequest (uint8_t hostId)
BleStackStatus | setBLE_PairingPassKey (uint8_t hostId, uint32_t hexPasskey)
BleStackStatus | setBLE_IOCapabilities (BLE_IOCaps_Param *ioCapsParam)
BleStackStatus | setBLE_BondingFlags (BLE_BondingFlags_Param *bondingParam)
BleStackStatus | setBLE_DataLength (uint8_t hostId, BLE_DataLength_Param *dataLenParam)
BleStackStatus | setBLE_CompanyId (uint16_t companyId)
BleStackStatus | getBLEGATT_MtuSize (uint8_t hostId, uint16_t *mtuSize)
BleStackStatus | getBLEGATT_HandleNumAddr (uint8_t hostId, BleGattRole gattRole, ATTRIBUTE_BLE *attributeElement, void *handleNumAddr)
BleStackStatus | getBLEGATT_RestoreCCCDValueFromBond (uint8_t hostId)
BleStackStatus | setBLEGATT_ReparseAttDatabase (uint8_t hostId)
BleStackStatus | setBLEGATT_ExchangeMtuRequest (uint8_t hostId, uint16_t clientRxMtu)
BleStackStatus | setBLEGATT_ReadCharacteristicValue (uint8_t hostId, uint16_t hdlNum)
BleStackStatus | setBLEGATT_ReadLongCharacteristicValue (uint8_t hostId, uint16_t hdlNum, uint16_t Offset)
BleStackStatus | setBLEGATT_ConfigCCCD (uint8_t hostId, uint16_t hdlNum, BleGattCCCDValue cccdVal)
BleStackStatus | setBLEGATT_Write (uint8_t hostId, uint16_t hdlNum, uint8_t *data, uint16_t length)
BleStackStatus | setBLEGATT_WriteWithoutRsp (uint8_t hostId, uint16_t hdlNum, uint8_t *data, uint16_t length)
BleStackStatus | setBLEGATT_PrepareWrite (uint8_t hostId, uint16_t hdlNum, uint8_t *data, uint16_t length)
BleStackStatus | setBLEGATT_ExecuteWrite (uint8_t hostId, uint16_t hdlNum, uint8_t flag)
BleStackStatus | setBLEGATT_PreferredMtuSize (uint8_t hostId, uint16_t preferredRxMtu)
BleStackStatus | setBLEGATT_ReadByTypeRsp (uint8_t hostId, uint16_t hdlNum, uint8_t *data, uint16_t length)
BleStackStatus | setBLEGATT_ReadRsp (uint8_t hostId, uint16_t hdlNum, uint8_t *data, uint16_t length)
BleStackStatus | setBLEGATT_GeneralReadRsp (uint8_t hostId, uint16_t hdlNum, uint8_t *data, uint16_t length)
BleStackStatus | setBLEGATT_ReadBlobRsp (uint8_t hostId, uint16_t hdlNum, uint8_t *data, uint16_t length)
BleStackStatus | setBLEGATT_Indication (uint8_t hostId, uint16_t hdlNum, uint8_t *data, uint16_t length)
BleStackStatus | setBLEGATT_Notification (uint8_t hostId, uint16_t hdlNum, uint8_t *data, uint16_t length)
BleStackStatus | setBLEGATT_ErrorRsp (uint8_t hostId, uint16_t hdlNum, BleAttOpcode opcode, BleAttErrorRsp errRsp)

## Detailed Description

## Function Documentation

## ◆ getBLE_BleDeviceAddr()

BleStackStatus getBLE_BleDeviceAddr | ( | BLE_Addr_Param * | addrParam | ) |

Get BLE Device Address and Device Address Type

This function is used to get BLE Local Device Address and Device Address Type.

Remarks
  [BLELIB_NOCONN], [BLELIB_P], [BLELIB_C], [BLELIB_PC]

Note
  BLE Address Type : PUBLIC_ADDR or RANDOM_ADDR
  BLE Address : Little Endian and the length is SIZE_BLE_ADDR
  If Device BLE Address is set to "01:02:03:04:05:06", addrParam->addr[0] = 0x06

Parameters

  [out] | addrParam | : a pointer to local device BLE address and BLE address type.

Return values

  BLESTACK_STATUS_ERR_INVALID_STATE | : BLE stack has not initialized.
  BLESTACK_STATUS_SUCCESS | : Setting success.

## ◆ getBLE_GapAdDataByAdType()

BleStackStatus getBLE_GapAdDataByAdType | ( | BLE_Event_ScanReportParam * | rptData,
|  | BLE_GAP_AD_TYPE | parsingAdType,
|  | uint8_t * | parsingData,
|  | uint8_t * | parsingDataLen
| ) |  |

Get BLE Advertising Parsing Data By Advertising Data Type

Remarks
  [BLELIB_NOCONN], [BLELIB_C], [BLELIB_PC]

Parameters

  [in] | rptData | : scanned advertising data to parse.
  [in] | parsingAdType | : parsing advertising type.
  [out] | parsingData | : a pointer to the parsing data.
  [out] | parsingDataLen | : a pointer to the length of parsing data.

Return values

  BLESTACK_STATUS_ERR_NOT_SUPPORTED | : Command not supported.
  BLESTACK_STATUS_ERR_INVALID_PARAM | : Invalid parameter which means error advertising data or there is no data of requested advertising data type.
  BLESTACK_STATUS_SUCCESS | : Setting success.

## ◆ getBLE_Phy()

BleStackStatus getBLE_Phy | ( | uint8_t | hostId | ) |

Get BLE TX/ RX PHY

Remarks
  [BLELIB_P], [BLELIB_C], [BLELIB_PC]

BLE Event
  Wait for BLECMD_EVENT_PHY_READ_COMPLETE event to get TX/ RX PHY.

Parameters

  [in] | hostId | : the link's host id.

Return values

  BLESTACK_STATUS_ERR_NOT_SUPPORTED | : Command not supported.
  BLESTACK_STATUS_ERR_INVALID_HOSTID | : Invalid host id.
  BLESTACK_STATUS_ERR_INVALID_STATE | : BLE stack has not initialized or there is no connection established with the host id.
  BLESTACK_STATUS_ERR_BUSY | : Message queue buffer full.
  BLESTACK_STATUS_SUCCESS | : Setting success.

## ◆ getBLE_RssiValue()

BleStackStatus getBLE_RssiValue | ( | uint8_t | hostId | ) |

Get BLE RSSI Value

Remarks
  [BLELIB_P], [BLELIB_C], [BLELIB_PC]

BLE Event
  Wait for BLECMD_EVENT_READ_RSSI_COMPLETE event to get last RSSI value.

Parameters

  [in] | hostId | : the link's host id.

Return values

  BLESTACK_STATUS_ERR_NOT_SUPPORTED | : Command not supported.
  BLESTACK_STATUS_ERR_INVALID_HOSTID | : Invalid host id.
  BLESTACK_STATUS_ERR_INVALID_STATE | : BLE stack has not initialized or there is no connection established with the host id.
  BLESTACK_STATUS_ERR_BUSY | : Message queue buffer full.
  BLESTACK_STATUS_SUCCESS | : Setting success.

## ◆ getBLEGATT_HandleNumAddr()

BleStackStatus getBLEGATT_HandleNumAddr | ( | uint8_t | hostId,
|  | BleGattRole | gattRole,
|  | ATTRIBUTE_BLE * | attributeElement,
|  | void * | handleNumAddr
| ) |  |

Get BLE GATT Handle Numbers

Remarks
  [BLELIB_P], [BLELIB_C], [BLELIB_PC]

Parameters

  [in] | hostId | : the link's host id.
  [in] | gattRole | : GATT role
  [in] | attributeElement | : a pointer to service attribute element.
  [out] | handleNumAddr | : a point to handle number table.

Return values

  BLESTACK_STATUS_ERR_NOT_SUPPORTED | : Command not supported.
  BLESTACK_STATUS_ERR_INVALID_HOSTID | : Invalid host id.
  BLESTACK_STATUS_ERR_INVALID_STATE | : BLE stack has not initialized.
  BLESTACK_STATUS_ERR_INVALID_PARAM | : Invalid parameters.
  BLESTACK_STATUS_SUCCESS | : Setting success.

## ◆ getBLEGATT_MtuSize()

BleStackStatus getBLEGATT_MtuSize | ( | uint8_t | hostId,
|  | uint16_t * | mtuSize
| ) |  |

Get BLE GATT MTU Size

Remarks
  [BLELIB_P], [BLELIB_C], [BLELIB_PC]

Parameters

  [in] | hostId | : the link's host id.
  [out] | mtuSize | : MTU size.

Return values

  BLESTACK_STATUS_ERR_NOT_SUPPORTED | : Command not supported.
  BLESTACK_STATUS_ERR_INVALID_HOSTID | : Invalid host id.
  BLESTACK_STATUS_ERR_INVALID_STATE | : BLE stack has not initialized.
  BLESTACK_STATUS_SUCCESS | : Setting success.

## ◆ getBLEGATT_RestoreCCCDValueFromBond()

BleStackStatus getBLEGATT_RestoreCCCDValueFromBond | ( | uint8_t | hostId | ) |

BLE GATT Get Characteristic Values from Bonded space

Remarks
  [BLELIB_P], [BLELIB_C], [BLELIB_PC]

Attention
  The link shall be in connection and encryption/ authentication mode or return error code.

Parameters

  [in] | hostId | : the link's host id.

Return values

  BLESTACK_STATUS_ERR_NOT_SUPPORTED | : Command not supported.
  BLESTACK_STATUS_ERR_INVALID_HOSTID | : Invalid host id.
  BLESTACK_STATUS_ERR_DB_PARSING_IN_PROGRESS | : Service/ characteristic discovering or authentication/ authorization have not completed.
  BLESTACK_STATUS_ERR_INVALID_STATE | : BLE stack has not initialized or there is no connection established with the host id.
  BLESTACK_STATUS_SUCCESS | : Setting success.

## ◆ setBLE_AdvData()

BleStackStatus setBLE_AdvData | ( | uint8_t * | advData,
|  | uint8_t | length
| ) |  |

Set BLE Advertising Data

Remarks
  [BLELIB_NOCONN], [BLELIB_P], [BLELIB_PC]

Note
  BLE advertising data length shall be less than or equal to 31 bytes, the input advData length shall be less than or equal to 32 bytes.
  AD Type please refer to BLE Gap Data Type Formats

      ||--------------------------------------------------------------------------------------------------------------------------------------||
      ||                                         <length octets = (1+alength) octets>                                                         ||
      ||                                                     advData                                                                          ||
      ||--------------------------------------------------------------------------------------------------------------------------------------||
      ||      <1 octet>            ||           <alength octets = (1+slength_1)+...+(1+slength_N)  octets>                                    ||
      ||BLE advertising data length||                        BLE advertising data                                                             ||
      ||--------------------------------------------------------------------------------------------------------------------------------------||
      ||                           ||              AD Structure 1                 ||  ........ ||               AD Structure N                ||
      ||--------------------------------------------------------------------------------------------------------------------------------------||
      ||                           ||<1 octet>||      <slength_1 octets>          ||           ||<1 octet>||    <slength_N octets>            ||
      ||                           ||slength_1||              Data                ||  ........ ||slength_N||              Data                ||
      ||--------------------------------------------------------------------------------------------------------------------------------------||
      ||                           ||         ||<1 octets>||<(slength_1-1) octets>||           ||         ||<1 octets>||<(slength_N-1) octets>||
      ||                           ||         || AD Type  ||     AD Data          ||  ........ ||         || AD Type  ||     AD Data          ||
      ||--------------------------------------------------------------------------------------------------------------------------------------||

Parameters

  [in] | advData | : a pointer to advertising data.
  [in] | length | : length of advData.

Return values

  BLESTACK_STATUS_ERR_NOT_SUPPORTED | : Command not supported.
  BLESTACK_STATUS_ERR_INVALID_STATE | : BLE stack has not initialized.
  BLESTACK_STATUS_ERR_INVALID_PARAM | : Invalid parameter.
  BLESTACK_STATUS_ERR_BUSY | : Message queue buffer full.
  BLESTACK_STATUS_SUCCESS | : Setting success.

## ◆ setBLE_AdvDisable()

BleStackStatus setBLE_AdvDisable | ( | void |  | ) |

Set BLE Stop Advertising

Remarks
  [BLELIB_NOCONN], [BLELIB_P], [BLELIB_PC]

BLE Event
  Wait for BLECMD_EVENT_ADV_COMPLETE event which indicates the advertisement has been stopped.

Return values

  BLESTACK_STATUS_ERR_NOT_SUPPORTED | : Command not supported.
  BLESTACK_STATUS_ERR_INVALID_STATE | : BLE stack has not initialized or can ONLY be set while in advertising state.
  BLESTACK_STATUS_ERR_BUSY | : Message queue buffer full.
  BLESTACK_STATUS_SUCCESS | : Setting success.

## ◆ setBLE_AdvEnable()

BleStackStatus setBLE_AdvEnable | ( | uint8_t | hostId | ) |

Set BLE Start Advertising

Remarks
  [BLELIB_NOCONN], [BLELIB_P], [BLELIB_PC]

BLE Event
  Wait for BLECMD_EVENT_ADV_COMPLETE event which indicates the advertisement has been started.

Parameters

  [in] | hostId | : the link's host ID or set to BLE_HOSTID_RESERVED to enable ADV_TYPE_ADV_NONCONN_IND or ADV_TYPE_SCAN_IND advertisement.

Return values

  BLESTACK_STATUS_ERR_NOT_SUPPORTED | : Command not supported or only ADV_TYPE_ADV_NONCONN_IND or ADV_TYPE_SCAN_IND advertisement can be enabled.
  BLESTACK_STATUS_ERR_INVALID_HOSTID | : Invalid host id.
  BLESTACK_STATUS_ERR_INVALID_STATE | : Invalid state usually happens in BLE stack has not initialized or there is a connection established with the host id or already in advertisement mode.
  BLESTACK_STATUS_ERR_BUSY | : Message queue buffer full.
  BLESTACK_STATUS_SUCCESS | : Setting success.

## ◆ setBLE_AdvParam()

BleStackStatus setBLE_AdvParam | ( | BLE_Adv_Param * | advParam | ) |

Set BLE Advertising Parameter

Remarks
  [BLELIB_NOCONN], [BLELIB_P], [BLELIB_PC]

Attention
  MUST set advDirectAddrParam if BLE advertising type is set to ADV_TYPE_ADV_DIRECT_IND.

Note
  Advertising interval Min. and Max. : ADV_INTERVAL_MIN to ADV_INTERVAL_MAX
  Advertising interval Min. shall be less than or equal to advertising interval Max.

Parameters

  [in] | advParam | : a pointer to advertising parameter

Return values

  BLESTACK_STATUS_ERR_NOT_SUPPORTED | : Command not supported.
  BLESTACK_STATUS_ERR_INVALID_STATE | : BLE stack has not initialized or can ONLY be set while the device is not in advertisement state.
  BLESTACK_STATUS_ERR_INVALID_PARAM | : Invalid parameter.
  BLESTACK_STATUS_ERR_BUSY | : Message queue buffer full.
  BLESTACK_STATUS_SUCCESS | : Setting success.

## ◆ setBLE_BleDeviceAddr()

BleStackStatus setBLE_BleDeviceAddr | ( | BLE_Addr_Param * | addrParam | ) |

Set BLE Device Address and Device Address Type

This function is used to set BLE Local Device Address and Device Address Type.

Remarks
  [BLELIB_NOCONN], [BLELIB_P], [BLELIB_C], [BLELIB_PC]

Attention
  MUST set BLE Device Address and Address Type after setRF_Init and setBLE_BleStackInit
  If the address/ address type change, MUST re-init advertisement parameter or scan parameter or create connection to use the updated address/ address type.

Note
  BLE Address Type : MUST be either PUBLIC_ADDR or RANDOM_ADDR
  If BLE Address Type is set to RANDOM_ADDR (static random address), the two most significant bits of the address shall be equal to 1.
  BLE Address : Little Endian and the length is SIZE_BLE_ADDR
  If Device BLE Address is set to "01:02:03:04:05:06", addrParam->addr[0] = 0x06

Parameters

  [in] | addrParam | : a pointer to local device BLE address and BLE address type

Return values

  BLESTACK_STATUS_ERR_NOT_SUPPORTED | : Command not supported.
  BLESTACK_STATUS_ERR_INVALID_STATE | : BLE stack has not initialized or can ONLY be set while in standby state.
  BLESTACK_STATUS_ERR_INVALID_PARAM | : Invalid parameter.
  BLESTACK_STATUS_SUCCESS | : Setting success.

## ◆ setBLE_BleStackGpio_Isr()

void setBLE_BleStackGpio_Isr | ( | void |  | ) |

Set BLE Stack Handle Interrupt ISR

This function is used to handle BLE stack interrupt.

Remarks
  [BLELIB_NOCONN], [BLELIB_P], [BLELIB_C], [BLELIB_PC]

## ◆ setBLE_BleStackInit()

BleStackStatus setBLE_BleStackInit | ( | void |  | ) |

Set BLE Stack Initialization

This function is used to initial BLE stack.

Remarks
  [BLELIB_NOCONN], [BLELIB_P], [BLELIB_C], [BLELIB_PC]

Attention
  MUST initial BLE stack after setRF_Init

Return values

  BLESTACK_STATUS_ERR_INVALID_STATE | : RF Phy has NOT initialized.
  BLESTACK_STATUS_ERR_INVALID_HOSTCOUNT | : Can ONLY be set while in standby state.
  BLESTACK_STATUS_SUCCESS | : Setting success.

## ◆ setBLE_BondingFlags()

BleStackStatus setBLE_BondingFlags | ( | BLE_BondingFlags_Param * | bondingParam | ) |

Set BLE Bonding Flags

Remarks
  [BLELIB_P], [BLELIB_C], [BLELIB_PC]

Attention
  if GATT role is BLE_GATT_ROLE_CLIENT :
  - Bonding is not supported if the peer device address type is "private device address".

Note
  Shall be issued while in standby state or return BLESTACK_STATUS_ERR_INVALID_STATE.

Parameters

  [in] | bondingParam | : a pointer to bonding flags.

Return values

  BLESTACK_STATUS_ERR_NOT_SUPPORTED | : Command not supported.
  BLESTACK_STATUS_ERR_INVALID_STATE | : Invalid state usually happens in BLE stack has not initialized or BLE state is not in standby mode.
  BLESTACK_STATUS_ERR_INVALID_PARAM | : Invalid parameter.
  BLESTACK_STATUS_SUCCESS | : Setting success.

## ◆ setBLE_CompanyId()

BleStackStatus setBLE_CompanyId | ( | uint16_t | companyId | ) |

Set BLE Company ID.

Remarks
  [BLELIB_P], [BLELIB_C], [BLELIB_PC]

Parameters

  [in] | companyId | : company id.

Return values

  BLESTACK_STATUS_SUCCESS | : Setting Completed.

## ◆ setBLE_ConnCancel()

BleStackStatus setBLE_ConnCancel | ( | void |  | ) |

Set BLE Cancel the On-going Connection Procedure

Remarks
  [BLELIB_C], [BLELIB_PC]

BLE Event
  Wait for BLECMD_EVENT_CONN_CANCEL_COMPLETE event which indicates the connection has been canceled.

Return values

  BLESTACK_STATUS_ERR_NOT_SUPPORTED | : Command not supported.
  BLESTACK_STATUS_ERR_INVALID_STATE | : BLE stack has not initialized or can ONLY be set while the connection is establishing.
  BLESTACK_STATUS_ERR_BUSY | : Message queue buffer full.
  BLESTACK_STATUS_SUCCESS | : Setting success.

## ◆ setBLE_ConnCreate()

BleStackStatus setBLE_ConnCreate | ( | uint8_t | hostId,
|  | BLE_Addr_Param * | peerAddrParam,
|  | BLE_Scan_Param * | scanParam,
|  | BLE_Conn_Param * | connParam
| ) |  |

Set BLE Create Connection

Remarks
  [BLELIB_C], [BLELIB_PC]

BLE Event
  Wait for BLECMD_EVENT_CONN_COMPLETE event which indicates the connection establishing process has been started.

Attention
  - The connection process will be stopped until the connection is established or setBLE_ConnCancel is called.

Parameters

  [in] | hostId | : the link's host id.
  [in] | peerAddrParam | : a pointer to the target peer device address and address type.
  [in] | scanParam | : a pointer to scan parameter.
  [in] | connParam | : a pointer to connection parameter.

Return values

  BLESTACK_STATUS_ERR_INVALID_HOSTID | : Invalid host id.
  BLESTACK_STATUS_ERR_INVALID_STATE | : Invalid state usually happens in BLE stack has not initialized or there is a connection established with the host id or there is another initialing process in on-going.
  BLESTACK_STATUS_ERR_BUSY | : Message queue buffer full.
  BLESTACK_STATUS_SUCCESS | : Setting success.

## ◆ setBLE_ConnCreateWithSetScanParam()

BleStackStatus setBLE_ConnCreateWithSetScanParam | ( | uint8_t | hostId,
|  | BLE_Addr_Param * | peerAddrParam,
|  | BLE_Conn_Param * | connParam
| ) |  |

Set BLE Create Connection with the setting of scan parameters by setBLE_ScanParam

Remarks
  [BLELIB_C], [BLELIB_PC]

BLE Event
  Wait for BLECMD_EVENT_CONN_COMPLETE event which indicates the connection establishing process has been started.

Attention
  The connection process will be stopped until the connection is established or setBLE_ConnCancel is called.

Note
  it calls setBLE_ConnCreate with the setting of scan parameters by setBLE_ScanParam otherwise the deafult scan parameters are:
  - scan type : SCAN_TYPE_ACTIVE
  - scan interval: 10 (10*0.625ms=6.25ms)
  - scan window : 10 10*0.625ms=6.25ms
  - scan filter : SCAN_FILTER_POLICY_ACCEPT_ALL

Parameters

  [in] | hostId | : the link's host id.
  [in] | peerAddrParam | : a pointer to the target peer device address and address type.
  [in] | connParam | : a pointer to connection parameter.

Return values

  BLESTACK_STATUS_ERR_NOT_SUPPORTED | : Command not supported.
  BLESTACK_STATUS_ERR_INVALID_HOSTID | : Invalid host id.
  BLESTACK_STATUS_ERR_INVALID_STATE | : Invalid state usually happens in BLE stack has not initialized or there is a connection established with the host id or there is another initialing process in on-going.
  BLESTACK_STATUS_ERR_BUSY | : Message queue buffer full.
  BLESTACK_STATUS_SUCCESS | : Setting success.

## ◆ setBLE_ConnUpdate()

BleStackStatus setBLE_ConnUpdate | ( | uint8_t | hostId,
|  | BLE_Conn_Param * | connParam
| ) |  |

BLE Update Connection Parameter

Remarks
  [BLELIB_P], [BLELIB_C], [BLELIB_PC]

BLE Event
  Wait for BLECMD_EVENT_CONN_UPDATE_COMPLETE event which indicates the connection parameter has been updated.

Note
  Conn Interval Min/Max : CONN_INTERVAL_MIN - CONN_INTERVAL_MAX
  Conn Latency : CONN_LATENCY_MIN - CONN_LATENCY_MAX
  Conn Svision Timeout : CONN_SUBTIMEOUT_MIN - CONN_SUBTIMEOUT_MAX
  The Svision Timeout in milliseconds shall be larger than (1 + connLatency) * CONN_INTERVAL_MAX * 2 , where CONN_INTERVAL_MAX is given in milliseconds.

Parameters

  [in] | connId | : the link's Host id.
  [in] | connParam | : a pointer to connection parameter.

Return values

  BLESTACK_STATUS_ERR_NOT_SUPPORTED | : Command not supported.
  BLESTACK_STATUS_ERR_INVALID_HOSTID | : Invalid host id.
  BLESTACK_STATUS_ERR_INVALID_STATE | : BLE stack has not initialized or there is no connection established with the host id.
  BLESTACK_STATUS_ERR_INVALID_PARAM | : Invalid parameter.
  BLESTACK_STATUS_ERR_TIMER_BUSY | : The connection parameter update timer is busy. Meaning there are still outstanding connection parameter update events.
  BLESTACK_STATUS_ERR_BUSY | : Message queue buffer full.
  BLESTACK_STATUS_SUCCESS | : Setting success.

## ◆ setBLE_DataLength()

BleStackStatus setBLE_DataLength | ( | uint8_t | hostId,
|  | BLE_DataLength_Param * | dataLenParam
| ) |  |

Set BLE Data Length Update

Remarks
  [BLELIB_P], [BLELIB_C], [BLELIB_PC]

BLE Event
  Wait for BLECMD_EVENT_DATA_LENGTH_UPDATE event to get updated BLE data length.

Note
  The range of data length is 27~251 bytes.

Parameters

  [in] | hostId | : the link's host id.
  [in] | dataLenParam | : a pointer to data length parameters.

Return values

  BLESTACK_STATUS_ERR_NOT_SUPPORTED | : Command not supported.
  BLESTACK_STATUS_ERR_INVALID_HOSTID | : Invalid host id.
  BLESTACK_STATUS_ERR_INVALID_STATE | : BLE stack has not initialized or there is no connection established with the host id.
  BLESTACK_STATUS_ERR_INVALID_PARAM | : Invalid parameter.
  BLESTACK_STATUS_ERR_BUSY | : Message queue buffer full.
  BLESTACK_STATUS_SUCCESS | : Setting success.

## ◆ setBLE_Disconnect()

BleStackStatus setBLE_Disconnect | ( | uint8_t | hostId | ) |

Set BLE Terminate the Connection

Remarks
  [BLELIB_P], [BLELIB_C], [BLELIB_PC]

BLE Event
  Wait for BLECMD_EVENT_DISCONN_COMPLETE event which indicates the connection has been terminated.

Parameters

  [in] | HostId | : the link's host id.

Return values

  BLESTACK_STATUS_ERR_NOT_SUPPORTED | : Command not supported.
  BLESTACK_STATUS_ERR_INVALID_HOSTID | : Invalid host id.
  BLESTACK_STATUS_ERR_INVALID_STATE | : BLE stack has not initialized or there is no connection established with the host id.
  BLESTACK_STATUS_ERR_BUSY | : Message queue buffer full.
  BLESTACK_STATUS_SUCCESS | : Setting success.

## ◆ setBLE_IOCapabilities()

BleStackStatus setBLE_IOCapabilities | ( | BLE_IOCaps_Param * | ioCapsParam | ) |

Set BLE IO Capabilities

Remarks
  [BLELIB_P], [BLELIB_C], [BLELIB_PC]

Note
  Shall be issued while in standby state or return BLESTACK_STATUS_ERR_INVALID_STATE.

Parameters

  [in] | ioCapsParam | : a pointer to IO capabilities parameter.

Return values

  BLESTACK_STATUS_ERR_NOT_SUPPORTED | : Command not supported.
  BLESTACK_STATUS_ERR_INVALID_STATE | : Invalid state usually happens in BLE stack has not initialized or BLE state is not in standby mode.
  BLESTACK_STATUS_ERR_INVALID_PARAM | : Invalid parameter.
  BLESTACK_STATUS_SUCCESS | : Setting success.

## ◆ setBLE_PairingPassKey()

BleStackStatus setBLE_PairingPassKey | ( | uint8_t | hostId,
|  | uint32_t | hexPasskey
| ) |  |

Set BLE Pairing PassKey Value

Remarks
  [BLELIB_P], [BLELIB_C], [BLELIB_PC]

Set PassKey value to do pairing process.

Parameters

  [in] | hostId | : the link's host id.
  [in] | hexPasskey | : passkey for 6-digit code.

Return values

  BLESTACK_STATUS_ERR_NOT_SUPPORTED | : Command not supported.
  BLESTACK_STATUS_ERR_INVALID_HOSTID | : Invalid host id.
  BLESTACK_STATUS_ERR_INVALID_STATE | : BLE stack has not initialized or there is no connection established with the host id.
  BLESTACK_STATUS_ERR_BUSY | : Message queue buffer full.
  BLESTACK_STATUS_SUCCESS | : Setting success.

## ◆ setBLE_Phy()

BleStackStatus setBLE_Phy | ( | uint8_t | hostId,
|  | BLE_Phy_Param * | blePhy
| ) |  |

Set BLE TX/ RX PHY

Remarks
  [BLELIB_P], [BLELIB_C], [BLELIB_PC]

BLE Event
  Wait for BLECMD_EVENT_PHY_UPDATE_COMPLETE event which indicates the BLE PHY is updated.

Note
  The setting of TX PHY must equal to RX PHY.

Parameters

  [in] | hostId | : the link's host id.
  [in] | blePhy | : a pointer to requested blePhy.

Return values

  BLESTACK_STATUS_ERR_NOT_SUPPORTED | : Command not supported.
  BLESTACK_STATUS_ERR_INVALID_HOSTID | : Invalid host id.
  BLESTACK_STATUS_ERR_INVALID_STATE | : BLE stack has not initialized or there is no connection established with the host id.
  BLESTACK_STATUS_ERR_INVALID_PARAM | : Invalid parameter.
  BLESTACK_STATUS_ERR_BUSY | : Message queue buffer full.
  BLESTACK_STATUS_SUCCESS | : Setting success.

## ◆ setBLE_ScanDisable()

BleStackStatus setBLE_ScanDisable | ( | void |  | ) |

Set BLE Stop Scanning

Remarks
  [BLELIB_NOCONN], [BLELIB_C], [BLELIB_PC]

BLE Event
  Wait for BLECMD_EVENT_SCAN_COMPLETE event which indicates the scan has been stopped.

Return values

  BLESTACK_STATUS_ERR_NOT_SUPPORTED | : Command not supported.
  BLESTACK_STATUS_ERR_INVALID_STATE | : BLE stack has not initialized or can ONLY be set while in scanning state.
  BLESTACK_STATUS_ERR_BUSY | : Message queue buffer full.
  BLESTACK_STATUS_SUCCESS | : Setting success.

## ◆ setBLE_ScanEnable()

BleStackStatus setBLE_ScanEnable | ( | void |  | ) |

Set BLE Start Scanning

Remarks
  [BLELIB_NOCONN], [BLELIB_C], [BLELIB_PC]

BLE Event
  Wait for BLECMD_EVENT_SCAN_COMPLETE event which indicates the scan has been started.
  Wait for BLECMD_EVENT_SCAN_REPORT event to receive scanned devices information.

Return values

  BLESTACK_STATUS_ERR_NOT_SUPPORTED | : Command not supported.
  BLESTACK_STATUS_ERR_INVALID_STATE | : BLE stack has not initialized or already in scanning mode.
  BLESTACK_STATUS_ERR_BUSY | : Message queue buffer full.
  BLESTACK_STATUS_SUCCESS | : Setting success.

## ◆ setBLE_ScanParam()

BleStackStatus setBLE_ScanParam | ( | BLE_Scan_Param * | scanParam | ) |

Set BLE Scanning Parameter

Remarks
  [BLELIB_NOCONN], [BLELIB_C], [BLELIB_PC]

Note
  Scan window can only be less than or equal to the scan interval.

Parameters

  [in] | scanParam | : a pointer to scanning parameter.

Return values

  BLESTACK_STATUS_ERR_NOT_SUPPORTED | : Command not supported.
  BLESTACK_STATUS_ERR_INVALID_STATE | : BLE stack has not initialized can ONLY be set while the device is not in scanning state.
  BLESTACK_STATUS_ERR_INVALID_PARAM | : Invalid parameter.
  BLESTACK_STATUS_ERR_BUSY | : Message queue buffer full.
  BLESTACK_STATUS_SUCCESS | : Setting success.

## ◆ setBLE_ScanRspData()

BleStackStatus setBLE_ScanRspData | ( | uint8_t * | scanRspData,
|  | uint8_t | length
| ) |  |

Set BLE Scan Response Data

Remarks
  [BLELIB_NOCONN], [BLELIB_P], [BLELIB_PC]

Note
  BLE scan response data length shall be less than or equal to 31 bytes, the input scanRspData length shall be less than or equal to 32 bytes.
  AD Type please refer to BLE Gap Data Type Formats

      ||----------------------------------------------------------------------------------------------------------------------------------------||
      ||                                         <length octets = (1+alength) octets>                                                           ||
      ||                                                     scanRspData                                                                        ||
      ||----------------------------------------------------------------------------------------------------------------------------------------||
      ||      <1 octet>              ||               <alength octets = (1+slength_1)+...+(1+slength_N)  octets>                                ||
      ||BLE scan response data length||                            BLE scan response data                                                       ||
      ||----------------------------------------------------------------------------------------------------------------------------------------||
      ||                             ||              AD Structure 1                 ||  ........ ||               AD Structure N                ||
      ||----------------------------------------------------------------------------------------------------------------------------------------||
      ||                             ||<1 octet>||      <slength_1 octets>          ||           ||<1 octet>||    <slength_N octets>            ||
      ||                             ||slength_1||              Data                ||  ........ ||slength_N||              Data                ||
      ||----------------------------------------------------------------------------------------------------------------------------------------||
      ||                             ||         ||<1 octets>||<(slength_1-1) octets>||           ||         ||<1 octets>||<(slength_N-1) octets>||
      ||                             ||         || AD Type  ||     AD Data          ||  ........ ||         || AD Type  ||     AD Data          ||
      ||----------------------------------------------------------------------------------------------------------------------------------------||

Parameters

  [in] | scanRspData | : a pointer to scan response data.
  [in] | length | : BLE scan response data.

Return values

  BLESTACK_STATUS_ERR_NOT_SUPPORTED | : Command not supported.
  BLESTACK_STATUS_ERR_INVALID_STATE | : BLE stack has not initialized.
  BLESTACK_STATUS_ERR_INVALID_PARAM | : Invalid parameter.
  BLESTACK_STATUS_ERR_BUSY | : Message queue buffer full.
  BLESTACK_STATUS_SUCCESS | : Setting success.

## ◆ setBLE_SecurityRequest()

BleStackStatus setBLE_SecurityRequest | ( | uint8_t | hostId | ) |

BLE Security Request

Remarks
  [BLELIB_P], [BLELIB_C], [BLELIB_PC]

BLE Event
  Wait for BLECMD_EVENT_AUTH_STATUS event which indicates the authentication status can be retrieved.

Parameters

  [in] | hostId | : the link's host id.

Return values

  BLESTACK_STATUS_ERR_NOT_SUPPORTED | : Command not supported.
  BLESTACK_STATUS_ERR_INVALID_HOSTID | : Invalid host id.
  BLESTACK_STATUS_ERR_INVALID_STATE | : Invalid BLE state, usually happens in BLE stack has not initialized or there is no connection established with the host id the link is already encrypted there is the same procedure has been processed.
  BLESTACK_STATUS_ERR_TIMER_BUSY | : The Security command timer is busy. Meaning there are still unfinished security events.
  BLESTACK_STATUS_ERR_BUSY | : Message queue buffer full.
  BLESTACK_STATUS_SUCCESS | : Setting success.

## ◆ setBLE_TxPower()

BleStackStatus setBLE_TxPower | ( | uint8_t | power_index,
|  | BleMode | bleMode
| ) |  |

Set BLE TX Power

Remarks
  [BLELIB_NOCONN], [BLELIB_P], [BLELIB_C], [BLELIB_PC]

Attention
  - Set advertising transmit power MUST before enable advertising.
  - Set scan transmit power MUST before enable scan.
  - Set initiator and connection transmit power MUST before connection creating.

Note
  Default TX power is set to the index "0" of "TXPOWER_TABLE" which is defined in "rf_power_definition.c".

Usage:
  If requested advertising TX power is +4 dBm please call API likes
  - setBLE_TxPower(TXPOWER_4DBM,STATE_BLE_ADVERTISING); // "TXPOWER_4DBM" defined in "rf_power_definition.h"

Parameters

  [in] | power_index | : requested TX power level in dBm, enter the index of TX power register table. The TX power register table please refer to "porting_rfpower.c".
  [in] | bleMode | : BLE mode. STATE_BLE_ADVERTISING : set advertising and connection transmit power for peripheral role. STATE_BLE_SCANNING : set scan transmit power. STATE_BLE_INITIATING : set initiator and connection transmit power.

Return values

  BLESTACK_STATUS_ERR_INVALID_STATE | : BLE stack has not initialized or in invalid BLE state for central role.
  BLESTACK_STATUS_ERR_INVALID_PARAM | : Invalid parameter.
  BLESTACK_STATUS_SUCCESS | : Setting success.

## ◆ setBLEGATT_ConfigCCCD()

BleStackStatus setBLEGATT_ConfigCCCD | ( | uint8_t | hostId,
|  | uint16_t | hdlNum,
|  | BleGattCCCDValue | cccdVal
| ) |  |

BLE GATT Configure CCCD(Client Characteristic Configuration Descriptor)

Remarks
  [BLELIB_C], [BLELIB_PC]

BLE Event
  Wait for OPCODE_ATT_WRITE_RESPONSE event if registered service/characteristic callback function.

Note
  This function supports for GATT role BLE_GATT_ROLE_CLIENT only.

Parameters

  [in] | hostId | : the link's host id.
  [in] | hdlNum | : cccd handle number.
  [in] | cccdVal | : CCCD value

Return values

  BLESTACK_STATUS_ERR_NOT_SUPPORTED | : Command not supported.
  BLESTACK_STATUS_ERR_INVALID_HOSTID | : Invalid host id.
  BLESTACK_STATUS_ERR_INVALID_PARAM | : Invalid parameter.
  BLESTACK_STATUS_ERR_DB_PARSING_IN_PROGRESS | : Service/ characteristic discovering or authentication/ authorization have not completed.
  BLESTACK_STATUS_ERR_INVALID_STATE | : BLE stack has not initialized or there is no connection established with the host id.
  BLESTACK_STATUS_ERR_SEQUENTIAL_PROTOCOL_VIOLATION | : Another GATT request already in progress please wait and retry.
  BLESTACK_STATUS_ERR_INVALID_HANDLE | : Invalid handle.
  BLESTACK_STATUS_ERR_BUSY | : Message queue buffer full.
  BLESTACK_STATUS_SUCCESS | : Setting success.

## ◆ setBLEGATT_ErrorRsp()

BleStackStatus setBLEGATT_ErrorRsp | ( | uint8_t | hostId,
|  | uint16_t | hdlNum,
|  | BleAttOpcode | opcode,
|  | BleAttErrorRsp | errRsp
| ) |  |

BLE GATT Set Error Response

Remarks
  [BLELIB_P], [BLELIB_PC]

Note
  The Error Response is used to state that a given request cannot be performed, and to provide the reason.

Parameters

  [in] | hostId | : the link's host id.
  [in] | hdlNum | : attribute handle in error.
  [in] | opcode | : attribute opcode in error.
  [in] | errRsp | : error code.

Return values

  BLESTACK_STATUS_ERR_NOT_SUPPORTED | : Command not supported.
  BLESTACK_STATUS_ERR_INVALID_HOSTID | : Invalid host id.
  BLESTACK_STATUS_ERR_INVALID_STATE | : BLE stack has not initialized or there is no connection established with the host id.
  BLESTACK_STATUS_ERR_INVALID_HANDLE | : Invalid handle.
  BLESTACK_STATUS_ERR_DB_PARSING_IN_PROGRESS | : Service/ characteristic discovering or authentication/ authorization have not completed.
  BLESTACK_STATUS_ERR_BUSY | : Message queue buffer full.
  BLESTACK_STATUS_SUCCESS | : Setting success.

## ◆ setBLEGATT_ExchangeMtuRequest()

BleStackStatus setBLEGATT_ExchangeMtuRequest | ( | uint8_t | hostId,
|  | uint16_t | clientRxMtu
| ) |  |

Set BLE Exchange MTU Request

Remarks
  [BLELIB_C], [BLELIB_PC]

BLE Event
  Wait for BLECMD_EVENT_EXCHANGE_MTU_SIZE event to get exchanged MTU size.

Attention
  This request shall only be sent once during a connection.

Note
  The range of input "clientRxMtu" is 23 ~ 247 bytes.
  This function supports for GATT role BLE_GATT_ROLE_CLIENT only.

Parameters

  [in] | hostId | : the link's host id.
  [in] | clientRxMtu | : client maximum receive MTU size.

Return values

  BLESTACK_STATUS_ERR_NOT_SUPPORTED | : Command not supported.
  BLESTACK_STATUS_ERR_INVALID_HOSTID | : Invalid host id.
  BLESTACK_STATUS_ERR_DB_PARSING_IN_PROGRESS | : Service/ characteristic discovering or authentication/ authorization have not completed.
  BLESTACK_STATUS_ERR_INVALID_CMD | : Invalid command, usually happens in requesting the command over 1 times.
  BLESTACK_STATUS_ERR_INVALID_STATE | : BLE stack has not initialized or there is no connection established with the host id.
  BLESTACK_STATUS_ERR_BUSY | : Message queue buffer full.
  BLESTACK_STATUS_SUCCESS | : Setting success.

## ◆ setBLEGATT_ExecuteWrite()

BleStackStatus setBLEGATT_ExecuteWrite | ( | uint8_t | hostId,
|  | uint16_t | hdlNum,
|  | uint8_t | flag
| ) |  |

BLE GATT Execute Write A Characteristic Value to A Server Data Queue (Execute Write Request)

Remarks
  [BLELIB_C], [BLELIB_PC]

BLE Event
  Wait for OPCODE_ATT_EXECUTE_WRITE_RESPONSE event if registered service/characteristic callback function.

Note
  The Execute Write Request is used to request the server to write or cancel the write of all the prepared values currently held in the prepare queue from this client.
  The Execute Write Response shall be sent after the attributes are written with the Data Queue succeeded.
  This function supports for GATT role BLE_GATT_ROLE_CLIENT only.

Parameters

  [in] | hostId | : the link's host id.
  [in] | hdlNum | : characteristic value handle.
  [in] | flag | : 0x00: all pending prepare write values shall be discarded for this client, 0x01: writ values that were queued by the previous prepare write requests.

Return values

  BLESTACK_STATUS_ERR_NOT_SUPPORTED | : Command not supported.
  BLESTACK_STATUS_ERR_INVALID_HOSTID | : Invalid host id.
  BLESTACK_STATUS_ERR_INVALID_STATE | : BLE stack has not initialized or there is no connection established with the host id.
  BLESTACK_STATUS_ERR_DB_PARSING_IN_PROGRESS | : Service/ characteristic discovering or authentication/ authorization have not completed.
  BLESTACK_STATUS_ERR_INVALID_HANDLE | : Invalid handle.
  BLESTACK_STATUS_ERR_SEQUENTIAL_PROTOCOL_VIOLATION | : Another GATT request already in progress please wait and retry.
  BLESTACK_STATUS_ERR_BUSY | : Message queue buffer full.
  BLESTACK_STATUS_SUCCESS | : Setting success.

## ◆ setBLEGATT_GeneralReadRsp()

BleStackStatus setBLEGATT_GeneralReadRsp | ( | uint8_t | hostId,
|  | uint16_t | hdlNum,
|  | uint8_t * | data,
|  | uint16_t | length
| ) |  |

BLE GATT Automatically Set Characteristic Read Response or Read By Type Response

Remarks
  [BLELIB_P], [BLELIB_PC]

Note
  This function supports for GATT role BLE_GATT_ROLE_SERVER only.

Parameters

  [in] | hostId | : the link's host id.
  [in] | hdlNum | : characteristic value handle.
  [in] | data | : data to set.
  [in] | length | : the length of data.

Return values

  BLESTACK_STATUS_ERR_NOT_SUPPORTED | : Command not supported.
  BLESTACK_STATUS_ERR_INVALID_HOSTID | : Invalid host id.
  BLESTACK_STATUS_ERR_DB_PARSING_IN_PROGRESS | : Service/ characteristic discovering or authentication/ authorization have not completed.
  BLESTACK_STATUS_ERR_INVALID_STATE | : BLE stack has not initialized or there is no connection established with the host id.
  BLESTACK_STATUS_ERR_INVALID_HANDLE | : Invalid handle.
  BLESTACK_STATUS_ERR_BUSY | : Message queue buffer full.
  BLESTACK_STATUS_SUCCESS | : Setting success.

## ◆ setBLEGATT_Indication()

BleStackStatus setBLEGATT_Indication | ( | uint8_t | hostId,
|  | uint16_t | hdlNum,
|  | uint8_t * | data,
|  | uint16_t | length
| ) |  |

BLE GATT Indicate the Attribute Value

Remarks
  [BLELIB_P], [BLELIB_PC]

BLE Event
  Wait for OPCODE_ATT_HANDlE_VAlUE_CONFIRMATION event if registered service/characteristic callback function.

Note
  When a server is configured to indicate a Characteristic Value to a client and expects the indication was successfully received.
  This function supports for GATT role BLE_GATT_ROLE_SERVER only.

Parameters

  [in] | hostId | : the link's host id.
  [in] | hdlNum | : characteristic value handle.
  [in] | data | : data to transmit.
  [in] | length | : the length of data.

Return values

  BLESTACK_STATUS_ERR_NOT_SUPPORTED | : Command not supported.
  BLESTACK_STATUS_ERR_INVALID_HOSTID | : Invalid host id.
  BLESTACK_STATUS_ERR_INVALID_STATE | : BLE stack has not initialized or there is no connection established with the host id.
  BLESTACK_STATUS_ERR_INVALID_HANDLE | : Invalid handle.
  BLESTACK_STATUS_ERR_DB_PARSING_IN_PROGRESS | : Service/ characteristic discovering or authentication/ authorization have not completed.
  BLESTACK_STATUS_ERR_SEQUENTIAL_PROTOCOL_VIOLATION | : Another GATT request already in progress please wait and retry.
  BLESTACK_STATUS_ERR_INVALID_PARAM | : Invalid parameter, please check the maximum length of data.
  BLESTACK_STATUS_ERR_BUSY | : Message queue buffer full.
  BLESTACK_STATUS_SUCCESS | : Setting success.

## ◆ setBLEGATT_Notification()

BleStackStatus setBLEGATT_Notification | ( | uint8_t | hostId,
|  | uint16_t | hdlNum,
|  | uint8_t * | data,
|  | uint16_t | length
| ) |  |

BLE GATT Notify the Attribute Value

Remarks
  [BLELIB_P], [BLELIB_PC]

Note
  When a server is configured to notify a Characteristic Value to a client without the acknowledgment that the notification was successfully received.
  This function supports for GATT role BLE_GATT_ROLE_SERVER only.

Parameters

  [in] | hostId | : the link's host id.
  [in] | hdlNum | : characteristic value handle.
  [in] | data | : data to transmit.
  [in] | length | : the length of data.

Return values

  BLESTACK_STATUS_ERR_NOT_SUPPORTED | : Command not supported.
  BLESTACK_STATUS_ERR_INVALID_HOSTID | : Invalid host id.
  BLESTACK_STATUS_ERR_INVALID_STATE | : BLE stack has not initialized or there is no connection established with the host id.
  BLESTACK_STATUS_ERR_INVALID_HANDLE | : Invalid handle.
  BLESTACK_STATUS_ERR_DB_PARSING_IN_PROGRESS | : Service/ characteristic discovering or authentication/ authorization have not completed.
  BLESTACK_STATUS_ERR_INVALID_PARAM | : Invalid parameter, please check the maximum length of data.
  BLESTACK_STATUS_ERR_BUSY | : Message queue buffer full.
  BLESTACK_STATUS_SUCCESS | : Setting success.

## ◆ setBLEGATT_PreferredMtuSize()

BleStackStatus setBLEGATT_PreferredMtuSize | ( | uint8_t | hostId,
|  | uint16_t | preferredRxMtu
| ) |  |

Set BLE Preferred MTU Size

Remarks
  [BLELIB_P], [BLELIB_PC]

Attention
  The default BLE Preferred MTU Size is set to 23.

Note
  The range of input "preferredRxMtu" is 23 ~ 247 bytes.
  This function supports for GATT role BLE_GATT_ROLE_SERVER only.

Parameters

  [in] | hostId | : the link's host id.
  [in] | preferredRxMtu | : preferred Rx MTU size.

Return values

  BLESTACK_STATUS_ERR_NOT_SUPPORTED | : Command not supported.
  BLESTACK_STATUS_ERR_INVALID_HOSTID | : Error host id.
  BLESTACK_STATUS_ERR_INVALID_STATE | : BLE stack has not initialized or can ONLY be set while in connection state.
  BLESTACK_STATUS_ERR_INVALID_PARAM | : Invalid parameter.
  BLESTACK_STATUS_SUCCESS | : Setting success.

## ◆ setBLEGATT_PrepareWrite()

BleStackStatus setBLEGATT_PrepareWrite | ( | uint8_t | hostId,
|  | uint16_t | hdlNum,
|  | uint8_t * | data,
|  | uint16_t | length
| ) |  |

BLE GATT Prepare Write A Characteristic Value to A Server Data Queue (Prepare Write Request)

Remarks
  [BLELIB_C], [BLELIB_PC]

BLE Event
  Wait for OPCODE_ATT_PREPARE_WRITE_RESPONSE event if registered service/characteristic callback function.

Note
  The Prepare Write Request is used to request the server to prepare to write the value of an attribute. The server will respond to this request with a Prepare Write Response, so that the client can verify that the value was received correctly.
  A Prepare Write Response shall be sent by the server if the write of the Data Queue succeeded.
  This function supports for GATT role BLE_GATT_ROLE_CLIENT only.

Parameters

  [in] | hostId | : the link's host id.
  [in] | hdlNum | : characteristic value handle.
  [in] | data | : data to transmit (with a 16bit Value Offset at beginning). i.e. offset = 0x01, data = [0x0A,0x0B] data = [0x01,0x00,0x0A,0x0B]
  [in] | length | : the length of data (include the 16bit Value Offset, 2 byte).

Return values

  BLESTACK_STATUS_ERR_NOT_SUPPORTED | : Command not supported.
  BLESTACK_STATUS_ERR_INVALID_HOSTID | : Invalid host id.
  BLESTACK_STATUS_ERR_INVALID_STATE | : BLE stack has not initialized or there is no connection established with the host id.
  BLESTACK_STATUS_ERR_DB_PARSING_IN_PROGRESS | : Service/ characteristic discovering or authentication/ authorization have not completed.
  BLESTACK_STATUS_ERR_INVALID_HANDLE | : Invalid handle.
  BLESTACK_STATUS_ERR_SEQUENTIAL_PROTOCOL_VIOLATION | : Another GATT request already in progress please wait and retry.
  BLESTACK_STATUS_ERR_INVALID_PARAM | : Invalid parameter, please check the maximum length of data.
  BLESTACK_STATUS_ERR_BUSY | : Message queue buffer full.
  BLESTACK_STATUS_SUCCESS | : Setting success.

## ◆ setBLEGATT_ReadBlobRsp()

BleStackStatus setBLEGATT_ReadBlobRsp | ( | uint8_t | hostId,
|  | uint16_t | hdlNum,
|  | uint8_t * | data,
|  | uint16_t | length
| ) |  |

BLE GATT Set Characteristic Read Blob Response

Remarks
  [BLELIB_P], [BLELIB_PC]

Note
  The read blob response is sent in reply to a received Read Blob Request and contains the value of the attribute that has been read.
  This function supports for GATT role BLE_GATT_ROLE_SERVER only.

Parameters

  [in] | hostId | : the link's host id.
  [in] | hdlNum | : characteristic value handle.
  [in] | data | : data to set.
  [in] | length | : the length of data.

Return values

  BLESTACK_STATUS_ERR_NOT_SUPPORTED | : Command not supported.
  BLESTACK_STATUS_ERR_INVALID_HOSTID | : Invalid host id.
  BLESTACK_STATUS_ERR_DB_PARSING_IN_PROGRESS | : Service/ characteristic discovering or authentication/ authorization have not completed.
  BLESTACK_STATUS_ERR_INVALID_STATE | : BLE stack has not initialized or there is no connection established with the host id.
  BLESTACK_STATUS_ERR_INVALID_HANDLE | : Invalid handle.
  BLESTACK_STATUS_ERR_BUSY | : Message queue buffer full.
  BLESTACK_STATUS_SUCCESS | : Setting success.

## ◆ setBLEGATT_ReadByTypeRsp()

BleStackStatus setBLEGATT_ReadByTypeRsp | ( | uint8_t | hostId,
|  | uint16_t | hdlNum,
|  | uint8_t * | data,
|  | uint16_t | length
| ) |  |

BLE GATT Set Characteristic Read By Type Response

Remarks
  [BLELIB_P], [BLELIB_PC]

Note
  The read by type response is sent in reply to a received Read By Type Request and contains the handle number and value of the attribute that has been read.
  This function supports for GATT role BLE_GATT_ROLE_SERVER only.

Parameters

  [in] | hostId | : the link's host id.
  [in] | hdlNum | : characteristic value handle.
  [in] | data | : data to set.
  [in] | length | : the length of data.

Return values

  BLESTACK_STATUS_ERR_NOT_SUPPORTED | : Command not supported.
  BLESTACK_STATUS_ERR_INVALID_HOSTID | : Invalid host id.
  BLESTACK_STATUS_ERR_DB_PARSING_IN_PROGRESS | : Service/ characteristic discovering or authentication/ authorization have not completed.
  BLESTACK_STATUS_ERR_INVALID_STATE | : BLE stack has not initialized or there is no connection established with the host id.
  BLESTACK_STATUS_ERR_INVALID_HANDLE | : Invalid handle.
  BLESTACK_STATUS_ERR_BUSY | : Message queue buffer full.
  BLESTACK_STATUS_SUCCESS | : Setting success.

## ◆ setBLEGATT_ReadCharacteristicValue()

BleStackStatus setBLEGATT_ReadCharacteristicValue | ( | uint8_t | hostId,
|  | uint16_t | hdlNum
| ) |  |

BLE GATT Read Characteristic Value (Read Request)

Remarks
  [BLELIB_C], [BLELIB_PC]

BLE Event
  Wait for OPCODE_ATT_READ_RESPONSE event if registered service/characteristic callback function.

Note
  Read a Characteristic Value from a server when the client knows the Characteristic Value Handle.
  This function supports for GATT role BLE_GATT_ROLE_CLIENT only.

Parameters

  [in] | hostId | : the link's host id.
  [in] | hdlNum | : characteristic value handle.

Return values

  BLESTACK_STATUS_ERR_NOT_SUPPORTED | : Command not supported.
  BLESTACK_STATUS_ERR_INVALID_HOSTID | : Invalid host id.
  BLESTACK_STATUS_ERR_NOT_SUPPORTED | : Invalid GATT role or no reading attribute definition, only supports for client.
  BLESTACK_STATUS_ERR_INVALID_STATE | : BLE stack has not initialized or there is no connection established with the host id.
  BLESTACK_STATUS_ERR_DB_PARSING_IN_PROGRESS | : Service/ characteristic discovering or authentication/ authorization have not completed.
  BLESTACK_STATUS_ERR_INVALID_HANDLE | : Invalid handle.
  BLESTACK_STATUS_ERR_SEQUENTIAL_PROTOCOL_VIOLATION | : Another GATT request already in progress please wait and retry.
  BLESTACK_STATUS_ERR_BUSY | : Message queue buffer full.
  BLESTACK_STATUS_SUCCESS | : Setting success.

## ◆ setBLEGATT_ReadLongCharacteristicValue()

BleStackStatus setBLEGATT_ReadLongCharacteristicValue | ( | uint8_t | hostId,
|  | uint16_t | hdlNum,
|  | uint16_t | Offset
| ) |  |

BLE GATT Read Long Characteristic Value (Read Blob Request)

Remarks
  [BLELIB_C], [BLELIB_PC]

BLE Event
  Wait for OPCODE_ATT_READ_BLOB_RESPONSE event if registered service/characteristic callback function.

Note
  read part of the value of an attribute at a given offset from a server when the client knows the Characteristic Value Handle.
  This function supports for GATT role BLE_GATT_ROLE_CLIENT only.

Parameters

  [in] | hostId | : the link's host id.
  [in] | hdlNum | : characteristic value handle.
  [in] | hdlNum | : characteristic value handle.

Return values

  BLESTACK_STATUS_ERR_NOT_SUPPORTED | : Command not supported.
  BLESTACK_STATUS_ERR_INVALID_HOSTID | : Invalid host id.
  BLESTACK_STATUS_ERR_NOT_SUPPORTED | : Invalid GATT role or no reading attribute definition, only supports for client.
  BLESTACK_STATUS_ERR_INVALID_STATE | : BLE stack has not initialized or there is no connection established with the host id.
  BLESTACK_STATUS_ERR_DB_PARSING_IN_PROGRESS | : Service/ characteristic discovering or authentication/ authorization have not completed.
  BLESTACK_STATUS_ERR_INVALID_HANDLE | : Invalid handle.
  BLESTACK_STATUS_ERR_SEQUENTIAL_PROTOCOL_VIOLATION | : Another GATT request already in progress please wait and retry.
  BLESTACK_STATUS_ERR_BUSY | : Message queue buffer full.
  BLESTACK_STATUS_SUCCESS | : Setting success.

## ◆ setBLEGATT_ReadRsp()

BleStackStatus setBLEGATT_ReadRsp | ( | uint8_t | hostId,
|  | uint16_t | hdlNum,
|  | uint8_t * | data,
|  | uint16_t | length
| ) |  |

BLE GATT Set Characteristic Read Response

Remarks
  [BLELIB_P], [BLELIB_PC]

Note
  The read response is sent in reply to a received Read Request and contains the value of the attribute that has been read.
  This function supports for GATT role BLE_GATT_ROLE_SERVER only.

Parameters

  [in] | hostId | : the link's host id.
  [in] | hdlNum | : characteristic value handle.
  [in] | data | : data to set.
  [in] | length | : the length of data.

Return values

  BLESTACK_STATUS_ERR_NOT_SUPPORTED | : Command not supported.
  BLESTACK_STATUS_ERR_INVALID_HOSTID | : Invalid host id.
  BLESTACK_STATUS_ERR_DB_PARSING_IN_PROGRESS | : Service/ characteristic discovering or authentication/ authorization have not completed.
  BLESTACK_STATUS_ERR_INVALID_STATE | : BLE stack has not initialized or there is no connection established with the host id.
  BLESTACK_STATUS_ERR_INVALID_HANDLE | : Invalid handle.
  BLESTACK_STATUS_ERR_BUSY | : Message queue buffer full.
  BLESTACK_STATUS_SUCCESS | : Setting success.

## ◆ setBLEGATT_ReparseAttDatabase()

BleStackStatus setBLEGATT_ReparseAttDatabase | ( | uint8_t | hostId | ) |

BLE Re-parse attribute database

Remarks
  [BLELIB_C], [BLELIB_PC]

BLE Event
  Wait for BLECMD_EVENT_ATT_DATABASE_PARSING_FINISHED event to get the result of the process.

Note
  This function supports for GATT role BLE_GATT_ROLE_CLIENT only.

Parameters

  [in] | hostId | the link's host id.

Return values

  BLESTACK_STATUS_ERR_NOT_SUPPORTED | : Command not supported.
  BLESTACK_STATUS_ERR_INVALID_HOSTID | : Invalid host id.
  BLESTACK_STATUS_ERR_INVALID_STATE | : BLE stack has not initialized or there is no connection established with the host id.
  BLESTACK_STATUS_ERR_DB_PARSING_IN_PROGRESS | : Already in Attribute database parsing process.
  BLESTACK_STATUS_SUCCESS | : Setting success.

## ◆ setBLEGATT_Write()

BleStackStatus setBLEGATT_Write | ( | uint8_t | hostId,
|  | uint16_t | hdlNum,
|  | uint8_t * | data,
|  | uint16_t | length
| ) |  |

BLE GATT Write A Characteristic Value to A Server (Write Request)

Remarks
  [BLELIB_C], [BLELIB_PC]

BLE Event
  Wait for OPCODE_ATT_WRITE_RESPONSE event if registered service/characteristic callback function.

Note
  The Write Request is used to request the server to write the value of an attribute and acknowledge that this has been achieved in a Write Response.
  A Write Response shall be sent by the server if the write of the Characteristic Value succeeded.
  This function supports for GATT role BLE_GATT_ROLE_CLIENT only.

Parameters

  [in] | hostId | : the link's host id.
  [in] | hdlNum | : characteristic value handle.
  [in] | data | : data to transmit.
  [in] | length | : the length of data.

Return values

  BLESTACK_STATUS_ERR_NOT_SUPPORTED | : Command not supported.
  BLESTACK_STATUS_ERR_INVALID_HOSTID | : Invalid host id.
  BLESTACK_STATUS_ERR_INVALID_STATE | : BLE stack has not initialized or there is no connection established with the host id.
  BLESTACK_STATUS_ERR_DB_PARSING_IN_PROGRESS | : Service/ characteristic discovering or authentication/ authorization have not completed.
  BLESTACK_STATUS_ERR_INVALID_HANDLE | : Invalid handle.
  BLESTACK_STATUS_ERR_SEQUENTIAL_PROTOCOL_VIOLATION | : Another GATT request already in progress please wait and retry.
  BLESTACK_STATUS_ERR_INVALID_PARAM | : Invalid parameter, please check the maximum length of data.
  BLESTACK_STATUS_ERR_BUSY | : Message queue buffer full.
  BLESTACK_STATUS_SUCCESS | : Setting success.

## ◆ setBLEGATT_WriteWithoutRsp()

BleStackStatus setBLEGATT_WriteWithoutRsp | ( | uint8_t | hostId,
|  | uint16_t | hdlNum,
|  | uint8_t * | data,
|  | uint16_t | length
| ) |  |

BLE GATT Write A Characteristic Value to A Server (Write Without Response Request)

Remarks
  [BLELIB_C], [BLELIB_PC]

Note
  Write a Characteristic Value to a server when the client knows the Characteristic Value Handle
  and the client does not need an acknowledgment that the write was successfully performed.
  This function supports for GATT role BLE_GATT_ROLE_CLIENT only.

Parameters

  [in] | hostId | : the link's host id.
  [in] | hdlNum | : characteristic value handle.
  [in] | data | : data to transmit.
  [in] | length | : the length of data.

Return values

  BLESTACK_STATUS_ERR_NOT_SUPPORTED | : Command not supported.
  BLESTACK_STATUS_ERR_INVALID_HOSTID | : Invalid host id.
  BLESTACK_STATUS_ERR_INVALID_STATE | : BLE stack has not initialized or there is no connection established with the host id.
  BLESTACK_STATUS_ERR_DB_PARSING_IN_PROGRESS | : Service/ characteristic discovering or authentication/ authorization have not completed.
  BLESTACK_STATUS_ERR_INVALID_HANDLE | : Invalid handle.
  BLESTACK_STATUS_ERR_INVALID_PARAM | : Invalid parameter, please check the maximum length of data.
  BLESTACK_STATUS_ERR_BUSY | : Message queue buffer full.
  BLESTACK_STATUS_SUCCESS | : Setting success.