view release on metacpan or  search on metacpan

lib/Device/ISDN/OCLM.pm  view on Meta::CPAN

package Device::ISDN::OCLM;

=head1 NAME

Device::ISDN::OCLM - A perl module to control the 3com OfficeConnect LanModem

=head1 SYNOPSIS

 $sp = 1;
 $pw = 'secret;
 $lanmodem = Device::ISDN::OCLM->new ();
 $lanmodem->password ($pw);
 $command = 'manualConnect';
 $status = $lanmodem->$command ($sp);
 while (($status eq 'CLOCK') || ($status eq 'PASSWORD') ||
        ($status eq 'CONNECTING') || ($status eq 'LOGGING IN')) {
   if ($status eq 'CLOCK') {
     sleep (1);
     $status = $lanmodem->setClock ();
   } elsif ($status eq 'PASSWORD') {
     sleep (1);
     $status = $lanmodem->enterPasword ();
   } elsif (($status eq 'CONNECTING') || ($status eq 'LOGGING IN')) {
     $command = 'connectStatus';
     $status = 'OK';
   }
   if ($status eq 'OK') {
     sleep (1);
     $status = $lanmodem->$command ($sp);
   }
 }
 print "$status\n";

=head1 DESCRIPTION

This module can be used to control the 3com OfficeConnect LanModem, an
ISDN TA/router. Device statistics can be queried and manual connections
can be brought up and taken down. Support is provided for setting the
clock if the device is power-cycled, and for automatically entering the
password if the device is password-protected.

All operations that access the device return a status code indicating
whether the operation was successful or not; and, if not, why. For
example, if you attempt to query device statistics and the device is
locked then the status code will indicate this fact, allowing you to enter
the password and retry the operation. Hence the loop in the above
synopsis.

This module does not perform these loops internally in an effort to allow
it to be embedded within a controlling application such as the B<oclm>
Perl command-line application, and a GNOME/GTK graphical user interface
that is available separately.

This module has a few warts; some are mandated by the device itself and
some are the fault of the author.

=head1 CONSTRUCTORS

The following constructor is provided:

=over 4

=item $lanmodem = Device::ISDN::OCLM->new ()

This class method constructs a new LanModem object. A default
HTTP user agent is created with no proxy information.

=back

=head1 METHODS

The following methods are provided:

=over 4

=item $copy = $lanmodem->clone ()

This method returns a clone of this object.

=item $oldHostname = $lanmodem->lanmodem ( [$newHostname] )

This method gets, and optionally sets, the hostname (and optionally port)
of the device being controlled. The default value is I<3com.oc.lanmodem>.

=item $oldPassword = $lanmodem->password ( [$newPassword] )

This method gets, and optionally sets, the password needed to access the
device. This is only needed if your device is password-protected.

=item $userAgent = $lanmodem->userAgent ()

This method gets the B<LWP::UserAgent> that is used by this object to access
the device. Use this if you want to configure HTTP proxy settings, etc.

=item $defHostname = $lanmodem->defaultLanModem ()

This method gets the default device hostname, I<3com.oc.lanmodem>.

=item $status = $lanmodem->manualConnect ($providerIndex)

This method attempts to manually connect to the specified service provider
(identified by index, starting from 1). The result will be one of the
standard status codes, I<'CONNECTING'> if the ISDN connection attempt is
in progress (most likely), I<'LOGGING IN'> if the device is attempting to
log in to the service provider, I<'ISDN FAILED'> if there was an error

lib/Device/ISDN/OCLM.pm  view on Meta::CPAN

previous request failed, then the result is indeterminate.

=item $status = $lanmodem->getLastStatistics ()

This method queries last call statistics from the device. This includes
details about the previous connection on each ISDN line, including its up
time, the reason for it going down, etc. The result will be one of the
standard status codes.

=item $info = $lanmodem->lastStatistics ()

This method returns the result of the previous last call statistics
query; the result is of type Device::ISDN::OCLM::LastStatistics. If the
previous request failed, then the result is indeterminate.

=item $status = $lanmodem->getLast10Statistics ()

This method queries last 10 call statistics from the device. This includes
details of the last 10 calls, including their durations, the reason for
going up, etc. The result will be one of the standard status codes.

=item $info = $lanmodem->last10Statistics ()

This method returns the result of the previous last 10 call statistics
query; the result is of type Device::ISDN::OCLM::Last10Statistics. If the
previous request failed, then the result is indeterminate.

=item $status = $lanmodem->getSPStatistics ()

This method queries service provider statistics from the device. This
includes the name of each configured service provider as well as how much
time you have spent connected to that provider, etc. The result will be
one of the standard status codes.

=item $info = $lanmodem->spStatistics ()

This method returns the result of the previous service provider statistics
query; the result is of type Device::ISDN::OCLM::SPStatistics. If the
previous request failed, then the result is indeterminate.

=back

=head1 STANDARD STATUS CODES

The following are the status codes that you should expect from any command
that you perform against the device:

=over 4

=item 'OK'

The command succeeded.

=item 'CLOCK'

The device clock is unset (probably because of a power cycle). You should
call B<setClock()> to set the clock and then repeat your original command.

=item 'PASSWORD'

The device is password locked. You should call B<enterPassword()> to enter
the password and then repeat your original command.

=item 'BAD HTML'

The device returned and unexpected HTML page. This is either because of
a bug in this module or because your firmware is different from mine.
Probably best to contact me and we can work out the problem.

=item 'BAD HTTP'

There was a problem performing an HTTP request of the device. Either you
got the hostname wrong, it is not reachable from your machine, there
was a network error, or something bizarre of that nature happened.

=back

=head1 BUGS

Specifying your password in any manner is, of course, insecure. Doesn't
support multiple concurrent connection attemps. Others unknown.

=head1 SEE ALSO

L<oclm>,
L<Device::ISDN::OCLM::ManualStatistics>,
L<Device::ISDN::OCLM::SystemStatistics>,
L<Device::ISDN::OCLM::ISDNStatistics>,
L<Device::ISDN::OCLM::CurrentStatistics>,
L<Device::ISDN::OCLM::LastStatistics>,
L<Device::ISDN::OCLM::Last10Statistics>,
L<Device::ISDN::OCLM::SPStatistics>,
L<Device::ISDN::OCLM::Statistics>

=head1 COPYRIGHT

Copyright 1999-2000 Merlin Hughes.

This library is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.

=head1 AUTHOR

Merlin Hughes E<lt>merlin@merlin.org>

=cut

# TODO: Figure out the WizStat2 thing. Maybe that is when there
# is a second connection attempt in progress!! If so, status has
# to be a bit smarter!!

# what about explicit deletion of HTML parsed things?

# TODO: store HTML locally
# TODO: explicit clock set
# TODO: last 10 calls

# TODO: if I've already downloaded a page, don't refetch it...

# "OK"
# "CLOCK"