libnetconf2  1.1.48
NETCONF library for clients and servers
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Server Session

Server-side NETCONF session manipulation. More...

Macros

#define NC_PSPOLL_NOSESSIONS   0x0001
 
#define NC_PSPOLL_TIMEOUT   0x0002
 
#define NC_PSPOLL_RPC   0x0004
 
#define NC_PSPOLL_BAD_RPC   0x0008
 
#define NC_PSPOLL_REPLY_ERROR   0x0010
 
#define NC_PSPOLL_SESSION_TERM   0x0020
 
#define NC_PSPOLL_SESSION_ERROR   0x0040
 
#define NC_PSPOLL_ERROR   0x0080
 
#define NC_PSPOLL_SSH_MSG   0x00100
 
#define NC_PSPOLL_SSH_CHANNEL   0x0200
 

Typedefs

typedef struct nc_server_reply *(* nc_rpc_clb )(struct lyd_node *rpc, struct nc_session *session)
 Prototype of callbacks that are called if some RPCs are received. More...
 

Functions

void nc_session_set_term_reason (struct nc_session *session, NC_SESSION_TERM_REASON reason)
 Set the termination reason for a session. Use only in nc_rpc_clb callbacks. More...
 
void nc_session_set_killed_by (struct nc_session *session, uint32_t sid)
 Set the session-id of the session responsible for this session's termination. More...
 
void nc_session_set_status (struct nc_session *session, NC_STATUS status)
 Set the status of a session. More...
 
void nc_set_global_rpc_clb (nc_rpc_clb clb)
 Set a global nc_rpc_clb that is called if the particular RPC request is received and the private field in the corresponding RPC schema node is NULL. More...
 
NC_MSG_TYPE nc_accept_inout (int fdin, int fdout, const char *username, struct nc_session **session)
 Accept a new session on a pre-established transport session. More...
 
struct nc_pollsession * nc_ps_new (void)
 Create an empty structure for polling sessions. More...
 
void nc_ps_free (struct nc_pollsession *ps)
 Free a pollsession structure. More...
 
int nc_ps_add_session (struct nc_pollsession *ps, struct nc_session *session)
 Add a session to a pollsession structure. More...
 
int nc_ps_del_session (struct nc_pollsession *ps, struct nc_session *session)
 Remove a session from a pollsession structure. More...
 
struct nc_session * nc_ps_get_session (const struct nc_pollsession *ps, uint16_t idx)
 Get a session from a pollsession structure matching the session ID. More...
 
uint16_t nc_ps_session_count (struct nc_pollsession *ps)
 Learn the number of sessions in a pollsession structure. More...
 
int nc_ps_poll (struct nc_pollsession *ps, int timeout, struct nc_session **session)
 Poll sessions and process any received RPCs. More...
 
void nc_ps_clear (struct nc_pollsession *ps, int all, void(*data_free)(void *))
 Remove sessions from a pollsession structure and call nc_session_free() on them. More...
 
time_t nc_session_get_start_time (const struct nc_session *session)
 Get session start time. More...
 
void nc_session_set_notif_status (struct nc_session *session, int notif_status)
 Set session notification subscription flag. More...
 
int nc_session_get_notif_status (const struct nc_session *session)
 Get session notification subscription flag. More...
 
int nc_session_is_callhome (const struct nc_session *session)
 Learn whether a session was created using Call Home or not. Works only for server sessions. More...
 

Detailed Description

Server-side NETCONF session manipulation.

Macro Definition Documentation

#define NC_PSPOLL_NOSESSIONS   0x0001

No sessions to poll.

Definition at line 301 of file session_server.h.

#define NC_PSPOLL_TIMEOUT   0x0002

Timeout elapsed.

Definition at line 302 of file session_server.h.

#define NC_PSPOLL_RPC   0x0004

RPC was correctly parsed and processed.

Definition at line 303 of file session_server.h.

#define NC_PSPOLL_BAD_RPC   0x0008

RPC was received, but failed to be parsed.

Definition at line 304 of file session_server.h.

#define NC_PSPOLL_REPLY_ERROR   0x0010

Response to the RPC was a <rpc-reply> of type error.

Definition at line 305 of file session_server.h.

#define NC_PSPOLL_SESSION_TERM   0x0020

Some session was terminated.

Definition at line 306 of file session_server.h.

#define NC_PSPOLL_SESSION_ERROR   0x0040

Some session was terminated incorrectly (not by a <close-session> or <kill-session> RPC).

Definition at line 307 of file session_server.h.

#define NC_PSPOLL_ERROR   0x0080

Other fatal errors (they are printed).

Definition at line 308 of file session_server.h.

#define NC_PSPOLL_SSH_MSG   0x00100

SSH message received (and processed, if relevant, only with SSH support).

Definition at line 311 of file session_server.h.

#define NC_PSPOLL_SSH_CHANNEL   0x0200

New SSH channel opened on an existing session (only with SSH support).

Definition at line 312 of file session_server.h.

Typedef Documentation

typedef struct nc_server_reply*(* nc_rpc_clb)(struct lyd_node *rpc, struct nc_session *session)

Prototype of callbacks that are called if some RPCs are received.

If session termination reason is changed in the callback, one last reply is sent and then the session is considered invalid.

The callback is set via nc_set_global_rpc_clb().

Parameters
[in]rpcParsed client RPC request.
[in]sessionSession the RPC arrived on.
Returns
Server reply. If NULL, an operation-failed error will be sent to the client.

Definition at line 58 of file session_server.h.

Function Documentation

void nc_session_set_term_reason ( struct nc_session *  session,
NC_SESSION_TERM_REASON  reason 
)

Set the termination reason for a session. Use only in nc_rpc_clb callbacks.

Parameters
[in]sessionSession to modify.
[in]reasonReason of termination.
void nc_session_set_killed_by ( struct nc_session *  session,
uint32_t  sid 
)

Set the session-id of the session responsible for this session's termination.

Parameters
[in]sessionSession to modify. Must have term_reason set to NC_SESSION_TERM_KILLED.
[in]sidSID of the killing session.
void nc_session_set_status ( struct nc_session *  session,
NC_STATUS  status 
)

Set the status of a session.

Parameters
[in]sessionSession to modify.
[in]statusStatus of the session.
void nc_set_global_rpc_clb ( nc_rpc_clb  clb)

Set a global nc_rpc_clb that is called if the particular RPC request is received and the private field in the corresponding RPC schema node is NULL.

Parameters
[in]clbAn user-defined nc_rpc_clb function callback, NULL to default.
NC_MSG_TYPE nc_accept_inout ( int  fdin,
int  fdout,
const char *  username,
struct nc_session **  session 
)

Accept a new session on a pre-established transport session.

Parameters
[in]fdinFile descriptor to read (unencrypted) XML data from.
[in]fdoutFile descriptor to write (unencrypted) XML data to.
[in]usernameNETCONF username as provided by the transport protocol.
[out]sessionNew session on success.
Returns
NC_MSG_HELLO on success, NC_MSG_BAD_HELLO on client <hello> message parsing fail, NC_MSG_WOULDBLOCK on timeout, NC_MSG_ERROR on other errors.
struct nc_pollsession* nc_ps_new ( void  )

Create an empty structure for polling sessions.

Returns
Empty pollsession structure, NULL on error.
void nc_ps_free ( struct nc_pollsession *  ps)

Free a pollsession structure.

!IMPORTANT! Make sure that ps is not accessible (is not used) by any thread before and after this call!

Parameters
[in]psPollsession structure to free.
int nc_ps_add_session ( struct nc_pollsession *  ps,
struct nc_session *  session 
)

Add a session to a pollsession structure.

Parameters
[in]psPollsession structure to modify.
[in]sessionSession to add to ps.
Returns
0 on success, -1 on error.
int nc_ps_del_session ( struct nc_pollsession *  ps,
struct nc_session *  session 
)

Remove a session from a pollsession structure.

Parameters
[in]psPollsession structure to modify.
[in]sessionSession to remove from ps.
Returns
0 on success, -1 on not found.
struct nc_session* nc_ps_get_session ( const struct nc_pollsession *  ps,
uint16_t  idx 
)

Get a session from a pollsession structure matching the session ID.

Parameters
[in]psPollsession structure to read from.
[in]idxIndex of the session.
Returns
Session on index, NULL if out-of-bounds.
uint16_t nc_ps_session_count ( struct nc_pollsession *  ps)

Learn the number of sessions in a pollsession structure.

Does not lock ps structure for efficiency.

Parameters
[in]psPollsession structure to check.
Returns
Number of sessions (even invalid ones) in ps, -1 on error.
int nc_ps_poll ( struct nc_pollsession *  ps,
int  timeout,
struct nc_session **  session 
)

Poll sessions and process any received RPCs.

Only one event on one session is handled in one function call. If this event is a session termination (NC_PSPOLL_SESSION_TERM returned), the session should be removed from ps.

Parameters
[in]psPollsession structure to use.
[in]timeoutPoll timeout in milliseconds. 0 for non-blocking call, -1 for infinite waiting.
[in]sessionSession that was processed and that specific return bits concern. Can be NULL.
Returns
Bitfield of NC_PSPOLL_* macros.
void nc_ps_clear ( struct nc_pollsession *  ps,
int  all,
void(*)(void *)  data_free 
)

Remove sessions from a pollsession structure and call nc_session_free() on them.

Calling this function with all false makes sense if nc_ps_poll() returned NC_PSPOLL_SESSION_TERM.

Parameters
[in]psPollsession structure to clear.
[in]allWhether to free all sessions, or only the invalid ones.
[in]data_freeSession user data destructor.
time_t nc_session_get_start_time ( const struct nc_session *  session)

Get session start time.

Parameters
[in]sessionSession to get the information from.
Returns
Session start time.
void nc_session_set_notif_status ( struct nc_session *  session,
int  notif_status 
)

Set session notification subscription flag.

It is used only to ignore timeouts, because they are ignored for sessions with active subscriptions.

Parameters
[in]sessionSession to modify.
[in]notif_status0 for no active subscriptions, non-zero for an active subscription.
int nc_session_get_notif_status ( const struct nc_session *  session)

Get session notification subscription flag.

Parameters
[in]sessionSession to get the information from.
Returns
0 for no active subscription, non-zero for an active subscription.
int nc_session_is_callhome ( const struct nc_session *  session)

Learn whether a session was created using Call Home or not. Works only for server sessions.

Parameters
[in]sessionSession to get the information from.
Returns
0 if a standard session, non-zero if a Call Home session.