aMail::Common Developer's arena

NAME

aMail::Common - provides the common subroutines for aMail operation

SYNOPSIS

    use aMail::Common

DESCRIPTION

This modules provides the common subroutines for aMail operation that are in the miscellaneous category, and are not placed in other aMail modules suc as Sec, L10N, etc. Also contains the settings for aMail customization.

SETTINGS

• time_til_expire: Maximum session legth, in seconds
  
• time_off_from_NY: The number of seconds the server this runs on is behind NY time
  
• skin: Defines the skin to be used. In this version (v2.1) the skin changes only the images.
  
• man_URL: Manual pages URL location
  
• skin_URL: Skins URL location
  
• dir_URL: cgi-bin (Perl scripts) directory path
  
• db_path: User data directory path
  
• img_URL: Images base (modified on language basis) URL location
  
• lang: Preferred system language (each use can change its language using user info page).
  
• spellpath: Path to ispell/aspell, blank will disable spellcheck feature
  
• spell_dictionary: Path to ispell/aspell dictionaries based on language
  
• info_color: colour used for informative texts
  
• background_color: coulour used for background
  
• caption_color: colour used for caption texts
  
• problem_color: colour used for problem texts
  
• reserved_files: list of filenames reserved in the upload area (not to be shown)
  

METHODS

Get_language($amail_ID)

Retrieves the user preferred language specified by the amail_ID passed as parameter. This one can be set in the Info User page. If it has not been specifid, or it's blank, the system language is returned.

Usage:

  use aMail::Common;
  $language = Get_language($amail_ID);

Set_location()

Returns the list of location variables and other aMail related info for the user specified in amail_ID. If it has not been specifid the system ID is used.

Usage :

  use aMail::Common;
  ($dir_URL, $db_path, $img_URL, $skin_URL, $man_URL, $VERSION) = Set_location( amail_ID );

Server_time()

Returns the time the server is behind NY time.

Usage:

  use aMail::Common;
  $SrvTime = Server_time();

Check_session( amail_ID, Session_ID )

Checks the correspondence between the amail ID and the session ID. Returns the time offset if all is right (no expired session, correct session ID, etc.). If something is wrong returns to the login scfreen (take a look at Go_login() ).

Usage:

  use aMail::Common;
  $time_offset = Check_session( $amail_ID, $Session_ID );

Go_login( status )

Generates the login page and ends the session. This page is used ONLY by Check_session().

FIX_ME: It's a good practice to store it in another module and make it privated or something in the style (anonymous sub ??).

Tha status are stored in login.pl and can be one of :

1. ``Your account has been created''
   
2. ``Please re-login to aMail''
   
3. ``Your session has expired, please re-login to aMail''
   
4. ``You have been logged out. You must re-enter your password to check mail''
   

Usage :

  use aMail::Common;
  Go_login( $status );

Caption()

Prints the one line table at the top of each screen.

Usage:

  use aMail::Common;
  Caption();

Parse_header( ref_to_header )

Parses a message (passed as a ference to an array containing the headers) and returns them parsed as a hash, containing one element per head.

Usage:

  aMail::Common;

  open( FH, $message_file );
  @line = <FH>;
  close FH;

  $i=0;
  while ($line[$i] ne "\n") { $i++; }   # Find out where header ends
  splice @line, $i;                     # Throw away the body
  chomp @line;                            # take off the <cr> at the end of line

  %header = Parse_header( \@line );     # Parse the header

Parse_email_date( date )

Converts the given date, in e-mail format, to epoch seconds (take a look at Perl manual pages to know what ``epoch seconds'' mean).

Usage:

  use aMail::Common;

  # Parse the header
  %header = Parse_header( \@line );

  # Convert the time to epoch seconds
  $epochtime=Parse_email_date($header{'date'});

Show_message_line( folder_file_line, message_count, time_offset, marked)

Prints the line corresponding to the info for the message specified. It's used in the folder contents page. Returns the message counter (message_count parameter) incremented by one. The parameters passed are :

• folder_file_line: line consisting of the corresponding line in the folder file (read, from, etc. separated by '|').
  
• message_count: message number counter
  
• time_offset: time offset
  
• marked: mark that shows the previous position in main page (this avoids the need to scroll from the beginning of the page)
  

Usage:

  use aMail::Common;
  Show_message_line( $folder_file_line, $message_count, $time_offset, $marked );

fmtdate( epoch_seconds )

Converts Epoch seconds into an e-mail date string. Is the inverse function of Parse_email_date(); (take a look at Perl manual pages to know what ``epoch seconds'' mean).

Usage:

  use aMail::Common;
  $date_foratted = fmtdate($date_in_epoch);

Seek_search( ref_mess_nums, ref_folder_info_hash, ref_messages, previous_index, direction )

FIX_ME: apparently it's not used

Make_undo( amail_ID )

Make a couple of folders file backups, since this file is pretty important. Returns a file handle to the open folders file.

Usage:

  use aMail::Common;
  $MAILBOX = Make_undo($amail_ID);

Rename_undo( amail_ID )

Makes arrangements to the folder file state, in case a modification must be reverted (undo).

Usage:

  use aMail::Common;
  Rename_undo($amail_ID);

FileCopy( original_file_path, copy_file_path );

Makes a copy of the file established in original_file_path in the path indicated by copy_file_path (emulates basic Unix 'cp' functionality)

Usage:

  use aMail::Common;
  $original = "/home/user1/.profile";
  $backup = "/home/user1/.profile.backup";
  FileCopy( $original, $backup );

Check_folder_name( folder )

Checks for the existence of the passed folder name, and for some restrictions (filename lenght, existence, etc.). Returns an HTML fragment according to the happened error (a null string in case of no error).

Usage:

  use aMail::Common;

  $FolderName = "MyFolder";

  print << HTML1
  <HTML>
  <HEAD>
  <TITLE>Test HTML</TITLE>
  <HEAD>
  <BODY>
  Testing for foldername "$FolderName".
  <P>
  HTML1

  print Check_folder_name( $FolderName );

  print << HTML2
  </BODY>
  </HTML>
  HTML2

Put_message (time, message, ref_messages )

Puts the messages in the folder in date order. The arguments are the message time (in epoch format), the message itself and a reference to the array containing the information stored in the folders file.

Usage:

  use aMail::Common;
  Put_message($epochtime, $this_mess,\@messages);

Get_head( ref_message_array, message_line_number)

Extract the header from the message whose reference is passed in ref_message_array. FIX_ME: message_line_number seems to be a nonsense unless its passed a value equals to zero. Instead it could serve as an accumulator for headers line numbers. Returns a reference to an array containing the headers uninterpreted (one line per array element) and the message_line_number passed added in the lines that this message contains.

WARNING !!! Get_head destroys the array whose reference is passed under ref_message_array

Usage:

  use aMail::Common;

  $message_line_number = 0;

  open( FH, "$db_path/$amail_ID/$msg_number");
  @message = <FH>;
  close FH;
  ($ref_header, $message_line_number) = Get_head(\@message,$message_line_number);
  print "The header has $message_line_number lines, and contains: \n @$ref_header";

Get_file_list( amail_ID )

Obtains the file list, as an array, for the uploads area specified by the user corresponding to aMail_ID.

Usage :

  use aMail::Common;
  @file_list = Get_file_list( $amail_ID );

Get_spellcheck()

Returns the path to the spelling tool ispell/aspell and dictionary for a given language

Usage :

  use aMail::Common;
  ($spellpath, $dictionary ) = Get_spellcheck( $lang );

Get_language_list()

Returns the list of languages in the dictionary list

Usage :

  use aMail::Common;
  (@languages ) = Get_language_list( );

aMail::Common Developer's arena