Developer's arena

TRex::Storage::EMail

NAME

TRex::Storage::EMail - provides e-mail storage services

SYNOPSIS

    use SOAP::Lite;

    my $handler = SOAP::Lite                                             
            -> uri('TRex/Storage/EMail')                                             
            -> proxy('http://'.$HOST .':'. $PORT .'/')
            -> on_fault(sub { my($soap, $res) = @_; 
                  die ref $res ? $res->faultstring : $soap->transport->status, "\n";
               });

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.

METHODS

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 TRex::Storage::EMail;

    my $authMethod = 'AMAIL';
    my $aMail_ID = 'bit-man';
    my $SID = obtainedThroguhPAM();
    my $name = "myNewFolder";
    my @authParams;

    push @authParams, $aMail_ID;
    push @authParams, $SID;

    ### ... handler creation via new() ...

    die "Crash !!!!\n"
         unless  $handler->authAuthenticate( $authMethod, @authParams)->result;

    die "Can't create folder $name\n"
         unless  $handler->folderCreate( $name, $authMethod, @authParams)->result;

Returned values

All the methods return 0 (zero) on success, and not zero on error (each error meaning is specified in each function documentation). The common error numbers, to all functions, are :

1, internal error
2, NOT USED
3, unsupported authentication method

`authGetMethods()`

Return the supported authentication methods as an array.

Usage:

    use SOAP::Lite;

    ### ... handler creation via new() ...

    my @auth_methods = $handler->authGetMethods()->result;

`authAuthenticate($@)`

Return a PAM_* error (see TRex::PAM module) in case of error, if AMAIL authentication is used. Zero in case of success.

Returns 3 if an unsupported authentication method is passed.

Usage:

    use SOAP::Lite;

    my $authMethod = 'USR_PWD';
    my $user = 'bit-man';
    my $pass = 'secret';
    my @authParams;

    push @authParams, $user;
    push @authParams, $pass;

    ### ... handler creation via new() ...

    die "Can't authenticate !!!!\n"
         unless ! $handler->authAuthenticate( $authMethod, @authParams)->result;

`folderCreate($@)`

Creates a folder

Returns :

11, if the folder already exists

Usage:

    use SOAP::Lite;

    my $name = 'myFolder';

    ### ... handler creation via new() ...
    ### ... authentication via authAuthenticate() ...

    die "Can't create folder $name !!!!\n"
        unless ! $handler->folderCreate( $name, 
                                         $authMethod, @authParams )->result;

`folderDestroy($@)`

Erases a folder

Returns :

21, if the folder isn't empty
22, if the folder doesn't exists

Usage:

    use SOAP::Lite;

    my $name = 'myFolder';

    ### ... handler creation via new() ...
    ### ... authentication via authAuthenticate() ...

    die "Can't delete folder $name !!!!\n"
        unless ! $handler->folderDestroy( $name, 
                                          $authMethod, @authParams )->result;

`folderRename($$@)`

Renames a folder

Returns :

31, if the folder (new name) already exists
32, if the folder (old name) doesn't exists

Usage:

    use SOAP::Lite;

    my $name = 'myFolder';

    ### ... handler creation via new() ...
    ### ... authentication via authAuthenticate() ...

    die "Can't delete folder $name !!!!\n"
        unless ! $handler->folderDestroy( $name, 
                                          $authMethod, @authParams )->result;

`folderRetrieve($@)`

Retrieves a folder contents

Returns :

41, if the folder doesn't exists

... and a list with the MIDs (Message IDs) contained in the folder and its attributes with the next format :

element 0: Message read (1) or not (0)
element 1: Sender address
element 2: Subject
element 3: Perl timestamp (FIX IT !!!)
element 4: Message ID
element 5: If it has an attachment (1) or not (0)
element 6: Size in bytes

... and so on

Usage:

    use SOAP::Lite;

    my $name = 'myFolder';

    ### ... handler creation via new() ...
    ### ... authentication via authAuthenticate() ...

    die "Can't retrieve folder $name contents !!!!\n"
        unless ! $handler->folderRetrieve( $name, 
                                          $authMethod, @authParams )->result;

`folderList(@)`

Retrieves the repository contents (folder list).

Returns the errors as listed in ``return values'' ... and an array with the folders contained in the repositorty and its attributes, all in an array with the next format:

element 0: folder name
element 1: number of msgs. in folder
element 2: number of un-read messages
element 3: size in bytes
element 4: folder ID (FID)

... and so on

Usage:

    use SOAP::Lite;

    my $name = 'myFolder';

    ### ... handler creation via new() ...
    ### ... authentication via authAuthenticate() ...

    my ($error, @folder) = $handler->folderList( $authMethod,
                                                 @authParams )->paramsall;

    die "Crashhhh Folder listing ($error) !!!\n"    if $error;

    foreach ( @folder )  {
        print "$_, ";
        $i++;
        if ( $i == 4 ) {
            print "\n";
            $i = 0;
        }
    }

`msgStore(@)`

Retrieves the repository contents (folder list).

Returns the errors as listed in ``return values'' ... and the MID assigned to the message

Usage:

    use SOAP::Lite;

    my $folderName = 'myFolder';
    my $msg = "Subject: Hi!\nHi Bobby\n";

    ### ... handler creation via new() ...
    ### ... authentication via authAuthenticate() ...

    my ($error, $MID) = $handler->msgStore( $folderName, $msg,
                                            $authMethod, @authParams )->paramsall;

    die "Crashhhh message storage ($error) !!!\n"    if $error;

`msgRetrieve($@)`

Retrieves a message

Returns :

41, if the message doesn't exists

... and the message specified by the MID parameter

Usage:

    use SOAP::Lite;

    ### ... handler creation via new() ...
    ### ... authentication via authAuthenticate() ...

    ($error, $message) = $handler->msgRetrieve( $MID, 
                                    $authMethod, @authParams )->paramsall;

    die "Can't retrieve message $MID !!!!\n"  if $error;

`msgDelete($@)`

Deletes the messages passed in the MID list (it must be in the Trash folder). The MID list contains a comma separated MIDs to be deleted.

The errors returned are:

41, the message doesn't exists
42, the message isn't in the Trash folder
43, the message can't be deleted

In case of a general error it is returned in the first variable (scalar) with an empty array as a second return value. If some of the messaged can be deleted (and some not) the global error is zero, and the error for each MID is returned as a list of errors, each one corresponding to each message in the MID list.

Usage:

    use SOAP::Lite;

    ### ... handler creation via new() ...
    ### ... authentication via authAuthenticate() ...

    $MIDList = "234235,289645,178923";
    ($globalError, @error) = $handler->msgDelete( $MIDList, 
                                                              $authMethod, @authParams )->paramsall;

    die "A global error ocurred trying to delete $MIDList"   if $globalError;

    my @MID = split ',', $MIDList;
    for ( my $i=0; $i < @error; $i++) {    
        print "Can't delete message $MID[$i] !!!!\n"  if $error[$i];
    };

`msgMove($$@)`

Moves messages to a new folder

Returns :

34, if the destination folder doesn't exists

In case of a general error it is returned in the first variable (scalar) with an empty array as a second return value. If some of the messaged can be moved (and some not) the global error is zero, and the error for each MID is returned as a list of errors, each one corresponding to each message in the MID list.

Usage:

    use SOAP::Lite;

    ### ... handler creation via new() ...
    ### ... authentication via authAuthenticate() ...

    $MIDList = "234235,289645,178923";
    $toFolderName = "zafarrancho";

    ($globalError, @error) = $handler->msgMove( $MIDList, $toFolderName,
                                    $authMethod, @authParams )->result;

    die "A global error ocurred trying to move $MIDList to folder $toFolderName"   if $globalError;

    my @MID = split ',', $MIDList;
    for ( my $i=0; $i < @error; $i++) {    
        print "Can't move message $MID[$i] !!!!\n"  if $error[$i];
    };

`msgTag($$@)`

Tags a message as read or not read

Returns no value at all (FIX ME !!)

Usage:

    use SOAP::Lite;

    ### ... handler creation via new() ...
    ### ... authentication via authAuthenticate() ...

    $error = $handler->msgTag( $MID, $hasBeenRead,
                               $authMethod, @authParams )->result;

    die "Can't mark message $MID as read !!!!\n"  if $error;

`search($$$@)`

Searches for messages in the $folderList that contains the text passed in $textToSearch

Returns an array with the MIDs (Message IDs) that satisfy the search criteria

Usage:

    use SOAP::Lite;

    ### ... handler creation via new() ...
    ### ... authentication via authAuthenticate() ...

    ($error, @MID) = $handler->search( $textList, $folderList,
                               $authMethod, @authParams )->result;

    die "Error while trying to search :-(\n"  if $error;

`close()`

Closes the relationship with the the e-mail storage.

Usage:

    use SOAP::Lite;

    ### ... handler creation via new() ...
    ### ... storage handling and stuff ...

    my $error = $handler->close( $authMethod, @authParams )->result;