LIBNUTCLIENT_TCP(3)
===================

NAME
----

libnutclient_tcp, nutclient_tcp_create_client, nutclient_tcp_is_connected,
nutclient_tcp_disconnect, nutclient_tcp_reconnect,
nutclient_tcp_set_timeout, nutclient_tcp_get_timeout,
nutclient_tcp_get_ssl_caps, nutclient_tcp_is_ssl,
nutclient_tcp_create_client_ssl_OpenSSL,
nutclient_tcp_set_ssl_config_OpenSSL,
nutclient_tcp_create_client_ssl_NSS,
nutclient_tcp_set_ssl_config_NSS,
nutclient_tcp_set_ssl_try,
nutclient_tcp_get_ssl_try,
nutclient_tcp_set_ssl_force,
nutclient_tcp_get_ssl_force,
nutclient_tcp_set_ssl_certverify,
nutclient_tcp_get_ssl_certverify,
nutclient_tcp_set_ssl_capath,
nutclient_tcp_get_ssl_capath,
nutclient_tcp_set_ssl_cafile,
nutclient_tcp_get_ssl_cafile,
nutclient_tcp_set_ssl_certfile,
nutclient_tcp_get_ssl_certfile,
nutclient_tcp_set_ssl_keyfile,
nutclient_tcp_get_ssl_keyfile,
nutclient_tcp_set_ssl_keypass,
nutclient_tcp_get_ssl_keypass,
nutclient_tcp_set_ssl_certstore_path,
nutclient_tcp_get_ssl_certstore_path,
nutclient_tcp_set_ssl_certstore_prefix,
nutclient_tcp_get_ssl_certstore_prefix,
nutclient_tcp_set_ssl_certident_name,
nutclient_tcp_get_ssl_certident_name,
nutclient_tcp_set_ssl_certhost_addr,
nutclient_tcp_get_ssl_certhost_addr,
nutclient_tcp_set_ssl_certhost_name,
nutclient_tcp_get_ssl_certhost_name -
TCP protocol related function for Network UPS Tools high-level client
access library

SYNOPSIS
--------

------
	#include <nutclient.h>
	#include <cstdint> /* uint16_t */
	#include <ctime> /* time_t */

	typedef NUTCLIENT_t NUTCLIENT_TCP_t;

	NUTCLIENT_TCP_t nutclient_tcp_create_client(
		const char* host, uint16_t port);

	int nutclient_tcp_is_connected(NUTCLIENT_TCP_t client);

	void nutclient_tcp_disconnect(NUTCLIENT_TCP_t client);

	int nutclient_tcp_reconnect(NUTCLIENT_TCP_t client);

	void nutclient_tcp_set_timeout(NUTCLIENT_TCP_t client, time_t timeout);

	time_t nutclient_tcp_get_timeout(NUTCLIENT_TCP_t client);

	/* SSL (NUT STARTTLS) support, behavior may be build-dependent
	 * (none/OpenSSL/NSS): */

	/* Capabilities of this build, bitmask: */
	#define UPSCLI_SSL_CAPS_NONE	0	/* No ability to use SSL */
	#define UPSCLI_SSL_CAPS_OPENSSL	(1 << 0)	/* Can use OpenSSL-specific setup */
	#define UPSCLI_SSL_CAPS_NSS	(1 << 1)	/* Can use Mozilla NSS-specific setup */
	#define UPSCLI_SSL_CAPS_CERTIDENT_PASS	(1 << 2)	/* Can use CERTIDENT (verify private key password) */
	#define UPSCLI_SSL_CAPS_CERTIDENT_NAME	(1 << 3)	/* Can use CERTIDENT (verify cert name) */
	#define UPSCLI_SSL_CAPS_CERTIDENT	(UPSCLI_SSL_CAPS_CERTIDENT_PASS | UPSCLI_SSL_CAPS_CERTIDENT_NAME)
	int nutclient_tcp_get_ssl_caps(void);

	/* Is the specified client currently connected in SSL mode? */
	int nutclient_tcp_is_ssl(NUTCLIENT_TCP_t client);

	NUTCLIENT_TCP_t nutclient_tcp_create_client_ssl_OpenSSL(
		const char* host, uint16_t port, int try_ssl = 0,
		int forcessl = -1, int certverify = -1,
		const char *ca_path = NULL, const char *ca_file = NULL,
		const char *cert_file = NULL, const char *key_file = NULL,
		const char *key_pass = NULL, const char *certident_name = NULL,
		const char *certhost_addr = NULL,
		const char *certhost_name = NULL);

	void nutclient_tcp_set_ssl_config_OpenSSL(NUTCLIENT_TCP_t client,
		int forcessl = -1, int certverify = -1,
		const char *ca_path = NULL, const char *ca_file = NULL,
		const char *cert_file = NULL, const char *key_file = NULL,
		const char *key_pass = NULL, const char *certident_name = NULL,
		const char *certhost_addr = NULL,
		const char *certhost_name = NULL);

	NUTCLIENT_TCP_t nutclient_tcp_create_client_ssl_NSS(
		const char* host, uint16_t port, int try_ssl = 0,
		int forcessl = -1, int certverify = -1,
		const char *certstore_path = NULL, const char *certstore_pass = NULL,
		const char *certstore_prefix = NULL,
		const char *certident_name = NULL,
		const char *certhost_addr = NULL,
		const char *certhost_name = NULL);

	void nutclient_tcp_set_ssl_config_NSS(NUTCLIENT_TCP_t client,
		int forcessl = -1, int certverify = -1,
		const char *certstore_path = NULL, const char *certstore_pass = NULL,
		const char *certstore_prefix = NULL,
		const char *certident_name = NULL,
		const char *certhost_addr = NULL,
		const char *certhost_name = NULL);

	/* Individual SSL option getters/setters: */

	void nutclient_tcp_set_ssl_try(NUTCLIENT_TCP_t client, int try_ssl);
	int nutclient_tcp_get_ssl_try(NUTCLIENT_TCP_t client);

	void nutclient_tcp_set_ssl_force(NUTCLIENT_TCP_t client, int forcessl);
	int nutclient_tcp_get_ssl_force(NUTCLIENT_TCP_t client);

	void nutclient_tcp_set_ssl_certverify(NUTCLIENT_TCP_t client, int certverify);
	int nutclient_tcp_get_ssl_certverify(NUTCLIENT_TCP_t client);

	/* OpenSSL (PEM): Trusted CA directory: */
	void nutclient_tcp_set_ssl_capath(NUTCLIENT_TCP_t client, const char* ca_path);
	const char* nutclient_tcp_get_ssl_capath(NUTCLIENT_TCP_t client);

	/* Trusted CA file: */
	void nutclient_tcp_set_ssl_cafile(NUTCLIENT_TCP_t client, const char* ca_file);
	const char* nutclient_tcp_get_ssl_cafile(NUTCLIENT_TCP_t client);

	/* Client certificate (public): */
	void nutclient_tcp_set_ssl_certfile(NUTCLIENT_TCP_t client, const char* cert_file);
	const char* nutclient_tcp_get_ssl_certfile(NUTCLIENT_TCP_t client);

	/* Client key (private): */
	void nutclient_tcp_set_ssl_keyfile(NUTCLIENT_TCP_t client, const char* key_file);
	const char* nutclient_tcp_get_ssl_keyfile(NUTCLIENT_TCP_t client);

	/* OpenSSL and NSS: Client key (private): */
	void nutclient_tcp_set_ssl_keypass(NUTCLIENT_TCP_t client, const char* key_pass);
	const char* nutclient_tcp_get_ssl_keypass(NUTCLIENT_TCP_t client);

	void nutclient_tcp_set_ssl_certstore_path(NUTCLIENT_TCP_t client,
		const char* certstore_path);
	const char* nutclient_tcp_get_ssl_certstore_path(NUTCLIENT_TCP_t client);

	void nutclient_tcp_set_ssl_certstore_prefix(NUTCLIENT_TCP_t client,
		const char* certstore_prefix);
	const char* nutclient_tcp_get_ssl_certstore_prefix(NUTCLIENT_TCP_t client);

	void nutclient_tcp_set_ssl_certident_name(NUTCLIENT_TCP_t client,
		const char* certident_name);
	const char* nutclient_tcp_get_ssl_certident_name(NUTCLIENT_TCP_t client);

	void nutclient_tcp_set_ssl_certhost_addr(NUTCLIENT_TCP_t client,
		const char* certhost_addr);
	const char* nutclient_tcp_get_ssl_certhost_addr(NUTCLIENT_TCP_t client);

	void nutclient_tcp_set_ssl_certhost_name(NUTCLIENT_TCP_t client,
		const char* certhost_name);
	const char* nutclient_tcp_get_ssl_certhost_name(NUTCLIENT_TCP_t client);
------

DESCRIPTION
-----------

These functions allow to manage connections to linkman:upsd[8]
using NUT TCP protocol.

* The *nutclient_tcp_create_client()* function create the 'NUTCLIENT_TCP_t'
  context and intend to connect to upsd at 'host' and 'port'.
+
The context must be freed by 'nutclient_destroy()'.

  - 'host' can be a sever name or a valid IPv4 or IPv6 address like
    "localhost", "127.0.0.1" or "::1".

  - 'port' is a valid TCP port, generally '3493'.

* The *nutclient_tcp_is_connected()* function test if the connection is valid.

* The *nutclient_tcp_disconnect()* function force to disconnect the specified
  connection.

* The *nutclient_tcp_reconnect()* function force to reconnect a connection,
  disconnecting it if needed.

* The *nutclient_tcp_set_timeout()* function set the timeout duration
  for I/O operations.

* The *nutclient_tcp_get_timeout()* function retrieve the timeout duration
  for I/O operations.
+
'timeout' values are specified in seconds, use negative values for blocking.

For `forcessl` and `certverify` integer values, `1` means required, `0` means
not required, and `-1` (the default) means use the global configuration.
For `certhost_addr` and `certhost_name`, the default `NULL` means use the
global configuration or connection host address.

SEE ALSO
--------

linkman:libnutclient[3]
linkman:libnutclient_general[3]
