// SPDX-License-Identifier: GPL-2.0-or-later /* * MGMTD Frontend Client Library api interfaces * Copyright (C) 2021 Vmware, Inc. * Pushpasis Sarkar */ #ifndef _FRR_MGMTD_FE_CLIENT_H_ #define _FRR_MGMTD_FE_CLIENT_H_ #ifdef __cplusplus extern "C" { #endif #include "mgmt_pb.h" #include "frrevent.h" #include "mgmt_defines.h" #include "mgmt_msg_native.h" /*************************************************************** * Macros ***************************************************************/ /* * The server port MGMTD daemon is listening for Backend Client * connections. */ #define MGMTD_FE_MSG_PROC_DELAY_USEC 10 #define MGMTD_FE_MAX_NUM_MSG_PROC 500 #define MGMTD_FE_MAX_NUM_MSG_WRITE 100 #define MGMTD_FE_MAX_MSG_LEN (64 * 1024) /*************************************************************** * Data-structures ***************************************************************/ #define MGMTD_SESSION_ID_NONE 0 #define MGMTD_CLIENT_ID_NONE 0 #define MGMTD_DS_NONE MGMTD__DATASTORE_ID__DS_NONE #define MGMTD_DS_RUNNING MGMTD__DATASTORE_ID__RUNNING_DS #define MGMTD_DS_CANDIDATE MGMTD__DATASTORE_ID__CANDIDATE_DS #define MGMTD_DS_OPERATIONAL MGMTD__DATASTORE_ID__OPERATIONAL_DS #define MGMTD_DS_MAX_ID MGMTD_DS_OPERATIONAL + 1 struct mgmt_fe_client; /* * All the client specific information this library needs to * initialize itself, setup connection with MGMTD FrontEnd interface * and carry on all required procedures appropriately. * * FrontEnd clients need to initialise a instance of this structure * with appropriate data and pass it while calling the API * to initialize the library (See mgmt_fe_client_lib_init for * more details). */ struct mgmt_fe_client_cbs { void (*client_connect_notify)(struct mgmt_fe_client *client, uintptr_t user_data, bool connected); void (*client_session_notify)(struct mgmt_fe_client *client, uintptr_t user_data, uint64_t client_id, bool create, bool success, uintptr_t session_id, uintptr_t user_session_client); void (*lock_ds_notify)(struct mgmt_fe_client *client, uintptr_t user_data, uint64_t client_id, uintptr_t session_id, uintptr_t user_session_client, uint64_t req_id, bool lock_ds, bool success, Mgmtd__DatastoreId ds_id, char *errmsg_if_any); void (*set_config_notify)(struct mgmt_fe_client *client, uintptr_t user_data, uint64_t client_id, uintptr_t session_id, uintptr_t user_session_client, uint64_t req_id, bool success, Mgmtd__DatastoreId ds_id, bool implcit_commit, char *errmsg_if_any); void (*commit_config_notify)(struct mgmt_fe_client *client, uintptr_t user_data, uint64_t client_id, uintptr_t session_id, uintptr_t user_session_client, uint64_t req_id, bool success, Mgmtd__DatastoreId src_ds_id, Mgmtd__DatastoreId dst_ds_id, bool validate_only, char *errmsg_if_any); int (*get_data_notify)(struct mgmt_fe_client *client, uintptr_t user_data, uint64_t client_id, uintptr_t session_id, uintptr_t user_session_client, uint64_t req_id, bool success, Mgmtd__DatastoreId ds_id, Mgmtd__YangData **yang_data, size_t num_data, int next_key, char *errmsg_if_any); int (*data_notify)(uint64_t client_id, uint64_t session_id, uintptr_t user_data, uint64_t req_id, Mgmtd__DatastoreId ds_id, Mgmtd__YangData **yang_data, size_t num_data); /* Called when get-tree result is returned */ int (*get_tree_notify)(struct mgmt_fe_client *client, uintptr_t user_data, uint64_t client_id, uint64_t session_id, uintptr_t session_ctx, uint64_t req_id, Mgmtd__DatastoreId ds_id, LYD_FORMAT result_type, void *result, size_t len, int partial_error); /* Called when edit result is returned */ int (*edit_notify)(struct mgmt_fe_client *client, uintptr_t user_data, uint64_t client_id, uint64_t session_id, uintptr_t session_ctx, uint64_t req_id, const char *xpath); /* Called when RPC result is returned */ int (*rpc_notify)(struct mgmt_fe_client *client, uintptr_t user_data, uint64_t client_id, uint64_t session_id, uintptr_t session_ctx, uint64_t req_id, const char *result); /* Called with asynchronous notifications from backends */ int (*async_notification)(struct mgmt_fe_client *client, uintptr_t user_data, uint64_t client_id, uint64_t session_id, uintptr_t session_ctx, const char *result); /* Called when new native error is returned */ int (*error_notify)(struct mgmt_fe_client *client, uintptr_t user_data, uint64_t client_id, uint64_t session_id, uintptr_t session_ctx, uint64_t req_id, int error, const char *errstr); }; extern struct debug mgmt_dbg_fe_client; /*************************************************************** * API prototypes ***************************************************************/ #define debug_fe_client(fmt, ...) \ DEBUGD(&mgmt_dbg_fe_client, "FE-CLIENT: %s: " fmt, __func__, \ ##__VA_ARGS__) #define log_err_fe_client(fmt, ...) \ zlog_err("FE-CLIENT: %s: ERROR: " fmt, __func__, ##__VA_ARGS__) #define debug_check_fe_client() \ DEBUG_MODE_CHECK(&mgmt_dbg_fe_client, DEBUG_MODE_ALL) /* * Initialize library and try connecting with MGMTD FrontEnd interface. * * params * Frontend client parameters. * * master_thread * Thread master. * * Returns: * Frontend client lib handler (nothing but address of mgmt_fe_client) */ extern struct mgmt_fe_client * mgmt_fe_client_create(const char *client_name, struct mgmt_fe_client_cbs *cbs, uintptr_t user_data, struct event_loop *event_loop); /* * Initialize library vty (adds debug support). * * This call should be added to your component when enabling other vty * code to enable mgmtd client debugs. When adding, one needs to also * add a their component in `xref2vtysh.py` as well. */ extern void mgmt_fe_client_lib_vty_init(void); /* * Print enabled debugging commands. */ extern void mgmt_debug_fe_client_show_debug(struct vty *vty); /* * Create a new Session for a Frontend Client connection. * * lib_hndl * Client library handler. * * client_id * Unique identifier of client. * * user_client * Client context. * * Returns: * MGMTD_SUCCESS on success, MGMTD_* otherwise. */ extern enum mgmt_result mgmt_fe_create_client_session(struct mgmt_fe_client *client, uint64_t client_id, uintptr_t user_client); /* * Delete an existing Session for a Frontend Client connection. * * lib_hndl * Client library handler. * * client_id * Unique identifier of client. * * Returns: * 0 on success, otherwise msg_conn_send_msg() return values. */ extern enum mgmt_result mgmt_fe_destroy_client_session(struct mgmt_fe_client *client, uint64_t client_id); /* * Send UN/LOCK_DS_REQ to MGMTD for a specific Datastore DS. * * lib_hndl * Client library handler. * * session_id * Client session ID. * * req_id * Client request ID. * * ds_id * Datastore ID (Running/Candidate/Oper/Startup) * * lock_ds * TRUE for lock request, FALSE for unlock request. * * Returns: * 0 on success, otherwise msg_conn_send_msg() return values. */ extern int mgmt_fe_send_lockds_req(struct mgmt_fe_client *client, uint64_t session_id, uint64_t req_id, Mgmtd__DatastoreId ds_id, bool lock_ds, bool scok); /* * Send SET_CONFIG_REQ to MGMTD for one or more config data(s). * * lib_hndl * Client library handler. * * session_id * Client session ID. * * req_id * Client request ID. * * ds_id * Datastore ID (Running/Candidate/Oper/Startup) * * conf_req * Details regarding the SET_CONFIG_REQ. * * num_req * Number of config requests. * * implcit commit * TRUE for implicit commit, FALSE otherwise. * * dst_ds_id * Destination Datastore ID where data needs to be set. * * Returns: * 0 on success, otherwise msg_conn_send_msg() return values. */ extern int mgmt_fe_send_setcfg_req(struct mgmt_fe_client *client, uint64_t session_id, uint64_t req_id, Mgmtd__DatastoreId ds_id, Mgmtd__YangCfgDataReq **config_req, int num_req, bool implicit_commit, Mgmtd__DatastoreId dst_ds_id); /* * Send SET_COMMMIT_REQ to MGMTD for one or more config data(s). * * lib_hndl * Client library handler. * * session_id * Client session ID. * * req_id * Client request ID. * * src_ds_id * Source datastore ID from where data needs to be committed from. * * dst_ds_id * Destination datastore ID where data needs to be committed to. * * validate_only * TRUE if data needs to be validated only, FALSE otherwise. * * abort * TRUE if need to restore Src DS back to Dest DS, FALSE otherwise. * * Returns: * 0 on success, otherwise msg_conn_send_msg() return values. */ extern int mgmt_fe_send_commitcfg_req(struct mgmt_fe_client *client, uint64_t session_id, uint64_t req_id, Mgmtd__DatastoreId src_ds_id, Mgmtd__DatastoreId dst_ds_id, bool validate_only, bool abort); /* * Send GET_REQ to MGMTD for one or more config data item(s). * * If is_config is true gets config from the MGMTD datastore, otherwise * operational state is queried from the backend clients. * * lib_hndl * Client library handler. * * session_id * Client session ID. * * is_config * True if get-config else get-data. * * req_id * Client request ID. * * ds_id * Datastore ID (Running/Candidate) * * data_req * Get xpaths requested. * * num_req * Number of get xpath requests. * * Returns: * 0 on success, otherwise msg_conn_send_msg() return values. */ extern int mgmt_fe_send_get_req(struct mgmt_fe_client *client, uint64_t session_id, uint64_t req_id, bool is_config, Mgmtd__DatastoreId ds_id, Mgmtd__YangGetDataReq **data_req, int num_reqs); /* * Send NOTIFY_REGISTER_REQ to MGMTD daemon. * * lib_hndl * Client library handler. * * session_id * Client session ID. * * req_id * Client request ID. * * ds_id * Datastore ID. * * register_req * TRUE if registering, FALSE otherwise. * * data_req * Details of the YANG notification data. * * num_reqs * Number of data requests. * * Returns: * 0 on success, otherwise msg_conn_send_msg() return values. */ extern int mgmt_fe_send_regnotify_req(struct mgmt_fe_client *client, uint64_t session_id, uint64_t req_id, Mgmtd__DatastoreId ds_id, bool register_req, Mgmtd__YangDataXPath **data_req, int num_reqs); /* * Send GET-DATA to MGMTD daemon. * * client * Client object. * * session_id * Client session ID. * * req_id * Client request ID. * * datastore * Datastore for getting data. * * result_type * The LYD_FORMAT of the result. * * flags * Flags to control the behavior of the request. * * defaults * Options to control the reporting of default values. * * xpath * the xpath to get. * * Returns: * 0 on success, otherwise msg_conn_send_msg() return values. */ extern int mgmt_fe_send_get_data_req(struct mgmt_fe_client *client, uint64_t session_id, uint64_t req_id, uint8_t datastore, LYD_FORMAT result_type, uint8_t flags, uint8_t defaults, const char *xpath); /* * Send EDIT to MGMTD daemon. * * client * Client object. * * session_id * Client session ID. * * req_id * Client request ID. * * datastore * Datastore for editing. * * request_type * The LYD_FORMAT of the request. * * flags * Flags to control the behavior of the request. * * operation * NB_OP_* operation to perform. * * xpath * the xpath to edit. * * data * the data tree. * * Returns: * 0 on success, otherwise msg_conn_send_msg() return values. */ extern int mgmt_fe_send_edit_req(struct mgmt_fe_client *client, uint64_t session_id, uint64_t req_id, uint8_t datastore, LYD_FORMAT request_type, uint8_t flags, uint8_t operation, const char *xpath, const char *data); /* * Send RPC request to MGMTD daemon. * * client * Client object. * * session_id * Client session ID. * * req_id * Client request ID. * * result_type * The LYD_FORMAT of the result. * * xpath * the xpath of the RPC. * * data * the data tree. * * Returns: * 0 on success, otherwise msg_conn_send_msg() return values. */ extern int mgmt_fe_send_rpc_req(struct mgmt_fe_client *client, uint64_t session_id, uint64_t req_id, LYD_FORMAT request_type, const char *xpath, const char *data); /* * Destroy library and cleanup everything. */ extern void mgmt_fe_client_destroy(struct mgmt_fe_client *client); /* * Get count of open sessions. */ extern uint mgmt_fe_client_session_count(struct mgmt_fe_client *client); /* * True if the current handled message is being short-circuited */ extern bool mgmt_fe_client_current_msg_short_circuit(struct mgmt_fe_client *client); /** * Get the name of the client * * Args: * The client object. * * Return: * The name of the client. */ extern const char *mgmt_fe_client_name(struct mgmt_fe_client *client); #ifdef __cplusplus } #endif #endif /* _FRR_MGMTD_FE_CLIENT_H_ */