Loading...
Searching...
No Matches
Server Session
Server

Server-side NETCONF session manipulation. More...

Collaboration diagram for Server Session:

## Macros

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

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

## Functions

NC_MSG_TYPE | nc_accept (int timeout, struct nc_session **session)
| Accept new sessions on all the listening endpoints.
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.
NC_MSG_TYPE | nc_ps_accept_ssh_channel (struct nc_pollsession *ps, struct nc_session **session)
| Accept a new NETCONF session on an SSH session of a running NETCONF session that was polled in `ps`. Call this function only when nc_ps_poll() on `ps` returns NC_PSPOLL_SSH_CHANNEL. The new session is only returned in `session`, it is not added to `ps`.
int | nc_ps_add_session (struct nc_pollsession *ps, struct nc_session *session)
| Add a session to a pollsession structure.
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.
int | nc_ps_del_session (struct nc_pollsession *ps, struct nc_session *session)
| Remove a session from a pollsession structure.
void | nc_ps_free (struct nc_pollsession *ps)
| Free a pollsession structure.
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.
struct nc_pollsession * | nc_ps_new (void)
| Create an empty structure for polling sessions.
int | nc_ps_poll (struct nc_pollsession *ps, int timeout, struct nc_session **session)
| Poll sessions and process any received RPCs.
uint16_t | nc_ps_session_count (struct nc_pollsession *ps)
| Learn the number of sessions in a pollsession structure.
NC_MSG_TYPE | nc_session_accept_ssh_channel (struct nc_session *orig_session, struct nc_session **session)
| Accept a new NETCONF session on an SSH session of a running NETCONF `orig_session`. Call this function only when nc_ps_poll() returns NC_PSPOLL_SSH_CHANNEL on `orig_session`.
void | nc_session_dec_notif_status (struct nc_session *session)
| Decrease session notification subscription flag count. Supports multiple subscriptions on one session.
int | nc_session_get_notif_status (const struct nc_session *session)
| Get session notification subscription flag.
time_t | nc_session_get_start_time (const struct nc_session *session)
| Get session start time.
void | nc_session_inc_notif_status (struct nc_session *session)
| Increase session notification subscription flag count. Supports multiple subscriptions on one session.
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.
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.
void | nc_session_set_status (struct nc_session *session, NC_STATUS status)
| Set the status of a session.
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.
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.

## Detailed Description

Server-side NETCONF session manipulation.

## Macro Definition Documentation

## NC_PSPOLL_BAD_RPC

#define NC_PSPOLL_BAD_RPC 0x0008

RPC was received, but failed to be parsed.

Definition at line 314 of file session_server.h.

## NC_PSPOLL_ERROR

#define NC_PSPOLL_ERROR 0x0080

Other fatal errors (they are printed).

Definition at line 318 of file session_server.h.

## NC_PSPOLL_NOSESSIONS

#define NC_PSPOLL_NOSESSIONS 0x0001

No sessions to poll.

Definition at line 311 of file session_server.h.

## NC_PSPOLL_REPLY_ERROR

#define NC_PSPOLL_REPLY_ERROR 0x0010

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

Definition at line 315 of file session_server.h.

## NC_PSPOLL_RPC

#define NC_PSPOLL_RPC 0x0004

RPC was correctly parsed and processed.

Definition at line 313 of file session_server.h.

## NC_PSPOLL_SESSION_ERROR

#define NC_PSPOLL_SESSION_ERROR 0x0040

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

Definition at line 317 of file session_server.h.

## NC_PSPOLL_SESSION_TERM

#define NC_PSPOLL_SESSION_TERM 0x0020

Some session was terminated.

Definition at line 316 of file session_server.h.

## NC_PSPOLL_SSH_CHANNEL

#define NC_PSPOLL_SSH_CHANNEL 0x0200

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

Definition at line 322 of file session_server.h.

## NC_PSPOLL_SSH_MSG

#define NC_PSPOLL_SSH_MSG 0x00100

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

Definition at line 321 of file session_server.h.

## NC_PSPOLL_TIMEOUT

#define NC_PSPOLL_TIMEOUT 0x0002

Timeout elapsed.

Definition at line 312 of file session_server.h.

## Typedef Documentation

## nc_rpc_clb

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] | rpc | Parsed client RPC request.
  [in] | session | Session the RPC arrived on.

Returns
  Server reply. If NULL, an operation-failed error will be sent to the client.

Definition at line 1 of file session_server.h.

## Function Documentation

## nc_accept()

NC_MSG_TYPE nc_accept | ( | int | timeout,
|  | struct nc_session ** | session
| ) |  |

Accept new sessions on all the listening endpoints.

Once a new (TCP/IP) conection is established a different (quite long) timeout is used for waiting for transport-related data, which means this call can block for much longer that `timeout`, but only with slow/faulty/malicious clients.

Parameters

  [in] | timeout | Timeout for receiving a new connection in milliseconds, 0 for non-blocking call, -1 for infinite waiting.
  [out] | session | New session.

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.

## nc_accept_inout()

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] | fdin | File descriptor to read (unencrypted) XML data from.
  [in] | fdout | File descriptor to write (unencrypted) XML data to.
  [in] | username | NETCONF username as provided by the transport protocol.
  [out] | session | New 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.

## nc_ps_accept_ssh_channel()

NC_MSG_TYPE nc_ps_accept_ssh_channel | ( | struct nc_pollsession * | ps,
|  | struct nc_session ** | session
| ) |  |

Accept a new NETCONF session on an SSH session of a running NETCONF session that was polled in `ps`. Call this function only when nc_ps_poll() on `ps` returns NC_PSPOLL_SSH_CHANNEL. The new session is only returned in `session`, it is not added to `ps`.

Parameters

  [in] | ps | Unmodified pollsession structure from the previous nc_ps_poll() call.
  [out] | session | New session.

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.

## nc_ps_add_session()

int nc_ps_add_session | ( | struct nc_pollsession * | ps,
|  | struct nc_session * | session
| ) |  |

Add a session to a pollsession structure.

Parameters

  [in] | ps | Pollsession structure to modify.
  [in] | session | Session to add to `ps`.

Returns
  0 on success, -1 on error.

## nc_ps_clear()

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] | ps | Pollsession structure to clear.
  [in] | all | Whether to free all sessions, or only the invalid ones.
  [in] | data_free | Session user data destructor.

## nc_ps_del_session()

int nc_ps_del_session | ( | struct nc_pollsession * | ps,
|  | struct nc_session * | session
| ) |  |

Remove a session from a pollsession structure.

Parameters

  [in] | ps | Pollsession structure to modify.
  [in] | session | Session to remove from `ps`.

Returns
  0 on success, -1 on not found.

## nc_ps_free()

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] | ps | Pollsession structure to free.

## nc_ps_get_session()

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] | ps | Pollsession structure to read from.
  [in] | idx | Index of the session.

Returns
  Session on index, NULL if out-of-bounds.

## nc_ps_new()

struct nc_pollsession * nc_ps_new | ( | void |  | ) |

Create an empty structure for polling sessions.

Returns
  Empty pollsession structure, NULL on error.

## nc_ps_poll()

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] | ps | Pollsession structure to use.
  [in] | timeout | Poll timeout in milliseconds. 0 for non-blocking call, -1 for infinite waiting.
  [in] | session | Session that was processed and that specific return bits concern. Can be NULL.

Returns
  Bitfield of NC_PSPOLL_* macros.

## nc_ps_session_count()

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] | ps | Pollsession structure to check.

Returns
  Number of sessions (even invalid ones) in `ps`, -1 on error.

## nc_session_accept_ssh_channel()

NC_MSG_TYPE nc_session_accept_ssh_channel | ( | struct nc_session * | orig_session,
|  | struct nc_session ** | session
| ) |  |

Accept a new NETCONF session on an SSH session of a running NETCONF `orig_session`. Call this function only when nc_ps_poll() returns NC_PSPOLL_SSH_CHANNEL on `orig_session`.

Parameters

  [in] | orig_session | Session that has a new SSH channel ready.
  [out] | session | New session.

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.

## nc_session_dec_notif_status()

void nc_session_dec_notif_status | ( | struct nc_session * | session | ) |

Decrease session notification subscription flag count. Supports multiple subscriptions on one session.

Parameters

  [in] | session | Session to modify.

## nc_session_get_notif_status()

int nc_session_get_notif_status | ( | const struct nc_session * | session | ) |

Get session notification subscription flag.

Parameters

  [in] | session | Session to get the information from.

Returns
  0 for no active subscription, non-zero for an active subscription.

## nc_session_get_start_time()

time_t nc_session_get_start_time | ( | const struct nc_session * | session | ) |

Get session start time.

Parameters

  [in] | session | Session to get the information from.

Returns
  Session start time.

## nc_session_inc_notif_status()

void nc_session_inc_notif_status | ( | struct nc_session * | session | ) |

Increase session notification subscription flag count. Supports multiple subscriptions on one session.

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

Parameters

  [in] | session | Session to modify.

## nc_session_is_callhome()

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] | session | Session to get the information from.

Returns
  0 if a standard session, non-zero if a Call Home session.

## nc_session_set_killed_by()

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] | session | Session to modify. Must have term_reason set to NC_SESSION_TERM_KILLED.
  [in] | sid | SID of the killing session.

## nc_session_set_status()

void nc_session_set_status | ( | struct nc_session * | session,
|  | NC_STATUS | status
| ) |  |

Set the status of a session.

Parameters

  [in] | session | Session to modify.
  [in] | status | Status of the session.

## nc_session_set_term_reason()

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] | session | Session to modify.
  [in] | reason | Reason of termination.

## nc_set_global_rpc_clb()

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] | clb | An user-defined nc_rpc_clb function callback, NULL to default.