aMess a Messaging Program

Implementation details

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.

A note, before starting with the methods, is that all methods return a value, which indicates an error when this values is undefinde (undef). The error number and text are stored in the variables $Error and $ErrorText. The text message is not language dependent, because it's intended for internal use.

auth_methods()

@return = auth_methods( { CLID => $ClassID } );

• CLID: Class ID. It's a mandatory parameter, and let us ask to the desired storage implementation for its preferred authentication methods.
• return: returned data in aRDF, containing : METHODS: an array of preferred authentication methods, ordered from most preferred to least preferred (1).

• NULL: No autentication is required
• USER_PWD: User and password
• AMAIL: Old aMail authentication schema

open()

$handle = open( { AUTH_METHOD => $auth_method,
                  AUTH_PARAMETERS => %auth_parameters,
                  CLID => $ClassID       } );

• auth_method: method to be used for authentication (obtained using the auth_methods() method)
• CLID: Class ID. It's a mandatory parameter, and let us bind to the desired storage implementation.
• auth_parameters: hash containing the parameters for authentication, that are: USER, PASSWORD: used to containg the USER and PASSWORD

In this implementation the class ID will be the name of the clase that implements the corresponding storage class as follows:

CLass ID    --->   Implemented in class

EMail       --->   aMail::Storage::EMail
Profile     --->   aMail::Storage::Profile
Config      --->   aMail::Storage::Config

close()

$handle->close();

read()

$ref_data = $handle->read( { LOCATOR => %aQL } )

• LOCATOR: used to locate the desired piece of data in the storage, and is formatted using aQL (aMail Query Language).
• ref_data: a reference to the data retrieved. It's storage class dependant, and to avoid aMail coding dependence on these data types and structure no interpretation should be attempted, instead the read_next() method should be used to return each of the multiple objects, that match the LOCATOR cirteria, in the aRDF format.

read_next()

%return = $handle->read_next( { DATA => $ref_data } );

• ref_data: a reference to the data retrieved (obtained through read)
• return: values returned in aRDF

insert() or update()

$handle->insert( { DATA => %Data } );
$handle->update( { DATA => %Data } );

• DATA: is the intended data to be added/updated in the corresponding storage class. It's coded in aRDF, to minimize dependences with the underlying modules

Example of usage

#!/usr/bin/perl
#
# This example is for use when the e-mail storage mechanism uses
# user/password athentication schema (such as many RDBMS do it).

use aMail::Storage;

######
## Queries about the accepted authentication methods
######

@auth_method = auth_methods( { CLID => 'EMail' } );

print "auth_methods failed :-(\nError: $ErrorText\n" 
    if ( ! defined @auth_method  );

######
## Look for User/password authentication method
######

foreach ( @auth_method ) {
    $ok = 1     if ( $_ eq 'USER_PWD' );
}

die "No User/Password authentication :-(\n"  
    if ( ! $ok );

######
## Create a connection
######

%auth_parameters = ( 'USER' => 'MyUser',
                     'PASSWDORD' => 'MyPassword'  );

$handle = open( { AUTH_METHOD => 'USER_PWD',
                  AUTH_PARAMETERS => %auth_parameters,
                  CLID => 'EMail'       } );

print "open failed :-(\nError: $ErrorText\n" 
    if ( ! defined $handle  );

######
## Queries the e-mail storage area
######

%aQL = ( 'FOLDER' => 'Sent',
         'SUBJECT' => 'aMail-devel');

$ref_data = $handle->read( { LOCATOR => %aQL } )

print "read failed :-(\nError: $ErrorText\n" 
    if ( ! defined $ref_data  );

######
## Read each record (??)
######

while ( %return = $handle->read_next( { DATA => $ref_data } ) ) {
    foreach ( keys %return ) {
        print "$_: " . $return{$_} . "\n";
    }
    print "-" x 50 . "\n";
}

######
## Bye, bye storage !!!
######

$handle->close();

aMess a Messaging program