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

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

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/