Issue
What is the Mirapoint Administrative Perl SDK?
Solution
The following information on the administrative Perl SDK may be useful, however, Mirapoint does not provide support for this development kit.
Description
Net::MirapointAdmin is a Perl module that simplifies the task of writing perl scripts to manage Mirapoint or RazorGate appliances. The API allows you to send Mirapoint protocol commands that automate administration tasks across the network. This facility requires perl 5.003 or later.
Two interfaces are available:
- Low-level-Sends and receives simple arguments.
- High-level-Handles 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.
The High-Level Interface
$obj = Net::MirapointAdmin->new(host=>$host, port=>$port)
$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);
The new (host=>$host,args) function takes a list of arguments, and uses these arguments to create a TCP/IP connection to the Mirapoint or RazorGate appliance's administration protocol interface. 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 S 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 or RazorGate 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 or RazorGate appliance - 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 response. The OK or NO response from the Mirapoint or RazorGate 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 or RazorGate appliance.
version()
Returns the version of the Mirapoint protocol running on the connected Mirapoint or RazorGate 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.
Low-Level Interface
$obj = Net::MirapointAdmin->new($host, $port)
$obj->connect;
$obj->xmit("tag LOGIN user pass")
uf = $obj->getbuf;
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.
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 or RazorGate 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,
    port => $port,
    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
For information on Net::MirapointAdmin, see the Mirapoint Administration Protocol Reference for your MOS release version.
For further assistance, contact Mirapoint Professional Services.
Comments
0 comments
Please sign in to leave a comment.