Zephyr Project API 4.0.99
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
MCUmgr callback API

MCUmgr callback API. More...

Modules

 MCUmgr enum_mgmt callback API
 MCUmgr enum_mgmt callback API.
 
 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_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...
 
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_IMAGE_SLOT_STATE = MGMT_DEF_EVT_OP_ID(MGMT_EVT_GRP_IMG, 6) , MGMT_EVT_OP_IMG_MGMT_SLOT_INFO_IMAGE = MGMT_DEF_EVT_OP_ID(MGMT_EVT_GRP_IMG, 7) ,
  MGMT_EVT_OP_IMG_MGMT_SLOT_INFO_SLOT = MGMT_DEF_EVT_OP_ID(MGMT_EVT_GRP_IMG, 8) , 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_BOOTLOADER_INFO = MGMT_DEF_EVT_OP_ID(MGMT_EVT_GRP_OS, 5) , 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...
 
enum  enum_mgmt_group_events { MGMT_EVT_OP_ENUM_MGMT_DETAILS = MGMT_DEF_EVT_OP_ID(MGMT_EVT_GRP_ENUM, 0) , MGMT_EVT_OP_ENUM_MGMT_ALL = MGMT_DEF_EVT_OP_ALL(MGMT_EVT_GRP_ENUM) }
 MGMT event opcodes for enumeration 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

◆ MGMT_EVT_GET_GROUP

#define MGMT_EVT_GET_GROUP (   event)    ((event >> 16) & MGMT_EVT_OP_ID_ALL)

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

Get event ID from event.

Typedef Documentation

◆ mgmt_cb

mgmt_cb

#include <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
eventmcumgr_op_t.
prev_statusmgmt_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).
rcIf 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.
groupIf 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_moreSet to true to abort further processing by additional handlers.
dataOptional event argument.
data_sizeSize 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

◆ enum_mgmt_group_events

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

MGMT event opcodes for enumeration management group.

Enumerator
MGMT_EVT_OP_ENUM_MGMT_DETAILS 

Callback when fetching details on supported command groups.

MGMT_EVT_OP_ENUM_MGMT_ALL 

Used to enable all enum_mgmt_group events.

◆ fs_mgmt_group_events

#include <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

#include <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_IMAGE_SLOT_STATE 

Callback when an image slot's state is encoded for a response.

MGMT_EVT_OP_IMG_MGMT_SLOT_INFO_IMAGE 

Callback when an slot list command outputs fields for an image.

MGMT_EVT_OP_IMG_MGMT_SLOT_INFO_SLOT 

Callback when an slot list command outputs fields for a slot of an image.

MGMT_EVT_OP_IMG_MGMT_ALL 

Used to enable all img_mgmt_group events.

◆ mgmt_cb_groups

#include <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_ENUM 
MGMT_EVT_GRP_USER_CUSTOM_START 

◆ mgmt_cb_return

#include <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 contains the error code of that group to return.

◆ os_mgmt_group_events

#include <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_BOOTLOADER_INFO 

Callback when a bootloader info command has been received, data is os_mgmt_bootloader_info_data.

MGMT_EVT_OP_OS_MGMT_ALL 

Used to enable all os_mgmt_group events.

◆ settings_mgmt_group_events

#include <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

#include <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

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

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

Parameters
eventmcumgr_op_t.
dataOptional event argument.
data_sizeSize of optional event argument (0 if none).
err_rcPointer to rc value.
err_groupPointer 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 <include/zephyr/mgmt/mcumgr/mgmt/callbacks.h>

Register event callback function.

Parameters
callbackCallback struct.

◆ mgmt_callback_unregister()

void mgmt_callback_unregister ( struct mgmt_callback callback)

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

Unregister event callback function.

Parameters
callbackCallback struct.

◆ mgmt_evt_get_index()

uint8_t mgmt_evt_get_index ( uint32_t  event)

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

Get event ID index from event.

Parameters
eventEvent to get ID index from.
Returns
Event index.