-*- mode: Text; fill-column: 78; -*-


	INTERFACE between ratatosk library and the interface

		    Martin Forssn


   TkRat software and its included text is Copyright 1996-2004 by
   Martin Forssn.

   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.

RatGetOpenHandler def
    Gets the folder handler of the folder if it is already open. Otherwise
    it returns an empty string.

$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. If the sender matches myself then use
          'To: recpient' instead.
      N - Like 'n' but withot the special handling of myself.
      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
      u - Message UID
      c - Canonalized subject
  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 command.

$folder setFlag {indexes} flag value
    Sets the specified flag of the messages specified by the list of indexes 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 value
    Returns a list of messages (thir indexes) that have the given flag
    set to the given value. 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
    Returns the role to use for this folder.

$folder dbinfo_get
    This is only valid for database folders. It returns the default
    values for new messages in this folder. The return value is a list
    consisting of:
      {list_of_keywords expiration_time expiration_event}

$folder dbinfo_set indexes keywords exdate extype    
    This is only valid for database folders. It update the keywords,
    expiration time and action for the messages whose indexes are included
    in the indexes list.


    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 role
    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.

$message pgp sign encrypt role signer enc_rcpts
    Do pgp operation on message. 'sign' and 'encrypt' are both booleans
    and inidcates which operation(s) to perform. 'role' is the role we are
    operating in. 'signer' is the use which should sign the message (ignores
    if 'sign' is false. 'enc_rcpts' is the recipients to which we should
    encrypt it (ignored if 'encrypt' is false. This modifies the message.

$message remove_internal
    Removes TkRat internal header fields from the message. This only has
    an effect on RatFrMessages.

$message duplicate
    Create a copy of this message

$message delete_attachments attachments dest_folder
    Delete the specified attachemnts and put the resulting message in
    the specified folder. Attachments are specified as a list of integers
    which give the "path" to the attachment.

$message rerunPGP
    Rerun any PGP operation on the body.

$message dbinfo_get
    This is only valid for database messages. It returns the current
    database  information for this message. The return value is a list
    consisting of:
      {list_of_keywords expiration_time expiration_event}


    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 [gen_if_empty]
    Asks the body if it has a good candidate for a filename for the user who
    wishes to save this bodypart. The return can be empty unless the
    optionional gen_if_empty flag is given in which case a random name will be
    returned.

$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", "pgp_bad", "pgp_err" or
    "pgp_abort"

$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 ?-nodomain? address ?role?
    Returns an address command containing the given address. Exactly one of
    -nodomain or role must be specified. -nodomain tells it to not associate a
    domain with the address while the role argument tells which domain to use
    if needed.


OLD
    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.
/OLD

    Aliases

RatAlias add book name fullname content comment pgp_key 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 pgp_key options}.

RatAlias list var ?nocase?
    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 elements {book fullname content comment pgp_key options}.
    If nocase is specified the all the keys in the array will be converted
    to lower case.

RatAlias read book filename
    Reads aliases from filename and adds them to the internal list as
    members of the given book.

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

RatAlias expand level adrlist role
    Takes one address line as argument and tries to do address expansion
    on it. How much the addresses are expanded is controlled by the level
    argument. The following values are legal:
    display    - Resolve for display. Entries which resolves to multiple
                 addresses are shown instead of expanded.
    sending    - Resolve for sending. All addresses are fully expanded.
    pgp        - Get pgp keys. Returns a tcl-list of pgp key tuples
                 {id name} or email addresses to encrypt the message to.
    pgpactions - Get the pgp actions requested by the addresses. The return
                 is a tuple of two booleans {sign encrypt}.


    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 the following elements:
        {key_id email_addresses description subjects sign encrypt}
    The keyring names 'PubRing' and 'SecRing' are reserved and refers to the
    users default keyring.

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.

RatNudgeSender
    Causes the sender process, if idle, to rescan the outbox and send any
    messages (if online).

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.

RatTestImport wildcard def
    Does atest import. Uses the definition passed in def and the given
    wildcard. The list of found items is returned.

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

RatDbaseInfo
    Returns some information about the database. The command returns a list
    with the following elements:
      * approximate number of messages in database
      * timstamp of earliest message
      * timestamp of last message
      * approximate size of database

RatDbasekeywords
    List the keywords usied in the database along whith a count of how
    many messages are using each keyword. Returns a list of tuples where
    each tuple is made up of a keyword and usage count.

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

RatCheckFolder def
    Checks if the specified folder exists. Returns true if it does.

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}

RatGetCTE datatype data
    Returns which CTE the data will fit into. The 'data' argument depends on
    the 'datatype' Valid datatypes are 'file', in which case data is a
    filename, and 'blob', in which case the data is the actual data to
    examine. The return value is one of 'binary', '8bit' or '7bit'.

RatCreateMessage role {envelope body}
    Creates a new message and returns the handler. The envelope is a list of
    tuples where each tuple contains header-name and value. The body is 
    described by the following informal grammar:
	body     - {type subtype {*param} encoding disp {*param} 
	            {*header} bodydata}
	type     - A MIME type
	subtype  - A MIME subtype
	param    - {name value}
	bodydata - {datablob / {*body}}
	datablob - {utfblob/file DATA}

RatExtractAddresses role adrlist...
    Parses the given address lists and returns the user@domain parts of
    them.

RatGenerateDate
    Generates a date-string formatted according to rfc822.

RatGenerateStipple height
    Generates a bitmap suitable as stipple for a text which is 'height'
    pixels high.

RatGetMatchingAddrsImpl addrlist match max
    Look for addresses in addrlist which starts with the match charaters
    (case insensitive). Return no more than "max" addresses.

RatGenerateMsgId role
    Return a suitable message id for the given role

RatCheckListFormat list_format
    Checks if the argument is a valid message list format. Returns ok
    if it is valid, otherwise an error message is returned.

RatDecodeUrlc string addr
    Decodes any %HH encoded characters in the given string. Addr should
    be true if this is an address field. Returns the string with the
    charcters decoded.


	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

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.

RatSendFailed name reason
    Called when TkRat fails to send a message. The "name" parameter contains a
    handler which identifies the message and "reason" is a text string
    describing what happened. This routine must take care of the passed
    message since it will otherwise be lost.

RatSaveOutgoing msg folder
    Try to save the give message to the given folder.
