Docuement active set length and add informative call for querying the limit

Author: paul-szczepanek-arm

features/FEATURE_BLE/ble/gap/Gap.h

@@ -544,6 +544,12 @@ class Gap {
      */
     virtual uint16_t getMaxConnectableAdvertisingDataLength();
 
+    /** Return maximum advertising data length you may set if advertising set is active.
+     *
+     * @return Maximum advertising data length you may set if advertising set is active.
+     */
+    virtual uint8_t getMaxActiveSetAdvertisingDataLength();
+
     /** Create an advertising set and apply the passed in parameters. The handle returned
      *  by this function must be used for all other calls that accept an advertising handle.
      *  When done with advertising, remove from the system using destroyAdvertisingSet().
@@ -589,6 +595,10 @@ class Gap {
      * @param handle Advertising set handle.
      * @param payload Advertising payload.
      *
+     * @note If advertising set is active you may only set payload of length equal or less
+     * than getMaxActiveSetAdvertisingDataLength(). If you require a longer payload you must
+     * stop the advertising set, set the payload and restart the set.
+     *
      * @return BLE_ERROR_NONE on success.
      *
      * @see ble::AdvertisingDataBuilder to build a payload.
@@ -604,6 +614,10 @@ class Gap {
      * @param handle Advertising set handle.
      * @param response Advertising scan response.
      *
+     * @note If advertising set is active you may only set payload of length equal or less
+     * than getMaxActiveSetAdvertisingDataLength(). If you require a longer payload you must
+     * stop the advertising set, set the payload and restart the set.
+     *
      * @return BLE_ERROR_NONE on success.
      *
      * @see ble::AdvertisingDataBuilder to build a payload.
@@ -669,6 +683,11 @@ class Gap {
      * @param payload Advertising payload.
      * @return BLE_ERROR_NONE on success.
      *
+     * @note If advertising set is active you may only set payload of length equal or less
+     * than getMaxActiveSetAdvertisingDataLength(). If you require a longer payload you must
+     * stop the advertising set, set the payload and restart the set. Stopping the set will
+     * cause peers to lose sync on the periodic set.
+     *
      * @see ble::AdvertisingDataBuilder to build a payload.
      *
      * @version 5+

features/FEATURE_BLE/ble/generic/GenericGap.h

@@ -95,6 +95,10 @@ class GenericGap :
      */
     virtual uint16_t getMaxConnectableAdvertisingDataLength();
 
+    /** @copydoc Gap::getMaxActiveSetAdvertisingDataLength
+     */
+    virtual uint8_t getMaxActiveSetAdvertisingDataLength();
+
     /** @copydoc Gap::createAdvertisingSet
      */
     virtual ble_error_t createAdvertisingSet(

features/FEATURE_BLE/source/gap/Gap.cpp

@@ -42,6 +42,12 @@ uint16_t Gap::getMaxConnectableAdvertisingDataLength()
     return LEGACY_ADVERTISING_MAX_SIZE;
 }
 
+uint8_t Gap::getMaxActiveSetAdvertisingDataLength()
+{
+    /* Requesting action from porter(s): override this API if this capability is supported. */
+    return LEGACY_ADVERTISING_MAX_SIZE;
+}
+
 ble_error_t Gap::createAdvertisingSet(
     advertising_handle_t *handle,
     const AdvertisingParameters &parameters

features/FEATURE_BLE/source/generic/GenericGap.cpp

@@ -2013,6 +2013,12 @@ uint16_t GenericGap::getMaxConnectableAdvertisingDataLength()
     return _pal_gap.get_maximum_connectable_advertising_data_length();
 }
 
+uint8_t GenericGap::getMaxActiveSetAdvertisingDataLength()
+{
+    useVersionTwoAPI();
+    return _pal_gap.get_max_hci_advertising_data_length();
+}
+
 ble_error_t GenericGap::createAdvertisingSet(
     advertising_handle_t *handle,
     const AdvertisingParameters &parameters