AdvertisingDataSimpleBuilder.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 BLE_GAP_SIMPLEADVERTISINGDATABUILDER_H
00018 #define BLE_GAP_SIMPLEADVERTISINGDATABUILDER_H
00019 
00020 #include "ble/gap/AdvertisingDataBuilder.h"
00021 
00022 namespace ble {
00023 
00024 /**
00025  * @addtogroup ble
00026  * @{
00027  * @addtogroup gap
00028  * @{
00029  */
00030 
00031 /**
00032  * Build advertising data.
00033  *
00034  * It is a simplified version of AdvertisingDataBuilder that can generate
00035  * advertising data "inline".
00036  *
00037  * It differs from AdvertisingDataBuilder on the following points:
00038  *   - The buffer used to build the advertising data is embedded in the object.
00039  *   - If insertion fails, an assertion is raised. Outside of debug mode, if an
00040  *   insertion fails, the buffer is not modified.
00041  *   - The API is fluent.
00042  *   - It hides advanced functions.
00043  *
00044  * @code
00045     void setupAdvertisingData(ble::Gap& gap)
00046     {
00047         using namespace ble;
00048         gap.setAdvertisingPayload(
00049             LEGACY_ADVERTISING_HANDLE,
00050             AdvertisingDataSimpleBuilder<LEGACY_ADVERTISING_MAX_SIZE>()
00051                 .setFlags()
00052                 .setName("My device", true)
00053                 .setAppearance(adv_data_appearance_t::GENERIC_HEART_RATE_SENSOR)
00054                 .setLocalService(ATT_UUID_HEART_RATE_SERVICE)
00055                 .getAdvertisingData()
00056         );
00057     }
00058  * @endcode
00059  */
00060 template<size_t DataSize>
00061 class AdvertisingDataSimpleBuilder {
00062 public:
00063     /**
00064      * Construct a AdvertisingDataSimpleBuilder
00065      */
00066     AdvertisingDataSimpleBuilder() : _builder(_buffer)
00067     {
00068     }
00069 
00070     /**
00071      * Add device appearance in the advertising payload.
00072      *
00073      * @param[in] appearance The appearance to advertise.
00074      *
00075      * @return A reference to this object.
00076      *
00077      * @note If the field is already present in the payload, it is replaced.
00078      */
00079     AdvertisingDataSimpleBuilder &setAppearance(adv_data_appearance_t appearance)
00080     {
00081         ble_error_t res = _builder.setAppearance(appearance);
00082         MBED_ASSERT(res == BLE_ERROR_NONE);
00083         return *this;
00084     }
00085 
00086     /**
00087      * Add BLE flags in the advertising payload.
00088      *
00089      * @param[in] flags Bitfield describing the capability of the device. See
00090      * allowed flags in Flags_t.
00091      *
00092      * @return A reference to this object.
00093      *
00094      * @note If the field is already present in the payload, it is replaced.
00095      */
00096     AdvertisingDataSimpleBuilder &setFlags(
00097         adv_data_flags_t flags = adv_data_flags_t::default_flags
00098     )
00099     {
00100         ble_error_t res = _builder.setFlags(flags);
00101         MBED_ASSERT(res == BLE_ERROR_NONE);
00102         return *this;
00103     }
00104 
00105     /**
00106      * Add the advertising TX in the advertising payload.
00107      *
00108      * @param[in] txPower Transmission power level in dB.
00109      *
00110      * @return A reference to this object.
00111      *
00112      * @note If the field is already present in the payload, it is replaced.
00113      */
00114     AdvertisingDataSimpleBuilder &setTxPowerAdvertised(advertising_power_t txPower)
00115     {
00116         ble_error_t res = _builder.setTxPowerAdvertised(txPower);
00117         MBED_ASSERT(res == BLE_ERROR_NONE);
00118         return *this;
00119     }
00120 
00121     /**
00122      * Add device name to the advertising payload.
00123      *
00124      * @note Data size for individual types cannot exceed 255 bytes.
00125      *
00126      * @param[in] name Null terminated string containing the name.
00127      * @param[in] complete Complete local name if true, otherwise
00128      *
00129      * @return A reference to this object.
00130      *
00131      * @note If the field is already present in the payload, it is replaced.
00132      */
00133     AdvertisingDataSimpleBuilder &setName(const char *name, bool complete = true)
00134     {
00135         ble_error_t res = _builder.setName(name, complete);
00136         MBED_ASSERT(res == BLE_ERROR_NONE);
00137         return *this;
00138     }
00139 
00140     /**
00141      * Add manufacturer specific data to the advertising payload.
00142      *
00143      * @note Data size for individual types cannot exceed 255 bytes.
00144      *
00145      * @param[in] data New data to be added.
00146      *
00147      * @return a reference to this object.
00148      */
00149     AdvertisingDataSimpleBuilder &setManufacturerSpecificData(mbed::Span<const uint8_t>  data)
00150     {
00151         ble_error_t res = _builder.setManufacturerSpecificData(data);
00152         MBED_ASSERT(res == BLE_ERROR_NONE);
00153         return *this;
00154     }
00155 
00156     /**
00157      * Add advertising interval to the payload. This field can only carry 2 bytes.
00158      *
00159      * @param interval Interval to advertise. Cannot be larger than 0xFFFF.
00160      *
00161      * @return a reference to this object.
00162      */
00163     AdvertisingDataSimpleBuilder &setAdvertisingInterval(adv_interval_t  interval)
00164     {
00165         ble_error_t res = _builder.setAdvertisingInterval(interval);
00166         MBED_ASSERT(res == BLE_ERROR_NONE);
00167         return *this;
00168     }
00169 
00170     /**
00171      * Add connection interval preferences to the payload
00172      *
00173      * @param min Minimum connection interval to advertise.
00174      * @param max Maximum connection interval to advertise.
00175      *
00176      * @return a reference to this object.
00177      */
00178     AdvertisingDataSimpleBuilder &setConnectionIntervalPreference(
00179         conn_interval_t  min,
00180         conn_interval_t  max
00181     )
00182     {
00183         ble_error_t res = _builder.setConnectionIntervalPreference(min, max);
00184         MBED_ASSERT(res == BLE_ERROR_NONE);
00185         return *this;
00186     }
00187 
00188     /**
00189      * Add service data to the advertising payload.
00190      *
00191      * @note Data size for individual types cannot exceed 255 bytes.
00192      *
00193      * @param[in] service UUID of the service.
00194      * @param[in] data New data to be added.
00195      *
00196      * @return A reference to this object.
00197      */
00198     AdvertisingDataSimpleBuilder &setServiceData(UUID service, mbed::Span<const uint8_t>  data)
00199     {
00200         ble_error_t res = _builder.setServiceData(service, data);
00201         MBED_ASSERT(res == BLE_ERROR_NONE);
00202         return *this;
00203     }
00204 
00205     /**
00206      * Add local service ID to the advertising payload. If the data can't fit,
00207      * no modification will take place.
00208      *
00209      * @note Data size for individual types cannot exceed 255 bytes.
00210      *
00211      * @param[in] data New data to be added.
00212      * @param[in] complete True if this is a complete list.
00213      *
00214      * @return A reference to this object.
00215      */
00216     AdvertisingDataSimpleBuilder &setLocalService(
00217         const UUID& data,
00218         bool complete = true
00219     )
00220     {
00221         ble_error_t res = _builder.setLocalServiceList(
00222                 mbed::make_Span(&data, 1), complete
00223             );
00224         MBED_ASSERT(res == BLE_ERROR_NONE);
00225         return *this;
00226     }
00227 
00228 
00229     /**
00230      * Add local service IDs to the advertising payload. If the data can't fit,
00231      * no modification will take place.
00232      *
00233      * @note Data size for individual types cannot exceed 255 bytes.
00234      *
00235      * @param[in] data New data to be added.
00236      * @param[in] complete True if this is a complete list.
00237      *
00238      * @return A reference to this object.
00239      */
00240     AdvertisingDataSimpleBuilder &setLocalServiceList(
00241         mbed::Span<const UUID> data,
00242         bool complete = true
00243     )
00244     {
00245         ble_error_t res = _builder.setLocalServiceList(data, complete);
00246         MBED_ASSERT(res == BLE_ERROR_NONE);
00247         return *this;
00248     }
00249 
00250     /**
00251      * Add a UUID of a solicited service.
00252      *
00253      * @note Data size for individual types cannot exceed 255 bytes.
00254      *
00255      * @param[in] data List of 128 or 16 bit service UUIDs.
00256      *
00257      * @return A reference to this object.
00258      */
00259     AdvertisingDataSimpleBuilder &setRequestedService(const UUID& data)
00260     {
00261         ble_error_t res = _builder.setRequestedServiceList(mbed::make_Span(&data, 1));
00262         MBED_ASSERT(res == BLE_ERROR_NONE);
00263         return *this;
00264     }
00265 
00266     /**
00267      * Add a list of UUIDs of solicited services.
00268      *
00269      * @note Data size for individual types cannot exceed 255 bytes.
00270      *
00271      * @param[in] data List of 128 or 16 bit service UUIDs.
00272      *
00273      * @return A reference to this object.
00274      */
00275     AdvertisingDataSimpleBuilder &setRequestedServiceList(mbed::Span<const UUID> data)
00276     {
00277         ble_error_t res = _builder.setRequestedServiceList(data);
00278         MBED_ASSERT(res == BLE_ERROR_NONE);
00279         return *this;
00280     }
00281 
00282     /**
00283      * Add a new field into the payload. The operation fails if type is already present.
00284      *
00285      * @note Data size for individual types cannot exceed 255 bytes.
00286      *
00287      * @param[in] advDataType The type of the field to add.
00288      * @param[in] fieldData Span of data to add.
00289      *
00290      * @return A reference to this object.
00291      */
00292     AdvertisingDataSimpleBuilder& addData(
00293         adv_data_type_t  advDataType,
00294         mbed::Span<const uint8_t>  fieldData
00295     )
00296     {
00297         ble_error_t res = _builder.addData(advDataType, fieldData);
00298         MBED_ASSERT(res == BLE_ERROR_NONE);
00299         return *this;
00300     }
00301 
00302     /**
00303      * Get the subspan of the buffer containing valid data.
00304      *
00305      * @return A Span containing the payload.
00306      */
00307     mbed::Span<const uint8_t>  getAdvertisingData() const
00308     {
00309         return _builder.getAdvertisingData();
00310     }
00311 
00312 private:
00313     uint8_t _buffer[DataSize];
00314     AdvertisingDataBuilder _builder;
00315 };
00316 
00317 /**
00318  * @}
00319  * @}
00320  */
00321 
00322 } // namespace ble
00323 
00324 
00325 #endif //BLE_GAP_SIMPLEADVERTISINGDATABUILDER_H