wiki:Documentation/Reference

Version 1 (modified by AmigaPhil, 12 months ago) (diff)

1st edit - Link fixes coming next

Languages:


Reference

Install structure

In the program directory for YAM the following files and directories will be found:

  • YAM The program itself
  • YAM.info The program icon
  • Resources/
    • Themes/ Themes used by YAM along its Graphical User Interface
    • Gallery/ Pictures of people mentioned in the address book
    • Certificates/
    • Spamfilters/
  • Rexx/ ARexx programs for YAM
  • incoming/ the incoming mailbox directory
  • outgoing/ the outgoing mailbox directory
  • sent/ the directory for sent mail
  • trash/ the directory for mail marked for deletion

Message storage

Each message is saved as a separate file of which the filename is constructed by encoding certain information about the mail (date, status, etc) using the Base64 standard encoding. The resulting name is compatible to any filesystem.

Example: QvZgMAAFe4M=.001,RA

QvZgMAAFe4M= Base64 encoded 5 bytes hash.

This hash is based on the DATE info from the message.

. (dot) - Separator.

001 Sequential value. Incremented by 1 if the base filename, including this part, already exists.

, (comma) - Separator.

RA Status of the message. Possible letters after the comma:

R - Read
A - Answered
M - Marked
Y -
J -

Every folder contains an .index file with the headers of every message in the directory. There is also a configuration file called .fconfig which holds the settings for that particular folder.

Theme handling

YAM will use the icons and pictures in /Themes/default along its Graphical User Interface. There are several kinds of icons:

config/config_#?, config_#?_big

These images are what you see when you open Settings to configure YAM.

folder/folder_#?, folder_#?_new

These are the images used in front of the basic Incoming, Deleted, Outgoing and Sent folders. Those with the "_new" suffix are used automatically whenever there is new or unread mail in the folder.

The "folder_fold" and "folder_unfold" images are special: they are used as the icon for folder groups.

A ".fimage" picture file in a folder overrides the default image. This is also the only method supported to have images displayed in front of custom folders.

icon/check.info, empty.info, new.info, old.info

Icons which show the status of the "Incoming" mailbox:

check.info YAM is checking for new mail
empty.info the mailbox is empty
new.info the mailbox has at least one new message
old.info the mailbox only holds "old" mail

status/status_#?

These are the status icons ? displayed by YAM to show the status of the messages.

The "status_mark" icon used when messages are set to "marked" is special: if it is not present, YAM will mark the messages by displaying the sender/recipient data in bold letters.

toolbar/tb_#?, tb_#?_G, tb_#?_S

These are the images used to build the toolbars in the Main, Read, Write and Address book windows. Those named "tb_#?_G" are the "ghosted" variety, i.e. they provide the images to be used when the icons must look ghosted. "tb_#?_S" are the "selected" variety, i.e. when you press a button.

.theme, logo, preview

.theme contains various important text variables that are needed for the theme engine to work.

The "logo" is what you see when you start and quit YAM and also in the "about" window in YAM. (Note: only the default logo is displayed, no matter what theme you have selected.)

The "preview" is a small preview that shows what that icon theme looks like in Settings/Look & Feel.

Misc file formats

The .addressbook file

This plain text file uses a hierarchical scheme following this general format:

    YAB4 - YAM Addressbook                          - Identifier
    @GROUP alias  ·································
    description                                   ·
    @USER alias     -------------.                ·
    e-mail address               |                ·
    real name                    |                ·
    description                  |                ·
    phone #                      |                ·
    street address               |                ·
    ZIP/City                      > Person        ·
    country                      |                ·
    PGP ID                       |                ·
    birth date                   |                ·
    portrait                     |                 · GROUP
    homepage                     |                ·
    default security             |                ·
    @ENDUSER        -------------'                ·
    @LIST alias     >>>>>>>>>>>>>>>>>>>>>>>>>>                 ·
    return address               v                ·
    list name                    v                ·
    description                  v                ·
    member #1                     >> LIST          ·
    member #2                    ^                ·
    ...                          ^                ·
    member #n                    ^                ·
                                 ^                ·
    @ENDLIST        >>>>>>>>>>>>>>>>>>>>>>>>>>                 ·
    @ENDGROUP     ·································

Groups, lists and people are started with @GROUP <alias>, @LIST <alias> and @USER <alias> and closed with @ENDGROUP, @ENDLIST and @ENDUSER, respectively. Groups may include lists, and lists may include members. Both lists and people may appear outside groups. List members may be either aliases, addresses or fully qualified "Real name <address>" pairs.

GUI-wise, a group may be dragged&dropped onto a distribution list and viceversa to get all its recipients added to the list. Recursive loops are watched and promptly avoided when appropriate - for instance, if a group contanining a list is dragged&dropped on that list, only the items available in the group other than the contents of the list itself are added to it.

The .emailcache file

This plain text file contains a list of the last n used recipients who were not in the address book, in the format "Name <address>" (or just "<address>" if the name is not available) with one entry per line.

New entries get added at the top. If the limit of entries set in the configuration is exceeded, the oldest entry (i.e. the one at the bottom) is dropped.

If it is already in the cache when writing the mail, the entry is moved to the top -- this way, the next time, the most recently used recipient will be suggested first. Entries in the address book will still have priority over the cache, though.

The .fconfig file

This plain text file exists in every folder and stores the settings used therein, using this format:

YFC1 - YAM Folder Configuration
Name = folder_name
MaxAge = age
Password = password
Type = folder_type
XPKType = type_number
Sort1 = primary_sort
Sort2 = secondary_sort
Stats = Y|N
MLSupport = Y|N
MLFromAddr = MLFrom_address
MLRepToAddr = MLRepTo_address
MLPattern = ML_pattern
MLAddress = ML_address
MLSignature = signature_number

where

  • Name is the name of the folder, as it appears in the folder list
  • MaxAge is the number of days the messages in the folder will be kept before removing them automatically, where 0 disables this feature (see Configuration/Start/Quit ?)
  • Password is the encoded counterpart of the password used to protect this folder, if any
  • Type is a number indicating which type this folder is (should be usually 0 for user folders - see the documentation for the FOLDERINFO ? command)
  • XPKType refers to the XPK mode used in the folder:

0 = none
1 = simple protection (password)
2 = compressed
3 = compressed with password

  • Sort1 refers to the primary sort criterion used in the folder, in negative form if the sort is reversed:

1 = Message date
2 = Date received
3 = Sender
4 = Recipient
5 = Subject
6 = Size
7 = Status

  • Sort2 is just the same as Sort1, but referred to the secondary sort criterion
  • Stats may be either Y or N depending on the status of the "AppIcon stats" flag
  • MLSupport may be either Y or N depending on the status of the "Mailing list support" flag
  • MLFromAddr shows the contents of the "From: address" field
  • MLRepToAddr shows the contents of the "Reply-To: address" field
  • MLPattern shows the contents of the "To: pattern" field
  • MLAddress shows the contents of the "To: address" field
  • MLSignature refers to the default signature to be used when posting messages to this mailing list:

0 = none
1 = default signature, i.e. PROGDIR:.signature
2 = alt. signature #1
3 = alt. signature #2

The .folders file

This plain text file uses a hierarchical scheme following this general format:

    YFO1 - YAM Folders                              - Identifier
    @FOLDER name    ------------------.
    directory                          > Folder
    @ENDFOLDER      ------------------'
    @GROUP name              ································
    status                                                  ·
    @FOLDER name    ------------------.                     ·
    directory                          > Folder             ·
    @ENDFOLDER      ------------------'                     ·
    @GROUP name              ······················         ·
    status                                        ·         ·
    @FOLDER name    ------------------.           ·          · GROUP
    directory                          > Folder   ·         ·
    @ENDFOLDER      ------------------'            · GROUP  ·
    @FOLDER name    ------------------.           ·         ·
    directory                          > Folder   ·         ·
    @ENDFOLDER      ------------------'           ·         ·
    @ENDGROUP                ······················         ·
    @ENDGROUP                ································

where <status> may be either 0 or 1, the latter meaning that the group is unfolded, e.g. its contents are being displayed. Folders may live both inside and outside groups, and groups may be nested.

The order of the folder tree is saved on disk whenever the Folder/Order/Save ? menu item is called.

The .glossary file

This file contains a list of the definitions made in the glossary ? using this format:

YDI1 - YAM Dictionary
@ENTRY abbreviation
contents
@ENDENTRY
@ENTRY abbreviation
contents
@ENDENTRY
...

The .uidl file

If "Avoid duplicates" is enabled in Configuration/New mail ?, YAM will use the UIDL POP3 command when connecting to your POP3 server to request an Unique ID Listing of the messages in your mail account. The POP3 server is responsible for assigning an unique ID to every message and put it into a "X-UIDL:" header.

If the server doesn't support the UIDL POP3 command, YAM will fall back to the TOP command and try using the "Message-ID:" header instead; if this also fails, an error will be generated.

The Unique ID Listing received from the server is compared against the contents of the "PROGDIR:.uidl" file; if this file doesn't exist yet, it will be created. This is a plain text file with one ID per line using the format <ID>@<POP3 server>, e.g.

9685@…
9686@…
9687@…
9688@…
(k5"!N1!"!RkI"!YT4"!@pop.wanadoo.es
9689@…
9690@…
9691@…
9692@…

Whenever an ID is already found in the "PROGDIR:.uidl" file, the relevant message will be considered a duplicate, and thus it won't be downloaded. New IDs not yet in the "PROGDIR:.uidl" file will be added to it as the corresponding messages are successfully downloaded.

The .users file

This file contains a list of the users that can log in and use YAM. YAM maintains this file by itself, so you shouldn't ever touch it, unless maybe you are moving YAM ? to another place in your hard disk.

The file uses the following format:

1st line: YUS2 - YAM Users
2nd line: @USER <username>
3rd line: mail directory of this user, e.g. Comm:YAM
4th line: number
5th line: encrypted password, if any
6th line: @ENDUSER

further lines: next user definition, upto 16 maximum.

where "number" is a value defining the status of this user combining the following set of elements:

No Supervisor privileges = 4
Share global address book = 2
Share global glossary = 1

Thus, "3" would mean the user has Supervisor privileges and is sharing the global address book and glossary. This is the default value in a single user setup.

The log file

The log file used by YAM is an ASCII file storing one event per line. Each line is saved in this format:

DD-MMM-YY HH:MM [code] Event description

where code is a two digit number and "Event description" is obviously the event description, possibly localized. Therefore, any computer-assisted software meant to analyze the log file data should refer to the code of the event.

Events out of the 30<->49 range will only be printed if "Log all events" is enabled in the Security options ?.

List of possible events:

0 - YAM started
1 - Logged in as user 'user_name'
2 - Logged in as 'user_name', using configuration 'config_file' and mail directory 'folder_path'

10 - Wrote new message for 'recipient' about 'subject', including n attachment(s)
11 - Replied message from 'sender' about 'subject'
12 - Forwarded message from 'sender' about 'subject' to 'recipient'
13 - Bounced message from 'sender' about 'subject' to 'recipient'
14 - Edited message from 'sender' to 'recipient' about 'subject'
20 - Deleted n message(s) in folder 'folder'
21 - Deleted message from 'sender' about 'subject' in folder 'folder'
22 - Moved n message(s) from folder 'folder' to 'folder'
23 - Moved message from 'sender' about 'subject' from folder 'folder' to 'folder'
24 - Copied n message(s) from folder 'folder' to 'folder'
25 - Copied message from 'sender' about 'subject' from folder 'folder' to 'folder'
26 - Filtered n message(s) in folder 'folder': n match(es)
30 - Retrieved n message(s) from POP3 account 'user_id@host'
31 - Logged in on POP3 account 'user_id@host': n messages waiting
32 - Retrieved message from 'sender' about 'subject' (n bytes)
40 - Sent n message(s) using SMTP server 'host'
41 - Connected to SMTP server 'host'
42 - Sent message to 'recipient' about 'subject' (n bytes)
50 - Imported n message(s) from file 'filename' into folder 'folder'
51 - Exported n message(s) from folder 'folder' to file 'filename'
60 - Saved configuration file 'config_file'
62 - Saved user configuration
70 - Saved address book 'filename'
71 - Added address book entry 'alias'
80 - Saved attachment 'filename' of message 'mailfile' in folder 'folder'
81 - Cropped attachment(s) of message 'mailfile' in folder 'folder'
82 - Changed subject 'subject' of message 'mailfile' in folder 'folder' to 'subject'
99 - YAM terminated