
	INTERFACE between ratatosk library and the interface

		    Martin Forssén


   TkRat software and its included text is Copyright 1996-2002 by
   Martin Forssén.

   The full text of the legal notice is contained in the file called
   COPYRIGHT, included with this distribution.



This file documents the tcl entities which the ratatosk C-library defines.
It also defines which tcl-functions the C-library expects the interface to
provide.

	COMMANDS AND ENTITIES PROVIDED BY THE LIBRARY

    Folder entities

RatOpenFolder def
    Opens a folder. The argument should be the definition of the folder to
    open.

$folder update mode
    Updates the mailbox. Mode can be either 'update', 'checkpoint' or
    'sync'. If it is 'update' then the function only check for new mail.
    If it is 'checkpoint' then it writes any unsaved flag-changes etc to disk
    and if it is 'sync' then the folder is expunged. Returns the number of
    new messages.

$folder close [force]
    Closes the folder. After this the folder handler is deleted. If the
    force argument is present and true then  the folder is closed no
    matter how many times it has been opened.

$folder setName name
    Sets the folder name to "name".

$folder info
    Returns a list with the following elements:
      Folder name (readable text string)
      Number of messages in folder (int)
      Size of folder (int)
    Some folder types may not support the size value. In this
    case -1 is returned.

$folder list format
    Returns a list with one entry per message in the folder The
    format of the entry is specified in the "format" argument.
    The "format" argument looks like a string to printf except
    the only thing that may follow the '%' (except another '%')
    is an optional integer (may be negative) and one of the
    following characters:
      s - Subject of message
      n - Name of sender (or mailaddress if the name is not
	  available)
      m - Mail address of sender
      r - Name of recipient
      R - Mail address of recipient
      b - Approximate size of message in bytes
      B - Approximate size of message in bytes (expressed as
	    a mangled number string)
      d - Message date (formatted)
      D - Message date (in seconds since the epoch)
      S - Message status (string of maximum 5 characters)
      i - Current message index in folder
      t - Threading string
      M - Message ID
  In some cases the message size may not be available. In that
  case it is replaced by a '?'.

$folder get index
    Returns a message handler for the message specified
    by "index". This is an index into the list of messages
    as it is returned by the list comnmand.

$folder setFlag index flag value
    Sets the specified flag of the message specified by "index" to
    a value (a boolean value). The flag is one of 'seen', 'deleted',
    'flagged' or 'answered'.

$folder getFlag index flag
    Gets the specified flag of the message specified by "index".
    The flag is one of 'seen', 'deleted','flagged' or 'answered'.

$folder flagged flag
    Returns a list of messages (thir indexes) that are marked with
    the given flag. Flag can be one of 'seen', 'deleted','flagged'
    or 'answered'.

$folder insert message [message ...]
    Inserts the messages whose handlers are passed in the
    message arguments into the folder.

$folder type
    Returns the type of the folder (dbase, std or dis).

$folder find message
    Returns the index in the folder for the specified message, or -1 if
    the message is not associated with this folder.

$folder match expId
    Returns a list of indexes of messages that matches the given expression
    (you get the id from RatParseExp).

$folder getSortOrder
    Returns the current sort order of a folder

$folder setSortOrder order
    Sets a new sort order of a folder

$folder netsync
    Synchronizes the folder over the network if possible (only disconnected
    folders support this).

$folder refcount
    Returns how many current references there are to this folder.

$folder role
    Retiurns the role to use for this folder.


    Message entities

Each message has an associated variable named msgInfo_$message. When the
message is deleted this variable is unset.

$message headers
    Returns a list which contains all header lines from the message.
    Each element of the list is a list of two elements, the first is
    the header name and the second is the value.

$message body
    Returns the name of the bodypart entity contained in this message

$message rawText
    Returns the complete message as text.

$message get field...
    Returns a list of address entities found in the specified fields.
    The following are the valid fields: return_path, from, sender,
    reply_to, to, cc and bcc.

$message reply to
    Creates a new message handler which is fit to use for RatSend which
    is a reply to this message. The to field is either sender or all and
    denotes to whom the reply should go. There will be a member named
    data in the handler array which contains the body text of the reply.
    The new handler is returned.

$message copy vfolder_def
    Inserts a copy of the message in the vfolder defined by vfolder_def.

$message list format
    Returns information about the message. This command works like
    the folder list command but operates on only one message. See the
    documentation on folder list for description of the format argument.

    Bodypart entities

$body children
    Returns a list of bodyparts contained in this bodypart. This only makes
    sense for multipart entities.

$body message
    Extracts a message from this bodypart and returns the message handler.
    This can only be done on message entities. If the message is empty
    an empty string is returned.

$body dsn
    Extracts the DSN data from a message/delivery-status body part. The
    data is returned as:
	{msg-fields} {{recipient1-fields} {recipient2-fields}}
    Where there can be an arbitrary number of recipient fields. Each item
    is actually a list of lists. Each sublist contains a key and a value.

$body type
    Returns a list containing the type and subtype of the bodypart.

$body params
    Returns a list of the parameters set for this bodypart. The list is
    a list of lists where each sublist contains two elements. The parameter
    name and its value.

$body parameter name
    Returns the value of the parameter specified by "name". If the
    parameter is unavailable an empty string is returned.

$body disp_type
    Returns the disposition type as set in the Content-Disposition
    header for this bodypart. If the bodypart does not have a
    Content-Disposition header the function returns an empty string.

$body disp_parm
    Returns a list of the parameters set in the Content-Disposition
    header for this bodypart. The list is a list of lists where each
    sublist contains two elements. The parameter name and its value.

$body id
    Returns the bodypart ID if available. Otherwise an empty string is
    returned.

$body description
    Returns the bodypart description if available. Otherwise an empty
    string is returned.

$body size
    Returns the size of the bodypart in bytes.

$body lines
    Returns the size of the bodypart in lines.

$body encoding
    Returns the encoding the body is in.

$body isGoodCharset
    Returns true if this body is encoded in a charset we know how to handle.

$body data encoded charset
    Returns a string which contains the body content. If encoded is
    false any contet-transfer-encoding will be undone. The optional
    charset parameter tells which charset we should assume the body
    is encoded in, if no charset is given the body parameters are used.

$body saveData fileId encoded convertNL
    Saves the body data in the already opened file. The file must be
    opened for writing. If encoded is true the data is saved in the
    form it is in the mailbox. If encoded is false any transport
    encoding is undone. The convertNL argument controls if the lineends
    are converted to simple '\n'.

$body findShowCommand
    This checks if there is an entry in the mailcaps that matches this
    bodypart. The return value is a list. If there was no matching element
    then every entry in the list is empty. The list is {cmd term copious
    desc bitmap}. And the entries are:
	cmd	- The command to use to show this body (possibly with '%s')
	term	- A '1' if this program needs a terminal
	copious	- A '1' if this program gives lots of output
	desc	- A description of this type
	bitmap	- The name of an xbm-file which contains an icon for this type

$body filename
    Asks the body if it has a good candidate for a filename for the user who
    wishes to save this bodypart.

$body encoded
    Returns 1 if the bodypart has been decoded. Zero otherwise.

$body sigstatus
    Gets the signature status for this bodypart. Possible return values
    are "pgp_none", "pgp_unchecked", "pgp_good" or "pgp_bad"

$body checksig
    Causes this bodypart to check the signature. The return value is the
    output from pgp.

$body getPGPOutput
    Returns the output of the PGP operation performed on this bodypart.


    Address entities

$address isMe useUP
    Returns 1 if this address points to me, otherwise 0 is returned.
    If useUP is present and false then any eventual userproc is not called.

$address compare address
    Compares two addresses and returns 0 if they point to the same user.
    Otherwise 1 is returned.

$address set personal name host
    Sets the address.

$address get form
    Returns the address in a textual form. The form argument can have the
    following values:
	rfc822	- returns the entire address in rfc822 format.
	mail	- returns the name of the mailbox
	name	- returns the personal name

RatCreateAddress address role
    Returns an address command containing the given address. The role arg
    tells which role to operate in.


    Message hold

RatHold insert handler description
    Insert the message described by handler into the hold with the given
    description text as description. For a description on handler see the
    RatSend command.

RatHold list
    Returns a list of descriptions of the messages in the hold.

RatHold extract index
    Extracts the intex'th message from the hold. A handler which has the
    same members as the one inserted is returned.


    Aliases

RatAlias add book name fullname content comment options
    Adds the given alias to the alias list.

RatAlias delete name ?...?
    Deletes the named aliases from the alias list.

RatAlias get alias
    Returns the definition of an alias. The return value is
    {book fullname content comment options}.

RatAlias list var
    Returns the alias list. The alias list is inserted into an array
    named "var". The index is the name of the alias and the content is
    a list of three elements {book fullname content comment options}.

RatAlias read filename
    Reads aliases from filename and adds them to the internal list.

RatAlias save book filename
    Saves an address book to the specified file.

RatAlias expand1 adrlist role
    Takes one address line as argument and tries to do first level alias
    expansion on it, i.e. any found aliases are complemented with their
    fullnames (if any). The new adrlist is returned.

RatAlias expand2 adrlist role
    Takes on adress line as argument and tries to do full alias expansion
    on it, i.e. every alias is replaced with its content.


    PGP commands

RatPGP listkeys [keyring]
    Lists the keys on a keyring. Returns a tuple of two elements where the
    first is a suitable title to show above the descriptions. The
    second element is a list of keys where each key is represented by
    a tuple of three elements. The key ID, a list of userids and a
    text description of the key.

RatPGP extract id [keyring]
    Returns the ascii version of the wanted key.

RatPGP add keys [keyring]
    Adds the given keys to the specified keyring.

    Misc commands

RatGenId
    Generate a unique ID (ie unique for this machine) which is a
    maximum of 14 characters long

RatWrapCited
    Wraps a text which is expected to be a cited message.

RatBgExec exitStatus args
    Works like the tcl exec command except that the commands is always
    placed in the background and the call to RatBgExec returns immediately.
    When the executed commands are done the variable exitStatus will be set
    to the exit value of the last process that exited.

RatSend action ?handler?
    If action is "init" then the ratDeferred variable is initialized.
    If the action is "sendDeferred" then all deferred messages are sent and
    the number of sent messages is returned. If the action is "kill" the the
    child is killed (if it exists).
    If action is "send" then we send the message identified by the handler
    using the prefered method of sending messages. The handler argument
    should be the name of an array which may contain the following entries
    (entries marked with a '*' are required):
	handler(remail)		- remail headers
	handler(date)		- message composition date string
	handler(from)		- originator address list
	handler(reply_to)	- reply address list
	handler(subject)	- message subject string
	handler(to)*		- primary recipient list
	handler(cc)		- secondary recipient list
	handler(bcc)		- blind secondary recipient list
	handler(in_reply_to)	- replied message ID
	handler(message_id)	- message ID
	handler(body)		- bodypart handler
	handler(request_dsn)	- true if DSN is requested
	handler(charset)*	- Which character set to use. If this is
				  auto then the best set is choosen for each
				  encoded entity. This also serves as default
				  for the bodyparts. ie if they do not have
				  a charset parameter
	handler(role)*          - The role to send the message as
    The bodypart handler should be the name of an array which may have
    the following elements ('*' marked entries are mandatory):
	bhandler(type)*		- type
	bhandler(subtype)*	- subtype
	bhandler(encoding)*	- CTE the data is in
	bhandler(parameter)	- list of parameters to Content-Type:
	bhandler(disp_type)	- disposition type
	bhandler(disp_parm)	- list of parameters to Content-Disposition:
	bhandler(id)		- bodypart identifier
	bhandler(description)	- bodypart description
	bhandler(filename)*	- name of file which contains the actual data
				  (not needed for multipart entities)
	bhandler(removeFile*)	- true if we should rmeove the file afterwards
	bhandler(children)	- list of parts in a multipart message
	bhandler(copy)		- true if should make a local copy of the file.

RatGetEncoding filename
    Examines a file and returns a guess of which MIME-encoding it is in.

RatCleanup
    This should always be called before the program exits.

RatTildeSubst
    Do tilde substitution on a filename and return the new filename.

RatTime [+days]
    Returns the time now, or in +days days as an integer (unix time).

RatInsert msgId keywords exDate exType
    Insert the given message into the dbase. Keywords are the keywords
    the message should get, exDate is expiration date in number of days
    from now. exType should be 'none', 'remove', 'incoming', 'backup' or
    'custom <cmd>'.

RatLock variable ...
    Locks the varibles agains changes. Locked variables can't be changed
    or unset.

RatIsLocked variable
    Returns 1 if the variable is locked, else 0 is returned.

RatType filename
    Tries to determine what MIME-type the given file has. The result is
    a list of two elements; {type/subtype encoding}.

RatDaysSinceExpire
    Returns the number of days that have passed since the last time the
    database was expired.

RatExpire inbox backupDir
    Expires the database. Inbox should be the name of the inbox folder (which
    must be open). Returns the following list: {num_scanned num_deleted
    num_backup num_inbox num_custom}.

RatDSNList
    List the messages in the list. Return a list of message entries.
    Each message entry consists of the following list:
    	{id date subject {{recipient1} {recipient2} ...}}
    The id identifies this message. The date is the number of seconds
    since the epoch when the message was sent. There may be one or more
    recipient blocks. The syntax is:
    	{status recipient id}
    Recipient is the recipient address. Id contains an identification
    which can be used in other calls to obtain more information about
    this delivery. Status is the current status and can have the
    following values: none, failed, delayed, delivered, relayed or expanded

RatDSNGet what id ?recipient?
    Returns data about the referenced DSN. The what argument can have
    one of the following values:
        msg	- A message handle which handles the DSN message.
        report  - A list of DSN report fields. Each item consists of
    	      	  a list with two values, the key and the value. The
    	      	  recipient argument determines which of the recipient
    	      	  fields to return.

RatSMTPSupportDSN host
    Returns true if the given host supports DSN.

RatImport id
    Imports mail folders. The id argument points to a vfolderdef. This
    command modifies the folder definitions under id.
OLD
    forms (knwon flags are trace and subscribed):
	{NAME dir {FLAGS} {OPTIONS} PATTERN DIR}
	{NAME mh {FLAGS} {OPTIONS} PATTERN DIR}
	{NAME imap {FLAGS} {OPTIONS} PATTERN HOST USER MBOX PORT}
    It will return a list of tuples, where the following tuples exists:
	{v vfolderdef}
	{s name {list of tuples}}
/OLD

RatLL line
    Returns the length of the given line. This function counts tab stops
    to the next even eight characters.

RatGen count
    Generates (and returns) a string of spaces which has the given length.

RatDbaseCheck fix
    Checks the dbase and if fix is true then it tries to fix the dbase as well.
    The result is a list with the following values:
	Total number of messages in index
	Number of malformed entries
	Number of entries without messages
	Number of unlinked messages
	Total size in bytes of all messages
	A list of diagnostic messages

RatParseExp expression
    Parses the given expression and returns an expression identifier.

RatGetExp id
    Returns the requested expression as a tcl list.

RatFreeExp id
    Removes the identified expression from all internal tables.

RatSplitAdr address
    Expects a string with addresses as input and splits it into a list
    of addresses.

RatMailcapReload
    Reloads the mailcap data

RatCreateFolder def
    Creates a new folder

RatDeleteFolder def
    Deletes a folder

RatMangleNumber number
    This command returns a short string represenatation of the number.

RatCheckEncodings variable charsets
    Checks if any of the encodings can encode the data contained in
    the variable whose name is passed in the variable argument. This
    function will return the name of the matching characters set or
    an empty string if none matches.

RatPurgePwChache
    Purge that password cache, both in memory and on disk

RatEncodeMutf7 string
    Encodes the given string in the modified version of UTF-7 described
    in section 5.1.3 of rfc2060.

RatEncodeQP charset string
    Expresses the given string in 'charset' and encodes that in QP.

RatDecodeQP charset string
    Deocdes the given string which is encoded in charset and then QP-encoded.

RatLibSetOnlineMode online
    Transistions into online or offline mode. The online argument
    should be a boolean indicating if the new mode is online or not.

RatBusy cmd
    Execute the command while "busying" the interface by changing the
    cursor and to block all user input.

RatGetCurrent what role
    Get current data. The 'what' parameter can have the following values:
    'host', 'mailbox', 'personal'. The results depends on the role
    definition.

RatGenerateAddresses handler
    Generates headers which will be used when sending the message identified
    by handler. Returns the following list:
	{from sender}

	TCL COMMANDS THE LIBRARY EXPECTS THE INTERFACE TO PROVIDE

RatLog level message duration
    Delivers a message from the library to the interface. The message is
    a string and level is a number with the following meaning:
	0 - babble messages from library, doesn't have to be shown
	1 - parse error, should probably be shown in some situations
	2 - informative message, should be displayed
	3 - warning messages, should be displayed
	4 - error, should be acknowledged by the user
	5 - fatal, the application is about to die
    The duration is an optional argument and can have a value of "time"
    or "explicit". If the value is explicit the a handle will be returned,
    and this handle can then be used in a call to RatClearLog

RatFormatDate year month day hour min sec
    This command gets a date expressed as numbers and is expected to return
    a string.

RatWantSave
    This command should ask the user if he wants to save an outgoing message.
    If the answer is no nothing is returned. If the answer is yes a the answer
    must look like one of these: {file <fname>} or {dbase <kwds> <extype>
    <exdate>}.

RatLogin host trial user prot port
    The host mentioned in the arguments requires an username and password
    for this user. The trial argument says how many tries we already have
    done. The user is the user we should try to log in as and prot is the
    protocol we are going to use. Finally port is the portnumber we will
    contact the remote host at. The routine should return a list of three
    elements {user passwd store} when store is a boolean indicating if we
    should store the password on disk or not.

RatDSNRecieve subject action recipient id
    A DSN has arrived for the mentioned message and recipient. Please notify
    the user.

UpdateDSN
    Gets called from the library when new DSN(s) arrive.
