4 use vars qw($VERSION $APP_VERSION @ISA $AUTOLOAD);
9 $VERSION = '0.1'; # $Id: APP.pm,v 1.1 1999-06-21 10:11:11 ivan Exp $
12 @ISA = qw(Net::Cmd IO::Socket::INET);
16 Net::APP - Critical Path Account Provisioning Protocol
23 $app = new Net::APP ( 'host:port',
26 Password => $password,
32 $app->ver( 'ver' => $Net::APP::APP_VERSION );
33 $app->login ( User => $user,
35 Password => $password,
38 $app->create_domain ( Domain => $domain );
39 $app->delete_domain ( Domain => $domain );
40 #etc. (see the Account Provisioning Protocol Developer's Guide, section 3.3)
43 $message = $app->message;
52 This module implements a client interface to Critical Path's Account
53 Provisioning Protocol, enabling a perl application to talk to APP servers.
54 This documentation assumes that you are familiar with the APP protocol
55 documented in the Account Provisioning Protocol Developer's Guide.
57 A new Net::APP object must be created with the I<new> method. Once this has
58 been done, all APP commands are accessed via method calls on the object.
64 =item new ( HOST:PORT [ , OPTIONS ] )
66 This is the constructor for a new Net::APP object. C<HOST> and C<PORT>
67 specify the host and port to connect to in cleartext. Typically this
68 connection is proxied via Safe Passage Secure Tunnel to Critical Path.
70 This method will connect to the APP server and execute the I<ver> method.
72 I<OPTIONS> are passed in a hash like fastion, using key and value pairs.
75 I<Timeout> - Set a timeout value (defaults to 120)
77 I<Debug> - Enable debugging information (see the debug method in L<Net::Cmd>)
79 I<User>, I<Domain>, I<Password> - if these exist, the I<new> method will also
80 execute the I<login> method automatically.
82 If the constructor fails I<undef> will be returned and an error message will be
89 my $class = ref($proto) || $proto;
90 my ($host, $port) = split(/:/, shift);
93 my $self = $class->SUPER::new( PeerAddr => $host,
96 Timeout => defined $arg{Timeout}
103 $self->debug(exists $arg{Debug} ? $arg{Debug} : undef);
105 my $response = $self->_app_response;
106 unless ( $self->message =~ /^HI APP/ ) {
107 $@ = $self->code. " ". $self->message;
112 $self->ver( 'ver' => $APP_VERSION );
113 unless ( $self->ok ) {
114 $@ = $self->code. " ". $self->message;
119 if ( exists $arg{User} && exists $arg{Domain} && exists $arg{Password} ) {
120 $self->login( User => $arg{User},
121 Domain => $arg{Domain},
122 Password => $arg{Password},
124 unless ( $self->ok ) {
125 $@ = $self->code. " ". $self->message;
144 See the Account Provisioning Protocol Developer's Guide for details. Commands
145 need not be in upper case, and options are passed in a hash-like fashion, as
146 a list of key-value pairs.
148 All options return a reference to a list containing the lines of the reponse,
149 or I<undef> upon failure. The first line is parsed for the status code and
150 message. You can check the status code and message using the normal Net::Cmd
151 I<message>, I<code>, I<ok>, and I<status> methods.
153 Only the get_num_domain_mailboxes, get_mailbox_availability and
154 get_mailbox_status methods currently return any additional response
155 information. No attempt is (yet) made to parse this data.
159 Returns the text message returned from the last command.
163 Returns the response code from the last command (see the Account Provisioning
164 Protcol Developer's Guide, chapter 4). The code `-1' is used to represent
165 unparsable output from the APP server, in which case the entire first line
166 of the response is returned by the I<messsage> method.
170 Returns true if the last code was an acceptable response.
181 Since the APP protocol has no concept of a "most significant digit" (see
182 L<Net::Cmd/status>), this is a noisy synonym for I<code>.
187 carp "status method called (use code instead)";
194 my $command = $AUTOLOAD;
196 $self->_app_command( $command, @_ );
197 $self->_app_response;
202 =head1 INTERNAL METHODS
204 These methods are not intended to be called by the user.
208 =item _app_command ( COMMAND [ , OPTIONS ] )
210 Sends I<COMMAND>, encoded as per the Account Provisioning Protocol Developer's
211 Guide, section 3.2. I<OPTIONS> are passed in a hash like
212 fashion, using key and value pairs.
221 $self->command ( uc($command),
222 map "\U$_\E=\"". _quote($arg{$_}). '"', keys %arg
224 $self->command( '.' );
229 Gets a response from the server. Returns a reference to a list containing
230 the lines, or I<undef> upon failure. You can check the status code and message
231 using the normal Net::Cmd I<message>, I<code>, I<ok>, and I<status> methods.
237 my $lines = $self->read_until_dot;
238 if ( $self->debug ) {
239 foreach ( @{$lines}, ".\n" ) { $self->debug_print('', $_ ) }
241 if ( $lines->[0] =~ /^(OK|ER)\s+(\d+)\s+(.*)$/ ) {
242 warn 'OK response with non-zero status!' if $1 eq 'OK' && $2;
243 warn 'ER response with zero status!' if $1 eq 'ER' && ! $2;
244 $self->set_status ( $2, $3 );
246 $self->set_status ( -1, $lines->[0] );
253 =head1 INTERNAL SUBROUTINES
255 These subroutines are not intended to be called by the user.
261 Doubles double quotes.
263 This is untested for strings containing consecutive double quotes.
269 $string =~ s/\"/\"\"/g; #consecutive quotes?
277 Ivan Kohler <ivan-netapp@sisd.com>.
279 This module is not sponsored or endorsed by Critical Path.
283 Copyright (c) 1999 Ivan Kohler.
284 Copyright (c) 1999 Silicon Interactive Software Design.
286 This program is free software; you can redistribute it and/or modify it under
287 the same terms as Perl itself.
291 $Id: APP.pm,v 1.1 1999-06-21 10:11:11 ivan Exp $
293 This module currently implements APP v2.1, as documented in the Account
294 Provisioning Protocol Developers Guide v2.1.
298 The Account Provisioning Protocol Developer's Guide is not publicly available.
300 It appears that Safe Passage Secure Tunnel establishes a standard SSL
301 connection. It should be possible to use Net::SSLeay and connect to the APP
304 Sending values with consecutive double quote characters is untested.
306 The get_num_domain_mailboxes, get_mailbox_availability and get_mailbox_status
307 methods currently return response information. No attempt is (yet) made to
312 Critical Path <http://www.cp.net/>,
313 Safe Passage Secure Tunnel <http://www.c2.net/products/spst>,
314 L<Net::SSLeay>, L<Net::Cmd>, perl(1).
319 Revision 1.1 1999-06-21 10:11:11 ivan