Attention! This is a draft version of the program documentation. 
If you feel that you could help in improving it, please contact us.

Please visit http://www.xrayapp.com/xray/help for latest version of help file.

1. Overview	
2. Program interface description.	
3. Configuration and tuning.
3.1 Tab "Servers"	
3.2 Tab "Filters"	
3.2.1 X-Ray Mail Assistant macros reference.	
3.3 Tab "SMTP Autoselect"	
3.4 Tab "SNTP Sync"	
3.5 Tab "Settings". (TODO General/Mixed)	
3.6. Tab "Statistics".	



1. Overview

X-Ray Mail Assistant (henceforth X-Ray) was created to make possible mail message header editing.
The program consists of 3 main parts:
*	X-Ray Server (xray.srv) - service module, invisible to user. Does all filtering 
work.
*	X-Ray Control Center (Xray.exe) - executable, which creates an icon in 
system tray and coordinates actions of user interface and service modules.
*	User Interface Library (UI.dll) - dynamic-link library, which contains all 
configuration dialogs.

This was done to optimize system resource usage. Thus, if Interface Library or 
Control Center is not needed at the moment, they can be unloaded.

2. Program interface description. 

This is how main program menu looks like:
{place a screenshot here}
It is available after right click on program icon in system tray.

*	Options - program configuration dialog
*	SMTP Servers - quick selection of default SMTP server
*	POP Servers - quick selection of default POP server 
*	Status - working mode selection. There are number of modes, which define 
program behaviour:
*	Active - service started, filering enabled;
*	Inactive - service started, filering disabled;
*	Disabled - service started, but does not accept new connections;
*	Stopped - service stopped;
*	Busy - service is working and is transferring data.
*	Schema - schema selection.
*	About - program information.
*	Exit - close program.

3. Configuration and tuning.

Program configuration dialog can be opened via item Options in program main menu.

3.1 Tab "Servers"
This tab is for setting parameters of mail servers, which will use X-Ray.
Server type: 	server type: SMTP or POP3;
Local port:	number of local port on which X-Ray will listen for connection;
Host/IP:	name or IP address of a mail server, to which X-Ray will forward all 
incoming connections.
Port:		port number of the mail server;
Alias:		server title;
Username:	username for authorizing on the mail server; 
Password:	password for authorizing on the mail server;
Confirm:	password confirmation field;

Note: For now authorization is available for POP3-servers only.
Note: If  "Use APOP if possible" option is enabled and POP3-server supports APOP 
authorization, but mail-client tries to use regular login/password authorization 
schema, X-Ray will use APOP authorization.

Notes:
*	One local port can be used for forwarding packets to only one mail server.
*	If more than one server with the same local port number was defined, then:
o	If the port number is different from "default" port for this protocol (for 
SMTP default port number is 25, for POP3 - 110. Defaults can be 
changed on tab Settings), then only one server will be active and all 
other servers will be ignored (X-Ray will show message box with a 
warning).
o	If the port number is "default" port, then all servers with this port will 
be accessible in SMTP/POP Servers submenu of main program menu 
and it will be possible to switch servers "on fly". Moreover, if proper 
option is enabled, then extended actions will be performed: SMTP 
servers will be used for SMTP Autoselect, and POP servers will be 
used for Cyclic change.

3.2 Tab "Filters"

Filtering is the primary task, which should perform X-Ray, so this tab is fundamental. 
For now, X-Ray can filter only mail headers, but we have plans for adding capabilities 
to work with all parts of mail message.

If you think that important and useful actions still not implemented in the program, 
please let us know and we'll try to implement it.

Filter is defined with its properties. Not all properties have sense  (and will be active) 
for all filter types. Let's have a closer look.

*	Filter Type:	server type: SMTP or POP3;
*	Filter Action:	action, performed by filter. Possible actions are:
*	Add:		adding of a new kludge;
*	Replace:	changing of a kludge value;
*	Rename:	kludge renaming;
*	Delete:		kludge deleting;
*	Special:	adding of a new kludge, if kludges already existing in the mail 
message fulfill imposed conditions. Application of this kludge is described 
little later.
*	Leave:		processing of this kludge will NOT be performed. (see. 
Continue Processing); can be used for logging.
*	Disabled:	enabling or disabling of the filter.
*	Continue Processing:	By default only one filter can be applied to a kludge; 
other filters will not process that kludge. Setting of this checkbox allows 
continuing processing of the kludge.
*	Kludge name:	name of a kludge to filter; 
*	Substring:	is the 'Kludge name' a partial string of full kludge name*
*	Case-insensitive:	is the 'Kludge name' case sensitive or not*
*	Condition: 	This field specify condition, which should be true to allow 
performing of filter action. Condition could contain macros (see below), other 
kludges (in form of $KludgeName), comparison operators ('==' for 'equal' and 
'!=' for 'not equal') and logical negation ('!') operator. If it is necessary, the field 
could contain more than one condition combined with logical-OR('||') or logical-
AND('&&') operators. Example of valid conditions:
o	$Subject != hi
o	$Pos($From, hotmail.com) == -1
o	($Pos($CurDate(), Sun) == -1) && (($Subject != forget me not) || ($From 
        == oldfriend@domain.com))    (this should be one looong line)
*	Kludge value:	This field defines what value will the kludge have after 
        processing. It can contain either string (then this string will become a new 
        value) or file name (for the file operations).
*	Separator & Delete source:	these options are available for Special action 
        type only (see description below).

*	File operations:	Kludge contents can be loaded from/saved to file with a help of 
        file operations.
*	Load Substitutions:	Name of the file which will be used to load new kludge 
        value. If the file contains more than one line, than program will pick a random 
        one. 
*	Save Kludge Value:	Name of the file to save kludge value to. If this file does 
not exist yet, it will be automatically created.
*	Save: When kludge value should be saved - before or after filter application. 
This field will be inactive if there is no sense in it; e.g. there is no sense saving 
kludge value before the kludge was created.

3.2.1 X-Ray macros reference.
Couple of words to explain how to use macroses.(coming soon.)

For now X-Ray has a short list of string manipulation functions( Maybe it will
be extended in future -- it depends on user input ;-) ).

I. Syntax:

1.	It is VERY simple.
2.	Function arguments should be enclosed in brackets.
3.	Function arguments should be separated with commas.
4.	All arguments are string -- no other data types.
4.1.	There is no need to put quotes (") to define a string.
4.1.1.	Quote will be treated as part of the string.
5.	Spaces before and after string will be truncated.
6.	All kludges in a message are accessible by $kludge_name.
Example: $Date, $Subject, $X-Mailer, etc.
7.	Function result can be used as an argument for another function ("nested
function calls").
8.	Functions names are CASE_SENSITIVE! So $POS or $pos will NOT work!
 
II. Description:

*	$CurDate() -- will insert Current date and time in regular mail format ( "Thu, 11 
Oct 2001 17:05:44 +0400").

*	$RawKludge() - now X-Ray could decode kludge value if it is encoded in 
Base64/QuotedPrintable form. This macros will return kludge value as it is. 
Could be useful in very rare and not trivial cases.
Example: $RawKludge($Subject).

*	$Pos(string, substring) -- returns zero-based position of "substring" inside of 
"string".
	Example: $Pos(test[here], [) will return "4".

*	$RPos(string, substring) -- returns zero-based position of last "substring" inside 
of "string". If there is only one "substring", than $RPos is equal to $Pos).
Example: $RPos(test[here]and[here], [) will return "13".

*	$SubStr(string, begin, end) -- returns part of "string" which starts on position 
"begin" and ends on position "end" of original string.
Example: $SubStr(test-this-now, 4, 9) will return "this".

*	$Cut(string, begin, end) -- invertion of $SubStr. Will return all characters of 
original string except for characters on position from "begin" to "end".

Example:$SubStr(test-this-now, 4, 9) will return "testnow".

Note, that characters located on position "begin" and "end" will also be cut out! 
(It was done intentionally to remove square bracket symbols --'[' and ']', etc.).

*	$CutStr(string, substring) -- Will return "string" without "substring" (if
	"substring" exists inside of "string").
Example: $CutStr(is this test, is) will return " this test".

*	$CutRStr(string, substring) -- Will return "string" without last "substring" (if 
"substring" exists more than once inside of "string". If there is only one 
"substring", than $CutRStr is equal to $CutStr).
Example: $CutRStr(is this test, is) will return "is th test".


III. Application.
These functions can be used in a lots of different ways.
1. Delete known list name from subject line.
Use $CutStr($Subject, your_list_name).
Example: $CutStr($Subject, [KerridwensKessel]).
 In this case a separate filter should be created for every list.

2. If it is known, that mail list name is enclosed in square brackets, $Pos/$RPos can be 
used to find position of opening ('[') and closing (']') bracket and supply it as argument 
for $Cut.
Example: $Cut($Subject, $RPos($Subject, [ ), $RPos($Subject, ] ) ).
This construction needs to be explained.
This is $Cut($Subject, start, end), where
"start" is "$RPos($Subject, [ )"
and
"end" is $RPos($Subject, ] )

Please note, that $RPos was used instead of just $Pos. It was done to handle cases like 
this: "Re[2]: [AX-Le] Pattern destruction and energy release", so "[AX-Le]" will be 
cut out and [2] -- won't.


It is necessary to remove more than one similar string (pair of brackets, for example), 
two identical filters should be created (If X-Ray will complain that one such a filter 
already exists, just add a space to make it little bit different :-). But don't forget to set 
"Continue processing" checkbox to let more than one filter process a kludge!

If more than one filter for a kludge was created, set "Continue processing" checkbox 
on!!!

3.3 Tab "SMTP Autoselect"
Theory
To avoid sending of 'junk mail' (or 'spam') via their mail servers, a lot of internet 
providers require users to authorize themselves before mail sending. Contemporary 
mail clients can be easily configured to work with most types of authorization (POP 
before SMTP, MD5, RFC 2554, etc.). But sometimes SMTP server allows sending a 
mail only for client, which IP-address is in specified range (usually this is IP-range 
assigned to the provider). So it won't be possible to connect via one provider and send 
mail via SMTP-server of another. 

X-Ray could automatically select SMTP-server from a specified list accordingly to 
current IP address. It is necessary to create a record for every IP-range with values:

*	Server:	SMTP server, which should be used for given provider;
*	Network & Subnet mask: definition of IP-range of the given provider.

Note: X-Ray will try to set those fields automatically in the next manner:
*	Network: current IP address
*	Subnet mask: value 255.255.255.0
In most cases those values should work fine. If not, try to play with a Subnet mask.

Quick configuration of SMTP Autoselect (must be done once for every provider):
-	connect to a provider;
-	go to SMTP Autoselect tab;
-	create a new record;
-	pick a server that will be used for mail redirection (the server should be created 
before this step).

Repeat the process for every provider that will be used with SMTP Autoselect. 
Don't forget to switch on "SMTP Autoselect" option (dialog "Options/Settings", or 
menu SMTP Servers/ SMTP Autoselect) and X-Ray will select SMTP server for 
automagically!

3.4 Tab "SNTP Sync"
Time synchronization feature will keep local clock precise. There are number of 
internet time servers. You could load some of them from this data file (,  
 ). 
To let X-Ray synchronize time, checkbox 'Enable time syncronization' should be 
set on.
Please note that correct time zone should be set on a computer, otherwise invalid time 
will be set. To avoid this effect, Under hour correction checkbox can be used. With 
it program assumes, that your computer clock could differ from SNTP server for not 
more than 1 hour.
In the program every time server has priority value associated with it. This value is 
number from 0 to 10, highest number means top priority. When created, server 
priority value is assigned to 5 (medium). When X-Ray is going to connect to a SNTP 
server it will pick a server with highest priority value of all. If there are more than one 
server with this priority level, they will be picked in round-robbin manner. 
Dynamically update priorities checkbox will make X-Ray to change a server 
priority value depending on server delay time. So servers, which are faster for you, 
will eventually have higher priority (and X-Ray will use them for time updates) than 
servers, to which you have a slow access. It is possible tune this process with 
Minimum/Maximum delay settings: if server delay time is less than Minimum 
delay, server's priority will be increased by 1; if server delay time is more than 
Maximum delay, server's priority will be decreased by 1. If the delay is somewhere 
in between, it won't be changed at all.
For a new SNTP server these values could be specified:
*	Host:	hostname or IP address of the server;
*	Port:	port number of the SNTP server (usually, 123);
*	Priority:	server priority value; default value is 5;
*	Comment:	free form description of the server.
3.5 Tab "Settings". 
This tab is for setting general program settings, such as:

Network:
Default SMTP Port:	default port number for SMTP servers; (TODO: 
reference to the explanation of the item) 
Default POP Port: default port number for POP3 servers; (TODO: 
reference to the explanation of the item)
Connect Timeout: amount of time, during which X-Ray will be waiting for 
response from a server. If this value is 0 (not recommended), then X-Ray will wait 
forever;
Allow local connections only: this value defines if X-Ray allowed to accept 
connections from remote hosts, or from local machine only;
SMTP Autoselect: enable SMTP autoselect; (TODO: reference to the explanation 
of the item)
POP Cyclic change:	enable POP Cyclic change; (TODO: reference to the explanation 
of the item)
Use APOP if possible: If POP3 server supports it, X-Ray will use APOP 
(authentication mechanism, which eliminates sending of clear-text password via 
internet). This option requires username/password be set in server properties.

Start & Stop:
Use Service: should X-Ray be started as system service*
Note: This item is available on NT systems (NT4, 2000, XP, etc.)
Note: If this item was set, then only service module will be started, without 
control center.
Run on system startup: should X-Ray Control Center be started on system 
startup*
On Startup: should X-Ray Control Center start X-Ray service, when started* 
On Exit: should X-Ray Control Center stop X-Ray service, when started*

Interface:
	Always on top: should the Options window, when opened, be on top of all 
other windows*
List options: List control interface options settings. 

3.6. Tab "Statistics".
This tab contains statistical information about X-Ray. Currently there are two smaller 
tabs: Mail and Time. 

Mail tab contains data about messages being received/sent/filtered:

*	Bytes In:	number of bytes, received by X-Ray;
*	Bytes Out:	number of bytes, sent by X-Ray;
*	Messages In:	number of messages, received by X-Ray;
*	Messages Out: 	number of messages, sent by X-Ray;
*	Filtered Data:	number of bytes, filtered by X-Ray; please note, that as 
far as X-Ray filters message header only, this number 
will be smaller than Bytes In number;
*	Cut Data: 	number of bytes, that were deleted by X-Ray 'delete' 
filters;
*	Connection attempt:	number of connections accepted by X-Ray;
*	Last Reset:	date and time when statistics collection started;
*	Refresh:	refresh the data;
*	Reset: 	reset the data to zeros;
*	Copy:	copy the data in clipboard.

Time contains data about time synchronization (see Tab "SNTP Sync"):
*	Server used:	name of the SNTP server used for time synchronization;
*	Last connected on:	date and time of last successful connect;
*	Server time:	time received from the server;
*	Difference:	difference between server time and local time;
*	Roundtrip delay:	time, packet took traveling to server and back.
*	Status:	connection status (success, timeout, etc.)
*	Check now!	Perform time synchronization. 

