NAME

Net::MirapointAdmin - Perl interface to the Mirapoint administration protocol

SYNOPSIS

High-Level Interface

 $obj = Net::MirapointAdmin->new(host=>$host, debug=>$debug, ssl=>$usessl)

 $obj->login($user, $password);

 $lasttag = $obj->send_command(qw/LICENSE STATUS/);

 $obj->get_response($lasttag);

 $obj->command(qw/USER LIST/, "", "", "");

 $obj->command_ok(qw/MAILBOX LIST/, "%", "", "");

 $obj->command_no(/Already exists/, qw/DL ADD/, $dl);

Low-Level Interface

 $obj = Net::MirapointAdmin->new($host)

 $obj->connect();

 $obj->xmit("tag LOGIN user pass")

 $buf = $obj->getbuf();

DESCRIPTION

Net::MirapointAdmin is a perl module that simplifies the task of writing perl scripts to manage Mirapoint systems. The API allows you to send Mirapoint protocol commands that automate administration tasks across the network.

Two interfaces are available: low-level and high-level. The low-level functions send and receive simple arguments. The high-level functions handle tag generation and stripping, quoted and literal arguments with binding to Perl data types (in an array context), optional response checking, and auto-logout before disconnect. In general, using the high-level interface is more convenient.

High-Level Interface

The new(host=>$host,args) function takes a list of arguments, and uses these arguments to create a TCP/IP connection to the Mirapoint server's administration protocol interface. In the case of a failure, $Net::MirapointAdmin::ERRSTR is set to the error message and undef is retruned. The arguments can include the following:

port => $port

This option specifies a specific port. It is not normally needed since the default port is selected based on the protocol used.

exception => $exception_function_ptr

The default exception handler is a function that prints an error message and dies. This may not always be appropriate (for example, when used as part of a CGI script). This option allows you to replace the default exception handler.

ssl => $ssl

The value of $ssl is either 0 (the default) to use a cleartext connection, or 1 to use an SSL connection. The new() function returns undef if an SSL connection is requested but not available.

debug => $debug

The module prints out TCP trace information if $debug is 1 (by default, $debug is 0).

Other Functions:

login($user, $pass)

Login to the Mirapoint host with the specified username or password. Return undef if unable to comply (the okno() function gives the reason).

$tag = send_command(@cmd)

Sends a command to the Mirapoint unit - the return value is the value to be used as the argument to the get_response() function.

@response = get_response($tag)

Checks and strips the tag from the reponse. The OK or NO response from the Mirapoint host can be retrieved with the okno() function. In a scalar context, the return value is the first argument of the return value. In an array context, the return value is an array of array-references. The outer array is organized by line, and the inner-array by field.

@response = command(@cmd)

The command() function combines the send_command() and get_response() functions, relieving the programmer of having to know about tags.

@response = command_ok(@cmd)

The command_ok() function is similar to the command() function, but insists on an OK response from the server. If the response was not an OK response, it raises an exception.

@response = command_no($pattern, @cmd)

The command_no() function is similar to the command_ok() function, but allows a NO response, providing that the NO response matches $pattern.

hostname()

Returns the host to which we are currently connected.

reported_hostname()

Returns the hostname as reported by the Mirapoint system.

version()

Returns the version of the Mirapoint protocol running on the connected Mirapoint host.

error()

Returns the last error generated by the module.

okno()

Returns the status of the last command executed.

connected()

Returns TRUE if the module is connected to a host, and FALSE otherwise.

loggedin()

Returns TRUE if the module has successfully logged in and is authenticated.

supports_ssl()

Returns 1 if the module supports SSL. This is generally used in the following manner:

        $ssl = Net::MirapointAdmin::supports_ssl();
        $mp = Net::MirapointAdmin->new(host => $host, ssl => $ssl);
mos_ver()

Returns the version of the Mirapoint protocol running on the connected Mirapoint host encoded into a hexadecimal number.

Low-Level Interface

In order to support more complex situations, a lower level interface is provided. This includes the following functions:

new($host, $port)

Connect to the specified host on the specified port. Note that an SSL connection is not possible using the low level interface.

connect()

Unlike the high-level interface, the low-level interface does not automatically connect to the remote host. connect() actually initiates the connection, and raises an exception on failure.

xmit($cmd)

Send the $cmd string directly to the server. The $cmd string should already have a tag in front of it. Returns the number of bytes sent on success, or undef on failure.

$cmd = getbuf()

Obtain one line from the Mirapoint host. Note that no dequoting of the resulting line is done, and the return value may not contain the full output of the command executed with the xmit() function. Returns undef on error (such as an invalid connection)

EXAMPLES

Login:
        $mp = Net::MirapointAdmin->new(host => $host,
                                   ssl => $ssl,
                                   debug => $debug);
        $mp->login($user, $password);
High-level command:
        $user = "bob"; $password = "pwd"; $fullname = "Bob Smith";
        $mp->command_ok(qw/USER ADD/, $user, $password, $fullname);
            results in:
        C: tag USER ADD bob pwd "Bob Smith"
        S: tag OK
High-level command and response:
        $pattern = ""; $start = "", $count = "";
        @users = $mp->command_ok(qw/USER LIST/, $pattern, $start, $count);
        @usernames = map { $_ = $$_[0] } @users;
            results in:
        C: tag USER LIST "" "" ""
        S: * tag "bob" "Bob Smith"
        S: * tag "joe" "Joe Brown"
        S: tag OK
        @users = ( [ "bob", "Bob Smith" ], [ "joe", "Joe Brown" ] )
        @usernames = ("bob", "joe");
With error checking (OK, or NO followed by pattern):
       $mp->command_no("Already exists", qw/DL ADD/, $dl);
Manual error checking:
        @response = $mp->command(qw/DLENTRY LIST/, $dl, "", "", "");
        if ($mp->okno =~ /^NO/) {
                ...
        }
Low-level routine:
        $mp->send_command(qw/EVENT WATCH Login/);
        while ($mp->connected()) {
                print $mp->getbuf();    # Get the next line
        }
Logout:
       undef $mp;              [Performs logout and disconnect]

SEE ALSO

        The Mirapoint Protocol Reference Manual
        http://support.mirapoint.com/