Hardware::UPS::Perl::Connection::Net - package of methods to connect to a remote UPS agent.

    use Hardware::UPS::Perl::Connection::Net;

    $net = Hardware::UPS::Perl::Connection::Net->new();

    $net = Hardware::UPS::Perl::Connection::Net->new({
	    Host    =>  192.168.41.2,
	    TCPPort =>  9050,
    });

    undef $net;                        # disconnects

Hardware::UPS::Perl::Connection::Net provides methods to connect to a remote UPS agent running on host Host at TCP port TCPPort.

Name:

new - creates a new UPS connection object using TCP/IP

Synopsis:

	$net = Hardware::UPS::Perl::Connection::Net->new();

	$net = Hardware::UPS::Perl::Connection::Net->new({
	    Host    => $host  ,
	    TCPPort => $port  ,
	    Logger  => $Logger,
    });

Description:

new initializes a connection object $net and opens the connection to a remotely running UPS agent via TCP, if the host $host and the TCP port $port are specified. If the initialization fails, new returns undef.

new expects either a single argument, the host and, optionally, the TCP port both separated by ":", or an anonymous hash as options consisting of key-value pairs.

Arguments:

$host[:$port]

optional; the host and, optionally, the TCP port; defines the host (and port), where the UPS agent is running.

Host => $host[:$port]

optional; the host; defines the host (and port), where the UPS agent is running.

TCPPort => $port

optional; the TCP port; defines the port at the host, where the UPS agent is running.

Logger => $logger

optional; a Hardware::UPS::Perl::Logging object; defines a logger; if not specified, a logger sending its output to STDERR is created.

See Also:

"connect", "connected", "disconnect", "getHost", "getLogger", "getTCPPort", "setHost", "setLogger", "setTCPPort"

Name:

setHost - sets the host to connect to

Synopsis:

	$net = Hardware::UPS::Perl::Connection::Net->new();

	$net->setHost($host);

Description:

setHost sets the host to connect to and returns the previous host if available, undef otherwise.

Arguments:

$host

host; defines a resolvable host.

See Also:

"new", "connect", "connected", "disconnect", "getHost", "setTCPPort", "getTCPPort"

Name:

getHost - gets the host to connect or connected to

Synopsis:

	$net = Hardware::UPS::Perl::Connection::Net->new({
	    Host    => 192.168.1.2
	    TCPPort => 9050,
    });

	$host = $net->getHost();

Description:

getHost returns the host to connect or already connected to.

See Also:

"new", "connect", "connected", "disconnect", "getTCPPort", "setHost", "setTCPPort"

Name:

setTCPPort - sets the TCP port to connect to

Synopsis:

	$net = Hardware::UPS::Perl::Connection::Net->new();

	$net->setTCPPort($port);

Description:

setTCPPort sets the TCP port to connect to and returns the previous TCP port if available, undef otherwise.

Arguments:

$port

natural number; TCP port.

See Also:

"new", "connect", "connected", "disconnect", "getHost", "getTCPPort", "setTCPPort"

Name:

getTCPPort - gets the TCP port to connect or connected to

Synopsis:

	$net = Hardware::UPS::Perl::Connection::Net->new({
	    Host    => 192.168.1.2
	    TCPPort => 9050,
    });

	$host = $net->getTCPPort();

Description:

getTCPPort returns the TCP port to connect or already connected to.

See Also:

"new", "connect", "connected", "disconnect", "getHost", "getLogger", "setHost", "setLogger", "setTCPPort"

Name:

setDebugLevel - sets the debug level

Synopsis:

	$net = Hardware::UPS::Perl::Connection::Net->new();

	$net->setDebugLevel(1);

Description:

setDebugLevel sets the debug level, the higher, the better. It returns the previous one if available, 0 otherwise.

Arguments:

$debugLevel

natural number; defines the debug level.

See Also:

"getDebugLevel"

Name:

getDebugLevel - gets the current debug level

Synopsis:

	$net = Hardware::UPS::Perl::Connection::Net->new();

	$debugLevel = $net->getDebugLevel();

Description:

getDebugLevel returns the current debug level.

See Also:

"setDebugLevel"

Name:

setLogger - sets the logger to use

Synopsis:

	$net    = Hardware::UPS::Perl::Connection::Net->new();

	$logger = Hardware::UPS::Perl::Logging->new();

	$net->setLogger($logger);

Description:

setLogger sets the logger object used for logging. setLogger returns the previous logger used.

Arguments:

$logger

required; a Hardware::UPS::Perl:Logging object; defines the logger for logging.

See Also:

"new", "getLogger"

Name:

getLogger - gets the current logger for logging

Synopsis:

	$net = Hardware::UPS::Perl::Connection::Net->new();

	$logger = $net->getLogger();

Description:

getLogger returns the current logger, i.e. a Hardware::UPS::Perl::Logging object used for logging, if defined, undef otherwise.

See Also:

"new", "setLogger"

Name:

getErrorMessage - gets the internal error message

Synopsis:

	$net = Hardware::UPS::Perl::Connection::Net->new();

	if (!$net->connected()) {
	    print STDERR $net->getErrorMessage(), "\n";
	    exit 0;
	}

Description:

getErrorMessage returns the internal error message, if something went wrong.

Name:

connect - connects to a romotely running UPS agent

Synopsis:

	$net = Hardware::UPS::Perl::Connection::Net->new();

	$net->connect();

	$net->connect({
	    Host    => $host,
	    TCPPort => $port,
    });

Description:

connect connects to an UPS agent running at TCP port $port on host $host using package IO::Socket::INET. If there is already a connection and the host and/or TCP port have changed, the old connection is dropped, otherwise nothing will be done. If no host and/or TCP port are specified, it will be checked whether the host and/or TCP port has been previously set by methods setHost and setTCPPort, respectively, and used for the connection, consequently. If no host and/or no port is available at all. the default host and default TCP port provided by package Hardware::UPS::Perl::Constants will be used, usually being the FQDN of the local host and port 9050.

Arguments:

Host => $host[:$port]

optional; host; defines a resolvable host (IP address, FQDN, hostname). The TCP port to be used can be appended with a ":".

TCPPort => $port

optional; TCP port; defines a valid TCP port.

See Also:

"new", "connected", "disconnect", "setHost", "getHost", "setTCPPort", "getTCPPort"

Name:

connected - tests the connection status

Synopsis:

	$net = Hardware::UPS::Perl::Connection::Net->new();

	$net->connect();
	if ($net->connected()) {
	    ...
	}

Description:

connected tests the connection status, returning 0, when not connected, and 1 when connected.

See Also:

"new", "connect", "disconnect"

Name:

disconnect - disconnects from an UPS agent

Synopsis:

	$net = Hardware::UPS::Perl::Connection::Net->new();

	$net->connect();
	$net->disconnect();

	$net = Hardware::UPS::Perl::Connection::Net->new();

	$net->connect();
	undef $net;

Description:

disconnect disconnects from an UPS agent.

Notes:

undef $net has the same effect as $net->disconnect().

See Also:

"new", "connect", "connected", "setHost", "getHost", "setTCPPort", "getTCPPort"

Name:

sendCommand - sending a command to the UPS agent

Synopsis:

	$net = Hardware::UPS::Perl::Connection::Net->new();

	$net->connect();
	$net->sendCommand($command, \$response, $responseSize);

Description:

sendCommand sends a command $command to an UPS agent connected appending the response size expected using <C-A> and "\n" and reads the response $response from the UPS agent using the package IO::Select.

Arguments:

$command

string; defines a command.

$response

string; the response from the UPS.

$responseSize

integer; the buffer size of the response from the UPS.

See Also:

"new", "connect", "connected", "disconnect"

Errno(3pm), IO::Select(3pm), IO::Socket::INET(3pm), Hardware::UPS::Perl::Connection(3pm), Hardware::UPS::Perl::Connection::Serial(3pm), Hardware::UPS::Perl::Constants(3pm), Hardware::UPS::Perl::Driver(3pm), Hardware::UPS::Perl::Driver::Megatec(3pm), Hardware::UPS::Perl::General(3pm), Hardware::UPS::Perl::Logging(3pm), Hardware::UPS::Perl::PID(3pm), Hardware::UPS::Perl::Utils(3pm)

Hardware::UPS::Perl::Connection::Net was inspired by the usv.pl program by Bernd Holzhauer, <www.cc-c.de>. The latest version of this program can be obtained from

    http://www.cc-c.de/german/linux/linux_usv.php

Another great resource was the Network UPS Tools site, which can be found at

    http://www.networkupstools.org

Hardware::UPS::Perl::Connection::Net was developed using perl 5.8.8 on a SuSE 10.1 Linux distribution.

There are plenty of them for sure. Maybe the embedded pod documentation has to be revised a little bit.

Suggestions to improve Hardware::UPS::Perl::Connection::Net are welcome, though due to the lack of time it might take a while to incorporate them.

Copyright (c) 2007 by Christian Reile, <Christian.Reile@t-online.de>. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. For further licensing details, please see the file COPYING in the distribution.

cut