clients/upsclient.{c,h}, docs/man/upscli_init.txt: introduce upscli_init_authconf() [#3329]

Signed-off-by: Jim Klimov <jimklimov+nut@gmail.com>

Author: jimklimov

clients/upsclient.c

@@ -757,6 +757,21 @@ int upscli_init(int certverify, const char *certpath,
 	return upscli_init2(certverify, certpath, certname, certpasswd, NULL);
 }
 
+/* NOTE: Maybe eventually these two methods below will invert:
+ *  who is implementation of whom.
+ * TODO: Consider a method that parses our collection from
+ *  upscli_get_authconf_list() to upscli_add_host_cert() and
+ *  set up the one most applicable set of client identity data
+ *  for that [user@host:port] combo.
+ */
+int upscli_init_authconf(upscli_autoconf_t *ac)
+{
+	if (!ac)
+		return -1;
+
+	return upscli_init2(ac->certverify, ac->certpath, ac->certident, ac->certpasswd, ac->certfile);
+}
+
 int upscli_init2(int certverify, const char *certpath,
 					const char *certname, const char *certpasswd,
 					const char *certfile)

clients/upsclient.h

@@ -152,6 +152,7 @@ struct timeval *upscli_upslog_start_sync(struct timeval *tv, const void *cookie)
  * client certificate file. Equivalent to prefer upscli_init2(..., NULL) */
 int upscli_init(int certverify, const char *certpath, const char *certname, const char *certpasswd);
 int upscli_init2(int certverify, const char *certpath, const char *certname, const char *certpasswd, const char *certfile);
+int upscli_init_authconf(upscli_autoconf_t *ac);
 int upscli_cleanup(void);
 
 int upscli_tryconnect(UPSCONN_t *ups, const char *host, uint16_t port, int flags, struct timeval *tv);

docs/man/Makefile.am

@@ -811,7 +811,7 @@ INST_MAN_DEV_API_PAGES = \
 	nutscan_init.$(MAN_SECTION_API)
 
 # Alias page for one text describing two commands:
-UPSCLI_INIT_DEPS = upscli_init2.$(MAN_SECTION_API)
+UPSCLI_INIT_DEPS = upscli_init2.$(MAN_SECTION_API) upscli_init_authconf.$(MAN_SECTION_API)
 $(UPSCLI_INIT_DEPS): upscli_init.$(MAN_SECTION_API)
 	touch $@
 

docs/man/upscli_init.txt

@@ -26,6 +26,8 @@ SYNOPSIS
 		const char *certname,
 		const char *certpasswd,
 		const char *certfile);
+
+	int upscli_init_authconf(upscli_autoconf_t *ac);
 ------
 
 DESCRIPTION
@@ -86,6 +88,10 @@ In both cases, the 'certname' (if not empty) can be used to verify that the
 specified file provides a certificate with expected subject name, or possibly
 matches the expected host name or IP address.
 
+The *upscli_init_authconf()* function uses the `upscli_autoconf_t` structure
+populated by linkman:upscli_read_authconf[3] to pass equivalent information
+from linkman:nutauth.conf[5] file(s).
+
 Other nuances
 -------------