doc UPDATE client context use clarification

Author: michalvasko

src/session_client.h

@@ -135,9 +135,9 @@ void nc_client_destroy(void);
  *
  * @param[in] fdin Input file descriptor for reading (clear) data from NETCONF server.
  * @param[in] fdout Output file descriptor for writing (clear) data for NETCONF server.
- * @param[in] ctx Optional custom context to use for the session. Disregarding whether set or not, any YANG modules
- * not present and supported by the server are attempted to be loaded using \<get-schema\> (if supported) and/or by
- * searching the searchpath (see ::nc_client_set_schema_searchpath()).
+ * @param[in,out] ctx Optional custom context to use for the session. If not set, a default context is created.
+ * Any YANG modules not present in the context and supported by the server are loaded using \<get-schema\>
+ * (if supported) and/or by searching the searchpath (see ::nc_client_set_schema_searchpath()).
  * @return Created NETCONF session object or NULL in case of error.
  */
 struct nc_session *nc_connect_inout(int fdin, int fdout, struct ly_ctx *ctx);
@@ -150,9 +150,9 @@ struct nc_session *nc_connect_inout(int fdin, int fdout, struct ly_ctx *ctx);
  * by sending and processing NETCONF \<hello\> messages.
  *
  * @param[in] address Path to the unix socket.
- * @param[in] ctx Optional custom context to use for the session. Disregarding whether set or not, any YANG modules
- * not present and supported by the server are attempted to be loaded using \<get-schema\> (if supported) and/or by
- * searching the searchpath (see ::nc_client_set_schema_searchpath()).
+ * @param[in,out] ctx Optional custom context to use for the session. If not set, a default context is created.
+ * Any YANG modules not present in the context and supported by the server are loaded using \<get-schema\>
+ * (if supported) and/or by searching the searchpath (see ::nc_client_set_schema_searchpath()).
  * @return Created NETCONF session object or NULL in case of error.
  */
 struct nc_session *nc_connect_unix(const char *address, struct ly_ctx *ctx);
@@ -349,9 +349,9 @@ const char *nc_client_ssh_get_username(void);
  * @param[in] host Hostname or address (both Ipv4 and IPv6 are accepted) of the target server.
  * 'localhost' is used by default if NULL is specified.
  * @param[in] port Port number of the target server. Default value 830 is used if 0 is specified.
- * @param[in] ctx Optional custom context to use for the session. Disregarding whether set or not, any YANG modules
- * not present and supported by the server are attempted to be loaded using \<get-schema\> (if supported) and/or by
- * searching the searchpath (see ::nc_client_set_schema_searchpath()).
+ * @param[in,out] ctx Optional custom context to use for the session. If not set, a default context is created.
+ * Any YANG modules not present in the context and supported by the server are loaded using \<get-schema\>
+ * (if supported) and/or by searching the searchpath (see ::nc_client_set_schema_searchpath()).
  * @return Created NETCONF session object or NULL on error.
  */
 struct nc_session *nc_connect_ssh(const char *host, uint16_t port, struct ly_ctx *ctx);
@@ -366,9 +366,9 @@ struct nc_session *nc_connect_ssh(const char *host, uint16_t port, struct ly_ctx
  *
  * @param[in] ssh_session libssh structure representing SSH session object. It is fully managed by the created session
  * including freeing it.
- * @param[in] ctx Optional custom context to use for the session. Disregarding whether set or not, any YANG modules
- * not present and supported by the server are attempted to be loaded using \<get-schema\> (if supported) and/or by
- * searching the searchpath (see ::nc_client_set_schema_searchpath()).
+ * @param[in,out] ctx Optional custom context to use for the session. If not set, a default context is created.
+ * Any YANG modules not present in the context and supported by the server are loaded using \<get-schema\>
+ * (if supported) and/or by searching the searchpath (see ::nc_client_set_schema_searchpath()).
  * @return Created NETCONF session object or NULL on error.
  */
 struct nc_session *nc_connect_libssh(ssh_session ssh_session, struct ly_ctx *ctx);
@@ -378,9 +378,9 @@ struct nc_session *nc_connect_libssh(ssh_session ssh_session, struct ly_ctx *ctx
  *
  * @param[in] session Existing NETCONF session. The session has to be created on SSH transport layer using libssh -
  * it has to be created by nc_connect_ssh(), nc_connect_libssh() or nc_connect_ssh_channel().
- * @param[in] ctx Optional custom context to use for the session. Disregarding whether set or not, any YANG modules
- * not present and supported by the server are attempted to be loaded using \<get-schema\> (if supported) and/or by
- * searching the searchpath (see ::nc_client_set_schema_searchpath()).
+ * @param[in,out] ctx Optional custom context to use for the session. If not set, a default context is created.
+ * Any YANG modules not present in the context and supported by the server are loaded using \<get-schema\>
+ * (if supported) and/or by searching the searchpath (see ::nc_client_set_schema_searchpath()).
  * @return Created NETCONF session object or NULL on error.
  */
 struct nc_session *nc_connect_ssh_channel(struct nc_session *session, struct ly_ctx *ctx);
@@ -464,9 +464,9 @@ void nc_client_tls_get_crl_paths(const char **crl_file, const char **crl_dir);
  * @param[in] host Hostname or address (both Ipv4 and IPv6 are accepted) of the target server.
  * 'localhost' is used by default if NULL is specified. It is verified by TLS when connecting to it.
  * @param[in] port Port number of the target server. Default value 6513 is used if 0 is specified.
- * @param[in] ctx Optional custom context to use for the session. Disregarding whether set or not, any YANG modules
- * not present and supported by the server are attempted to be loaded using \<get-schema\> (if supported) and/or by
- * searching the searchpath (see ::nc_client_set_schema_searchpath()).
+ * @param[in,out] ctx Optional custom context to use for the session. If not set, a default context is created.
+ * Any YANG modules not present in the context and supported by the server are loaded using \<get-schema\>
+ * (if supported) and/or by searching the searchpath (see ::nc_client_set_schema_searchpath()).
  * @return Created NETCONF session object or NULL on error.
  */
 struct nc_session *nc_connect_tls(const char *host, uint16_t port, struct ly_ctx *ctx);
@@ -477,9 +477,9 @@ struct nc_session *nc_connect_tls(const char *host, uint16_t port, struct ly_ctx
  * The TLS session supplied is expected to be fully connected and authenticated!
  *
  * @param[in] tls libssl structure representing the TLS session object.
- * @param[in] ctx Optional custom context to use for the session. Disregarding whether set or not, any YANG modules
- * not present and supported by the server are attempted to be loaded using \<get-schema\> (if supported) and/or by
- * searching the searchpath (see ::nc_client_set_schema_searchpath()).
+ * @param[in,out] ctx Optional custom context to use for the session. If not set, a default context is created.
+ * Any YANG modules not present in the context and supported by the server are loaded using \<get-schema\>
+ * (if supported) and/or by searching the searchpath (see ::nc_client_set_schema_searchpath()).
  * @return Created NETCONF session object or NULL on error.
  */
 struct nc_session *nc_connect_libssl(SSL *tls, struct ly_ctx *ctx);

src/session_client_ch.h

@@ -4,7 +4,7 @@
  * @brief libnetconf2 Call Home session client manipulation
  *
  * @copyright
- * Copyright (c) 2015 - 2021 CESNET, z.s.p.o.
+ * Copyright (c) 2015 - 2023 CESNET, z.s.p.o.
  *
  * This source code is licensed under BSD 3-Clause License (the "License").
  * You may not use this file except in compliance with the License.
@@ -44,8 +44,10 @@ extern "C" {
  * @brief Accept a Call Home connection on any of the listening binds.
  *
  * @param[in] timeout Timeout for receiving a new connection in milliseconds, 0 for
- *            non-blocking call, -1 for infinite waiting.
- * @param[in] ctx Session context to use. Can be NULL.
+ * non-blocking call, -1 for infinite waiting.
+ * @param[in,out] ctx Optional custom context to use for the session. If not set, a default context is created.
+ * Any YANG modules not present in the context and supported by the server are loaded using \<get-schema\>
+ * (if supported) and/or by searching the searchpath (see ::nc_client_set_schema_searchpath()).
  * @param[out] session New session.
  * @return 1 on success, 0 on timeout, -1 on error.
  */
@@ -73,7 +75,7 @@ int nc_accept_callhome(int timeout, struct ly_ctx *ctx, struct nc_session **sess
  * nc_client_ssh_ch_get_auth_hostkey_check_clb()).
  *
  * @param[in] auth_hostkey_check Function to call, returns 0 on success, non-zero in error.
- *                               If NULL, the default callback is set.
+ * If NULL, the default callback is set.
  * @param[in] priv Optional private data to be passed to the callback function.
  */
 void nc_client_ssh_ch_set_auth_hostkey_check_clb(int (*auth_hostkey_check)(const char *hostname, ssh_session session, void *priv),
@@ -97,7 +99,7 @@ void nc_client_ssh_ch_get_auth_hostkey_check_clb(int (**auth_hostkey_check)(cons
  * nc_client_ssh_ch_get_auth_password_clb()).
  *
  * @param[in] auth_password Function to call, returns the password for username\@hostname.
- *                          If NULL, the default callback is set.
+ * If NULL, the default callback is set.
  * @param[in] priv Optional private data to be passed to the callback function.
  */
 void nc_client_ssh_ch_set_auth_password_clb(char *(*auth_password)(const char *username, const char *hostname, void *priv),
@@ -121,8 +123,7 @@ void nc_client_ssh_ch_get_auth_password_clb(char *(**auth_password)(const char *
  * nc_client_ssh_ch_get_auth_interactive_clb()).
  *
  * @param[in] auth_interactive Function to call for every question, returns the answer for
- *                             authentication name with instruction and echoing prompt.
- *                             If NULL, the default callback is set.
+ * authentication name with instruction and echoing prompt. If NULL, the default callback is set.
  * @param[in] priv Optional private data to be passed to the callback function.
  */
 void nc_client_ssh_ch_set_auth_interactive_clb(char *(*auth_interactive)(const char *auth_name, const char *instruction,
@@ -147,8 +148,8 @@ void nc_client_ssh_ch_get_auth_interactive_clb(char *(**auth_interactive)(const
  * freeing the private data when necessary (the private data can be obtained by
  * nc_client_ssh_ch_get_auth_privkey_passphrase_clb()).
  *
- * @param[in] auth_privkey_passphrase Function to call for every question, returns
- *                                    the passphrase for the specific private key.
+ * @param[in] auth_privkey_passphrase Function to call for every question, returns the passphrase for the specific
+ * private key.
  * @param[in] priv Optional private data to be passed to the callback function.
  */
 void nc_client_ssh_ch_set_auth_privkey_passphrase_clb(char *(*auth_privkey_passphrase)(const char *privkey_path, void *priv),
@@ -301,7 +302,7 @@ int nc_client_tls_ch_del_bind(const char *address, uint16_t port);
  *
  * @param[in] client_cert Path to the file containing the client certificate.
  * @param[in] client_key Path to the file containing the private key for the @p client_cert.
- *                       If NULL, key is expected to be stored with @p client_cert.
+ * If NULL, key is expected to be stored with @p client_cert.
  * @return 0 on success, -1 on error.
  */
 int nc_client_tls_ch_set_cert_key_paths(const char *client_cert, const char *client_key);
@@ -310,29 +311,26 @@ int nc_client_tls_ch_set_cert_key_paths(const char *client_cert, const char *cli
  * @brief Get client Call Home authentication identity - a certificate and a private key.
  *
  * @param[out] client_cert Path to the file containing the client certificate. Can be NULL.
- * @param[out] client_key Path to the file containing the private key for the @p client_cert.
- *                        Can be NULL.
+ * @param[out] client_key Path to the file containing the private key for the @p client_cert. Can be NULL.
  */
 void nc_client_tls_ch_get_cert_key_paths(const char **client_cert, const char **client_key);
 
 /**
  * @brief Set client Call Home trusted CA certificates.
  *
  * @param[in] ca_file Location of the CA certificate file used to verify server certificates.
- *                    For more info, see the documentation for SSL_CTX_load_verify_locations() from OpenSSL.
+ * For more info, see the documentation for SSL_CTX_load_verify_locations() from OpenSSL.
  * @param[in] ca_dir Location of the CA certificates directory used to verify the server certificates.
- *                   For more info, see the documentation for SSL_CTX_load_verify_locations() from OpenSSL.
+ * For more info, see the documentation for SSL_CTX_load_verify_locations() from OpenSSL.
  * @return 0 on success, -1 on error.
  */
 int nc_client_tls_ch_set_trusted_ca_paths(const char *ca_file, const char *ca_dir);
 
 /**
  * @brief Get client Call Home trusted CA certificates.
  *
- * @param[out] ca_file Location of the CA certificate file used to verify server certificates.
- *                     Can be NULL.
- * @param[out] ca_dir Location of the CA certificates directory used to verify the server certificates.
- *                    Can be NULL.
+ * @param[out] ca_file Location of the CA certificate file used to verify server certificates. Can be NULL.
+ * @param[out] ca_dir Location of the CA certificates directory used to verify the server certificates. Can be NULL.
  */
 void nc_client_tls_ch_get_trusted_ca_paths(const char **ca_file, const char **ca_dir);
 
@@ -348,10 +346,8 @@ int nc_client_tls_ch_set_crl_paths(const char *crl_file, const char *crl_dir);
 /**
  * @brief Get client Call Home Certificate Revocation Lists.
  *
- * @param[out] crl_file Location of the CRL certificate file used to check for revocated certificates.
- *                      Can be NULL.
- * @param[out] crl_dir Location of the CRL certificate directory used to check for revocated certificates.
- *                     Can be NULL.
+ * @param[out] crl_file Location of the CRL certificate file used to check for revocated certificates. Can be NULL.
+ * @param[out] crl_dir Location of the CRL certificate directory used to check for revocated certificates. Can be NULL.
  */
 void nc_client_tls_ch_get_crl_paths(const char **crl_file, const char **crl_dir);