The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
perl-Hardware-UPS-Perl-0.43
River stage zero No dependents
++
/ Hardware::UPS::Perl::Connection::Net

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.

See Also:

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

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.

See Also:

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

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.

See Also:

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

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"

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.

See Also:

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

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.

See Also:

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

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

See Also:

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

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.

See Also:

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

SEE ALSO

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)

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