[aMail-checkins] CVS: new_project/docs/devel/Storage EMail.html,NONE,1.1 Storage.html,NONE,1.1

SourceForge Headquarters 1320 Columbia Street Suite 310 San Diego, CA 92101 +1 (858) 422-6466

Update of /cvsroot/amail/new_project/docs/devel/Storage
In directory usw-pr-cvs1:/tmp/cvs-serv15045/docs/devel/Storage

Added Files:
	EMail.html Storage.html 
Log Message:
Alpha 1 stage for aMail::Storage and aMail::Storage::EMail

--- NEW FILE ---
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
<TITLE>Developer's arena - aMail::Storage::EMail</TITLE>
<LINK REV="made" HREF="mailto:pro...@po...">
</HEAD>

<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
<BODY BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#000080" ALINK="#FF0000">
<TABLE WIDTH="80%">
 <TR>
  <TD>
   <IMG SRC="../doc/media/logo.gif" ALT="[aMail documentation]">
  </TD>

  <TD ALIGN="center">
   <H1>Developer's arena</H1>
   <H1>aMail::Storage::EMail</H1>
  </TD>
 </TR>
</TABLE>

<A NAME="__index__"></A>
<!-- INDEX BEGIN -->
<!--

<UL>

	<LI><A HREF="#name">NAME</A></LI>
	<LI><A HREF="#synopsis">SYNOPSIS</A></LI>
	<LI><A HREF="#description">DESCRIPTION</A></LI>
	<LI><A HREF="#methods">METHODS</A></LI>
	<UL>

		<LI><A HREF="#common usage">Common usage</A></LI>
		<LI><A HREF="#authgetmethods">authGetMethods</A></LI>
		<LI><A HREF="#authauthenticate">authAuthenticate</A></LI>
		<LI><A HREF="#foldercreate">folderCreate</A></LI>
		<LI><A HREF="#local_pam_conversation()"><CODE>local_pam_conversation()</CODE></A></LI>
	</UL>

</UL>
-->
<!-- INDEX END -->

<P>
<HR>
<H1><A NAME="name">NAME</A></H1>
<P>aMail::Storage::EMail - provides e-mail storage services</P>
<P>
<HR>
<H1><A NAME="synopsis">SYNOPSIS</A></H1>
<PRE>
    use SOAP::Lite;</PRE>
<PRE>
    my $handler = SOAP::Lite                                             
            -&gt; uri('aMail/Storage/EMail')                                             
            -&gt; proxy('<A HREF="http://">http://</A>'.$HOST .':'. $PORT .'/')
            -&gt; on_fault(sub { my($soap, $res) = @_; 
                  die ref $res ? $res-&gt;faultstring : $soap-&gt;transport-&gt;status, &quot;\n&quot;;
               });</PRE>
<P>
<HR>
<H1><A NAME="description">DESCRIPTION</A></H1>
<P>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.</P>
<P>
<HR>
<H1><A NAME="methods">METHODS</A></H1>
<P>
<H2><A NAME="common usage">Common usage</A></H2>
<P>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 !).</P>
<P>Usage:</P>
<PRE>
    use aMail::Storage::EMail;</PRE>
<PRE>
    my $authMethod = 'AMAIL';
    my $aMail_ID = 'bit-man';
    my $SID = obtainedThroguhPAM();
    my $name = &quot;myNewFolder&quot;;</PRE>
<PRE>
    ### ... handler craetion via new() ...
</PRE>
<PRE>

    die &quot;Crash !!!!\n&quot;
         unless  $handler-&gt;authAuthenticate( $authMethod, $aMail_ID, $SID)-&gt;result;</PRE>
<PRE>
    die &quot;Can't create folder $name\n&quot;
         unless  $handler-&gt;folderCreate( $name, $authMethod, $aMail_ID, $SID)-&gt;result;</PRE>
<P>Note: all methods return 0 (zero) on success, and not zero on error.</P>
<P>
<H2><A NAME="authgetmethods">authGetMethods</A></H2>
<P>Return the supported authentication methods as an array.</P>
<P>Usage:</P>
<PRE>
    use SOAP::Lite;
</PRE>
<PRE>

    ### ... handler craetion via new() ...</PRE>
<PRE>

    my @auth_methods = $handler-&gt;authGetMethods()-&gt;result;</PRE>
<P>
<H2><A NAME="authauthenticate">authAuthenticate</A></H2>
<P>Return a PAM_* error (see aMail::PAM module) in case of error, if
AMAIL authentication is used. Zero in case of success.</P>
<P>Returns 999 if an unsupported authentication method is passed.</P>
<P>Usage:</P>
<PRE>
    use SOAP::Lite;</PRE>
<PRE>
    my $authMethod = 'USR_PWD';
    my $user = 'bit-man';
    my $pass = 'secret';</PRE>
<PRE>
    ### ... handler craetion via new() ...</PRE>
<PRE>
    die &quot;Can't authenticate !!!!\n&quot;
         unless ! $handler-&gt;authAuthenticate( $authMethod, $user, $pass)-&gt;result;</PRE>
<P>
<H2><A NAME="foldercreate">folderCreate</A></H2>
<P>Creates a folder</P>
<P>Returns :</P>
<UL>
<LI><STRONG><A NAME="item_1_if_unsupported_uthentication_method">1 if unsupported uthentication method</A></STRONG><BR>

<LI><STRONG><A NAME="item_2_if_authentication_failed">2 if authentication failed</A></STRONG><BR>

<LI><STRONG><A NAME="item_3_if_the_folder_file_can%27t_be_locked">3 if the folder file can't be locked</A></STRONG><BR>

<LI><STRONG><A NAME="item_4_if_the_folder_already_exists">4 if the folder already exists</A></STRONG><BR>

</UL>
<P>Usage:</P>
<PRE>
    use SOAP::Lite;</PRE>
<PRE>
    my $name = 'myFolder';</PRE>
<PRE>
    ### ... handler craetion via new() ...
    ### ... authentication via authAuthenticate() ...</PRE>
<PRE>
    die &quot;Can't create folder $name !!!!\n&quot;
        unless ! $handler-&gt;folderCreate( $name, 
                                         $authMethod'}, @authParams )-&gt;result;</PRE>
<P>
<H2><A NAME="local_pam_conversation()"><CODE>local_pam_conversation()</CODE></A></H2>
<P>Default conversation routine used in PAM</P>
<P>Usage:</P>
<PRE>
  * in case PAM asks for a credential, message PAM_PROMPT_ECHO_OFF() or 
  PAM_PROMPT_ECHO_ON(), the value stored in the $SID scalar is passed to PAM
</PRE>
<PRE>

  * in case a PAM sends a PAM_ERROR_MSG(), it is stored in $problem</PRE>

<HR>
<TABLE WIDTH="80%">
 <TR>
  <TD>
   <IMG SRC="../doc/media/logo.gif" ALT="[aMail documentation]">
  </TD>

  <TD ALIGN="center">
   <H1>Developer's arena</H1>
   <H1>aMail::Storage::EMail</H1>
  </TD>
 </TR>
</TABLE>

</HTML>

--- NEW FILE ---
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
<TITLE>Developer's arena - aMail::Storage</TITLE>
<LINK REV="made" HREF="mailto:pro...@po...">
</HEAD>

<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
<BODY BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#000080" ALINK="#FF0000">
<TABLE WIDTH="80%">
 <TR>
  <TD>
   <IMG SRC="../doc/media/logo.gif" ALT="[aMail documentation]">
  </TD>

  <TD ALIGN="center">
   <H1>Developer's arena</H1>
   <H1>aMail::Storage</H1>
  </TD>
 </TR>
</TABLE>

<A NAME="__index__"></A>
<!-- INDEX BEGIN -->
<!--

<UL>

	<LI><A HREF="#name">NAME</A></LI>
	<LI><A HREF="#synopsis">SYNOPSIS</A></LI>
	<LI><A HREF="#description">DESCRIPTION</A></LI>
	<LI><A HREF="#first sight">First sight</A></LI>
	<LI><A HREF="#implementation details">Implementation details</A></LI>
	<LI><A HREF="#methods">METHODS</A></LI>
	<UL>

		<LI><A HREF="#new($)"><CODE>new($)</CODE></A></LI>
		<LI><A HREF="#authmethods()"><CODE>authMethods()</CODE></A></LI>
		<LI><A HREF="#open(%)"><CODE>open(%)</CODE></A></LI>
	</UL>

</UL>
-->
<!-- INDEX END -->

<P>
<HR>
<H1><A NAME="name">NAME</A></H1>
<P>aMail::Storage - provides storage management services</P>
<P>
<HR>
<H1><A NAME="synopsis">SYNOPSIS</A></H1>
<PRE>
    use aMail::Storage;</PRE>
<P>
<HR>
<H1><A NAME="description">DESCRIPTION</A></H1>
<P>The data storage module is an abstraction presented to the core (or 
anyone interfacing with it) to manage the storage of any persistent
data storage. This one must be emphasized, mainly because all volatile
info would be stored in memory storage (accessed through variables),
and not through the Data Storage. Albeith the generic name is retained
for simplicity, and because in a future implementation volatile info 
could be accessed also through this module (this could be very useful 
for data that must be encrypted).</P>
<P>To allow a generic use of this interface (and that allows the storage 
in any media) in a consistent way across any storage access method 
(plain text files, relational databases, etc.), hidding the implementation
details to the core.</P>
<P>
<HR>
<H1><A NAME="first sight">First sight</A></H1>
<P>The actions that all storage allow us to do are reading data from it 
and writing into it. Additionally there's security considerations to 
do, such as context creation (authentication), internal data structure
preparation, and so on.</P>
<P>Based on these generic assumptions, the next methods will be used:</P>
<UL>
<LI><STRONG><A NAME="item_open%3A_initiates_the_relationship_between_the_pro">open: initiates the relationship between the program and the data storage</A></STRONG><BR>

<LI><STRONG><A NAME="item_close%3A_closes_the_relationship">close: closes the relationship</A></STRONG><BR>

<LI><STRONG><A NAME="item_storage">read: reads data objects from the data storage (first usage)</A></STRONG><BR>

<LI><STRONG><A NAME="item_read_next%3A_reads_the_next_object_from_data_stora">read_next: reads the next object from data storage</A></STRONG><BR>

<LI><STRONG><A NAME="item_insert%3A_adds_tha_passsed_data_to_the_data_storag">insert: adds tha passsed data to the data storage</A></STRONG><BR>

<LI><STRONG><A NAME="item_update%3A_updates_the_passed_data_into_the_data_st">update: updates the passed data into the data storage</A></STRONG><BR>

</UL>
<P>Additionally the storage is separated into distinct storage classes, 
each one representing a conceptually different stored data but that 
could be implemented in the same media. Examples of these are 
configuration data, profile data and e-mails.</P>
<P>There exist the next the so called class ID, that identifies the storage
class, whcih are:</P>
<UL>
<LI><STRONG><A NAME="item_EMail%3A_E%2Dmail_store">EMail: E-mail store</A></STRONG><BR>

<LI><STRONG><A NAME="item_Config%3A_System_configuration_data_store">Config: System configuration data store</A></STRONG><BR>

<LI><STRONG><A NAME="item_Profile%3A_User_profile_storage">Profile: User profile storage</A></STRONG><BR>

</UL>
<P>
<HR>
<H1><A NAME="implementation details">Implementation details</A></H1>
<P>The class attributed to the storage objects is aMail::Storage.</P>
<P>As explained, each object has methods (open, close, read, write, etc.)
to manipulate data in the data storage, whose interface (and usage) is
defined in the following paragraphs.</P>
<P>A note, before starting with the methods, is that all methods return a
non-zero value that indicates an error; when this value is zero is a 
success code. The error meaning is specified in each method documentation.</P>
<P>
<HR>
<H1><A NAME="methods">METHODS</A></H1>
<P>
<H2><A NAME="new($)"><CODE>new($)</CODE></A></H2>
<P>This is the constructor, an returns a new handler for to the
specified storage class (mandatory parameter).</P>
<P>Usage :</P>
<PRE>
  use aMail::Storage;</PRE>
<PRE>
  my $handler = aMail::Storage-&gt;new( 'EMail' );
  die &quot;Crashhhh new() !!!\n&quot;  if ( ! defined $handler );</PRE>
<P>
<H2><A NAME="authmethods()"><CODE>authMethods()</CODE></A></H2>
<P>Each class ID can be implemented using different technologies (relational
database, LDAP repository, etc.), and using distinct authentication schemas.</P>
<P>The returned value is an array containing the preferred authentication methods,
ordered from most preferred to least preferred.</P>
<P>The supported authentication methods are:</P>
<UL>
<LI><STRONG><A NAME="item_NULL%3A_No_autentication_is_required">NULL: No autentication is required</A></STRONG><BR>

<LI><STRONG><A NAME="item_USER_PWD%3A_User_and_password">USER_PWD: User and password</A></STRONG><BR>

<LI><STRONG><A NAME="item_AMAIL%3A_Old_aMail_authentication_schema">AMAIL: Old aMail authentication schema</A></STRONG><BR>

</UL>
<P>Usage :</P>
<PRE>
  use aMail::Storage;</PRE>
<PRE>
  my $handler = aMail::Storage-&gt;new( 'EMail' );
  die &quot;Crashhhh new() !!!\n&quot;  if ( ! defined $handler );
</PRE>
<PRE>

  my @authMethods = authMethods();</PRE>
<P>
<H2><A NAME="open(%)"><CODE>open(%)</CODE></A></H2>
<P>Opens a connection to the desired storage class.</P>
<P>The parameters are passed  in a hash, and the key values corresopnd
to the desired parameters to be passed:</P>
<UL>
<LI><STRONG><A NAME="item_method">AUTH_METHOD : Authenticated method (described previously)</A></STRONG><BR>

<LI><STRONG><A NAME="item_AUTH_PARAMETERS_%3A_hash_containing_the_authentica">AUTH_PARAMETERS : hash containing the authentication credentials.
In case of NULL is an empty hash, if USER_PWD the keys USER and PASSWORD
must be passed, and if AMAIL the keys aMail_ID and SID will be used.</A></STRONG><BR>

The the code returned is the corresponding to each storage class.
<P></P></UL>
<P>Usage :</P>
<PRE>
  use aMail::Storage;</PRE>
<PRE>
  my $handler = aMail::Storage-&gt;new( 'EMail' );
  die &quot;Crashhhh new() !!!\n&quot;  if ( ! defined $handler );
</PRE>
<PRE>

  my @authMethods = $handler-&gt;authMethods();
  die &quot;Unknown authentication method\n&quot;
      if  ! AMAIL_Method_in_list( @authMethods );</PRE>
<PRE>
  die &quot;Can't authenticate\n&quot;
      unless  $handler-&gt;open( { AUTH_METHOD =&gt; 'AMAIL',
                              AUTH_PARAMETERS =&gt; { aMail_ID =&gt; 'bit-man', 
                                                   SID =&gt; '331868645' } } );</PRE>

<HR>
<TABLE WIDTH="80%">
 <TR>
  <TD>
   <IMG SRC="../doc/media/logo.gif" ALT="[aMail documentation]">
  </TD>

  <TD ALIGN="center">
   <H1>Developer's arena</H1>
   <H1>aMail::Storage</H1>
  </TD>
 </TR>
</TABLE>

</HTML>