NAME

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

SYNOPSIS

    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

DESCRIPTION

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

LIST OF METHODS

new

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.

setHost

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.

getHost

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.

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.

getTCPPort

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.

setDebugLevel

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"

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"

setLogger

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"

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"

getErrorMessage

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.

connect

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.

connected

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"

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().

sendCommand

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.

NOTES

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.

BUGS

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.

AUTHOR

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

To install Hardware::UPS::Perl::PID, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Hardware::UPS::Perl::PID

CPAN shell

perl -MCPAN -e shell
install Hardware::UPS::Perl::PID

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

LIST OF METHODS

new

setHost

getHost

setTCPPort

getTCPPort

setDebugLevel

getDebugLevel

setLogger

getLogger

getErrorMessage

connect

connected

disconnect

sendCommand

SEE ALSO

NOTES

BUGS

AUTHOR

Module Install Instructions