| nRF5 SDK v12.0.0 |

Choose documentation: | nRF5 SDK | S130 SoftDevice API | S132 SoftDevice API | S212 SoftDevice API | S332 SoftDevice API

All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Modules | Data Structures | Macros | Enumerations | Functions
Mailbox library
SDK common libraries

Mailbox for safely queuing items. More...

## Modules
| Thread safe mailbox configuration

## Data Structures
struct | app_mailbox_t
| Mailbox definition structure. More...

## Macros
#define | APP_MAILBOX_DEF(name, QUEUE_SZ, ITEM_SZ)
| Macro to statically allocate memory for a given mailbox queue. More...

## Enumerations
enum | app_mailbox_overflow_mode_t { APP_MAILBOX_MODE_NO_OVERFLOW, APP_MAILBOX_MODE_OVERFLOW }
| Supported overflow modes. More...

## Functions
ret_code_t | app_mailbox_create (const app_mailbox_t *p_mailbox)
| Function for creating a mailbox queue. More...
ret_code_t | app_mailbox_put (const app_mailbox_t *p_mailbox, void *p_item)
| Function for putting an item in the mailbox queue. More...
ret_code_t | app_mailbox_sized_put (const app_mailbox_t *p_mailbox, void *p_item, uint16_t size)
| Function for putting an item with a specified size in the mailbox queue. More...
ret_code_t | app_mailbox_get (const app_mailbox_t *p_mailbox, void *p_item)
| Function for getting an item from the mailbox queue. More...
ret_code_t | app_mailbox_sized_get (const app_mailbox_t *p_mailbox, void *p_item, uint16_t *p_size)
| Function for getting an item and its size from the mailbox queue. More...
uint32_t | app_mailbox_length_get (const app_mailbox_t *p_mailbox)
| Function for getting the current length of the mailbox queue. More...
void | app_mailbox_mode_set (const app_mailbox_t *p_mailbox, app_mailbox_overflow_mode_t mode)
| Function for changing the mode of overflow handling. More...

## Detailed Description

Mailbox for safely queuing items.

## Macro Definition Documentation

#define APP_MAILBOX_DEF | ( |  | name,
|  |  | QUEUE_SZ,
|  |  | ITEM_SZ
| ) |  |

Value:
static uint32_t STRING_CONCATENATE(mailbox_items_,name)[(1 + CEIL_DIV((ITEM_SZ),4)) * (QUEUE_SZ)];\
static app_mailbox_cb_t STRING_CONCATENATE(mailbox_cb_,name); \
const app_mailbox_t name = \
{ \
.p_pool = STRING_CONCATENATE(mailbox_items_,name), \
.p_cb = STRING_CONCATENATE(&mailbox_cb_,name), \
.queue_sz = (uint8_t)(QUEUE_SZ), \
.item_sz = (uint16_t)(ITEM_SZ), \
}

Macro to statically allocate memory for a given mailbox queue.

## Enumeration Type Documentation

enum app_mailbox_overflow_mode_t

Supported overflow modes.

Enumerator
APP_MAILBOX_MODE_NO_OVERFLOW | If the mailbox is full, app_mailbox_put does not add a new element.
APP_MAILBOX_MODE_OVERFLOW | If the mailbox is full, the oldest element is lost and a new one is added.

## Function Documentation

ret_code_t app_mailbox_create | ( | const app_mailbox_t * | p_mailbox | ) |

Function for creating a mailbox queue.

This function creates and initializes a mailbox queue.

Parameters

  [in] | p_mailbox | Pointer to the mailbox.

Return values

  NRF_SUCCESS | If the queue was successfully created.

ret_code_t app_mailbox_get | ( | const app_mailbox_t * | p_mailbox,
|  | void * | p_item
| ) |  |

Function for getting an item from the mailbox queue.

Parameters

  [in] | p_mailbox | Pointer to the mailbox.
  [out] | p_item | Pointer to the output location for the dequeued item.

Return values

  NRF_SUCCESS | If the item was retrieved successfully.
  NRF_ERROR_NO_MEM | If the queue is empty.

uint32_t app_mailbox_length_get | ( | const app_mailbox_t * | p_mailbox | ) |

Function for getting the current length of the mailbox queue.

Parameters

  [in] | p_mailbox | Pointer to the mailbox.

Returns
  Current number of elements in the queue.

void app_mailbox_mode_set | ( | const app_mailbox_t * | p_mailbox,
|  | app_mailbox_overflow_mode_t | mode
| ) |  |

Function for changing the mode of overflow handling.

Parameters

  [in] | p_mailbox | Pointer to the mailbox.
  | mode | New mode to set.

ret_code_t app_mailbox_put | ( | const app_mailbox_t * | p_mailbox,
|  | void * | p_item
| ) |  |

Function for putting an item in the mailbox queue.

Parameters

  [in] | p_mailbox | Pointer to the mailbox.
  [in] | p_item | Pointer to the item to be queued.

Return values

  NRF_SUCCESS | If the item was enqueued.
  NRF_ERROR_NO_MEM | If the queue is full.

ret_code_t app_mailbox_sized_get | ( | const app_mailbox_t * | p_mailbox,
|  | void * | p_item,
|  | uint16_t * | p_size
| ) |  |

Function for getting an item and its size from the mailbox queue.

Parameters

  [in] | p_mailbox | Pointer to the mailbox.
  [out] | p_item | Pointer to the output location for the dequeued item.
  [out] | p_size | Pointer to the item size.

Return values

  NRF_SUCCESS | If the item was retrieved successfully.
  NRF_ERROR_NO_MEM | If the queue is empty.

ret_code_t app_mailbox_sized_put | ( | const app_mailbox_t * | p_mailbox,
|  | void * | p_item,
|  | uint16_t | size
| ) |  |

Function for putting an item with a specified size in the mailbox queue.

Parameters

  [in] | p_mailbox | Pointer to the mailbox.
  [in] | p_item | Pointer to the item to be queued.
  [in] | size | Size of the item.

Return values

  NRF_SUCCESS | If the item was enqueued.
  NRF_ERROR_NO_MEM | If the queue is full.