git.marmaro.de Git - mmh/blob - docs/README.hooks

   1 Jon Steinhart's (jon@fourwinds.com) External Program Hooks
   2 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   3
   4 This blurb describes a changes to nmh that implement an interface
   5 to external programs.  This interface is different than the limited
   6 interface provided by things like the rmmproc context entry.
   7
   8
   9 Why Did I Do This?
  10 ~~~~~~~~~~~~~~~~~~
  11
  12 I'm working on a project (grokmail) that will get released via GPL sometime
  13 soon.  This project keeps a database synchronized with the messages in the
  14 mail system.  New functionality is built on top of this database.  This
  15 functionality allows fast searching, and searching based on interest
  16 criteria.  The latter can be used for spam filtering.
  17
  18 The changes to nmh allow external programs to be run whenever a message is
  19 added to a folder, removed from a folder, or refiled.  The changes are
  20 implemented in a general way so that it can be used for other purposes than
  21 mine.
  22
  23 What Are The Changes?
  24 ~~~~~~~~~~~~~~~~~~~~~
  25
  26 The changes add four new profile components:
  27
  28 add-hook:       This is the full pathname of a program that is invoked
  29                 whenever a message is added to a folder.  The program
  30                 is passed one argument which is the full pathname of the
  31                 message file.  The program is executed after the message
  32                 is written so that it can act upon that message.
  33
  34 del-hook:       This is the full pathname of a program that is invoked
  35                 whenever a message is deleted from a folder.  The program
  36                 is passed one argument which is the full pathname of the
  37                 message file.  The program is executed before the message
  38                 is written so that it can act upon that message.
  39
  40 ref-hook:       This is the full pathname of a program that is invoked
  41                 whenever a message is refiled.  The program is passed two
  42                 arguments:  the first is the full pathname of the original
  43                 message file, the second is the full pathname of the final
  44                 message file.  The program is executed after the message
  45                 is written.
  46
  47 message is moved from one place to another.  So, for example, the command
  48
  49         refile -link
  50
  51 The definition of refiling is a bit tricky.  The refile hook is executed if a
  52 causes the add hook to be executed, not the refile hook, because a new message
  53 is created, the old one isn't moved.
  54
  55 These changes affect the following commands:
  56
  57 burst:          The add hook is executed for messages burst from a digest, and
  58                 for the table of contents if -inplace is specified.  The delete
  59                 hook is executed for the original message if -inplace is
  60                 specified.  The refile hook is executed for messages that are
  61                 moved.
  62
  63 folder:         The refile hook is executed for -pack.
  64
  65 inc:            The add hook is executed when messages are incorporated.
  66
  67 refile:         Either the add or refile hooks are executed.
  68
  69 rmf:            The delete hook is executed when messages are deleted.
  70
  71 rmm:            The delete hook is executed when messages are deleted.
  72
  73 sortm:          The refile hook is executed for each message moved.  Note that
  74                 a magic temporary message number of 2147483647 is used to hold
  75                 messages as they are being shuffled.
  76
  77 rcvstore:       The add hook is executed when messages are stored.
  78
  79 mhstore:        The add hook is executed when messages are stored.
  80
  81 Did I Do This Correctly?
  82 ~~~~~~~~~~~~~~~~~~~~~~~~
  83
  84 Well, sort of.  This all works, but I'm not really happy with it.  The issue
  85 is that an examination of the nmh code shows that message handling is scattered
  86 all over the place.  Although there are library routines such as folder_addmsg
  87 and folder_delmsgs, they are not used consistently.  Long term, I think that it
  88 would be better to make all message handling go through the same choke points.
  89
  90 Also, I added a function to run the external programs.  This sort of stuff is
  91 also scattered around the nmh code, for example in the code to run the rmmproc.
  92 Again, I'd like to make this more consistent in the long term.
  93
  94 What Files Did I Change?
  95 ~~~~~~~~~~~~~~~~~~~~~~~~
  96 uip/
  97         burst.c
  98         inc.c
  99         refile.c
 100         rmf.c
 101         sortm.c
 102
 103 sbr/
 104         folder_addmsg.c
 105         folder_delmsgs.c
 106         folder_pack.c
 107         ext_hook.c      (new file)
 108
 109 Old config options:
 110 ~~~~~~~~~~~~~~~~~~~
 111
 112 In the original implementation availible config option, which are removed.
 113
 114 msg-hook:       This is a text message that is output if the execution of
 115                 one of the external hook programs fails.  There is a built-in
 116                 default message if none is specified.
 117                 This is removed, because I don't see this is necesarry and it's
 118                 not a good idee to pass a user provided string direkt in an
 119                 format string.
 120