NAME

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

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";

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

CONSTRUCTORS

The following constructor is provided:

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

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

METHODS

The following methods are provided:

$copy = $lanmodem->clone ()

This method returns a clone of this object.

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

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

$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.

$userAgent = $lanmodem->userAgent ()

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

$defHostname = $lanmodem->defaultLanModem ()

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

$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, 'CONNECTING' if the ISDN connection attempt is in progress (most likely), 'LOGGING IN' if the device is attempting to log in to the service provider, 'ISDN FAILED' if there was an error placing the ISDN call or 'LOGON FAILED' if there was an error logging on. Currently, further details of the error are not available.

Once you have called this and the response is 'CONNECTING' or 'LOGGING IN' then you should poll the connectStatus() method to determine the updated connection attempt status.

If you call this method while the device is already connecting to, or logging into the service provider, then the results are not clearly defined; the connection attempt may be aborted. If you call this after the device has connected to the service provider, then again it is not clearly defined; it may return success.

$status = $lanmodem->connectStatus ($providerIndex)

This method returns the connection status of the call currently in progress to the specified provider.

$status = $lanmodem->manualDisconnect ($lineIndex)

This method attempts to manually disconnect the specified ISDN line (identified by index, starting from 1). The result will be one of the standard status codes.

$status = $lanmodem->manualAbort ($lineIndex)

This method attempts to abort the current connection attempt on the specified ISDN line (identified by index, starting from 1). The result will be one of the standard status codes.

$status = $lanmodem->enterPassword ()

This method enters the password on the device to unlock it. You should first configure a password through the password() method. This method should generally be called when a query returns the status code 'PASSWORD'. The result will be one of the standard status codes or 'BAD PASSWORD' if the password you configured is incorrect.

$status = $lanmodem->setClock ()

This method sets the time on the device to the current time on your system. This should generally be called when a query returns the status code 'CLOCK'. The result will be one of the standard status codes.

$status = $lanmodem->getManualStatistics ()

This method queries manual calling statistics from the device. This includes all configured service providers and whether they are currently connected or not. The result will be one of the standard status codes.

$info = $lanmodem->manualStatistics ()

This method returns the result of the previous manual calling statistics query; the result is of type Device::ISDN::OCLM::ManualStatistics. If the previous request failed, then the result is indeterminate.

$status = $lanmodem->getSystemStatistics ()

This method queries system statistics from the device. This includes the device serial number, firmware revision etc. The result will be one of the standard status codes.

$info = $lanmodem->systemStatistics ()

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

$status = $lanmodem->getISDNStatistics ()

This method queries ISDN statistics from the device. This includes the status of the different ISDN layers, etc. The result will be one of the standard status codes.

$info = $lanmodem->isdnStatistics ()

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

$status = $lanmodem->getCurrentStatistics ()

This method queries current call statistics from the device. This includes details about the current connection on each ISDN line, including its up time, to whom it is connected, etc. The result will be one of the standard status codes.

$info = $lanmodem->currentStatistics ()

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

$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.

$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.

$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.

$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.

$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.

$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.

STANDARD STATUS CODES

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

'OK'

The command succeeded.

'CLOCK'

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

'PASSWORD'

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

'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.

'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.

BUGS

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

SEE ALSO

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

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.

AUTHOR

Merlin Hughes <merlin@merlin.org>