[aMail-checkins] CVS: new_project/program/lib/Storage EMail.pm,1.5,1.6

[Victor A. R. <bi...@us...>]

Update of /cvsroot/amail/new_project/program/lib/Storage
In directory usw-pr-cvs1:/tmp/cvs-serv26627/program/lib/Storage

Modified Files:
	EMail.pm 
Log Message:
Documentation added to aMail::Storage y aMail::Storage::EMail (pod, of course !!)


Index: EMail.pm
===================================================================
RCS file: /cvsroot/amail/new_project/program/lib/Storage/EMail.pm,v
retrieving revision 1.5
retrieving revision 1.6
diff -C2 -r1.5 -r1.6
*** EMail.pm	16 Aug 2002 21:49:55 -0000	1.5
--- EMail.pm	23 Aug 2002 00:02:49 -0000	1.6
***************
*** 3,6 ****
--- 3,31 ----
  package aMail::Storage::EMail;
  
+ =pod
+ 
+ =head1 NAME
+ 
+ aMail::Storage::EMail - provides e-mail storage services
+ 
+ =head1 SYNOPSIS
+ 
+     use SOAP::Lite;
+ 
+     my $handler = SOAP::Lite                                             
+             -> uri('aMail/Storage/EMail')                                             
+             -> proxy('http://'.$HOST .':'. $PORT .'/')
+             -> on_fault(sub { my($soap, $res) = @_; 
+                   die ref $res ? $res->faultstring : $soap->transport->status, "\n";
+                });
+ 
+ =head1 DESCRIPTION
+ 
+ Basically allows the e-mail store in a flat folder based structure, that
+ doesn't allow the creation of folders containing folders, where each
+ e-mail must be asociated (or stored into) an existing folder.
+ 
+ =cut
+ 
  use Exporter;
  @ISA = ('Exporter');
***************
*** 11,24 ****
  use aMail::Sec;
  
  ##
  ##  Pending issues:
  ##
! ##  1.- The returned values for each fucntion are not defined
  
  
! ################ Settings
! my @acceptedMethods = [ 'AMAIL' ];
! my $db_path = '/home/bit-man';
! #########################################
  
  my $SID = "";
--- 36,79 ----
  use aMail::Sec;
  
+ 
+ ################ Settings
+ my @acceptedMethods = [ 'AMAIL' ];
+ my $db_path = '/home/bit-man/initialize_user';
+ #########################################
+ 
  ##
  ##  Pending issues:
  ##
! ##  - authAuthenticate returns a 999 error when no invalid auth
! ##    it's not a stylish error code, anyway (and can be overlapped
! ##    by a module that returns a 999 code)
  
+ =pod
  
! =head1 METHODS
! 
! =head2 Common usage
! 
! All methods, except authGetMethods, expect the parameters "authentication
! method" (authMethod), and the authentication parameters. It should be enough
! to pass them once, but no persistence mechanism has been implemented (yet !).
! 
! Usage:
! 
!     use aMail::Storage::EMail;
! 
!     my $authMethod = 'AMAIL';
!     my $aMail_ID = 'bit-man';
!     my $SID = obtainedThroguhPAM();
!     my $name = "myNewFolder";
! 
!     die "Crash !!!!\n"
!          unless  $handler->authAuthenticate( $authMethod, $aMail_ID, $SID)->result;
! 
!     die "Can't create folder $name\n"
!          unless  $handler->folderCreate( $name, $authMethod, $aMail_ID, $SID)->result;
! 
! Note: all methods return 0 (zero) on success, and not zero on error.
! =cut
  
  my $SID = "";
***************
*** 26,33 ****
--- 81,122 ----
  
  
+ =head2 authGetMethods
+ 
+ Return the supported authentication methods as an array.
+ 
+ Usage:
+ 
+     use SOAP::Lite;
+ 
+     my @auth_methods = $handler->authGetMethods()->result;
+ 
+ =cut
+ 
  sub authGetMethods() {
      return @acceptedMethods;
  }
  
+ 
+ =head2 authAuthenticate
+ 
+ Return a PAM_* error (see aMail::PAM module) in case of error, if
+ AMAIL authentication is used. Zero in case of success.
+ 
+ Returns 999 if an unsupported authentication method is passed.
+ 
+ Usage:
+ 
+     use SOAP::Lite;
+ 
+     my $authMethod = 'USR_PWD';
+     my $user = 'bit-man';
+     my $pass = 'secret';
+ 
+     die "Can't authenticate !!!!\n"
+          unless  $handler->authAuthenticate( $authMethod, $user, $pass)->result;
+ 
+ 
+ =cut
+ 
  sub authAuthenticate() {
      my $self = shift;
***************
*** 42,47 ****
  		      };
  		      
!     ## I'm sorry, no valid authentication method;
!     return 0;
  }
  
--- 131,136 ----
  		      };
  		      
!     ## I'm sorry, invalid authentication method;
!     return 999;
  }
  
***************
*** 54,58 ****
      my $aMail_ID =  $param[0];
      
!     return 0    if ( ! defined handlePAM( $aMail_ID ) );
      print "Folder creation: $folder\n";
      
--- 143,147 ----
      my $aMail_ID =  $param[0];
      
!     return 0    if ( !  handlePAM( $aMail_ID ) );
      print "Folder creation: $folder\n";
      
***************
*** 183,202 ****
      $problem = ( ref($sec_handle) ? PAM_SUCCESS() : ref($sec_handle) );
      print "Problem: $problem\n"; 
!     return undef    unless ( $problem == PAM_SUCCESS() );
  
      print "Authenticate\n";
      $problem = $sec_handle->pam_authenticate();
!     return undef    unless ( $problem == PAM_SUCCESS() );
  
      print "Mgmt\n";
      $problem = $sec_handle->pam_acct_mgmt();
!     return undef    unless ( $problem == PAM_SUCCESS() );
  
      print "Open_session\n";
      $problem = $sec_handle->pam_open_session();
!     return undef    unless ( $problem == PAM_SUCCESS() );
      
      print "END\n";
!     return 1;
  }
  1;
--- 272,291 ----
      $problem = ( ref($sec_handle) ? PAM_SUCCESS() : ref($sec_handle) );
      print "Problem: $problem\n"; 
!     return $problem    unless ( $problem == PAM_SUCCESS() );
  
      print "Authenticate\n";
      $problem = $sec_handle->pam_authenticate();
!     return $problem    unless ( $problem == PAM_SUCCESS() );
  
      print "Mgmt\n";
      $problem = $sec_handle->pam_acct_mgmt();
!     return $problem    unless ( $problem == PAM_SUCCESS() );
  
      print "Open_session\n";
      $problem = $sec_handle->pam_open_session();
!     return $problem    unless ( $problem == PAM_SUCCESS() );
      
      print "END\n";
!     return 0;
  }
  1;