sd_ble_evt_get()

uint32_t sd_ble_evt_get	(	uint8_t *	p_dest,
		uint16_t *	p_len )

#include <ble.h>

Get an event from the pending events queue.

Parameters

[out]	p_dest	Pointer to buffer to be filled in with an event, or NULL to retrieve the event length. This buffer must be aligned to the extend defined by BLE_EVT_PTR_ALIGNMENT. The buffer should be interpreted as a ble_evt_t struct.
[in,out]	p_len	Pointer the length of the buffer, on return it is filled with the event length.

This call allows the application to pull a BLE event from the BLE stack. The application is signaled that an event is available from the BLE stack by the triggering of the SD_EVT_IRQn interrupt. The application is free to choose whether to call this function from thread mode (main context) or directly from the Interrupt Service Routine that maps to SD_EVT_IRQn. In any case however, and because the BLE stack runs at a higher priority than the application, this function should be called in a loop (until NRF_ERROR_NOT_FOUND is returned) every time SD_EVT_IRQn is raised to ensure that all available events are pulled from the BLE stack. Failure to do so could potentially leave events in the internal queue without the application being aware of this fact.

Sizing the p_dest buffer is equally important, since the application needs to provide all the memory necessary for the event to be copied into application memory. If the buffer provided is not large enough to fit the entire contents of the event, NRF_ERROR_DATA_SIZE will be returned and the application can then call again with a larger buffer size. The maximum possible event length is defined by BLE_EVT_LEN_MAX. The application may also "peek" the event length by providing p_dest as a NULL pointer and inspecting the value of *p_len upon return:

\code
uint16_t len;
errcode = sd_ble_evt_get(NULL, &len);
\endcode

Relevant Message Sequence Charts

Interrupt-driven Event Retrieval

Thread Mode Event Retrieval

Return values

NRF_SUCCESS	Event pulled and stored into the supplied buffer.
NRF_ERROR_INVALID_ADDR	Invalid or not sufficiently aligned pointer supplied.
NRF_ERROR_NOT_FOUND	No events ready to be pulled.
NRF_ERROR_DATA_SIZE	Event ready but could not fit into the supplied buffer.