rulefile.specs.txt

JK Proxy Project - Version 0.1 ------------------------------ This was going to be a proxy serve

rulefile.cpp specifications
---------------------------

This a more or less detailled description of what the code in this file
does, how it works and how it should be used.


Overview
--------
A 'rulefile' in the proxy project is a special config file which
defines a list of rules messages are checked against to see if they are
spam or not.


Specifications of a rulefile
----------------------------
There are currently only two commands which are allowed in a rule file:
- rule
- loadlist

'rule' creates a new rule and takes 6 parameters:

1. parameter: Must be 'header' or 'body' and defines which part of the
              message this rules applies to

2. parameter: If 1. parameter is 'header' this defines the header 
              entity which will be used for checking (e.g. 'subject' or
              'from'). If first parameter is 'body' this field must be
              empty.

3. parameter: Type of rule. This defines which kind of check the rule
              processor is supposed to perform when processing this 
              rule. 
              This can be 'equals', 'notequals', 'contains', 
              'notcontains', 'pattern', 'notpattern'. The first 4 rule
              types should be self-explanatory, the last two ones mean
              that a pattern matching will be performed.

4. parameter: This param simply sets if the check defined in parameter
              3 will be performed case-sensitively or-insensitively.
              'C' stands for case-sensitive and 'I' for 
              case-insensitive

5. parameter: This sets what the part of the message defines above is
              actually checked against. This can be a single string
              enclosed in quotes or a list prefixed by an '@'. A 'list' 
              means a list of words loaded from a file. This list must 
              have been loaded via the 'loadlist' command before. 
              When applying a rule with a list as the 5th parameter 
              each word of the list will seperately be checked.

6. parameter: In this parameter we define what is done with an email if
              the rule matches. This can be 'isspam' or 'pass'. If a 
              message passes it will always be forwarded to the client,
              what happens to a message which "is spam" is defined in 
              the config file of the module which uses the rule-
              processor (e.g. the email module)


Sample 'rule' command:

rule header, subject, contains, I, @badwords, isspam


'loadlist' takes two parameters. The first parameter is the the name
to which an 'rule' command can refer later on and the second 
parameter is file that contains the list of words to be used 

Sample 'loadlist' command: (can precede sample 'rule' command above)

loadlist badwords, ./badwords.txt



Functions
---------
This module exports only two functions:

LoadRules()
ReleaseRuleFile()


'LoadRules' opens a rule file, reads the contents and forms a RULEFILE
struct which is returned as a pointer. This RULEFILE struct can then
be forwarded to the rule processor.

'ReleaseRuleFile' releases all memory that have been allocated for a
RULEFILE struct. It is very important to call this procedure when a
RULEFILE struct is not needed anymore as this struct may use a
significant amount of memory.