lib/mgmt_fe_client.h

   1 // SPDX-License-Identifier: GPL-2.0-or-later
   2 /*
   3  * MGMTD Frontend Client Library api interfaces
   4  * Copyright (C) 2021  Vmware, Inc.
   5  *                     Pushpasis Sarkar <spushpasis@vmware.com>
   6  */
   7
   8 #ifndef _FRR_MGMTD_FE_CLIENT_H_
   9 #define _FRR_MGMTD_FE_CLIENT_H_
  10
  11 #ifdef __cplusplus
  12 extern "C" {
  13 #endif
  14
  15 #include "mgmt_pb.h"
  16 #include "thread.h"
  17 #include "mgmtd/mgmt_defines.h"
  18
  19 /***************************************************************
  20  * Macros
  21  ***************************************************************/
  22
  23 /*
  24  * The server port MGMTD daemon is listening for Backend Client
  25  * connections.
  26  */
  27
  28 #define MGMTD_FE_CLIENT_ERROR_STRING_MAX_LEN 32
  29
  30 #define MGMTD_FE_DEFAULT_CONN_RETRY_INTVL_SEC 5
  31
  32 #define MGMTD_FE_MSG_PROC_DELAY_USEC 10
  33 #define MGMTD_FE_MAX_NUM_MSG_PROC 500
  34
  35 #define MGMTD_FE_MSG_WRITE_DELAY_MSEC 1
  36 #define MGMTD_FE_MAX_NUM_MSG_WRITE 100
  37
  38 #define GMGD_FE_MAX_NUM_REQ_ITEMS 64
  39
  40 #define MGMTD_FE_MSG_MAX_LEN 9000
  41
  42 #define MGMTD_SOCKET_FE_SEND_BUF_SIZE 65535
  43 #define MGMTD_SOCKET_FE_RECV_BUF_SIZE MGMTD_SOCKET_FE_SEND_BUF_SIZE
  44
  45 /***************************************************************
  46  * Data-structures
  47  ***************************************************************/
  48
  49 #define MGMTD_SESSION_ID_NONE 0
  50
  51 #define MGMTD_CLIENT_ID_NONE 0
  52
  53 #define MGMTD_DS_NONE MGMTD__DATASTORE_ID__DS_NONE
  54 #define MGMTD_DS_RUNNING MGMTD__DATASTORE_ID__RUNNING_DS
  55 #define MGMTD_DS_CANDIDATE MGMTD__DATASTORE_ID__CANDIDATE_DS
  56 #define MGMTD_DS_OPERATIONAL MGMTD__DATASTORE_ID__OPERATIONAL_DS
  57 #define MGMTD_DS_MAX_ID MGMTD_DS_OPERATIONAL + 1
  58
  59 /*
  60  * All the client specific information this library needs to
  61  * initialize itself, setup connection with MGMTD FrontEnd interface
  62  * and carry on all required procedures appropriately.
  63  *
  64  * FrontEnd clients need to initialise a instance of this structure
  65  * with appropriate data and pass it while calling the API
  66  * to initialize the library (See mgmt_fe_client_lib_init for
  67  * more details).
  68  */
  69 struct mgmt_fe_client_params {
  70         char name[MGMTD_CLIENT_NAME_MAX_LEN];
  71         uintptr_t user_data;
  72         unsigned long conn_retry_intvl_sec;
  73
  74         void (*client_connect_notify)(uintptr_t lib_hndl,
  75                                       uintptr_t user_data,
  76                                       bool connected);
  77
  78         void (*client_session_notify)(uintptr_t lib_hndl,
  79                                       uintptr_t user_data,
  80                                       uint64_t client_id,
  81                                       bool create, bool success,
  82                                       uintptr_t session_id,
  83                                       uintptr_t user_session_ctx);
  84
  85         void (*lock_ds_notify)(uintptr_t lib_hndl, uintptr_t user_data,
  86                                uint64_t client_id, uintptr_t session_id,
  87                                uintptr_t user_session_ctx, uint64_t req_id,
  88                                bool lock_ds, bool success,
  89                                Mgmtd__DatastoreId ds_id, char *errmsg_if_any);
  90
  91         void (*set_config_notify)(uintptr_t lib_hndl, uintptr_t user_data,
  92                                   uint64_t client_id, uintptr_t session_id,
  93                                   uintptr_t user_session_ctx, uint64_t req_id,
  94                                   bool success, Mgmtd__DatastoreId ds_id,
  95                                   char *errmsg_if_any);
  96
  97         void (*commit_config_notify)(
  98                 uintptr_t lib_hndl, uintptr_t user_data, uint64_t client_id,
  99                 uintptr_t session_id, uintptr_t user_session_ctx,
 100                 uint64_t req_id, bool success, Mgmtd__DatastoreId src_ds_id,
 101                 Mgmtd__DatastoreId dst_ds_id, bool validate_only,
 102                 char *errmsg_if_any);
 103
 104         enum mgmt_result (*get_data_notify)(
 105                 uintptr_t lib_hndl, uintptr_t user_data, uint64_t client_id,
 106                 uintptr_t session_id, uintptr_t user_session_ctx,
 107                 uint64_t req_id, bool success, Mgmtd__DatastoreId ds_id,
 108                 Mgmtd__YangData **yang_data, size_t num_data, int next_key,
 109                 char *errmsg_if_any);
 110
 111         enum mgmt_result (*data_notify)(
 112                 uint64_t client_id, uint64_t session_id, uintptr_t user_data,
 113                 uint64_t req_id, Mgmtd__DatastoreId ds_id,
 114                 Mgmtd__YangData **yang_data, size_t num_data);
 115 };
 116
 117 /***************************************************************
 118  * API prototypes
 119  ***************************************************************/
 120
 121 /*
 122  * Initialize library and try connecting with MGMTD FrontEnd interface.
 123  *
 124  * params
 125  *    Frontend client parameters.
 126  *
 127  * master_thread
 128  *    Thread master.
 129  *
 130  * Returns:
 131  *    Frontend client lib handler (nothing but address of mgmt_fe_client_ctx)
 132  */
 133 extern uintptr_t
 134 mgmt_fe_client_lib_init(struct mgmt_fe_client_params *params,
 135                             struct thread_master *master_thread);
 136
 137 /*
 138  * Create a new Session for a Frontend Client connection.
 139  *
 140  * lib_hndl
 141  *    Client library handler.
 142  *
 143  * client_id
 144  *    Unique identifier of client.
 145  *
 146  * user_ctx
 147  *    Client context.
 148  *
 149  * Returns:
 150  *    MGMTD_SUCCESS on success, MGMTD_* otherwise.
 151  */
 152 extern enum mgmt_result mgmt_fe_create_client_session(uintptr_t lib_hndl,
 153                                                           uint64_t client_id,
 154                                                           uintptr_t user_ctx);
 155
 156 /*
 157  * Delete an existing Session for a Frontend Client connection.
 158  *
 159  * lib_hndl
 160  *    Client library handler.
 161  *
 162  * client_id
 163  *    Unique identifier of client.
 164  *
 165  * Returns:
 166  *    MGMTD_SUCCESS on success, MGMTD_* otherwise.
 167  */
 168 extern enum mgmt_result mgmt_fe_destroy_client_session(uintptr_t lib_hndl,
 169                                                        uint64_t client_id);
 170
 171 /*
 172  * Send UN/LOCK_DS_REQ to MGMTD for a specific Datastore DS.
 173  *
 174  * lib_hndl
 175  *    Client library handler.
 176  *
 177  * session_id
 178  *    Client session ID.
 179  *
 180  * req_id
 181  *    Client request ID.
 182  *
 183  * ds_id
 184  *    Datastore ID (Running/Candidate/Oper/Startup)
 185  *
 186  * lock_ds
 187  *    TRUE for lock request, FALSE for unlock request.
 188  *
 189  * Returns:
 190  *    MGMTD_SUCCESS on success, MGMTD_* otherwise.
 191  */
 192 extern enum mgmt_result
 193 mgmt_fe_lock_ds(uintptr_t lib_hndl, uintptr_t session_id, uint64_t req_id,
 194                     Mgmtd__DatastoreId ds_id, bool lock_ds);
 195
 196 /*
 197  * Send SET_CONFIG_REQ to MGMTD for one or more config data(s).
 198  *
 199  * lib_hndl
 200  *    Client library handler.
 201  *
 202  * session_id
 203  *    Client session ID.
 204  *
 205  * req_id
 206  *    Client request ID.
 207  *
 208  * ds_id
 209  *    Datastore ID (Running/Candidate/Oper/Startup)
 210  *
 211  * conf_req
 212  *    Details regarding the SET_CONFIG_REQ.
 213  *
 214  * num_req
 215  *    Number of config requests.
 216  *
 217  * implcit commit
 218  *    TRUE for implicit commit, FALSE otherwise.
 219  *
 220  * dst_ds_id
 221  *    Destination Datastore ID where data needs to be set.
 222  *
 223  * Returns:
 224  *    MGMTD_SUCCESS on success, MGMTD_* otherwise.
 225  */
 226 extern enum mgmt_result
 227 mgmt_fe_set_config_data(uintptr_t lib_hndl, uintptr_t session_id,
 228                             uint64_t req_id, Mgmtd__DatastoreId ds_id,
 229                             Mgmtd__YangCfgDataReq **config_req, int num_req,
 230                             bool implicit_commit, Mgmtd__DatastoreId dst_ds_id);
 231
 232 /*
 233  * Send SET_COMMMIT_REQ to MGMTD for one or more config data(s).
 234  *
 235  * lib_hndl
 236  *    Client library handler.
 237  *
 238  * session_id
 239  *    Client session ID.
 240  *
 241  * req_id
 242  *    Client request ID.
 243  *
 244  * src_ds_id
 245  *    Source datastore ID from where data needs to be committed from.
 246  *
 247  * dst_ds_id
 248  *    Destination datastore ID where data needs to be committed to.
 249  *
 250  * validate_only
 251  *    TRUE if data needs to be validated only, FALSE otherwise.
 252  *
 253  * abort
 254  *    TRUE if need to restore Src DS back to Dest DS, FALSE otherwise.
 255  *
 256  * Returns:
 257  *    MGMTD_SUCCESS on success, MGMTD_* otherwise.
 258  */
 259 extern enum mgmt_result
 260 mgmt_fe_commit_config_data(uintptr_t lib_hndl, uintptr_t session_id,
 261                                uint64_t req_id, Mgmtd__DatastoreId src_ds_id,
 262                                Mgmtd__DatastoreId dst_ds_id, bool validate_only,
 263                                bool abort);
 264
 265 /*
 266  * Send GET_CONFIG_REQ to MGMTD for one or more config data item(s).
 267  *
 268  * lib_hndl
 269  *    Client library handler.
 270  *
 271  * session_id
 272  *    Client session ID.
 273  *
 274  * req_id
 275  *    Client request ID.
 276  *
 277  * ds_id
 278  *    Datastore ID (Running/Candidate)
 279  *
 280  * data_req
 281  *    Get config requested.
 282  *
 283  * num_req
 284  *    Number of get config requests.
 285  *
 286  * Returns:
 287  *    MGMTD_SUCCESS on success, MGMTD_* otherwise.
 288  */
 289 extern enum mgmt_result
 290 mgmt_fe_get_config_data(uintptr_t lib_hndl, uintptr_t session_id,
 291                             uint64_t req_id, Mgmtd__DatastoreId ds_id,
 292                             Mgmtd__YangGetDataReq **data_req, int num_reqs);
 293
 294 /*
 295  * Send GET_DATA_REQ to MGMTD for one or more data item(s).
 296  *
 297  * Similar to get config request but supports getting data
 298  * from operational ds aka backend clients directly.
 299  */
 300 extern enum mgmt_result
 301 mgmt_fe_get_data(uintptr_t lib_hndl, uintptr_t session_id, uint64_t req_id,
 302                      Mgmtd__DatastoreId ds_id, Mgmtd__YangGetDataReq **data_req,
 303                      int num_reqs);
 304
 305 /*
 306  * Send NOTIFY_REGISTER_REQ to MGMTD daemon.
 307  *
 308  * lib_hndl
 309  *    Client library handler.
 310  *
 311  * session_id
 312  *    Client session ID.
 313  *
 314  * req_id
 315  *    Client request ID.
 316  *
 317  * ds_id
 318  *    Datastore ID.
 319  *
 320  * register_req
 321  *    TRUE if registering, FALSE otherwise.
 322  *
 323  * data_req
 324  *    Details of the YANG notification data.
 325  *
 326  * num_reqs
 327  *    Number of data requests.
 328  *
 329  * Returns:
 330  *    MGMTD_SUCCESS on success, MGMTD_* otherwise.
 331  */
 332 extern enum mgmt_result
 333 mgmt_fe_register_yang_notify(uintptr_t lib_hndl, uintptr_t session_id,
 334                                  uint64_t req_id, Mgmtd__DatastoreId ds_id,
 335                                  bool register_req,
 336                                  Mgmtd__YangDataXPath **data_req, int num_reqs);
 337
 338 /*
 339  * Destroy library and cleanup everything.
 340  */
 341 extern void mgmt_fe_client_lib_destroy(uintptr_t lib_hndl);
 342
 343 #ifdef __cplusplus
 344 }
 345 #endif
 346
 347 #endif /* _FRR_MGMTD_FE_CLIENT_H_ */