AdvertisingDataBuilder.h

00001 /* mbed Microcontroller Library
00002  * Copyright (c) 2006-2013 ARM Limited
00003  *
00004  * Licensed under the Apache License, Version 2.0 (the "License");
00005  * you may not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  *
00008  *     http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 
00017 #ifndef MBED_GAP_ADVERTISING_DATA_H__
00018 #define MBED_GAP_ADVERTISING_DATA_H__
00019 
00020 #include <stdint.h>
00021 #include <string.h>
00022 #include <stdlib.h>
00023 
00024 #include "ble/BLETypes.h"
00025 #include "platform/NonCopyable.h"
00026 
00027 #include "ble/blecommon.h"
00028 #include "UUID.h "
00029 #include "ble/gap/AdvertisingDataTypes.h"
00030 #include "ble/gap/Types.h"
00031 
00032 namespace ble {
00033 
00034 /**
00035  * @addtogroup ble
00036  * @{
00037  * @addtogroup gap
00038  * @{
00039  */
00040 
00041 /**
00042  * Build advertising data.
00043  *
00044  * The builder accepts an array of bytes in input and returns the result of the
00045  * construction with getAdvertisingData().
00046  */
00047 class AdvertisingDataBuilder {
00048 public:
00049     /** Advertising data needs a user-provided buffer to store the data.
00050      *
00051      * @param buffer Buffer used to store the data.
00052      * @note Use Gap::getMaxAdvertisingDataLength() to find out how much can be accepted.
00053      */
00054     AdvertisingDataBuilder(mbed::Span<uint8_t>  buffer);
00055 
00056     /** Advertising data needs a user provided buffer to store the data.
00057      *
00058      * @param buffer Pointer to buffer to be used for storing advertising data.
00059      * @param buffer_size Size of the buffer.
00060      * @note Use Gap::getMaxAdvertisingDataLength() to find out how much can be accepted.
00061      */
00062     AdvertisingDataBuilder(uint8_t *buffer, size_t buffer_size);
00063 
00064     /**
00065      * Get the subspan of the buffer containing valid data.
00066      *
00067      * @return A Span containing the payload.
00068      */
00069     mbed::Span<const uint8_t>  getAdvertisingData() const;
00070 
00071     /**
00072      * Add a new field into the payload. Returns an error if type is already present.
00073      *
00074      * @note Data size for individual types cannot exceed 255 bytes.
00075      *
00076      * @param[in] advDataType The type of the field to add.
00077      * @param[in] fieldData Span of data to add.
00078      *
00079      * @retval BLE_ERROR_NONE on success.
00080      * @retval BLE_ERROR_BUFFER_OVERFLOW if buffer is too small to contain the new data.
00081      * @retval BLE_ERROR_OPERATION_NOT_PERMITTED if data type already present.
00082      * @retval BLE_ERROR_INVALID_PARAM if size of data is too big too fit in an individual data field.
00083      */
00084     ble_error_t addData(
00085         adv_data_type_t  advDataType,
00086         mbed::Span<const uint8_t>  fieldData
00087     );
00088 
00089     /**
00090      * Replace a new field into the payload. Will fail if type is not already present.
00091      *
00092      * @note Data size for individual types cannot exceed 255 bytes.
00093      *
00094      * @param[in] advDataType The type of the field to add.
00095      * @param[in] fieldData Span of data to add.
00096      *
00097      * @retval BLE_ERROR_NONE on success.
00098      * @retval BLE_ERROR_BUFFER_OVERFLOW if buffer is too small to contain the new data.
00099      * @retval BLE_ERROR_NOT_FOUND if data type not present.
00100      * @retval BLE_ERROR_INVALID_PARAM if size of data is too big too fit in an individual data field.
00101      */
00102     ble_error_t replaceData(
00103         adv_data_type_t  advDataType,
00104         mbed::Span<const uint8_t>  fieldData
00105     );
00106 
00107     /**
00108      * Append data to an existing field in the payload. Will fail if type is not already
00109      * present.
00110      *
00111      * @note Data size for individual types cannot exceed 255 bytes.
00112      *
00113      * @param[in] advDataType The type of the field to add.
00114      * @param[in] fieldData Span of data to add.
00115      *
00116      * @retval BLE_ERROR_NONE on success.
00117      * @retval BLE_ERROR_BUFFER_OVERFLOW if buffer is too small to contain the new data.
00118      * @retval BLE_ERROR_NOT_FOUND if data type not present.
00119      * @retval BLE_ERROR_INVALID_PARAM if size of data is too big too fit in an individual data field.
00120      */
00121     ble_error_t appendData(
00122         adv_data_type_t  advDataType,
00123         mbed::Span<const uint8_t>  fieldData
00124     );
00125 
00126     /**
00127      * Remove existing date of given type. Will return an error if type is not present.
00128      *
00129      * @param[in] advDataType The type of the field to remove.
00130      *
00131      * @return BLE_ERROR_NONE returned on success, BLE_ERROR_INVALID_PARAM if field doesn't exist
00132      */
00133     ble_error_t removeData(adv_data_type_t  advDataType);
00134 
00135     /**
00136      * Adds a new field into the payload. If the supplied advertising data type is
00137      * already present in the advertising payload, then the value is replaced.
00138      *
00139      * @note Data size for individual types cannot exceed 255 bytes.
00140      *
00141      * @param[in] advDataType The type of the field to add.
00142      * @param[in] fieldData Span of data to add.
00143      *
00144      * @retval BLE_ERROR_NONE on success.
00145      * @retval BLE_ERROR_BUFFER_OVERFLOW if buffer is too small to contain the new data.
00146      * @retval BLE_ERROR_INVALID_PARAM if size of data is too big too fit in an individual data field.
00147      */
00148     ble_error_t addOrReplaceData(
00149         adv_data_type_t  advDataType,
00150         mbed::Span<const uint8_t>  fieldData
00151     );
00152 
00153     /**
00154      * Adds a new field into the payload. If the supplied advertising data type is
00155      * already present in the advertising payload, then the value is replaced.
00156      *
00157      * @note Data size for individual types cannot exceed 255 bytes.
00158      *
00159      * @param[in] advDataType The type of the field to add.
00160      * @param[in] fieldData Span of data to add.
00161      *
00162      * @retval BLE_ERROR_NONE on success.
00163      * @retval BLE_ERROR_BUFFER_OVERFLOW if buffer is too small to contain the new data.
00164      * @retval BLE_ERROR_INVALID_PARAM if size of data is too big too fit in an individual data field.
00165      */
00166     ble_error_t addOrAppendData(
00167         adv_data_type_t  advDataType,
00168         mbed::Span<const uint8_t>  fieldData
00169     );
00170 
00171     /**
00172      * Clears the advertising data payload.
00173      *
00174      * @post getPayloadLen() returns 0.
00175      */
00176     void clear();
00177 
00178     /**
00179      * Add device appearance in the advertising payload.
00180      *
00181      * @param[in] appearance The appearance to advertise.
00182      *
00183      * @retval BLE_ERROR_NONE on success.
00184      * @retval BLE_ERROR_BUFFER_OVERFLOW if buffer is too small to contain the new data.
00185      *
00186      * @note This call is equivalent to calling addOrReplaceData() with
00187      * adv_data_type_t::APPEARANCE as the field type.
00188      */
00189     ble_error_t setAppearance(adv_data_appearance_t appearance);
00190 
00191     /**
00192      * Add BLE flags in the advertising payload.
00193      *
00194      * @param[in] flags Bitfield describing the capability of the device. See
00195      * allowed flags in Flags_t.
00196      *
00197      * @retval BLE_ERROR_NONE on success.
00198      * @retval BLE_ERROR_BUFFER_OVERFLOW if buffer is too small to contain the new data.
00199      *
00200      * @note This call is equivalent to calling addOrReplaceData() with
00201      * adv_data_type_t::FLAGS as the field type.
00202      */
00203     ble_error_t setFlags(
00204         adv_data_flags_t flags = adv_data_flags_t::default_flags
00205     );
00206 
00207     /**
00208      * Add the advertising TX in the advertising payload.
00209      *
00210      * @param[in] txPower Transmission power level in dB.
00211      *
00212      * @retval BLE_ERROR_NONE on success.
00213      * @retval BLE_ERROR_BUFFER_OVERFLOW if buffer is too small to contain the new data.
00214      *
00215      * @note This call is equivalent to calling addOrReplaceData() with
00216      * adv_data_type_t::TX_POWER_LEVEL as the field type.
00217      */
00218     ble_error_t setTxPowerAdvertised(advertising_power_t txPower);
00219 
00220     /**
00221      * Add device name to the advertising payload.
00222      *
00223      * @note Data size for individual types cannot exceed 255 bytes.
00224      *
00225      * @param[in] name Null terminated string containing the name.
00226      * @param[in] complete Complete local name if true, otherwise
00227      *
00228      * @retval BLE_ERROR_NONE on success.
00229      * @retval BLE_ERROR_BUFFER_OVERFLOW if buffer is too small to contain the new data.
00230      * @retval BLE_ERROR_INVALID_PARAM if size of data is too big too fit in an individual data field.
00231      */
00232     ble_error_t setName(const char *name, bool complete = true);
00233 
00234     /**
00235      * Add manufacturer-specific data to the advertising payload.
00236      *
00237      * @note Data size for individual types cannot exceed 255 bytes.
00238      *
00239      * @param[in] data New data to be added.
00240      *
00241      * @retval BLE_ERROR_NONE on success.
00242      * @retval BLE_ERROR_BUFFER_OVERFLOW if buffer is too small to contain the new data.
00243      * @retval BLE_ERROR_INVALID_PARAM if size of data is too big too fit in an individual
00244      *                                 data field or the data is too small (must contain
00245      *                                 2 bytes of manufacturer ID)
00246      */
00247     ble_error_t setManufacturerSpecificData(mbed::Span<const uint8_t>  data);
00248 
00249     /**
00250      * Add advertising interval to the payload. This field can only carry 2 bytes.
00251      *
00252      * @param interval Interval to advertise. Cannot be larger than 0xFFFF.
00253 
00254      * @retval BLE_ERROR_NONE on success.
00255      * @retval BLE_ERROR_BUFFER_OVERFLOW if buffer is too small to contain the new data.
00256      * @retval BLE_ERROR_INVALID_PARAM if interval value outside of valid range.
00257      */
00258     ble_error_t setAdvertisingInterval(adv_interval_t  interval);
00259 
00260     /**
00261      * Add connection interval preferences to the payload
00262      *
00263      * @param min Minimum connection interval to advertise.
00264      * @param max Maximum connection interval to advertise.
00265 
00266      * @retval BLE_ERROR_NONE on success.
00267      * @retval BLE_ERROR_BUFFER_OVERFLOW if buffer is too small to contain the new data.
00268      */
00269     ble_error_t setConnectionIntervalPreference(
00270         conn_interval_t  min,
00271         conn_interval_t  max
00272     );
00273 
00274     /**
00275      * Add service data data to the advertising payload.
00276      *
00277      * @note Data size for individual types cannot exceed 255 bytes.
00278      *
00279      * @param[in] service UUID of the service.
00280      * @param[in] data New data to be added.
00281      *
00282      * @retval BLE_ERROR_NONE on success.
00283      * @retval BLE_ERROR_BUFFER_OVERFLOW if buffer is too small to contain the new data.
00284      * @retval BLE_ERROR_INVALID_PARAM if size of data is too big too fit in an individual data field.
00285      */
00286     ble_error_t setServiceData(UUID service, mbed::Span<const uint8_t>  data);
00287 
00288     /**
00289      * Add local service IDs to the advertising payload. If the data can't fit,
00290      * no modification will take place.
00291      *
00292      * @note Data size for individual types cannot exceed 255 bytes.
00293      *
00294      * @param[in] data New data to be added.
00295      * @param[in] complete True if this is a complete list.
00296      *
00297      * @retval BLE_ERROR_NONE on success.
00298      * @retval BLE_ERROR_BUFFER_OVERFLOW if buffer is too small to contain the new data.
00299      * @retval BLE_ERROR_INVALID_PARAM if number of UUIDs of any one type is too high.
00300      */
00301     ble_error_t setLocalServiceList(
00302         mbed::Span<const UUID> data,
00303         bool complete = true
00304     );
00305 
00306     /**
00307      * Add a list of UUIDs of solicited services.
00308      *
00309      * @note Data size for individual types cannot exceed 255 bytes.
00310      *
00311      * @param[in] data List of 128 or 16 bit service UUIDs.
00312      *
00313      * @retval BLE_ERROR_NONE on success.
00314      * @retval BLE_ERROR_BUFFER_OVERFLOW if buffer is too small to contain the new data.
00315      * @retval BLE_ERROR_INVALID_PARAM if number of UUIDs of any one type is too high.
00316      */
00317     ble_error_t setRequestedServiceList(mbed::Span<const UUID> data);
00318 
00319     /**
00320      * Return a span of data containing the the type of data requested.
00321      *
00322      * @param[out] data Span used to return the requested data.
00323      * @param[in] advDataType Data type to return.
00324      *
00325      * @return BLE_ERROR_NONE if data was found and BLE_ERROR_NOT_FOUND if not.
00326      */
00327     ble_error_t getData(
00328         mbed::Span<const uint8_t>  &data,
00329         adv_data_type_t  advDataType
00330     );
00331 
00332 private:
00333     /**
00334     * Search advertisement data for a specific field.
00335     *
00336     * @param[in] type The type of the field to find.
00337     *
00338     * @return A pointer to the first element in the field if found. The first
00339     * element being the length of the field followed by the value of the field.
00340     * NULL if the field is not present in the payload.
00341     */
00342     uint8_t *findField(adv_data_type_t  type);
00343 
00344     /**
00345      * Get field size (includes type and size bytes)
00346      *
00347      * @param type The field type.
00348      *
00349      * @return Size of the whole field including type and size bytes.
00350      */
00351     uint8_t getFieldSize(adv_data_type_t  type);
00352 
00353     /**
00354      * Append advertising data based on the specified type.
00355      *
00356      * @note Data size for individual types cannot exceed 255 bytes.
00357      *
00358      * @param[in] advDataType Type of the new data.
00359      * @param[in] fieldData Span of data to add.
00360      *
00361      * @retval BLE_ERROR_NONE on success.
00362      * @retval BLE_ERROR_BUFFER_OVERFLOW if buffer is too small to contain the new data.
00363      */
00364     ble_error_t addField(
00365         adv_data_type_t  advDataType,
00366         mbed::Span<const uint8_t>  fieldData
00367     );
00368 
00369     /**
00370      * Append data to a field in the advertising payload.
00371      *
00372      * @note Data size for individual types cannot exceed 255 bytes.
00373      *
00374      * @param[in] fieldData Span of data to add.
00375      * @param[in] field Pointer to the field in the advertising buffer.
00376      *
00377      * @return BLE_ERROR_NONE on success.
00378      */
00379     ble_error_t appendToField(
00380         mbed::Span<const uint8_t>  fieldData,
00381         uint8_t *field
00382     );
00383 
00384     /**
00385      * Update in place the value of a field in the advertising payload.
00386      *
00387      * @note Data size for individual types cannot exceed 255 bytes.
00388      *
00389      * @param[in] advDataType Type of the new data.
00390      * @param[in] fieldData Span of data to add.
00391      * @param[in] field Pointer to the field of type @p advDataType in the
00392      * advertising buffer.
00393      *
00394      * @retval BLE_ERROR_NONE on success.
00395      * @retval BLE_ERROR_BUFFER_OVERFLOW if buffer is too small to contain the new data.
00396      */
00397     ble_error_t replaceField(
00398         adv_data_type_t  advDataType,
00399         mbed::Span<const uint8_t>  fieldData,
00400         uint8_t *field
00401     );
00402 
00403     /**
00404      * Remove the field.
00405      *
00406      * @param[in] field Pointer to the field in the advertising buffer.
00407      *
00408      * @return BLE_ERROR_NONE on success.
00409      */
00410     ble_error_t removeField(uint8_t *field);
00411 
00412     /**
00413      * Add a list of UUIDs to given types.
00414      *
00415      * @note Data size for individual types cannot exceed 255 bytes.
00416      *
00417      * @param[in] data List of 128 or 16 bit service UUIDs.
00418      * @param[in] shortType Type of field to add the short UUIDs to.
00419      * @param[in] longType Type of field to add the long UUIDs to.
00420      *
00421      * @retval BLE_ERROR_NONE on success.
00422      * @retval BLE_ERROR_BUFFER_OVERFLOW if buffer is too small to contain the new data.
00423      * @retval BLE_ERROR_INVALID_PARAM if number of UUIDs of any one type is too high.
00424      */
00425     ble_error_t setUUIDData(
00426         mbed::Span<const UUID> data,
00427         adv_data_type_t  shortType,
00428         adv_data_type_t  longType
00429     );
00430 
00431 private:
00432     /** The memory backing the the data provided by the user. */
00433     mbed::Span<uint8_t>  _buffer;
00434 
00435     /** Length of the data added to the advertising buffer. */
00436     uint8_t _payload_length;
00437 };
00438 
00439 /**
00440  * @}
00441  * @}
00442  */
00443 
00444 } // namespace ble
00445 
00446 #endif /* ifndef MBED_GAP_ADVERTISING_DATA_H__ */