Callbacks

MCUmgr Callback API. More...

Topics
	Enumeration Management Callbacks
	MCUmgr Enumeration Management Callbacks API.
	File System Management Callbacks
	MCUmgr File System Management Callbacks API.
	Image Management Callbacks
	MCUmgr Image Management Callbacks API.
	OS Management Callbacks
	MCUmgr OS Management Callbacks API.
	Settings Management Callbacks
	MCUmgr Settings Management Callbacks API.

Data Structures
struct	mgmt_callback
	MGMT callback struct. More...
struct	mgmt_evt_op_cmd_arg
	Arguments for MGMT_EVT_OP_CMD_RECV, MGMT_EVT_OP_CMD_STATUS and MGMT_EVT_OP_CMD_DONE. More...

Macros
#define	MGMT_EVT_GET_GROUP(event)
	Get group from event.
#define	MGMT_EVT_GET_ID(event)
	Get event ID from event.

Typedefs
typedef enum mgmt_cb_return(*	mgmt_cb) (uint32_t event, enum mgmt_cb_return prev_status, int32_t *rc, uint16_t *group, bool *abort_more, void *data, size_t data_size)
	Function to be called on MGMT notification/event.

Enumerations
enum	mgmt_cb_return { MGMT_CB_OK , MGMT_CB_ERROR_RC , MGMT_CB_ERROR_ERR }
	MGMT event callback return value. More...
enum	mgmt_cb_groups {   MGMT_EVT_GRP_ALL = 0 , MGMT_EVT_GRP_SMP , MGMT_EVT_GRP_OS , MGMT_EVT_GRP_IMG ,   MGMT_EVT_GRP_FS , MGMT_EVT_GRP_SETTINGS , MGMT_EVT_GRP_ENUM , MGMT_EVT_GRP_USER_CUSTOM_START = MGMT_GROUP_ID_PERUSER }
	MGMT event callback group IDs. More...
enum	smp_all_events { MGMT_EVT_OP_ALL = MGMT_DEF_EVT_OP_ALL(MGMT_EVT_GRP_ALL) }
	MGMT event opcodes for all command processing. More...
enum	smp_group_events { MGMT_EVT_OP_CMD_RECV = MGMT_DEF_EVT_OP_ID(MGMT_EVT_GRP_SMP, 0) , MGMT_EVT_OP_CMD_STATUS = MGMT_DEF_EVT_OP_ID(MGMT_EVT_GRP_SMP, 1) , MGMT_EVT_OP_CMD_DONE = MGMT_DEF_EVT_OP_ID(MGMT_EVT_GRP_SMP, 2) , MGMT_EVT_OP_CMD_ALL = MGMT_DEF_EVT_OP_ALL(MGMT_EVT_GRP_SMP) }
	MGMT event opcodes for base SMP command processing. More...

Functions
uint8_t	mgmt_evt_get_index (uint32_t event)
	Get event ID index from event.
enum mgmt_cb_return	mgmt_callback_notify (uint32_t event, void *data, size_t data_size, int32_t *err_rc, uint16_t *err_group)
	This function is called to notify registered callbacks about mcumgr notifications/events.
void	mgmt_callback_register (struct mgmt_callback *callback)
	Register event callback function.
void	mgmt_callback_unregister (struct mgmt_callback *callback)
	Unregister event callback function.

Detailed Description

MCUmgr Callback API.

Macro Definition Documentation

MGMT_EVT_GET_GROUP

#define MGMT_EVT_GET_GROUP

(

event

)

#include <zephyr/mgmt/mcumgr/mgmt/callback_defines.h>

Value:

((event >> 16) & MGMT_EVT_OP_ID_ALL)

Get group from event.

MGMT_EVT_GET_ID

#define MGMT_EVT_GET_ID

(

event

)

#include <zephyr/mgmt/mcumgr/mgmt/callback_defines.h>

Value:

(event & MGMT_EVT_OP_ID_ALL)

Get event ID from event.

Typedef Documentation

mgmt_cb

typedef enum mgmt_cb_return(* mgmt_cb) (uint32_t event, enum mgmt_cb_return prev_status, int32_t *rc, uint16_t *group, bool *abort_more, void *data, size_t data_size)

#include <zephyr/mgmt/mcumgr/mgmt/callbacks.h>

Function to be called on MGMT notification/event.

This callback function is used to notify an application or system about a MCUmgr mgmt event.

Parameters

event	mcumgr_op_t.
prev_status	mgmt_cb_return of the previous handler calls, if it is an error then it will be the first error that was returned by a handler (i.e. this handler is being called for a notification only, the return code will be ignored).
rc	If prev_status is MGMT_CB_ERROR_RC then this is the SMP error that was returned by the first handler that failed. If prev_status is MGMT_CB_ERROR_ERR then this will be the group error rc code returned by the first handler that failed. If the handler wishes to raise an SMP error, this must be set to the mcumgr_err_t status and MGMT_CB_ERROR_RC must be returned by the function, if the handler wishes to raise a ret error, this must be set to the group ret status and MGMT_CB_ERROR_ERR must be returned by the function.
group	If prev_status is MGMT_CB_ERROR_ERR then this is the group of the ret error that was returned by the first handler that failed. If the handler wishes to raise a ret error, this must be set to the group ret status and MGMT_CB_ERROR_ERR must be returned by the function.
abort_more	Set to true to abort further processing by additional handlers.
data	Optional event argument.
data_size	Size of optional event argument (0 if no data is provided).

Returns

mgmt_cb_return indicating the status to return to the calling code (only checked when this is the first failure reported by a handler).

Enumeration Type Documentation

mgmt_cb_groups

enum mgmt_cb_groups

#include <zephyr/mgmt/mcumgr/mgmt/callback_defines.h>

MGMT event callback group IDs.

Note that this is not a 1:1 mapping with mcumgr_group_t values.

Enumerator
MGMT_EVT_GRP_ALL
MGMT_EVT_GRP_SMP
MGMT_EVT_GRP_OS
MGMT_EVT_GRP_IMG
MGMT_EVT_GRP_FS
MGMT_EVT_GRP_SETTINGS
MGMT_EVT_GRP_ENUM
MGMT_EVT_GRP_USER_CUSTOM_START

mgmt_cb_return

enum mgmt_cb_return

#include <zephyr/mgmt/mcumgr/mgmt/callback_defines.h>

MGMT event callback return value.

Enumerator
MGMT_CB_OK	No error.
MGMT_CB_ERROR_RC	SMP protocol error and err_rc contains the mcumgr_err_t error code.
MGMT_CB_ERROR_ERR	Group (application-level) error and err_group contains the group ID that caused the error and err_rc contains the error code of that group to return.

smp_all_events

enum smp_all_events

#include <zephyr/mgmt/mcumgr/mgmt/callback_defines.h>

MGMT event opcodes for all command processing.

Enumerator
MGMT_EVT_OP_ALL	Used to enable all events.

smp_group_events

enum smp_group_events

#include <zephyr/mgmt/mcumgr/mgmt/callbacks.h>

MGMT event opcodes for base SMP command processing.

Enumerator
MGMT_EVT_OP_CMD_RECV	Callback when a command is received, data is mgmt_evt_op_cmd_arg.
MGMT_EVT_OP_CMD_STATUS	Callback when a status is updated, data is mgmt_evt_op_cmd_arg.
MGMT_EVT_OP_CMD_DONE	Callback when a command has been processed, data is mgmt_evt_op_cmd_arg.
MGMT_EVT_OP_CMD_ALL	Used to enable all smp_group events.

Function Documentation

mgmt_callback_notify()

enum mgmt_cb_return mgmt_callback_notify	(	uint32_t	event,
		void *	data,
		size_t	data_size,
		int32_t *	err_rc,
		uint16_t *	err_group )

#include <zephyr/mgmt/mcumgr/mgmt/callbacks.h>

This function is called to notify registered callbacks about mcumgr notifications/events.

Parameters

event	mcumgr_op_t.
data	Optional event argument.
data_size	Size of optional event argument (0 if none).
err_rc	Pointer to rc value.
err_group	Pointer to group value.

Returns

mgmt_cb_return either MGMT_CB_OK if all handlers returned it, or MGMT_CB_ERROR_RC if the first failed handler returned an SMP error (in which case err_rc will be updated with the SMP error) or MGMT_CB_ERROR_ERR if the first failed handler returned a ret group and error (in which case err_group will be updated with the failed group ID and err_rc will be updated with the group-specific error code).

mgmt_callback_register()

void mgmt_callback_register

(

struct mgmt_callback *

callback

)

#include <zephyr/mgmt/mcumgr/mgmt/callbacks.h>

Register event callback function.

Parameters

callback

Callback struct.

mgmt_callback_unregister()

void mgmt_callback_unregister

(

struct mgmt_callback *

callback

)

#include <zephyr/mgmt/mcumgr/mgmt/callbacks.h>

Unregister event callback function.

Parameters

callback

Callback struct.

mgmt_evt_get_index()

uint8_t mgmt_evt_get_index

(

uint32_t

event

)

#include <zephyr/mgmt/mcumgr/mgmt/callbacks.h>

Get event ID index from event.

Parameters

event

Event to get ID index from.

Returns

Event index.