- updated for APP version 3.3NET_APP_0_02

- 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

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<HOST> and C<PORT>
 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<ver> 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<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
-I<message>, I<code>, I<ok>, and I<status> methods.
+Unless noted below, all commands return a reference to a list containing the
+lines of the reponse, or I<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 I<message>, I<code>, I<ok>, and I<status> 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<messsage> 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-netapp_pod@sisd.com>.
+Ivan Kohler <ivan-netapp_pod@420.am>.
 
 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 <http://www.cp.net/>,
-Safe Passage Secure Tunnel <http://www.c2.net/products/spst>,
-L<Net::SSLeay>, L<Net::Cmd>, 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 <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>,
+L<IO::Socket>, L<Net::Cmd>, 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: <http://www.sisd.com/netapp>
 
 Ivan Kohler <ivan-netapp_readme@420.am>
 
-$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 <<END;
 In order to test Net::APP, you need a cleartext APP server available, i.e. a
-Safe Passage tunnel, and an account on the APP server.
+Safe Passage or tunnel or Stunnel <http://www.stunnel.org>, 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,