From 924a225b5684a0172546f9ae204d13a376900e5d Mon Sep 17 00:00:00 2001 From: ivan Date: Fri, 9 Nov 2001 21:58:40 +0000 Subject: [PATCH] - updated for APP version 3.3 - documentation on using stunnel instead of Safe Passage - useful get_domain_mailboxes and get_mailbox_forward_only methods that return perl data structures instead of unparsed lines --- APP.pm | 114 ++++++++++++++++++++++++++++++++++++++++-------------------- Changes | 6 ++++ Makefile.PL | 5 ++- README | 7 ++-- test.pl | 9 +++-- 5 files changed, 96 insertions(+), 45 deletions(-) diff --git a/APP.pm b/APP.pm index 0b425c0..3bd2923 100644 --- a/APP.pm +++ b/APP.pm @@ -5,9 +5,10 @@ use vars qw($VERSION $APP_VERSION @ISA $AUTOLOAD); use Carp; use IO::Socket; use Net::Cmd; +#use Text::CSV_XS; -$VERSION = '0.1'; # $Id: APP.pm,v 1.2 2001-04-10 13:46:43 ivan Exp $ -$APP_VERSION = '2.1'; +$VERSION = '0.2'; # $Id: APP.pm,v 1.3 2001-11-09 21:58:40 ivan Exp $ +$APP_VERSION = '3.3'; @ISA = qw(Net::Cmd IO::Socket::INET); @@ -65,7 +66,10 @@ been done, all APP commands are accessed via method calls on the object. This is the constructor for a new Net::APP object. C and C specify the host and port to connect to in cleartext. Typically this -connection is proxied via Safe Passage Secure Tunnel to Critical Path. +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 I method. @@ -145,14 +149,64 @@ 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. -All options return a reference to a list containing the lines of the reponse, -or I 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 -I, I, I, and I methods. +Unless noted below, all commands return a reference to a list containing the +lines of the reponse, or I 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 I, I, I, and I methods. -Only the get_num_domain_mailboxes, get_mailbox_availability and +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. No attempt is (yet) made to parse this data. +information. Unless specifically noted below, no attempt is (yet) made to +parse this data. + +=item 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. + +=cut + +sub get_domain_mailboxes { + my $self = shift; +# my $command = $AUTOLOAD; +# $command =~ s/.*://; + my $command = 'get_domain_mailboxes'; +# my $csv = new Text::CSV_XS; + $self->_app_command( $command, @_ ); + [ map { chomp; [ map { s/(^"|"$)//g; $_ } + split(/(?<=[^"]")\s+(?="[^"])/, $_) + ] + } + grep { $_ !~ /^,$/ } + splice( @{$self->_app_response}, 2 ) + ]; +} + +=item get_mailbox_forward_only + +Returns the forward email address. + +=cut + +sub get_mailbox_forward_only { + my $self = shift; +# my $command = $AUTOLOAD; +# $command =~ s/.*://; + my $command = 'get_mailbox_forward_only'; + $self->_app_command( $command, @_ ); + + my $lines = $self->_app_response; + + unless ( $lines->[1] =~ /^FORWARD_EMAIL="([^"]+)"$/ ) { + warn $lines->[1]; + $self->set_status ( -1, $lines->[0] ); + return undef; + } + + $1; + +} =item message @@ -167,7 +221,8 @@ of the response is returned by the I method. =item ok -Returns true if the last code was an acceptable response. +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. =cut @@ -260,8 +315,6 @@ These subroutines are not intended to be called by the user. Doubles double quotes. -This is untested for strings containing consecutive double quotes. - =cut sub _quote { @@ -274,34 +327,29 @@ sub _quote { =head1 AUTHOR -Ivan Kohler . +Ivan Kohler . This module is not sponsored or endorsed by Critical Path. =head1 COPYRIGHT -Copyright (c) 1999 Ivan Kohler. -Copyright (c) 1999 Silicon Interactive Software Design. +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. -=head1 VERSION +=head1 PROTOCOL VERSION -$Id: APP.pm,v 1.2 2001-04-10 13:46:43 ivan Exp $ - -This module currently implements APP v2.1, as documented in the Account -Provisioning Protocol Developers Guide v2.1. +This module currently implements APP v3.3, as documented in the Account +Provisioning Protocol Developers Guide v3.3. =head1 BUGS The Account Provisioning Protocol Developer's Guide is not publicly available. -It appears that Safe Passage Secure Tunnel establishes a standard SSL -connection. It should be possible to use Net::SSLeay and connect to the APP -server directly. - -Sending values with consecutive double quote characters is untested. +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 @@ -310,18 +358,10 @@ parse this data. =head1 SEE ALSO Critical Path , -Safe Passage Secure Tunnel , -L, L, perl(1). - -=head1 HISTORY - -$Log: APP.pm,v $ -Revision 1.2 2001-04-10 13:46:43 ivan -update email addresses and CVS information - -Revision 1.1.1.1 1999/06/21 10:11:11 ivan -new project - +APP documentation , +Safe Passage Secure Tunnel , +Stunnel , +L, L, perl(1). =cut diff --git a/Changes b/Changes index 41aa4f8..0293d6b 100644 --- a/Changes +++ b/Changes @@ -1,5 +1,11 @@ Revision history for Perl extension Net::APP. +0.2 Fri Nov 9 13:33:15 2001 + - updated for APP version 3.3 + - documentation on using stunnel instead of Safe Passage + - useful get_domain_mailboxes and get_mailbox_forward_only methods + that return perl data structures instead of unparsed lines + 0.1 Sun Jun 20 23:15:58 1999 - original version; created by h2xs 1.19 diff --git a/Makefile.PL b/Makefile.PL index eaf6a10..c12e768 100644 --- a/Makefile.PL +++ b/Makefile.PL @@ -4,6 +4,9 @@ use ExtUtils::MakeMaker; WriteMakefile( 'NAME' => 'Net::APP', 'VERSION_FROM' => 'APP.pm', # finds $VERSION - 'PREREQ_PM' => { 'Net::Cmd' => 0, }, + 'PREREQ_PM' => { 'Net::Cmd' => 0, +# 'IO::Socket::SSL' => 0, +# 'Text::CSV_XS' => 0, + }, 'dist' => {}, ); diff --git a/README b/README index 472c2d8..5979cc4 100644 --- a/README +++ b/README @@ -1,7 +1,6 @@ -Net::APP v0.1 +Net::APP v0.2 -Copyright (c) 1999 Ivan Kohler. -Copyright (c) 1999 Silicon Interactive Software Design. +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. @@ -35,4 +34,4 @@ Homepage: Ivan Kohler -$Id: README,v 1.4 2001-04-10 13:46:43 ivan Exp $ +$Id: README,v 1.5 2001-11-09 21:58:40 ivan Exp $ diff --git a/test.pl b/test.pl index aaa3715..fc1dfe5 100644 --- a/test.pl +++ b/test.pl @@ -33,7 +33,10 @@ sub input { print <, and an account on +the APP server. + +(i.e. stunnel -P none -c -d 8888 -r appsandbox.criticalpath.net:8889) END @@ -47,7 +50,7 @@ my $password = input "Enter your APP password: "; print "\n\n"; system("stty echo"); test 2, my $app = new Net::APP ( "$hostname:$port", - Debug => 1, + Debug => 0, ); test 3, $app->login( User => $user, Domain => $domain, @@ -59,7 +62,7 @@ test 6, $app->code == 0; $app->close(); undef $app; test 6, $app = new Net::APP ( "$hostname:$port", - Debug => 1, + Debug => 0, User => $user, Domain => $domain, Password => $password, -- 2.11.0