MCUmgr callback API

MCUmgr callback API. More...

Modules
	MCUmgr fs_mgmt callback API
	MCUmgr fs_mgmt callback API.
	MCUmgr img_mgmt callback API
	MCUmgr img_mgmt callback API.
	MCUmgr os_mgmt callback API
	MCUmgr os_mgmt callback API.
	MCUmgr settings_mgmt callback API
	MCUmgr settings_mgmt callback 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)   ((event >> 16) & MGMT_EVT_OP_ID_ALL)
	Get group from event.
#define	MGMT_EVT_GET_ID(event)   (event & MGMT_EVT_OP_ID_ALL)
	Get event ID from event.
#define	MGMT_CB_ERROR_RET   __DEPRECATED_MACRO MGMT_CB_ERROR_ERR

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_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...
enum	fs_mgmt_group_events { MGMT_EVT_OP_FS_MGMT_FILE_ACCESS = MGMT_DEF_EVT_OP_ID(MGMT_EVT_GRP_FS, 0) , MGMT_EVT_OP_FS_MGMT_ALL = MGMT_DEF_EVT_OP_ALL(MGMT_EVT_GRP_FS) }
	MGMT event opcodes for filesystem management group. More...
enum	img_mgmt_group_events {   MGMT_EVT_OP_IMG_MGMT_DFU_CHUNK = MGMT_DEF_EVT_OP_ID(MGMT_EVT_GRP_IMG, 0) , MGMT_EVT_OP_IMG_MGMT_DFU_STOPPED = MGMT_DEF_EVT_OP_ID(MGMT_EVT_GRP_IMG, 1) , MGMT_EVT_OP_IMG_MGMT_DFU_STARTED = MGMT_DEF_EVT_OP_ID(MGMT_EVT_GRP_IMG, 2) , MGMT_EVT_OP_IMG_MGMT_DFU_PENDING = MGMT_DEF_EVT_OP_ID(MGMT_EVT_GRP_IMG, 3) ,   MGMT_EVT_OP_IMG_MGMT_DFU_CONFIRMED = MGMT_DEF_EVT_OP_ID(MGMT_EVT_GRP_IMG, 4) , MGMT_EVT_OP_IMG_MGMT_DFU_CHUNK_WRITE_COMPLETE = MGMT_DEF_EVT_OP_ID(MGMT_EVT_GRP_IMG, 5) , MGMT_EVT_OP_IMG_MGMT_ALL = MGMT_DEF_EVT_OP_ALL(MGMT_EVT_GRP_IMG) }
	MGMT event opcodes for image management group. More...
enum	os_mgmt_group_events {   MGMT_EVT_OP_OS_MGMT_RESET = MGMT_DEF_EVT_OP_ID(MGMT_EVT_GRP_OS, 0) , MGMT_EVT_OP_OS_MGMT_INFO_CHECK = MGMT_DEF_EVT_OP_ID(MGMT_EVT_GRP_OS, 1) , MGMT_EVT_OP_OS_MGMT_INFO_APPEND = MGMT_DEF_EVT_OP_ID(MGMT_EVT_GRP_OS, 2) , MGMT_EVT_OP_OS_MGMT_DATETIME_GET = MGMT_DEF_EVT_OP_ID(MGMT_EVT_GRP_OS, 3) ,   MGMT_EVT_OP_OS_MGMT_DATETIME_SET = MGMT_DEF_EVT_OP_ID(MGMT_EVT_GRP_OS, 4) , MGMT_EVT_OP_OS_MGMT_ALL = MGMT_DEF_EVT_OP_ALL(MGMT_EVT_GRP_OS) }
	MGMT event opcodes for operating system management group. More...
enum	settings_mgmt_group_events { MGMT_EVT_OP_SETTINGS_MGMT_ACCESS = MGMT_DEF_EVT_OP_ID(MGMT_EVT_GRP_SETTINGS, 0) , MGMT_EVT_OP_SETTINGS_MGMT_ALL = MGMT_DEF_EVT_OP_ALL(MGMT_EVT_GRP_SETTINGS) }
	MGMT event opcodes for settings management group. 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_CB_ERROR_RET

#define MGMT_CB_ERROR_RET   __DEPRECATED_MACRO MGMT_CB_ERROR_ERR

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

MGMT_EVT_GET_GROUP

#define MGMT_EVT_GET_GROUP

(

event

)

((event >> 16) & MGMT_EVT_OP_ID_ALL)

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

Get group from event.

MGMT_EVT_GET_ID

#define MGMT_EVT_GET_ID

(

event

)

(event & MGMT_EVT_OP_ID_ALL)

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

Get event ID from event.

Typedef Documentation

mgmt_cb

mgmt_cb

#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

fs_mgmt_group_events

enum fs_mgmt_group_events

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

MGMT event opcodes for filesystem management group.

Enumerator
MGMT_EVT_OP_FS_MGMT_FILE_ACCESS	Callback when a file has been accessed, data is fs_mgmt_file_access().
MGMT_EVT_OP_FS_MGMT_ALL	Used to enable all fs_mgmt_group events.

img_mgmt_group_events

enum img_mgmt_group_events

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

MGMT event opcodes for image management group.

Enumerator
MGMT_EVT_OP_IMG_MGMT_DFU_CHUNK	Callback when a client sends a file upload chunk, data is img_mgmt_upload_check().
MGMT_EVT_OP_IMG_MGMT_DFU_STOPPED	Callback when a DFU operation is stopped.
MGMT_EVT_OP_IMG_MGMT_DFU_STARTED	Callback when a DFU operation is started.
MGMT_EVT_OP_IMG_MGMT_DFU_PENDING	Callback when a DFU operation has finished being transferred.
MGMT_EVT_OP_IMG_MGMT_DFU_CONFIRMED	Callback when an image has been confirmed.
MGMT_EVT_OP_IMG_MGMT_DFU_CHUNK_WRITE_COMPLETE	Callback when an image write command has finished writing to flash.
MGMT_EVT_OP_IMG_MGMT_ALL	Used to enable all img_mgmt_group events.

mgmt_cb_groups

enum mgmt_cb_groups

#include <zephyr/mgmt/mcumgr/mgmt/callbacks.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_USER_CUSTOM_START

mgmt_cb_return

enum mgmt_cb_return

#include <zephyr/mgmt/mcumgr/mgmt/callbacks.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 contians the error code of that group to return.

os_mgmt_group_events

enum os_mgmt_group_events

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

MGMT event opcodes for operating system management group.

Enumerator
MGMT_EVT_OP_OS_MGMT_RESET	Callback when a reset command has been received, data is os_mgmt_reset_data.
MGMT_EVT_OP_OS_MGMT_INFO_CHECK	Callback when an info command is processed, data is os_mgmt_info_check.
MGMT_EVT_OP_OS_MGMT_INFO_APPEND	Callback when an info command needs to output data, data is os_mgmt_info_append.
MGMT_EVT_OP_OS_MGMT_DATETIME_GET	Callback when a datetime get command has been received.
MGMT_EVT_OP_OS_MGMT_DATETIME_SET	Callback when a datetime set command has been received, data is struct rtc_time().
MGMT_EVT_OP_OS_MGMT_ALL	Used to enable all os_mgmt_group events.

settings_mgmt_group_events

enum settings_mgmt_group_events

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

MGMT event opcodes for settings management group.

Enumerator
MGMT_EVT_OP_SETTINGS_MGMT_ACCESS	Callback when a setting is read/written/deleted.
MGMT_EVT_OP_SETTINGS_MGMT_ALL	Used to enable all settings_mgmt_group events.

smp_all_events

enum smp_all_events

#include <zephyr/mgmt/mcumgr/mgmt/callbacks.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 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.