aMail::Common Developer's arena

NAME

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

SYNOPSIS

    use TRex::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_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)
  
• logConfigFile: filename for logging configuration file
  

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 TRex::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 TRex::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 TRex::Common;
  $SrvTime = Server_time();

Time_offset( $amail_ID )

Returns the time offset between server and user time.

Usage:

  use TRex::Common;
  $time_offset = Time_offset( $amail_ID );

process_pam_error( $pam_error_code )

pam_conversation()

Default conversation routine used in PAM

Usage:

  * in case PAM asks for a credential, message PAM_PROMPT_ECHO_OFF() or 
  PAM_PROMPT_ECHO_ON(), the value stored in the global variable 
  $amail_passwd is passed to PAM

  * in case a PAM sends a PAM_ERROR_MSG(), it is stored in $problem

Caption()

Prints the one line table at the top of each screen. The prerequisite is that a variable $lang, indicating the actual language used, is allocated in the 'main' script script. Usage:

  use TRex::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:

  TRex::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 TRex::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 TRex::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 TRex::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 TRex::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 TRex::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 TRex::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 TRex::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 TRex::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 TRex::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 TRex::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 TRex::Common;
  ($spellpath, $dictionary ) = Get_spellcheck( $lang );

Get_language_list()

Returns the list of languages in the dictionary list

Usage :

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

initLogger($$)

Returns the logger (for a logger class) and is returned in the reference passed as the second argument.

Usage :

  use TRex::Common;
  my $logger;
  initLogger( 'TRex.Core', \$logger );

aMail::Common Developer's arena