How long do pointers to characteristic data need to be valid?

[Tim]

The documentation is lacking critical details about what the soft devices do with characteristic data you give it. When you create or update a characteristic you need to give it a pointer to the data. At this point two things can happen:

1. The data is copied to some internal buffer and the pointer is discarded.
2. The pointer is saved and used later (e.g. when the characteristic is read).

Which is it? This should be documented for every function that takes pointers like this as it can lead to horrible horrible bugs if you assume 1, but it's actually 2.

Another example of where this needs to be documented is setting/updating connection parameters. In fact nearly every soft device function takes pointer arguments so there is a lot of dangerous ambiguity in the API.

[Ulrich Myhre]

This is actually documented together with the API calls themselves.

For p_value of ble_gatts_attr_t (used in sd_ble_gatts_characteristic_add, your example) this is stated:

Pointer to the attribute data. Please note that if the @ref BLE_GATTS_VLOC_USER value location is selected in the attribute metadata, this will have to point to a buffer that remains valid through the lifetime of the attribute. This excludes usage of automatic variables that may go out of scope or any other temporary location. The stack may access that memory directly without the application's knowledge. For writable characteristics, this value must not be a location in flash memory.

Which means that the lifetime is defined based on ble_gatts_attr_md_t.vloc.

If there are any other places where our documentation is lacking this, then please give us a hint.

[Tim]

Ah found it here: infocenter.nordicsemi.com/.../structble__gatts__attr__t.html By the way the formatting seems a bit wrong on that page. I think it would be nice if the function documentation mention this, rather than just the documentation for the parameter structure.