nut-debian/clients/nutclient.h

1073 lines
30 KiB
C
Raw Normal View History

2013-11-24 17:00:12 +02:00
/* nutclient.h - definitions for nutclient C/C++ library
Copyright (C) 2012 Emilien Kia <emilien.kia@gmail.com>
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*/
#ifndef NUTCLIENT_HPP_SEEN
#define NUTCLIENT_HPP_SEEN
/* Begin of C++ nutclient library declaration */
#ifdef __cplusplus
#include <string>
#include <vector>
#include <map>
#include <set>
#include <exception>
2022-07-10 10:23:45 +03:00
#include <cstdint>
#include <ctime>
/* See include/common.h for details behind this */
#ifndef NUT_UNUSED_VARIABLE
#define NUT_UNUSED_VARIABLE(x) (void)(x)
#endif
2013-11-24 17:00:12 +02:00
namespace nut
{
namespace internal
{
class Socket;
} /* namespace internal */
class Client;
class TcpClient;
class Device;
class Variable;
class Command;
/**
* Basic nut exception.
*/
class NutException : public std::exception
{
public:
NutException(const std::string& msg):_msg(msg){}
2022-07-10 10:23:45 +03:00
NutException(const NutException&) = default;
NutException& operator=(NutException& rhs) = default;
virtual ~NutException() override;
virtual const char * what() const noexcept override {return this->_msg.c_str();}
virtual std::string str() const noexcept {return this->_msg;}
2013-11-24 17:00:12 +02:00
private:
std::string _msg;
};
/**
* System error.
*/
class SystemException : public NutException
{
public:
SystemException();
2022-07-10 10:23:45 +03:00
SystemException(const SystemException&) = default;
SystemException& operator=(SystemException& rhs) = default;
virtual ~SystemException() override;
2013-11-24 17:00:12 +02:00
private:
static std::string err();
};
/**
* IO oriented nut exception.
*/
class IOException : public NutException
{
public:
IOException(const std::string& msg):NutException(msg){}
2022-07-10 10:23:45 +03:00
IOException(const IOException&) = default;
IOException& operator=(IOException& rhs) = default;
virtual ~IOException() override;
2013-11-24 17:00:12 +02:00
};
/**
* IO oriented nut exception specialized for unknown host
*/
class UnknownHostException : public IOException
{
public:
UnknownHostException():IOException("Unknown host"){}
2022-07-10 10:23:45 +03:00
UnknownHostException(const UnknownHostException&) = default;
UnknownHostException& operator=(UnknownHostException& rhs) = default;
virtual ~UnknownHostException() override;
2013-11-24 17:00:12 +02:00
};
/**
* IO oriented nut exception when client is not connected
*/
class NotConnectedException : public IOException
{
public:
NotConnectedException():IOException("Not connected"){}
2022-07-10 10:23:45 +03:00
NotConnectedException(const NotConnectedException&) = default;
NotConnectedException& operator=(NotConnectedException& rhs) = default;
virtual ~NotConnectedException() override;
2013-11-24 17:00:12 +02:00
};
/**
* IO oriented nut exception when there is no response.
*/
class TimeoutException : public IOException
{
public:
TimeoutException():IOException("Timeout"){}
2022-07-10 10:23:45 +03:00
TimeoutException(const TimeoutException&) = default;
TimeoutException& operator=(TimeoutException& rhs) = default;
virtual ~TimeoutException() override;
2013-11-24 17:00:12 +02:00
};
2022-07-10 10:23:45 +03:00
/**
* Cookie given when performing async action, used to redeem result at a later date.
*/
typedef std::string TrackingID;
/**
* Result of an async action.
*/
typedef enum
{
UNKNOWN,
PENDING,
SUCCESS,
INVALID_ARGUMENT,
FAILURE,
} TrackingResult;
typedef std::string Feature;
2013-11-24 17:00:12 +02:00
/**
* A nut client is the starting point to dialog to NUTD.
* It can connect to an NUTD then retrieve its device list.
* Use a specific client class to connect to a NUTD.
*/
class Client
{
friend class Device;
friend class Variable;
friend class Command;
public:
2022-07-10 10:23:45 +03:00
virtual ~Client();
2013-11-24 17:00:12 +02:00
/**
* Intend to authenticate to a NUTD server.
* Set the username and password associated to the connection.
* \param user User name.
* \param passwd Password.
* \todo Is his method is global to all connection protocol or is it specific to TCP ?
* \note Actually, authentication fails only if already set, not if bad values are sent.
*/
2022-07-10 10:23:45 +03:00
virtual void authenticate(const std::string& user, const std::string& passwd) = 0;
2013-11-24 17:00:12 +02:00
/**
* Disconnect from the NUTD server.
* \todo Is his method is global to all connection protocol or is it specific to TCP ?
*/
2022-07-10 10:23:45 +03:00
virtual void logout() = 0;
2013-11-24 17:00:12 +02:00
/**
* Device manipulations.
* \see nut::Device
* \{
*/
/**
* Retrieve a device from its name.
* If the device does not exist, a bad (not ok) device is returned.
* \param name Name of the device.
* \return The device.
*/
2022-07-10 10:23:45 +03:00
virtual Device getDevice(const std::string& name);
2013-11-24 17:00:12 +02:00
/**
* Retrieve the list of all devices supported by UPSD server.
* \return The set of supported devices.
*/
2022-07-10 10:23:45 +03:00
virtual std::set<Device> getDevices();
2013-11-24 17:00:12 +02:00
/**
* Test if a device is supported by the NUTD server.
* \param dev Device name.
* \return true if supported, false otherwise.
*/
2022-07-10 10:23:45 +03:00
virtual bool hasDevice(const std::string& dev);
2013-11-24 17:00:12 +02:00
/**
* Retrieve names of devices supported by NUTD server.
* \return The set of names of supported devices.
*/
2022-07-10 10:23:45 +03:00
virtual std::set<std::string> getDeviceNames() = 0;
2013-11-24 17:00:12 +02:00
/**
* Retrieve the description of a device.
* \param name Device name.
* \return Device description.
*/
2022-07-10 10:23:45 +03:00
virtual std::string getDeviceDescription(const std::string& name) = 0;
2013-11-24 17:00:12 +02:00
/** \} */
/**
* Variable manipulations.
* \see nut::Variable
* \{
*/
/**
* Retrieve names of all variables supported by a device.
* \param dev Device name
* \return Variable names
*/
2022-07-10 10:23:45 +03:00
virtual std::set<std::string> getDeviceVariableNames(const std::string& dev) = 0;
2013-11-24 17:00:12 +02:00
/**
* Retrieve names of read/write variables supported by a device.
* \param dev Device name
* \return RW variable names
*/
2022-07-10 10:23:45 +03:00
virtual std::set<std::string> getDeviceRWVariableNames(const std::string& dev) = 0;
2013-11-24 17:00:12 +02:00
/**
* Test if a variable is supported by a device.
* \param dev Device name
* \param name Variable name
* \return true if the variable is supported.
*/
2022-07-10 10:23:45 +03:00
virtual bool hasDeviceVariable(const std::string& dev, const std::string& name);
2013-11-24 17:00:12 +02:00
/**
* Retrieve the description of a variable.
* \param dev Device name
* \param name Variable name
* \return Variable description if provided.
*/
2022-07-10 10:23:45 +03:00
virtual std::string getDeviceVariableDescription(const std::string& dev, const std::string& name) = 0;
2013-11-24 17:00:12 +02:00
/**
* Retrieve values of a variable.
* \param dev Device name
* \param name Variable name
* \return Variable values (usually one) if available.
*/
2022-07-10 10:23:45 +03:00
virtual std::vector<std::string> getDeviceVariableValue(const std::string& dev, const std::string& name) = 0;
2013-11-24 17:00:12 +02:00
/**
* Retrieve values of all variables of a device.
* \param dev Device name
* \return Variable values indexed by variable names.
*/
2022-07-10 10:23:45 +03:00
virtual std::map<std::string,std::vector<std::string> > getDeviceVariableValues(const std::string& dev);
/**
* Retrieve values of all variables of a set of devices.
* \param devs Device names
* \return Variable values indexed by variable names, indexed by device names.
*/
virtual std::map<std::string,std::map<std::string,std::vector<std::string> > > getDevicesVariableValues(const std::set<std::string>& devs);
2013-11-24 17:00:12 +02:00
/**
* Intend to set the value of a variable.
* \param dev Device name
* \param name Variable name
* \param value Variable value
2022-07-10 10:23:45 +03:00
*/
virtual TrackingID setDeviceVariable(const std::string& dev, const std::string& name, const std::string& value) = 0;
2013-11-24 17:00:12 +02:00
/**
* Intend to set the value of a variable.
* \param dev Device name
* \param name Variable name
2022-07-10 10:23:45 +03:00
* \param values Vector of variable values
*/
virtual TrackingID setDeviceVariable(const std::string& dev, const std::string& name, const std::vector<std::string>& values) = 0;
2013-11-24 17:00:12 +02:00
/** \} */
/**
* Instant command manipulations.
* \see nut::Command
* \{
*/
/**
* Retrieve names of all commands supported by a device.
* \param dev Device name
* \return Command names
*/
2022-07-10 10:23:45 +03:00
virtual std::set<std::string> getDeviceCommandNames(const std::string& dev) = 0;
2013-11-24 17:00:12 +02:00
/**
* Test if a command is supported by a device.
* \param dev Device name
* \param name Command name
* \return true if the command is supported.
*/
2022-07-10 10:23:45 +03:00
virtual bool hasDeviceCommand(const std::string& dev, const std::string& name);
2013-11-24 17:00:12 +02:00
/**
* Retrieve the description of a command.
* \param dev Device name
* \param name Command name
* \return Command description if provided.
*/
2022-07-10 10:23:45 +03:00
virtual std::string getDeviceCommandDescription(const std::string& dev, const std::string& name) = 0;
2013-11-24 17:00:12 +02:00
/**
* Intend to execute a command.
* \param dev Device name
* \param name Command name
2022-07-10 10:23:45 +03:00
* \param param Additional command parameter
2013-11-24 17:00:12 +02:00
*/
2022-07-10 10:23:45 +03:00
virtual TrackingID executeDeviceCommand(const std::string& dev, const std::string& name, const std::string& param="") = 0;
2013-11-24 17:00:12 +02:00
/** \} */
/**
* Device specific commands.
* \{
*/
/**
* Log the current user (if authenticated) for a device.
* \param dev Device name.
*/
2022-07-10 10:23:45 +03:00
virtual void deviceLogin(const std::string& dev) = 0;
2013-11-24 17:00:12 +02:00
/**
2022-07-10 10:23:45 +03:00
* Retrieve the number of user logged-in for the specified device.
2013-11-24 17:00:12 +02:00
* \param dev Device name.
* \return Number of logged-in users.
*/
2022-07-10 10:23:45 +03:00
virtual int deviceGetNumLogins(const std::string& dev) = 0;
/* NOTE: "master" is deprecated since NUT v2.8.0 in favor of "primary".
* For the sake of old/new server/client interoperability,
* practical implementations should try to use one and fall
* back to the other, and only fail if both return "ERR".
*/
virtual void deviceMaster(const std::string& dev) = 0;
virtual void devicePrimary(const std::string& dev) = 0;
virtual void deviceForcedShutdown(const std::string& dev) = 0;
/**
* Retrieve the result of a tracking ID.
* \param id Tracking ID.
*/
virtual TrackingResult getTrackingResult(const TrackingID& id) = 0;
virtual bool hasFeature(const Feature& feature);
virtual bool isFeatureEnabled(const Feature& feature) = 0;
virtual void setFeature(const Feature& feature, bool status) = 0;
static const Feature TRACKING;
2013-11-24 17:00:12 +02:00
protected:
Client();
};
/**
* TCP NUTD client.
* It connect to NUTD with a TCP socket.
*/
class TcpClient : public Client
{
2022-07-10 10:23:45 +03:00
/* We have a number of direct-call methods we do not expose
* generally, but still want covered with integration tests
*/
friend class NutActiveClientTest;
2013-11-24 17:00:12 +02:00
public:
/**
* Construct a nut TcpClient object.
* You must call one of TcpClient::connect() after.
*/
TcpClient();
/**
* Construct a nut TcpClient object then connect it to the specified server.
* \param host Server host name.
* \param port Server port.
*/
2022-07-10 10:23:45 +03:00
TcpClient(const std::string& host, uint16_t port = 3493);
~TcpClient() override;
2013-11-24 17:00:12 +02:00
/**
* Connect it to the specified server.
* \param host Server host name.
* \param port Server port.
*/
2022-07-10 10:23:45 +03:00
void connect(const std::string& host, uint16_t port = 3493);
2013-11-24 17:00:12 +02:00
/**
* Connect to the server.
* Host name and ports must have already set (usefull for reconnection).
*/
2022-07-10 10:23:45 +03:00
void connect();
2013-11-24 17:00:12 +02:00
/**
* Test if the connection is active.
* \return tru if the connection is active.
*/
bool isConnected()const;
/**
* Force the deconnection.
*/
void disconnect();
/**
* Set the timeout in seconds.
* \param timeout Timeout n seconds, negative to block operations.
*/
2022-07-10 10:23:45 +03:00
void setTimeout(time_t timeout);
2013-11-24 17:00:12 +02:00
/**
* Retrieve the timeout.
* \returns Current timeout in seconds.
*/
2022-07-10 10:23:45 +03:00
time_t getTimeout()const;
2013-11-24 17:00:12 +02:00
/**
* Retriueve the host name of the server the client is connected to.
* \return Server host name
*/
std::string getHost()const;
/**
* Retriueve the port of host of the server the client is connected to.
* \return Server port
*/
2022-07-10 10:23:45 +03:00
uint16_t getPort()const;
2013-11-24 17:00:12 +02:00
2022-07-10 10:23:45 +03:00
virtual void authenticate(const std::string& user, const std::string& passwd) override;
virtual void logout() override;
2013-11-24 17:00:12 +02:00
2022-07-10 10:23:45 +03:00
virtual Device getDevice(const std::string& name) override;
virtual std::set<std::string> getDeviceNames() override;
virtual std::string getDeviceDescription(const std::string& name) override;
2013-11-24 17:00:12 +02:00
2022-07-10 10:23:45 +03:00
virtual std::set<std::string> getDeviceVariableNames(const std::string& dev) override;
virtual std::set<std::string> getDeviceRWVariableNames(const std::string& dev) override;
virtual std::string getDeviceVariableDescription(const std::string& dev, const std::string& name) override;
virtual std::vector<std::string> getDeviceVariableValue(const std::string& dev, const std::string& name) override;
virtual std::map<std::string,std::vector<std::string> > getDeviceVariableValues(const std::string& dev) override;
virtual std::map<std::string,std::map<std::string,std::vector<std::string> > > getDevicesVariableValues(const std::set<std::string>& devs) override;
virtual TrackingID setDeviceVariable(const std::string& dev, const std::string& name, const std::string& value) override;
virtual TrackingID setDeviceVariable(const std::string& dev, const std::string& name, const std::vector<std::string>& values) override;
2013-11-24 17:00:12 +02:00
2022-07-10 10:23:45 +03:00
virtual std::set<std::string> getDeviceCommandNames(const std::string& dev) override;
virtual std::string getDeviceCommandDescription(const std::string& dev, const std::string& name) override;
virtual TrackingID executeDeviceCommand(const std::string& dev, const std::string& name, const std::string& param="") override;
virtual void deviceLogin(const std::string& dev) override;
/* FIXME: Protocol update needed to handle master/primary alias
* and probably an API bump also, to rename/alias the routine.
*/
virtual void deviceMaster(const std::string& dev) override;
virtual void devicePrimary(const std::string& dev) override;
virtual void deviceForcedShutdown(const std::string& dev) override;
virtual int deviceGetNumLogins(const std::string& dev) override;
virtual TrackingResult getTrackingResult(const TrackingID& id) override;
virtual bool isFeatureEnabled(const Feature& feature) override;
virtual void setFeature(const Feature& feature, bool status) override;
2013-11-24 17:00:12 +02:00
protected:
2022-07-10 10:23:45 +03:00
std::string sendQuery(const std::string& req);
void sendAsyncQueries(const std::vector<std::string>& req);
static void detectError(const std::string& req);
TrackingID sendTrackingQuery(const std::string& req);
2013-11-24 17:00:12 +02:00
2022-07-10 10:23:45 +03:00
std::vector<std::string> get(const std::string& subcmd, const std::string& params = "");
2013-11-24 17:00:12 +02:00
2022-07-10 10:23:45 +03:00
std::vector<std::vector<std::string> > list(const std::string& subcmd, const std::string& params = "");
std::vector<std::vector<std::string> > parseList(const std::string& req);
2013-11-24 17:00:12 +02:00
static std::vector<std::string> explode(const std::string& str, size_t begin=0);
static std::string escape(const std::string& str);
private:
std::string _host;
2022-07-10 10:23:45 +03:00
uint16_t _port;
time_t _timeout;
2013-11-24 17:00:12 +02:00
internal::Socket* _socket;
};
/**
* Device attached to a client.
* Device is a lightweight class which can be copied easily.
*/
class Device
{
friend class Client;
friend class TcpClient;
2022-07-10 10:23:45 +03:00
friend class TcpClientMock;
#ifdef _NUTCLIENTTEST_BUILD
friend class NutClientTest;
#endif
2013-11-24 17:00:12 +02:00
public:
~Device();
Device(const Device& dev);
2022-07-10 10:23:45 +03:00
Device& operator=(const Device& dev);
2013-11-24 17:00:12 +02:00
/**
* Retrieve the name of the device.
* The name is the unique id under which NUTD known the device.
*/
std::string getName()const;
/**
* Retrieve the client to which the device is attached.
*/
const Client* getClient()const;
/**
* Retrieve the client to which the device is attached.
*/
Client* getClient();
/**
* Test if the device is valid (has a name and is attached to a client).
*/
bool isOk()const;
/**
* Test if the device is valid (has a name and is attached to a client).
2022-07-10 10:23:45 +03:00
* @see Device::isOk()
2013-11-24 17:00:12 +02:00
*/
operator bool()const;
/**
* Test if the device is not valid (has no name or is not attached to any client).
2022-07-10 10:23:45 +03:00
* @see Device::isOk()
2013-11-24 17:00:12 +02:00
*/
bool operator!()const;
/**
* Test if the two devices are sames (same name ad same client attached to).
*/
bool operator==(const Device& dev)const;
2022-07-10 10:23:45 +03:00
/**
* Comparison operator.
*/
bool operator<(const Device& dev)const;
2013-11-24 17:00:12 +02:00
/**
* Retrieve the description of the devce if specified.
*/
2022-07-10 10:23:45 +03:00
std::string getDescription();
2013-11-24 17:00:12 +02:00
/**
* Intend to retrieve the value of a variable of the device.
* \param name Name of the variable to get.
2022-07-10 10:23:45 +03:00
* \return Value of the variable, if available.
2013-11-24 17:00:12 +02:00
*/
2022-07-10 10:23:45 +03:00
std::vector<std::string> getVariableValue(const std::string& name);
2013-11-24 17:00:12 +02:00
/**
* Intend to retrieve values of all variables of the devices.
* \return Map of all variables values indexed by their names.
*/
2022-07-10 10:23:45 +03:00
std::map<std::string,std::vector<std::string> > getVariableValues();
2013-11-24 17:00:12 +02:00
/**
* Retrieve all variables names supported by the device.
* \return Set of available variable names.
*/
2022-07-10 10:23:45 +03:00
std::set<std::string> getVariableNames();
2013-11-24 17:00:12 +02:00
/**
* Retrieve all Read/Write variables names supported by the device.
* \return Set of available Read/Write variable names.
*/
2022-07-10 10:23:45 +03:00
std::set<std::string> getRWVariableNames();
2013-11-24 17:00:12 +02:00
/**
* Intend to set the value of a variable of the device.
* \param name Variable name.
* \param value New variable value.
*/
2022-07-10 10:23:45 +03:00
void setVariable(const std::string& name, const std::string& value);
2013-11-24 17:00:12 +02:00
/**
* Intend to set values of a variable of the device.
* \param name Variable name.
2022-07-10 10:23:45 +03:00
* \param values Vector of new variable values.
2013-11-24 17:00:12 +02:00
*/
2022-07-10 10:23:45 +03:00
void setVariable(const std::string& name, const std::vector<std::string>& values);
2013-11-24 17:00:12 +02:00
/**
* Retrieve a Variable object representing the specified variable.
2022-07-10 10:23:45 +03:00
* \param name Variable name.
2013-11-24 17:00:12 +02:00
* \return Variable object.
*/
2022-07-10 10:23:45 +03:00
Variable getVariable(const std::string& name);
2013-11-24 17:00:12 +02:00
/**
* Retrieve Variable objects representing all variables available for the device.
* \return Set of Variable objects.
*/
2022-07-10 10:23:45 +03:00
std::set<Variable> getVariables();
2013-11-24 17:00:12 +02:00
/**
* Retrieve Variable objects representing all Read/Write variables available for the device.
* \return Set of Variable objects.
*/
2022-07-10 10:23:45 +03:00
std::set<Variable> getRWVariables();
2013-11-24 17:00:12 +02:00
/**
* Retrieve names of all commands supported by the device.
* \return Set of available command names.
*/
2022-07-10 10:23:45 +03:00
std::set<std::string> getCommandNames();
2013-11-24 17:00:12 +02:00
/**
* Retrieve objects for all commands supported by the device.
* \return Set of available Command objects.
*/
2022-07-10 10:23:45 +03:00
std::set<Command> getCommands();
2013-11-24 17:00:12 +02:00
/**
* Retrieve an object representing a command of the device.
* \param name Command name.
* \return Command object.
*/
2022-07-10 10:23:45 +03:00
Command getCommand(const std::string& name);
2013-11-24 17:00:12 +02:00
/**
* Intend to execute a command on the device.
* \param name Command name.
2022-07-10 10:23:45 +03:00
* \param param Additional command parameter
2013-11-24 17:00:12 +02:00
*/
2022-07-10 10:23:45 +03:00
TrackingID executeCommand(const std::string& name, const std::string& param="");
2013-11-24 17:00:12 +02:00
/**
* Login current client's user for the device.
*/
2022-07-10 10:23:45 +03:00
void login();
/* FIXME: Protocol update needed to handle master/primary alias
* and probably an API bump also, to rename/alias the routine.
*/
void master();
void primary();
void forcedShutdown();
2013-11-24 17:00:12 +02:00
/**
* Retrieve the number of logged user for the device.
* \return Number of users.
*/
2022-07-10 10:23:45 +03:00
int getNumLogins();
2013-11-24 17:00:12 +02:00
protected:
Device(Client* client, const std::string& name);
private:
Client* _client;
std::string _name;
};
/**
* Variable attached to a device.
* Variable is a lightweight class which can be copied easily.
*/
class Variable
{
friend class Device;
friend class TcpClient;
2022-07-10 10:23:45 +03:00
friend class TcpClientMock;
#ifdef _NUTCLIENTTEST_BUILD
friend class NutClientTest;
#endif
2013-11-24 17:00:12 +02:00
public:
~Variable();
Variable(const Variable& var);
2022-07-10 10:23:45 +03:00
Variable& operator=(const Variable& var);
2013-11-24 17:00:12 +02:00
/**
* Retrieve variable name.
*/
std::string getName()const;
/**
* Retrieve the device to which the variable is attached to.
*/
const Device* getDevice()const;
/**
* Retrieve the device to which the variable is attached to.
*/
Device* getDevice();
/**
* Test if the variable is valid (has a name and is attached to a device).
*/
bool isOk()const;
/**
* Test if the variable is valid (has a name and is attached to a device).
* @see Variable::isOk()
*/
operator bool()const;
/**
* Test if the variable is not valid (has no name or is not attached to any device).
* @see Variable::isOk()
*/
bool operator!()const;
/**
* Test if the two variables are sames (same name ad same device attached to).
*/
bool operator==(const Variable& var)const;
/**
* Less-than operator (based on variable name) to allow variable sorting.
*/
bool operator<(const Variable& var)const;
/**
* Intend to retrieve variable value.
* \return Value of the variable.
*/
2022-07-10 10:23:45 +03:00
std::vector<std::string> getValue();
2013-11-24 17:00:12 +02:00
/**
* Intend to retireve variable description.
* \return Variable description if provided.
*/
2022-07-10 10:23:45 +03:00
std::string getDescription();
2013-11-24 17:00:12 +02:00
/**
* Intend to set a value to the variable.
* \param value New variable value.
*/
2022-07-10 10:23:45 +03:00
void setValue(const std::string& value);
2013-11-24 17:00:12 +02:00
/**
* Intend to set (multiple) values to the variable.
2022-07-10 10:23:45 +03:00
* \param values Vector of new variable values.
2013-11-24 17:00:12 +02:00
*/
2022-07-10 10:23:45 +03:00
void setValues(const std::vector<std::string>& values);
2013-11-24 17:00:12 +02:00
protected:
Variable(Device* dev, const std::string& name);
private:
Device* _device;
std::string _name;
};
/**
* Command attached to a device.
* Command is a lightweight class which can be copied easily.
*/
class Command
{
friend class Device;
friend class TcpClient;
2022-07-10 10:23:45 +03:00
friend class TcpClientMock;
#ifdef _NUTCLIENTTEST_BUILD
friend class NutClientTest;
#endif
2013-11-24 17:00:12 +02:00
public:
~Command();
Command(const Command& cmd);
2022-07-10 10:23:45 +03:00
Command& operator=(const Command& cmd);
2013-11-24 17:00:12 +02:00
/**
* Retrieve command name.
*/
std::string getName()const;
/**
* Retrieve the device to which the command is attached to.
*/
const Device* getDevice()const;
/**
* Retrieve the device to which the command is attached to.
*/
Device* getDevice();
/**
* Test if the command is valid (has a name and is attached to a device).
*/
bool isOk()const;
/**
* Test if the command is valid (has a name and is attached to a device).
* @see Command::isOk()
*/
operator bool()const;
/**
* Test if the command is not valid (has no name or is not attached to any device).
* @see Command::isOk()
*/
bool operator!()const;
/**
* Test if the two commands are sames (same name ad same device attached to).
*/
bool operator==(const Command& var)const;
/**
* Less-than operator (based on command name) to allow comand sorting.
*/
bool operator<(const Command& var)const;
/**
* Intend to retireve command description.
* \return Command description if provided.
*/
2022-07-10 10:23:45 +03:00
std::string getDescription();
2013-11-24 17:00:12 +02:00
/**
2022-07-10 10:23:45 +03:00
* Intend to execute the instant command on device.
* \param param Optional additional command parameter
2013-11-24 17:00:12 +02:00
*/
2022-07-10 10:23:45 +03:00
void execute(const std::string& param="");
2013-11-24 17:00:12 +02:00
protected:
Command(Device* dev, const std::string& name);
private:
Device* _device;
std::string _name;
};
} /* namespace nut */
#endif /* __cplusplus */
/* End of C++ nutclient library declaration */
/* Begin of C nutclient library declaration */
#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */
/**
* Array of string manipulation functions.
* \{
*/
/** Array of string.*/
typedef char** strarr;
/**
* Alloc an array of string.
*/
2022-07-10 10:23:45 +03:00
strarr strarr_alloc(size_t count);
2013-11-24 17:00:12 +02:00
/**
* Free an array of string.
*/
void strarr_free(strarr arr);
2022-07-10 10:23:45 +03:00
/**
* Convert C++ types into an array of string.
*/
strarr stringvector_to_strarr(const std::vector<std::string>& strset);
strarr stringset_to_strarr(const std::set<std::string>& strset);
2013-11-24 17:00:12 +02:00
/**
* Nut general client types and functions.
* \{
*/
/** Hidden structure representing a connection to NUTD. */
typedef void* NUTCLIENT_t;
/**
2022-07-10 10:23:45 +03:00
* Destroy a client.
2013-11-24 17:00:12 +02:00
* \param client Nut client handle.
*/
void nutclient_destroy(NUTCLIENT_t client);
/**
* Authenticate into the server.
* \param client Nut client handle.
* \param login User name.
* \param passwd Password.
*/
void nutclient_authenticate(NUTCLIENT_t client, const char* login, const char* passwd);
/**
* Log out from server.
* \param client Nut client handle.
*/
void nutclient_logout(NUTCLIENT_t client);
/**
* Register current user on the device.
* \param client Nut client handle.
* \param dev Device name to test.
*/
void nutclient_device_login(NUTCLIENT_t client, const char* dev);
/**
* Retrieve the number of users registered on a device.
* \param client Nut client handle.
* \param dev Device name to test.
*/
int nutclient_get_device_num_logins(NUTCLIENT_t client, const char* dev);
/**
* Set current user as master user of the device.
* \param client Nut client handle.
* \param dev Device name to test.
*/
2022-07-10 10:23:45 +03:00
/* FIXME: Protocol update needed to handle master/primary alias
* and probably an API bump also, to rename/alias the routine.
*/
2013-11-24 17:00:12 +02:00
void nutclient_device_master(NUTCLIENT_t client, const char* dev);
2022-07-10 10:23:45 +03:00
void nutclient_device_primary(NUTCLIENT_t client, const char* dev);
2013-11-24 17:00:12 +02:00
/**
* Set the FSD flag for the device.
* \param client Nut client handle.
* \param dev Device name to test.
*/
void nutclient_device_forced_shutdown(NUTCLIENT_t client, const char* dev);
/**
* Retrieve the list of devices of a client.
* \param client Nut client handle.
* \return Array of string containing device names. Must be freed with strarr_free(strarr).
*/
strarr nutclient_get_devices(NUTCLIENT_t client);
/**
* Test if a device is supported by the client.
* \param client Nut client handle.
* \param dev Device name to test.
* \return 1 if supported, 0 otherwise.
*/
int nutclient_has_device(NUTCLIENT_t client, const char* dev);
/**
* Intend to retrieve device description.
* \param client Nut client handle.
* \param dev Device name to test.
* \return Description of device. Must be freed after use.
*/
char* nutclient_get_device_description(NUTCLIENT_t client, const char* dev);
/**
* Intend to retrieve device variable names.
* \param client Nut client handle.
* \param dev Device name.
* \return Array of string containing variable names. Must be freed with strarr_free(strarr).
*/
strarr nutclient_get_device_variables(NUTCLIENT_t client, const char* dev);
/**
* Intend to retrieve device read/write variable names.
* \param client Nut client handle.
* \param dev Device name.
* \return Array of string containing read/write variable names. Must be freed with strarr_free(strarr).
*/
strarr nutclient_get_device_rw_variables(NUTCLIENT_t client, const char* dev);
/**
* Test if a variable is supported by the device and the client.
* \param client Nut client handle.
* \param dev Device name.
* \param var Variable name.
* \return 1 if supported, 0 otherwise.
*/
int nutclient_has_device_variable(NUTCLIENT_t client, const char* dev, const char* var);
/**
* Intend to retrieve device variable description.
* \param client Nut client handle.
* \param dev Device name.
* \param var Variable name.
* \return Description of device variable. Must be freed after use.
*/
char* nutclient_get_device_variable_description(NUTCLIENT_t client, const char* dev, const char* var);
/**
* Intend to retrieve device variable values.
* \param client Nut client handle.
* \param dev Device name.
* \param var Variable name.
* \return Array of string containing variable values. Must be freed with strarr_free(strarr).
*/
strarr nutclient_get_device_variable_values(NUTCLIENT_t client, const char* dev, const char* var);
/**
* Intend to set device variable value.
* \param client Nut client handle.
* \param dev Device name.
* \param var Variable name.
* \param value Value to set.
*/
void nutclient_set_device_variable_value(NUTCLIENT_t client, const char* dev, const char* var, const char* value);
/**
* Intend to set device variable multiple values.
* \param client Nut client handle.
* \param dev Device name.
* \param var Variable name.
* \param values Values to set. The cller is responsible to free it after call.
*/
void nutclient_set_device_variable_values(NUTCLIENT_t client, const char* dev, const char* var, const strarr values);
/**
* Intend to retrieve device command names.
* \param client Nut client handle.
* \param dev Device name.
* \return Array of string containing command names. Must be freed with strarr_free(strarr).
*/
strarr nutclient_get_device_commands(NUTCLIENT_t client, const char* dev);
/**
* Test if a command is supported by the device and the client.
* \param client Nut client handle.
* \param dev Device name.
* \param cmd Command name.
* \return 1 if supported, 0 otherwise.
*/
int nutclient_has_device_command(NUTCLIENT_t client, const char* dev, const char* cmd);
/**
* Intend to retrieve device command description.
* \param client Nut client handle.
* \param dev Device name.
* \param cmd Command name.
* \return Description of device command. Must be freed after use.
*/
char* nutclient_get_device_command_description(NUTCLIENT_t client, const char* dev, const char* cmd);
/**
* Intend to execute device command.
* \param client Nut client handle.
* \param dev Device name.
* \param cmd Command name.
*/
2022-07-10 10:23:45 +03:00
void nutclient_execute_device_command(NUTCLIENT_t client, const char* dev, const char* cmd, const char* param="");
2013-11-24 17:00:12 +02:00
/** \} */
/**
* Nut TCP client dedicated types and functions
* \{
*/
/**
2022-07-10 10:23:45 +03:00
* Hidden structure representing a TCP connection to NUTD.
2013-11-24 17:00:12 +02:00
* NUTCLIENT_TCP_t is back compatible to NUTCLIENT_t.
*/
typedef NUTCLIENT_t NUTCLIENT_TCP_t;
/**
* Create a client to NUTD using a TCP connection.
* \param host Host name to connect to.
* \param port Host port.
2022-07-10 10:23:45 +03:00
* \return New client or nullptr if failed.
2013-11-24 17:00:12 +02:00
*/
2022-07-10 10:23:45 +03:00
NUTCLIENT_TCP_t nutclient_tcp_create_client(const char* host, uint16_t port);
2013-11-24 17:00:12 +02:00
/**
* Test if a nut TCP client is connected.
* \param client Nut TCP client handle.
* \return 1 if connected, 0 otherwise.
*/
int nutclient_tcp_is_connected(NUTCLIENT_TCP_t client);
/**
* Disconnect a nut TCP client.
* \param client Nut TCP client handle.
*/
void nutclient_tcp_disconnect(NUTCLIENT_TCP_t client);
/**
* Intend to reconnect a nut TCP client.
* \param client Nut TCP client handle.
* \return 0 if correctly connected.
* \todo Implement different error codes.
*/
int nutclient_tcp_reconnect(NUTCLIENT_TCP_t client);
/**
* Set the timeout value for the TCP connection.
* \param timeout Timeout in seconds, negative for blocking.
*/
2022-07-10 10:23:45 +03:00
void nutclient_tcp_set_timeout(NUTCLIENT_TCP_t client, time_t timeout);
2013-11-24 17:00:12 +02:00
/**
* Retrieve the timeout value for the TCP connection.
* \return Timeout value in seconds.
*/
2022-07-10 10:23:45 +03:00
time_t nutclient_tcp_get_timeout(NUTCLIENT_TCP_t client);
2013-11-24 17:00:12 +02:00
/** \} */
#ifdef __cplusplus
}
#endif /* __cplusplus */
/* End of C nutclient library declaration */
#endif /* NUTCLIENT_HPP_SEEN */