Import of the watch repository from Pebble

src/fw/applib/bluetooth/ble_ad_parse.h

@@ -0,0 +1,206 @@
+/*
+ * Copyright 2024 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#pragma once
+
+#include <bluetooth/bluetooth_types.h>
+
+//! @file ble_ad_parse.h
+//! API to serialize and deserialize advertisment and scan response payloads.
+//!
+//! Inbound payloads, as received using the ble_scan.h public API, can be
+//! consumed/deserialized using the functions below.
+//!
+//! Outbound payloads can be created/serialized and then advertised using the
+//! gap_le_advert.h functions. At the moment, there is no public API.
+
+// -----------------------------------------------------------------------------
+// Consuming BLEAdData:
+// -----------------------------------------------------------------------------
+
+//! Searching the advertisement data to check whether a given service UUID is
+//! included.
+//! @param ad The advertisement data
+//! @param service_uuid The UUID of the service to look for
+//! @return true if the service UUID was found, false if not
+bool ble_ad_includes_service(const BLEAdData *ad, const Uuid *service_uuid);
+
+//! If present, copies the Service UUIDs from the advertisement data.
+//! @param ad The advertisement data
+//! @param[out] uuids_out An array of Uuid`s into which the found Service UUIDs
+//! will be copied.
+//! @param num_uuids The size of the uuids_out array.
+//! @return The total number of found Service UUIDs. This might be a larger
+//! number than num_uuids, if the passed array was not large enough to hold all
+//! the UUIDs.
+//! @note All UUIDs from advertisement data will be converted to their 128-bit
+//! equivalents using the Bluetooth Base UUID using bt_uuid_expand_16bit or
+//! bt_uuid_expand_32bit.
+//! @see ble_ad_get_number_of_service_uuids
+uint8_t ble_ad_copy_service_uuids(const BLEAdData *ad,
+                                  Uuid *uuids_out,
+                                  uint8_t num_uuids);
+
+//! If present, returns the number of Service UUIDs the advertisement data
+//! contains.
+//! @param ad The advertisement data
+//! @return If Service UUIDs data is present, the number of UUIDs is contains,
+//! or zero otherwise.
+uint8_t ble_ad_get_number_of_service_uuids(const BLEAdData *ad);
+
+//! If present, gets the TX Power Level from the advertisement data.
+//! @param ad The advertisement data
+//! @param[out] tx_power_level_out Will contain the TX Power Level if the return
+//! value is true.
+//! @return true if the TX Power Level was found and assigned.
+bool ble_ad_get_tx_power_level(const BLEAdData *ad, int8_t *tx_power_level_out);
+
+//! If present, copies the Local Name from the advertisement data.
+//! If the Local Name is bigger than the size of the buffer, only the part that
+//! fits will be copied. For convenience, the copied c-string will always be
+//! zero terminated for you.
+//! @param ad The advertisement data
+//! @param buffer The buffer into which to copy the Local Name, if found.
+//! @param size The size of the buffer
+//! @return The size of the Local Name in bytes, *including* zero terminator.
+//! Note that this might be more than the size of the provided buffer.
+//! If the Local Name was not found, the return value will be zero.
+size_t ble_ad_copy_local_name(const BLEAdData *ad,
+                              char *buffer, size_t size);
+
+//! If the Local Name is present in the advertisment data, returns the number
+//! of bytes a C-string needs to be to hold the full name.
+//! @param ad The advertisement data
+//! @return The size of the Local Name in bytes, *including* zero terminator.
+//! If the Local Name is not present, zero is returned.
+size_t ble_ad_get_local_name_buffer_size(const BLEAdData *ad);
+
+//! If present, copies the Manufacturer Specific data from the advertisement
+//! data. If the provided buffer is smaller than the size of the data, only
+//! the data up that fits the buffer will be copied.
+//! @param ad The advertisement data
+//! @param[out] company_id_out Out: The Company Identifier Code, see
+//! https://www.bluetooth.org/en-us/specification/assigned-numbers/company-identifiers
+//! This will only get written, if there was Manufacturer Specific data in the
+//! advertisement. In case you are not interested in getting the company ID,
+//! NULL can be passed in.
+//! @param buffer The buffer into which to copy the Manufacturer Specific Data,
+//! if found.
+//! @param size The size of the buffer
+//! @return The size of the Manufacturer Specific data in bytes. Note that this
+//! can be larger than the size of the provided buffer. If the Manufacturer
+//! Specific data was not found, the return value will be zero.
+//! @see ble_ad_get_manufacturer_specific_data_size
+size_t ble_ad_copy_manufacturer_specific_data(const BLEAdData *ad,
+                                              uint16_t *company_id_out,
+                                              uint8_t *buffer, size_t size);
+
+//! Gets the size in bytes of Manufacturer Specific data in the advertisment.
+//! @param ad The advertisement data
+//! @return The size of the data, in bytes. If the Manufacturer Specific data is
+//! not present, zero is returned.
+size_t ble_ad_get_manufacturer_specific_data_size(const BLEAdData *ad);
+
+//! Gets the size in bytes of the raw advertisement and scan response data.
+//! @param ad The advertisement data
+//! @return The size of the raw advertisement and scan response data in bytes.
+size_t ble_ad_get_raw_data_size(const BLEAdData *ad);
+
+//! Copies the raw bytes of advertising and scan response data into a buffer.
+//! If there was scan response data, it will be concatenated directly after the
+//! advertising data.
+//! @param ad The advertisement data
+//! @param buffer The buffer into which to copy the raw bytes
+//! @param size The size of the buffer
+//! @return The number of bytes copied.
+size_t ble_ad_copy_raw_data(const BLEAdData *ad, uint8_t *buffer, size_t size);
+
+
+// -----------------------------------------------------------------------------
+// Creating BLEAdData:
+// -----------------------------------------------------------------------------
+
+//! Creates a blank, mutable advertisement and scan response payload.
+//! It can contain up to 31 bytes of advertisement data and up to 31 bytes of
+//! scan response data. The underlying storage for this is automatically
+//! allocated.
+//! @note When adding elements to the BLEAdData, using the ble_ad_set_...
+//! functions, elements will be added to the advertisement data part first.
+//! If the element to add does not fit, the scan response is automatically
+//! used. Added elements cannot span across the two parts.
+//! @return The blank payload object.
+//! @note BLEAdData created with this function must be destroyed at some point
+//! in time using ble_ad_destroy()
+//! @note Use the ble_ad_set... functions to write data into the object. The
+//! data written to it will occupy the advertisement payload until there is not
+//! enough space left, in which case all following data is written into the scan
+//! response. @see ble_ad_start_scan_response()
+BLEAdData* ble_ad_create(void);
+
+//! Destroys an advertisement payload that was created earlier with
+//! ble_ad_create().
+void ble_ad_destroy(BLEAdData *ad);
+
+//! Marks the start of the scan response and finalizes the advertisement
+//! payload. This forces successive writes to be written to the scan response,
+//! even though it would have fit into the advertisement payload.
+void ble_ad_start_scan_response(BLEAdData *ad_data);
+
+//! Writes the Service UUID list to the advertisement or scan response payload.
+//! The list is assumed to be the complete list of Service UUIDs.
+//! @param ad The advertisement payload as created earlier by ble_ad_create()
+//! @param uuids Array of UUIDs to add to the list. If the UUIDs are all derived
+//! from the Bluetooth SIG base UUID, this function will automatically use
+//! a smaller Service UUID size if possible.
+//! @see bt_uuid_expand_16bit
+//! @see bt_uuid_expand_32bit
+//! @param num_uuids Number of UUIDs in the uuids array.
+//! @return true if the data was successfully written or false if not.
+bool ble_ad_set_service_uuids(BLEAdData *ad,
+                              const Uuid uuids[], uint8_t num_uuids);
+
+//! Writes the Local Name to the advertisement or scan response payload.
+//! @param ad The advertisement payload as created earlier by ble_ad_create()
+//! @param local_name Zero terminated, UTF-8 string with the Local Name. The
+//! name is assumed to be complete and not abbreviated.
+//! @return true if the data was successfully written or false if not.
+bool ble_ad_set_local_name(BLEAdData *ad,
+                           const char *local_name);
+
+//! Writes the TX Power Level to advertisement or scan response payload.
+//! The actual transmission power level value is set automatically, based on the
+//! value as used by the Bluetooth hardware.
+//! @param ad The advertisement payload as created earlier by ble_ad_create()
+//! @return true if the data was successfully written or false if not.
+bool ble_ad_set_tx_power_level(BLEAdData *ad);
+
+//! Writes Manufacturer Specific Data to advertisement or scan response payload.
+//! @param ad The advertisement payload as created earlier by ble_ad_create()
+//! @param company_id The Company Identifier Code, see
+//! https://www.bluetooth.org/en-us/specification/assigned-numbers/company-identifiers
+//! @param data The data
+//! @param size The size of data in bytes
+//! @return true if the data was successfully written or false if not.
+bool ble_ad_set_manufacturer_specific_data(BLEAdData *ad,
+                                           uint16_t company_id,
+                                           const uint8_t *data, size_t size);
+
+//! @internal -- Do not export
+//! Writes the Flags AD Type to the advertisement or scan response payload.
+//! @param ad The advertisement payload as created earlier by ble_ad_create()
+//! @param flags The flags to write. See Core_v4.0.pdf Vol 3, Appendix C, 18.1.
+//! @return true if the data was successfully written or false if not.
+bool ble_ad_set_flags(BLEAdData *ad, uint8_t flags);