/ 
Net-APP-0.2
River stage zero No dependents
/ Net::APP

NAME

Net::APP - Critical Path Account Provisioning Protocol

SYNOPSIS

use Net::APP;

#constructor
$app = new Net::APP ( 'host:port',
                      User     => $user,
                      Domain   => $domain,
                      Password => $password,
                      Timeout  => 60,
                      Debug    => 1,
                    ) or die $@;

#commands
$app->ver( 'ver' => $Net::APP::APP_VERSION );
$app->login ( User     => $user,
              Domain   => $domain,
              Password => $password,
            );

$app->create_domain ( Domain => $domain );
$app->delete_domain ( Domain => $domain );
#etc. (see the Account Provisioning Protocol Developer's Guide, section 3.3)

#command status
$message = $app->message;
$code = $app->code;
$bool = $app->ok();

#destructor
$app->close();

DESCRIPTION

This module implements a client interface to Critical Path's Account Provisioning Protocol, enabling a perl application to talk to APP servers. This documentation assumes that you are familiar with the APP protocol documented in the Account Provisioning Protocol Developer's Guide.

A new Net::APP object must be created with the new method. Once this has been done, all APP commands are accessed via method calls on the object.

METHODS

new ( HOST:PORT [ , OPTIONS ] )

This is the constructor for a new Net::APP object. HOST and PORT specify the host and port to connect to in cleartext. Typically this connection is proxied via Safe Passage Secure Tunnel or Stunnel http://www.stunnel.org/ using a command such as:

stunnel -P none -c -d 8888 -r your.cp.address.and:port

This method will connect to the APP server and execute the ver method.

OPTIONS are passed in a hash like fastion, using key and value pairs. Possible options are:

Timeout - Set a timeout value (defaults to 120)

Debug - Enable debugging information (see the debug method in Net::Cmd)

User, Domain, Password - if these exist, the new method will also execute the login method automatically.

If the constructor fails undef will be returned and an error message will be in $@.

ver
login
create_domain
delete_domain
etc.

See the Account Provisioning Protocol Developer's Guide for details. Commands need not be in upper case, and options are passed in a hash-like fashion, as a list of key-value pairs.

Unless noted below, all commands return a reference to a list containing the lines of the reponse, or undef upon failure. The first line is parsed for the status code and message. You can check the status code and message using the normal Net::Cmd message, code, ok, and status methods.

Some methods return additional response information, such as get_num_domain_mailboxes, get_domain_mailboxes, get_mailbox_availability and get_mailbox_status methods currently return any additional response information. Unless specifically noted below, no attempt is (yet) made to parse this data.

get_domain_mailboxes

Returns an arrayref of arrayrefs, each with three elements: username, mailbox type, and workgroup. The protocol calls them: MAILBOX, TYPE, and WORKGROUP.

get_mailbox_forward_only

Returns the forward email address.

message

Returns the text message returned from the last command.

code

Returns the response code from the last command (see the Account Provisioning Protcol Developer's Guide, chapter 4). The code `-1' is used to represent unparsable output from the APP server, in which case the entire first line of the response is returned by the messsage method.

ok

Returns true if the last response code was not an error. Since the only non-error code is 0, this is just the negation of the code method.

status

Since the APP protocol has no concept of a "most significant digit" (see "status" in Net::Cmd), this is a noisy synonym for code.

INTERNAL METHODS

These methods are not intended to be called by the user.

_app_command ( COMMAND [ , OPTIONS ] )

Sends COMMAND, encoded as per the Account Provisioning Protocol Developer's Guide, section 3.2. OPTIONS are passed in a hash like fashion, using key and value pairs.

_app_response

Gets a response from the server. Returns a reference to a list containing the lines, or undef upon failure. You can check the status code and message using the normal Net::Cmd message, code, ok, and status methods.

INTERNAL SUBROUTINES

These subroutines are not intended to be called by the user.

_quote

Doubles double quotes.

AUTHOR

Ivan Kohler <ivan-netapp_pod@420.am>.

This module is not sponsored or endorsed by Critical Path.

COPYRIGHT

Copyright (c) 2001 Ivan Kohler. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

PROTOCOL VERSION

This module currently implements APP v3.3, as documented in the Account Provisioning Protocol Developers Guide v3.3.

BUGS

The Account Provisioning Protocol Developer's Guide is not publicly available.

It appears that Safe Passage Secure Tunnel and Stunnel establish standard SSL connections. It should be possible to use Net::SSLeay and connect to the APP server directly. Initial prototyping with IO::Socket::SSL was not promising. :(

The get_num_domain_mailboxes, get_mailbox_availability and get_mailbox_status methods currently return response information. No attempt is (yet) made to parse this data.

SEE ALSO

Critical Path <http://www.cp.net/>, APP documentation <http://support.cp.net/products/email_messaging/documentation/index.jsp>, Safe Passage Secure Tunnel <http://www.int.c2.net/external/?link=spst/index.php3>, Stunnel <http://www.stunnel.org>, IO::Socket, Net::Cmd, perl(1).