sysrepo  2.0.47
YANG-based system repository for all-around configuration management.
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Connection and Session API

Functions

int sr_connect (const sr_conn_options_t opts, sr_conn_ctx_t **conn)
 Connects to the sysrepo datastore. If possible (no other connections exist), also apply any scheduled changes. More...
 
int sr_connection_count (uint32_t *conn_count)
 Learn the current global number of alive connections. More...
 
int sr_discard_oper_changes (sr_conn_ctx_t *conn, sr_session_ctx_t *session, const char *xpath, uint32_t timeout_ms)
 Discard stored push operational data owned by this connection. More...
 
int sr_disconnect (sr_conn_ctx_t *conn)
 Disconnect from the sysrepo datastore. More...
 
uint32_t sr_get_content_id (sr_conn_ctx_t *conn)
 Get content ID of the current YANG module set. It conforms to the requirements for ietf-yang-library "content-id" node value. More...
 
struct ly_ctx * sr_get_context (sr_conn_ctx_t *conn)
 Get the libyang context used by a connection. Can be used in an application for working with data and schemas. Do NOT change this context! More...
 
int sr_get_error_data (sr_error_info_err_t *err, uint32_t idx, uint32_t *size, const void **data)
 Get a specific chunk of error data. More...
 
uid_t sr_get_su_uid (void)
 Get the sysrepo SUPERUSER UID. More...
 
void sr_session_del_orig_data (sr_session_ctx_t *session)
 Remove all pushed event originator data. More...
 
int sr_session_dup_error (sr_session_ctx_t *src_session, sr_session_ctx_t *trg_session)
 Copy the first error (if any) from a session to a callback session. More...
 
sr_conn_ctx_tsr_session_get_connection (sr_session_ctx_t *session)
 Get the connection the session was created on. More...
 
sr_datastore_t sr_session_get_ds (sr_session_ctx_t *session)
 Learn the datastore a session operates on. More...
 
int sr_session_get_error (sr_session_ctx_t *session, const sr_error_info_t **error_info)
 Retrieve information about the error that has occurred during the last operation executed within provided session. More...
 
uint32_t sr_session_get_id (sr_session_ctx_t *session)
 Return the assigned session ID of the sysrepo session. More...
 
int sr_session_get_orig_data (sr_session_ctx_t *session, uint32_t idx, uint32_t *size, const void **data)
 Get a specific chunk of event originator data in a callback. More...
 
const char * sr_session_get_orig_name (sr_session_ctx_t *session)
 Get event originator name. More...
 
const char * sr_session_get_user (sr_session_ctx_t *session)
 Get the effective user of a session. More...
 
int sr_session_notif_buffer (sr_session_ctx_t *session)
 Use notification buffering for the session. More...
 
int sr_session_push_error_data (sr_session_ctx_t *session, uint32_t size, const void *data)
 Push (add) another chunk of error data for a failed callback communicated back to the originator. Its meaning is specific to the error data format (which must be set prior to calling this function) identifier and can be read from the error structure by the originator using sr_get_error_data(). More...
 
int sr_session_push_orig_data (sr_session_ctx_t *session, uint32_t size, const void *data)
 Push (add) another chunk of event originator data used for all events sent on this session. Its meaning is specific to the originator name (which must be set prior to calling this function) and can be read from the implicit event session in the callbacks using sr_session_get_orig_data(). More...
 
int sr_session_set_error_format (sr_session_ctx_t *session, const char *error_format)
 Set error data format identifier for a failed callback communicated back to the originator. This format name should be used for interpreting the error data set by sr_session_push_error_data(). More...
 
int sr_session_set_error_message (sr_session_ctx_t *session, const char *format,...)
 Set an error message for a failed callback communicated back to the originator. Does not print the message. More...
 
int sr_session_set_orig_name (sr_session_ctx_t *session, const char *orig_name)
 Set event originator name used for all events sent on this session. It can then be read from the implicit event session in the callbacks using sr_session_get_orig_name(). This name should be used for interpreting the data set by sr_session_push_orig_data(). More...
 
int sr_session_set_user (sr_session_ctx_t *session, const char *user)
 Set the effective user of a session to a different one that the process owner. More...
 
int sr_session_start (sr_conn_ctx_t *conn, const sr_datastore_t datastore, sr_session_ctx_t **session)
 Start a new session. More...
 
int sr_session_stop (sr_session_ctx_t *session)
 Stop the session and releases resources tied to it. More...
 
int sr_session_switch_ds (sr_session_ctx_t *session, sr_datastore_t ds)
 Change datastore which the session operates on. All subsequent calls will be issued on the chosen datastore. Previous calls are not affected. More...
 
int sr_session_unsubscribe (sr_session_ctx_t *session)
 Unsubscribe all subscriptions created by this session. More...
 
int sr_set_diff_check_callback (sr_conn_ctx_t *conn, sr_diff_check_cb callback)
 Set callback for checking every diff before it is applied on the datastore. The diff is final (only CRUD operations) but without any implicit changes caused by validation. This callback is primarily meant to allow full NACM (NETCONF Access Control) to be performed by a NETCONF server. More...
 
typedef struct sr_conn_ctx_s sr_conn_ctx_t
 Sysrepo connection. More...
 

Detailed Description

Typedef Documentation

typedef struct sr_conn_ctx_s sr_conn_ctx_t

Sysrepo connection.

Definition at line 87 of file sysrepo_types.h.

Function Documentation

int sr_connect ( const sr_conn_options_t  opts,
sr_conn_ctx_t **  conn 
)

Connects to the sysrepo datastore. If possible (no other connections exist), also apply any scheduled changes.

Note
Do not use fork(2) after creating a connection. Sysrepo internally stores the connection ID of every connection. Forking will duplicate the connection and ID resulting in a mismatch.
Parameters
[in]optsOptions overriding default connection handling by this call.
[out]connConnection that can be used for subsequent API calls (automatically allocated, it is supposed to be released by the caller using sr_disconnect).
Returns
Error code (SR_ERR_OK on success).
int sr_connection_count ( uint32_t *  conn_count)

Learn the current global number of alive connections.

Parameters
[out]conn_countCurrent number of connections.
Returns
Error code (SR_ERR_OK on success).
int sr_discard_oper_changes ( sr_conn_ctx_t conn,
sr_session_ctx_t session,
const char *  xpath,
uint32_t  timeout_ms 
)

Discard stored push operational data owned by this connection.

Required WRITE access.

Parameters
[in]connConnection to use.
[in]sessionOptional session to read SID and originator data from.
[in]xpathSelected data to discard, if NULL all the data owned by the connection are discarded.
[in]timeout_msChange callback timeout in milliseconds. If 0, default is used. Note that this timeout is measured separately for each callback meaning this whole function call can easily take more time than this timeout if there are changes applied for several subscribers.
Returns
Error code (SR_ERR_OK on success).
int sr_disconnect ( sr_conn_ctx_t conn)

Disconnect from the sysrepo datastore.

Cleans up and frees connection context allocated by sr_connect. All sessions and subscriptions started within the connection will be automatically stopped and cleaned up too.

Note
On error the function should be retried and must eventually succeed.
Parameters
[in]connConnection acquired with sr_connect call.
Returns
Error code (SR_ERR_OK on success).
uint32_t sr_get_content_id ( sr_conn_ctx_t conn)

Get content ID of the current YANG module set. It conforms to the requirements for ietf-yang-library "content-id" node value.

Parameters
[in]connConnection to use.
Returns
Content ID.
struct ly_ctx* sr_get_context ( sr_conn_ctx_t conn)

Get the libyang context used by a connection. Can be used in an application for working with data and schemas. Do NOT change this context!

Parameters
[in]connConnection to use.
Returns
Const libyang context.
int sr_get_error_data ( sr_error_info_err_t err,
uint32_t  idx,
uint32_t *  size,
const void **  data 
)

Get a specific chunk of error data.

Parameters
[in]errError structure to use.
[in]idxIndex of the error data chunk, starts at 0.
[out]sizeOptional size of the error data chunk.
[out]dataPointer to an opaque error data chunk.
Returns
Error code (SR_ERR_OK on success).
uid_t sr_get_su_uid ( void  )

Get the sysrepo SUPERUSER UID.

Returns
Sysrepo SU UID.
void sr_session_del_orig_data ( sr_session_ctx_t session)

Remove all pushed event originator data.

Parameters
[in]sessionSession (not DS-specific) to use.
int sr_session_dup_error ( sr_session_ctx_t src_session,
sr_session_ctx_t trg_session 
)

Copy the first error (if any) from a session to a callback session.

Parameters
[in]src_sessionSession (not DS-specific) to read the error from.
[in]trg_sessionImplicit session provided in a callback.
Returns
Error code (SR_ERR_OK on success).
sr_conn_ctx_t* sr_session_get_connection ( sr_session_ctx_t session)

Get the connection the session was created on.

Parameters
[in]sessionSession (not DS-specific) to use.
Returns
Sysrepo connection.
sr_datastore_t sr_session_get_ds ( sr_session_ctx_t session)

Learn the datastore a session operates on.

Parameters
[in]sessionSession to use.
Returns
Datastore of the session.
int sr_session_get_error ( sr_session_ctx_t session,
const sr_error_info_t **  error_info 
)

Retrieve information about the error that has occurred during the last operation executed within provided session.

Parameters
[in]sessionSession (not DS-specific) to use.
[out]error_infoDetailed error information. Be aware that returned pointer may change by the next API call executed within the provided session. Do not free or modify returned values.
Returns
Error code (SR_ERR_OK on success).
uint32_t sr_session_get_id ( sr_session_ctx_t session)

Return the assigned session ID of the sysrepo session.

Parameters
[in]sessionSession (not DS-specific) to use.
Returns
sysrepo SID or 0 in case of error.
int sr_session_get_orig_data ( sr_session_ctx_t session,
uint32_t  idx,
uint32_t *  size,
const void **  data 
)

Get a specific chunk of event originator data in a callback.

Parameters
[in]sessionImplicit session provided in a callback.
[in]idxIndex of the data chunk, starts at 0.
[out]sizeOptional size of the data chunk.
[out]dataPointer to an opaque data chunk.
Returns
Error code (SR_ERR_OK on success).
const char* sr_session_get_orig_name ( sr_session_ctx_t session)

Get event originator name.

Parameters
[in]sessionImplicit session provided in a callback.
Returns
Originator name if set, NULL otherwise.
const char* sr_session_get_user ( sr_session_ctx_t session)

Get the effective user of a session.

Parameters
[in]sessionSession (not DS-specific) to use.
Returns
Session user.
int sr_session_notif_buffer ( sr_session_ctx_t session)

Use notification buffering for the session.

When a notification is sent using this session for a module that supports replay (notification should be stored), the notification function does not wait until it is stored but delegates this work to a special thread and returns.

Parameters
[in]sessionSession (not DS-specific) whose notifications will be buffered.
Returns
Error code (SR_ERR_OK on success).
int sr_session_push_error_data ( sr_session_ctx_t session,
uint32_t  size,
const void *  data 
)

Push (add) another chunk of error data for a failed callback communicated back to the originator. Its meaning is specific to the error data format (which must be set prior to calling this function) identifier and can be read from the error structure by the originator using sr_get_error_data().

Parameters
[in]sessionImplicit session provided in a callback.
[in]sizeSize of the error data chunk.
[in]dataPointer to an opaque error data chunk.
Returns
Error code (SR_ERR_OK on success).
int sr_session_push_orig_data ( sr_session_ctx_t session,
uint32_t  size,
const void *  data 
)

Push (add) another chunk of event originator data used for all events sent on this session. Its meaning is specific to the originator name (which must be set prior to calling this function) and can be read from the implicit event session in the callbacks using sr_session_get_orig_data().

Parameters
[in]sessionSession (not DS-specific) to use.
[in]sizeSize of the data chunk.
[in]dataPointer to an opaque data chunk.
Returns
Error code (SR_ERR_OK on success).
int sr_session_set_error_format ( sr_session_ctx_t session,
const char *  error_format 
)

Set error data format identifier for a failed callback communicated back to the originator. This format name should be used for interpreting the error data set by sr_session_push_error_data().

Parameters
[in]sessionImplicit session provided in a callback.
[in]error_formatArbitrary error format identifier.
Returns
Error code (SR_ERR_OK on success).
int sr_session_set_error_message ( sr_session_ctx_t session,
const char *  format,
  ... 
)

Set an error message for a failed callback communicated back to the originator. Does not print the message.

Note
Intended for diff-check, change, RPC/action, or operational callbacks to be used on the provided session.
Parameters
[in]sessionImplicit session provided in a callback.
[in]formatHuman-readable format of the error message.
[in]...Format parameters.
Returns
Error code (SR_ERR_OK on success).
int sr_session_set_orig_name ( sr_session_ctx_t session,
const char *  orig_name 
)

Set event originator name used for all events sent on this session. It can then be read from the implicit event session in the callbacks using sr_session_get_orig_name(). This name should be used for interpreting the data set by sr_session_push_orig_data().

Parameters
[in]sessionSession (not DS-specific) to use.
[in]orig_nameArbitrary originator name.
Returns
Error code (SR_ERR_OK on success).
int sr_session_set_user ( sr_session_ctx_t session,
const char *  user 
)

Set the effective user of a session to a different one that the process owner.

Required SUPERUSER access.

Parameters
[in]sessionSession (not DS-specific) to change.
[in]userSystem user.
Returns
Error code (SR_ERR_OK on success).
int sr_session_start ( sr_conn_ctx_t conn,
const sr_datastore_t  datastore,
sr_session_ctx_t **  session 
)

Start a new session.

Parameters
[in]connConnection acquired with sr_connect call.
[in]datastoreDatastore on which all sysrepo functions within this session will operate. Later on, datastore can be later changed using sr_session_switch_ds call. Functionality of some sysrepo calls does not depend on datastore. If your session will contain just calls like these, you can pass any valid value (e.g. SR_DS_RUNNING).
[out]sessionSession context that can be used for subsequent API calls (automatically allocated, can be released by calling sr_session_stop).
Returns
Error code (SR_ERR_OK on success).
int sr_session_stop ( sr_session_ctx_t session)

Stop the session and releases resources tied to it.

Also releases any locks held and frees subscriptions created (only) by this session.

Note
On error the function should be retried and must eventually succeed. Subscriptions, even if they no longer handle any events are never freed and should be freed manually using sr_unsubscribe.
Parameters
[in]sessionSession to use.
Returns
Error code (SR_ERR_OK on success).
int sr_session_switch_ds ( sr_session_ctx_t session,
sr_datastore_t  ds 
)

Change datastore which the session operates on. All subsequent calls will be issued on the chosen datastore. Previous calls are not affected.

Parameters
[in]sessionSession to modify.
[in]dsNew datastore that will be operated on.
Returns
Error code (SR_ERR_OK on success).
int sr_session_unsubscribe ( sr_session_ctx_t session)

Unsubscribe all subscriptions created by this session.

Note
Subscriptions, even if they no longer handle any events are never freed and should be freed manually using sr_unsubscribe.
Parameters
[in]sessionSession to use.
Returns
Error code (SR_ERR_OK on success).
int sr_set_diff_check_callback ( sr_conn_ctx_t conn,
sr_diff_check_cb  callback 
)

Set callback for checking every diff before it is applied on the datastore. The diff is final (only CRUD operations) but without any implicit changes caused by validation. This callback is primarily meant to allow full NACM (NETCONF Access Control) to be performed by a NETCONF server.

Required SUPERUSER access.

Parameters
[in]connConnection, whose all sessions diffs will be passed to this callback.
[in]callbackCallback to call for every diff.
Returns
Error code (SR_ERR_OK on success).